how to document stuff most users don't want to see

classic Classic list List threaded Threaded
13 messages Options
Reply | Threaded
Open this post in threaded view
|

how to document stuff most users don't want to see

Charles Geyer
The functions metrop and temper in the mcmc package have a debug = FALSE
argument that when TRUE adds a lot of debugging information to the returned
list.  This is absolutely necessary to test the functions, because one
generally knows nothing about the simulated distribution except what what
one learns from MCMC samples.  Hence you must expose all details of the
simulation to have any hope of checking that it is doing what it is supposed
to do.  However, this information is of interested mostly (perhaps solely)
to developers.  So I didn't document it in the Rd files for these functions.

But it has ocurred to me that people might be interested in how these functions
are validated, and I would like to document the debug output somewhere, but I
don't want to clutter up the documentation that ordinary users see.  That
suggests a separate help page for debugging.  Looking at "Writing R Extensions"
it doesn't seem like there is a type of Rd file for this purpose.  I suppose
it could be added in (fairly long) sections titled "Debug Output" in metrop.Rd
and temper.Rd or it could be put in a package help page (although that's not
what that kind of page is really for).  Any other possibilities to consider?
--
Charles Geyer
Professor, School of Statistics
University of Minnesota
[hidden email]

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: how to document stuff most users don't want to see

Duncan Murdoch
On 10/5/2009 1:50 PM, Charles Geyer wrote:

> The functions metrop and temper in the mcmc package have a debug = FALSE
> argument that when TRUE adds a lot of debugging information to the returned
> list.  This is absolutely necessary to test the functions, because one
> generally knows nothing about the simulated distribution except what what
> one learns from MCMC samples.  Hence you must expose all details of the
> simulation to have any hope of checking that it is doing what it is supposed
> to do.  However, this information is of interested mostly (perhaps solely)
> to developers.  So I didn't document it in the Rd files for these functions.
>
> But it has ocurred to me that people might be interested in how these functions
> are validated, and I would like to document the debug output somewhere, but I
> don't want to clutter up the documentation that ordinary users see.  That
> suggests a separate help page for debugging.  Looking at "Writing R Extensions"
> it doesn't seem like there is a type of Rd file for this purpose.  I suppose
> it could be added in (fairly long) sections titled "Debug Output" in metrop.Rd
> and temper.Rd or it could be put in a package help page (although that's not
> what that kind of page is really for).  Any other possibilities to consider?

I think writing it up in a vignette would probably be most appropriate.
  You can link directly to a vignette from a man page (though not,
unfortunately, vice versa).  For example, if you look at
package?grid, you'll see a list that was generated by this code:

Further information is available in the following
\link{vignettes}:
\tabular{ll}{
\code{grid} \tab Introduction to \code{grid} (\url{../doc/grid.pdf})\cr
\code{displaylist} \tab Display Lists in \code{grid}
(\url{../doc/displaylist.pdf})\cr

...

Duncan Murdoch

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: how to document stuff most users don't want to see

William Dunlap
In reply to this post by Charles Geyer
There are several help files in the R sources that
describe concepts and not particular R objects.
E.g., help(Methods), help(Syntax), and help(regex).
They don't have a docType  entry and their alias
entries do not refer to functions.  Perhaps your
debugging documentation could go into a similar
*.Rd file.

Does check balk at such help files in a package? Should it?
Should there be a special docType for such help files?

Bill Dunlap
Spotfire, TIBCO Software
wdunlap tibco.com  

> -----Original Message-----
> From: [hidden email]
> [mailto:[hidden email]] On Behalf Of Charles Geyer
> Sent: Monday, October 05, 2009 10:51 AM
> To: [hidden email]
> Subject: [Rd] how to document stuff most users don't want to see
>
> The functions metrop and temper in the mcmc package have a
> debug = FALSE
> argument that when TRUE adds a lot of debugging information
> to the returned
> list.  This is absolutely necessary to test the functions, because one
> generally knows nothing about the simulated distribution
> except what what
> one learns from MCMC samples.  Hence you must expose all
> details of the
> simulation to have any hope of checking that it is doing what
> it is supposed
> to do.  However, this information is of interested mostly
> (perhaps solely)
> to developers.  So I didn't document it in the Rd files for
> these functions.
>
> But it has ocurred to me that people might be interested in
> how these functions
> are validated, and I would like to document the debug output
> somewhere, but I
> don't want to clutter up the documentation that ordinary
> users see.  That
> suggests a separate help page for debugging.  Looking at
> "Writing R Extensions"
> it doesn't seem like there is a type of Rd file for this
> purpose.  I suppose
> it could be added in (fairly long) sections titled "Debug
> Output" in metrop.Rd
> and temper.Rd or it could be put in a package help page
> (although that's not
> what that kind of page is really for).  Any other
> possibilities to consider?
> --
> Charles Geyer
> Professor, School of Statistics
> University of Minnesota
> [hidden email]
>
> ______________________________________________
> [hidden email] mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel
>

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: how to document stuff most users don't want to see

Spencer Graves-3
There are many arguments in many functions that are rarely used.  I
prefer to see it all documented in the help pages.  If they are not
documented in the help pages (and sometimes even if they are), a user
who wants them can invent other ways to get similar information with
much greater effort, and do so for years only to eventually find a much
easier way buried in the documentation.  Example:  I was frustrated for
years that "nls" would refuse to produce output if it did not converge.  
I often used "optim" instead of "nls" for that reason.  However, the
list returned by "optim" does not have the nice methods that one can use
with an "nls" object.  Eventually, I found the "warnOnly" option
documented under "nls.control", which has made "nls" easier for me to use.

Spencer Graves


William Dunlap wrote:

> There are several help files in the R sources that
> describe concepts and not particular R objects.
> E.g., help(Methods), help(Syntax), and help(regex).
> They don't have a docType  entry and their alias
> entries do not refer to functions.  Perhaps your
> debugging documentation could go into a similar
> *.Rd file.
>
> Does check balk at such help files in a package? Should it?
> Should there be a special docType for such help files?
>
> Bill Dunlap
> Spotfire, TIBCO Software
> wdunlap tibco.com  
>
>  
>> -----Original Message-----
>> From: [hidden email]
>> [mailto:[hidden email]] On Behalf Of Charles Geyer
>> Sent: Monday, October 05, 2009 10:51 AM
>> To: [hidden email]
>> Subject: [Rd] how to document stuff most users don't want to see
>>
>> The functions metrop and temper in the mcmc package have a
>> debug = FALSE
>> argument that when TRUE adds a lot of debugging information
>> to the returned
>> list.  This is absolutely necessary to test the functions, because one
>> generally knows nothing about the simulated distribution
>> except what what
>> one learns from MCMC samples.  Hence you must expose all
>> details of the
>> simulation to have any hope of checking that it is doing what
>> it is supposed
>> to do.  However, this information is of interested mostly
>> (perhaps solely)
>> to developers.  So I didn't document it in the Rd files for
>> these functions.
>>
>> But it has ocurred to me that people might be interested in
>> how these functions
>> are validated, and I would like to document the debug output
>> somewhere, but I
>> don't want to clutter up the documentation that ordinary
>> users see.  That
>> suggests a separate help page for debugging.  Looking at
>> "Writing R Extensions"
>> it doesn't seem like there is a type of Rd file for this
>> purpose.  I suppose
>> it could be added in (fairly long) sections titled "Debug
>> Output" in metrop.Rd
>> and temper.Rd or it could be put in a package help page
>> (although that's not
>> what that kind of page is really for).  Any other
>> possibilities to consider?
>> --
>> Charles Geyer
>> Professor, School of Statistics
>> University of Minnesota
>> [hidden email]
>>
>> ______________________________________________
>> [hidden email] mailing list
>> https://stat.ethz.ch/mailman/listinfo/r-devel
>>
>>    
>
> ______________________________________________
> [hidden email] mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel
>
>  


--
Spencer Graves, PE, PhD
President and Chief Operating Officer
Structure Inspection and Monitoring, Inc.
751 Emerson Ct.
San José, CA 95126
ph:  408-655-4567

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: how to document stuff most users don't want to see

Patrick Burns
I think the problem is more subtle
than Spencer implies.  It is good
to have as much documentation as
possible.  However, if a help file
is long and complex, then people
get intimidated and don't read it
at all.

It would be nice to have a feature
so that help files can be displayed
with different levels of detail.  A
sophisticated version of this scheme
might even assume different levels of
knowledge of the user so that the least
detailed level might be longer (but
easier) than a more detailed level.



Patrick Burns
[hidden email]
+44 (0)20 8525 0696
http://www.burns-stat.com
(home of "The R Inferno" and "A Guide for the Unwilling S User")


spencerg wrote:

> There are many arguments in many functions that are rarely used.  I
> prefer to see it all documented in the help pages.  If they are not
> documented in the help pages (and sometimes even if they are), a user
> who wants them can invent other ways to get similar information with
> much greater effort, and do so for years only to eventually find a much
> easier way buried in the documentation.  Example:  I was frustrated for
> years that "nls" would refuse to produce output if it did not converge.  
> I often used "optim" instead of "nls" for that reason.  However, the
> list returned by "optim" does not have the nice methods that one can use
> with an "nls" object.  Eventually, I found the "warnOnly" option
> documented under "nls.control", which has made "nls" easier for me to use.
> Spencer Graves
>
>
> William Dunlap wrote:
>> There are several help files in the R sources that
>> describe concepts and not particular R objects.
>> E.g., help(Methods), help(Syntax), and help(regex).
>> They don't have a docType  entry and their alias
>> entries do not refer to functions.  Perhaps your
>> debugging documentation could go into a similar
>> *.Rd file.
>>
>> Does check balk at such help files in a package? Should it?
>> Should there be a special docType for such help files?
>>
>> Bill Dunlap
>> Spotfire, TIBCO Software
>> wdunlap tibco.com
>>  
>>> -----Original Message-----
>>> From: [hidden email]
>>> [mailto:[hidden email]] On Behalf Of Charles Geyer
>>> Sent: Monday, October 05, 2009 10:51 AM
>>> To: [hidden email]
>>> Subject: [Rd] how to document stuff most users don't want to see
>>>
>>> The functions metrop and temper in the mcmc package have a debug = FALSE
>>> argument that when TRUE adds a lot of debugging information to the
>>> returned
>>> list.  This is absolutely necessary to test the functions, because one
>>> generally knows nothing about the simulated distribution except what
>>> what
>>> one learns from MCMC samples.  Hence you must expose all details of the
>>> simulation to have any hope of checking that it is doing what it is
>>> supposed
>>> to do.  However, this information is of interested mostly (perhaps
>>> solely)
>>> to developers.  So I didn't document it in the Rd files for these
>>> functions.
>>>
>>> But it has ocurred to me that people might be interested in how these
>>> functions
>>> are validated, and I would like to document the debug output
>>> somewhere, but I
>>> don't want to clutter up the documentation that ordinary users see.  
>>> That
>>> suggests a separate help page for debugging.  Looking at "Writing R
>>> Extensions"
>>> it doesn't seem like there is a type of Rd file for this purpose.  I
>>> suppose
>>> it could be added in (fairly long) sections titled "Debug Output" in
>>> metrop.Rd
>>> and temper.Rd or it could be put in a package help page (although
>>> that's not
>>> what that kind of page is really for).  Any other possibilities to
>>> consider?
>>> --
>>> Charles Geyer
>>> Professor, School of Statistics
>>> University of Minnesota
>>> [hidden email]
>>>
>>> ______________________________________________
>>> [hidden email] mailing list
>>> https://stat.ethz.ch/mailman/listinfo/r-devel
>>>
>>>    
>>
>> ______________________________________________
>> [hidden email] mailing list
>> https://stat.ethz.ch/mailman/listinfo/r-devel
>>
>>  
>
>

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: how to document stuff most users don't want to see

Sean O'Riordain-2
In some cases it would be nice to have a lot of examples explaining the
different uses of different parameters instead of the more usual.

I like the way in which log4j allows one to parameterise at runtime the
verboseness of different parts of a runtime.  So hypothetically (and
assuming a lot!) one could have a default amount of help info and a
different default amount of examples... so when printed the default info
wouldn't be too overwhelming - but it would be possible to ask for more
info.

Sean


On Tue, Oct 6, 2009 at 8:53 AM, Patrick Burns <[hidden email]>wrote:

> I think the problem is more subtle
> than Spencer implies.  It is good
> to have as much documentation as
> possible.  However, if a help file
> is long and complex, then people
> get intimidated and don't read it
> at all.
>
> It would be nice to have a feature
> so that help files can be displayed
> with different levels of detail.  A
> sophisticated version of this scheme
> might even assume different levels of
> knowledge of the user so that the least
> detailed level might be longer (but
> easier) than a more detailed level.
>
>
>
> Patrick Burns
> [hidden email]
> +44 (0)20 8525 0696
> http://www.burns-stat.com
> (home of "The R Inferno" and "A Guide for the Unwilling S User")
>
>
>
> spencerg wrote:
>
>> There are many arguments in many functions that are rarely used.  I prefer
>> to see it all documented in the help pages.  If they are not documented in
>> the help pages (and sometimes even if they are), a user who wants them can
>> invent other ways to get similar information with much greater effort, and
>> do so for years only to eventually find a much easier way buried in the
>> documentation.  Example:  I was frustrated for years that "nls" would refuse
>> to produce output if it did not converge.  I often used "optim" instead of
>> "nls" for that reason.  However, the list returned by "optim" does not have
>> the nice methods that one can use with an "nls" object.  Eventually, I found
>> the "warnOnly" option documented under "nls.control", which has made "nls"
>> easier for me to use.
>> Spencer Graves
>>
>>
>> William Dunlap wrote:
>>
>>> There are several help files in the R sources that
>>> describe concepts and not particular R objects.
>>> E.g., help(Methods), help(Syntax), and help(regex).
>>> They don't have a docType  entry and their alias
>>> entries do not refer to functions.  Perhaps your
>>> debugging documentation could go into a similar
>>> *.Rd file.
>>>
>>> Does check balk at such help files in a package? Should it?
>>> Should there be a special docType for such help files?
>>>
>>> Bill Dunlap
>>> Spotfire, TIBCO Software
>>> wdunlap tibco.com
>>>
>>>> -----Original Message-----
>>>> From: [hidden email] [mailto:
>>>> [hidden email]] On Behalf Of Charles Geyer
>>>> Sent: Monday, October 05, 2009 10:51 AM
>>>> To: [hidden email]
>>>> Subject: [Rd] how to document stuff most users don't want to see
>>>>
>>>> The functions metrop and temper in the mcmc package have a debug = FALSE
>>>> argument that when TRUE adds a lot of debugging information to the
>>>> returned
>>>> list.  This is absolutely necessary to test the functions, because one
>>>> generally knows nothing about the simulated distribution except what
>>>> what
>>>> one learns from MCMC samples.  Hence you must expose all details of the
>>>> simulation to have any hope of checking that it is doing what it is
>>>> supposed
>>>> to do.  However, this information is of interested mostly (perhaps
>>>> solely)
>>>> to developers.  So I didn't document it in the Rd files for these
>>>> functions.
>>>>
>>>> But it has ocurred to me that people might be interested in how these
>>>> functions
>>>> are validated, and I would like to document the debug output somewhere,
>>>> but I
>>>> don't want to clutter up the documentation that ordinary users see.
>>>>  That
>>>> suggests a separate help page for debugging.  Looking at "Writing R
>>>> Extensions"
>>>> it doesn't seem like there is a type of Rd file for this purpose.  I
>>>> suppose
>>>> it could be added in (fairly long) sections titled "Debug Output" in
>>>> metrop.Rd
>>>> and temper.Rd or it could be put in a package help page (although that's
>>>> not
>>>> what that kind of page is really for).  Any other possibilities to
>>>> consider?
>>>> --
>>>> Charles Geyer
>>>> Professor, School of Statistics
>>>> University of Minnesota
>>>> [hidden email]
>>>>
>>>> ______________________________________________
>>>> [hidden email] mailing list
>>>> https://stat.ethz.ch/mailman/listinfo/r-devel
>>>>
>>>>
>>>>
>>>
>>> ______________________________________________
>>> [hidden email] mailing list
>>> https://stat.ethz.ch/mailman/listinfo/r-devel
>>>
>>>
>>>
>>
>>
>>
> ______________________________________________
> [hidden email] mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel
>

        [[alternative HTML version deleted]]

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: how to document stuff most users don't want to see

Seth Falcon-3
Writing good documentation is hard.  I can appreciate the desire to
find technological solutions that improve documentation.  However, the
benefit of a help system that allows for varying degrees of verbosity
is very likely to be overshadowed by the additional complexity imposed
on the help system.

Users would need to learn how to tune the help system.  Developers
would need to learn and follow the system of variable verbosity.  This
time would be better spent by developers simply improving the
documentation and by users by simply reading the improved
documentation.

My $0.02.

+ seth

--
Seth Falcon | @sfalcon | http://userprimary.net/user

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: how to document stuff most users don't want to see

Spencer Graves-3
I write *.Rd files primarily because it helps me think through what I
want the software to do AND because the "\examples" provide any degree
of unit testing I feel I need to create "trustworth software" (to quote
Chambers).  The fact that I can then share the resulting package with
others is a marvelous byproduct of this approach to software
development, but not the primary reason I do it.  Earlier today, I read
where Hadley had had problems with my code and had to read the help file
carefully to understand how to fix the problem.  I immediately wrote to
Hadley inviting more input (and to my collaborator to suggest that the
package be placed on R-Forge to make it easier for people to improve
documentation, etc.).


Adding my $0.02 to Seth's.


Spencer


Seth Falcon wrote:

> Writing good documentation is hard.  I can appreciate the desire to
> find technological solutions that improve documentation.  However, the
> benefit of a help system that allows for varying degrees of verbosity
> is very likely to be overshadowed by the additional complexity imposed
> on the help system.
>
> Users would need to learn how to tune the help system.  Developers
> would need to learn and follow the system of variable verbosity.  This
> time would be better spent by developers simply improving the
> documentation and by users by simply reading the improved
> documentation.
>
> My $0.02.
>
> + seth
>
>  


--
Spencer Graves, PE, PhD
President and Chief Operating Officer
Structure Inspection and Monitoring, Inc.
751 Emerson Ct.
San José, CA 95126
ph:  408-655-4567

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: how to document stuff most users don't want to see

Patrick Burns
In reply to this post by Seth Falcon-3
Under the system of development we
now have, I agreee with Seth's
assertion.  But if there were
people dedicated to documentation,
then I think something like what I
described could be workable.

Pat


Seth Falcon wrote:

> Writing good documentation is hard.  I can appreciate the desire to
> find technological solutions that improve documentation.  However, the
> benefit of a help system that allows for varying degrees of verbosity
> is very likely to be overshadowed by the additional complexity imposed
> on the help system.
>
> Users would need to learn how to tune the help system.  Developers
> would need to learn and follow the system of variable verbosity.  This
> time would be better spent by developers simply improving the
> documentation and by users by simply reading the improved
> documentation.
>
> My $0.02.
>
> + seth
>

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: how to document stuff most users don't want to see

Duncan Murdoch
In reply to this post by Patrick Burns
Patrick Burns wrote:

> I think the problem is more subtle
> than Spencer implies.  It is good
> to have as much documentation as
> possible.  However, if a help file
> is long and complex, then people
> get intimidated and don't read it
> at all.
>
> It would be nice to have a feature
> so that help files can be displayed
> with different levels of detail.  A
> sophisticated version of this scheme
> might even assume different levels of
> knowledge of the user so that the least
> detailed level might be longer (but
> easier) than a more detailed level.
>  

We do have that.  Vignettes can be linked to help, and they can be
arbitrarily complex, including examples with graphs, etc.

Duncan Murdoch

>
>
> Patrick Burns
> [hidden email]
> +44 (0)20 8525 0696
> http://www.burns-stat.com
> (home of "The R Inferno" and "A Guide for the Unwilling S User")
>
>
> spencerg wrote:
>  
>> There are many arguments in many functions that are rarely used.  I
>> prefer to see it all documented in the help pages.  If they are not
>> documented in the help pages (and sometimes even if they are), a user
>> who wants them can invent other ways to get similar information with
>> much greater effort, and do so for years only to eventually find a much
>> easier way buried in the documentation.  Example:  I was frustrated for
>> years that "nls" would refuse to produce output if it did not converge.  
>> I often used "optim" instead of "nls" for that reason.  However, the
>> list returned by "optim" does not have the nice methods that one can use
>> with an "nls" object.  Eventually, I found the "warnOnly" option
>> documented under "nls.control", which has made "nls" easier for me to use.
>> Spencer Graves
>>
>>
>> William Dunlap wrote:
>>    
>>> There are several help files in the R sources that
>>> describe concepts and not particular R objects.
>>> E.g., help(Methods), help(Syntax), and help(regex).
>>> They don't have a docType  entry and their alias
>>> entries do not refer to functions.  Perhaps your
>>> debugging documentation could go into a similar
>>> *.Rd file.
>>>
>>> Does check balk at such help files in a package? Should it?
>>> Should there be a special docType for such help files?
>>>
>>> Bill Dunlap
>>> Spotfire, TIBCO Software
>>> wdunlap tibco.com
>>>  
>>>      
>>>> -----Original Message-----
>>>> From: [hidden email]
>>>> [mailto:[hidden email]] On Behalf Of Charles Geyer
>>>> Sent: Monday, October 05, 2009 10:51 AM
>>>> To: [hidden email]
>>>> Subject: [Rd] how to document stuff most users don't want to see
>>>>
>>>> The functions metrop and temper in the mcmc package have a debug = FALSE
>>>> argument that when TRUE adds a lot of debugging information to the
>>>> returned
>>>> list.  This is absolutely necessary to test the functions, because one
>>>> generally knows nothing about the simulated distribution except what
>>>> what
>>>> one learns from MCMC samples.  Hence you must expose all details of the
>>>> simulation to have any hope of checking that it is doing what it is
>>>> supposed
>>>> to do.  However, this information is of interested mostly (perhaps
>>>> solely)
>>>> to developers.  So I didn't document it in the Rd files for these
>>>> functions.
>>>>
>>>> But it has ocurred to me that people might be interested in how these
>>>> functions
>>>> are validated, and I would like to document the debug output
>>>> somewhere, but I
>>>> don't want to clutter up the documentation that ordinary users see.  
>>>> That
>>>> suggests a separate help page for debugging.  Looking at "Writing R
>>>> Extensions"
>>>> it doesn't seem like there is a type of Rd file for this purpose.  I
>>>> suppose
>>>> it could be added in (fairly long) sections titled "Debug Output" in
>>>> metrop.Rd
>>>> and temper.Rd or it could be put in a package help page (although
>>>> that's not
>>>> what that kind of page is really for).  Any other possibilities to
>>>> consider?
>>>> --
>>>> Charles Geyer
>>>> Professor, School of Statistics
>>>> University of Minnesota
>>>> [hidden email]
>>>>
>>>> ______________________________________________
>>>> [hidden email] mailing list
>>>> https://stat.ethz.ch/mailman/listinfo/r-devel
>>>>
>>>>    
>>>>        
>>> ______________________________________________
>>> [hidden email] mailing list
>>> https://stat.ethz.ch/mailman/listinfo/r-devel
>>>
>>>  
>>>      
>>    
>
> ______________________________________________
> [hidden email] mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel
>

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: how to document stuff most users don't want to see

William Dunlap
In reply to this post by Patrick Burns
> -----Original Message-----
> From: Patrick Burns [mailto:[hidden email]]
> Sent: Tuesday, October 06, 2009 12:53 AM
> To: spencerg
> Cc: William Dunlap; [hidden email]; [hidden email]
> Subject: Re: [Rd] how to document stuff most users don't want to see
>
> I think the problem is more subtle
> than Spencer implies.  It is good
> to have as much documentation as
> possible.  However, if a help file
> is long and complex, then people
> get intimidated and don't read it
> at all.
>
> It would be nice to have a feature
> so that help files can be displayed
> with different levels of detail.

Using a link to another help file is an established
way of doing this.  Help file writers know how to put
in links and readers know how use them. Charlie's
question was how to describe the debugging output
that few people would want to know about.  I don't
think he wanted to write a narrative vignette that
told how to use the debug output to solve problems
but he wanted to make the format of the output
available.  Why not have help(myFunction) say
   debug: a logical scalar saying whether to enable [debugging
      output] or not
just as help(grep) says
   pattern: character string containing a [regular expression]
       (or character string for fixed = TRUE) to be matched
or help(title) says
    quite a bit of mathematical notation is available such as
    sub- and superscripts, greek letters, fractions, etc:
    see [plotmath]  
?  (The [] indicates a link to another Rd file that gives more
detail about the matter.)

Bill Dunlap
Spotfire, TIBCO Software
wdunlap tibco.com  

> A
> sophisticated version of this scheme
> might even assume different levels of
> knowledge of the user so that the least
> detailed level might be longer (but
> easier) than a more detailed level.
>
>
>
> Patrick Burns
> [hidden email]
> +44 (0)20 8525 0696
> http://www.burns-stat.com
> (home of "The R Inferno" and "A Guide for the Unwilling S User")
>
>
> spencerg wrote:
> > There are many arguments in many functions that are rarely used.  I
> > prefer to see it all documented in the help pages.  If they are not
> > documented in the help pages (and sometimes even if they
> are), a user
> > who wants them can invent other ways to get similar
> information with
> > much greater effort, and do so for years only to eventually
> find a much
> > easier way buried in the documentation.  Example:  I was
> frustrated for
> > years that "nls" would refuse to produce output if it did
> not converge.  
> > I often used "optim" instead of "nls" for that reason.  
> However, the
> > list returned by "optim" does not have the nice methods
> that one can use
> > with an "nls" object.  Eventually, I found the "warnOnly" option
> > documented under "nls.control", which has made "nls" easier
> for me to use.
> > Spencer Graves
> >
> >
> > William Dunlap wrote:
> >> There are several help files in the R sources that
> >> describe concepts and not particular R objects.
> >> E.g., help(Methods), help(Syntax), and help(regex).
> >> They don't have a docType  entry and their alias
> >> entries do not refer to functions.  Perhaps your
> >> debugging documentation could go into a similar
> >> *.Rd file.
> >>
> >> Does check balk at such help files in a package? Should it?
> >> Should there be a special docType for such help files?
> >>
> >> Bill Dunlap
> >> Spotfire, TIBCO Software
> >> wdunlap tibco.com
> >>  
> >>> -----Original Message-----
> >>> From: [hidden email]
> >>> [mailto:[hidden email]] On Behalf Of Charles Geyer
> >>> Sent: Monday, October 05, 2009 10:51 AM
> >>> To: [hidden email]
> >>> Subject: [Rd] how to document stuff most users don't want to see
> >>>
> >>> The functions metrop and temper in the mcmc package have
> a debug = FALSE
> >>> argument that when TRUE adds a lot of debugging
> information to the
> >>> returned
> >>> list.  This is absolutely necessary to test the
> functions, because one
> >>> generally knows nothing about the simulated distribution
> except what
> >>> what
> >>> one learns from MCMC samples.  Hence you must expose all
> details of the
> >>> simulation to have any hope of checking that it is doing
> what it is
> >>> supposed
> >>> to do.  However, this information is of interested mostly
> (perhaps
> >>> solely)
> >>> to developers.  So I didn't document it in the Rd files for these
> >>> functions.
> >>>
> >>> But it has ocurred to me that people might be interested
> in how these
> >>> functions
> >>> are validated, and I would like to document the debug output
> >>> somewhere, but I
> >>> don't want to clutter up the documentation that ordinary
> users see.  
> >>> That
> >>> suggests a separate help page for debugging.  Looking at
> "Writing R
> >>> Extensions"
> >>> it doesn't seem like there is a type of Rd file for this
> purpose.  I
> >>> suppose
> >>> it could be added in (fairly long) sections titled "Debug
> Output" in
> >>> metrop.Rd
> >>> and temper.Rd or it could be put in a package help page (although
> >>> that's not
> >>> what that kind of page is really for).  Any other
> possibilities to
> >>> consider?
> >>> --
> >>> Charles Geyer
> >>> Professor, School of Statistics
> >>> University of Minnesota
> >>> [hidden email]
> >>>
> >>> ______________________________________________
> >>> [hidden email] mailing list
> >>> https://stat.ethz.ch/mailman/listinfo/r-devel
> >>>
> >>>    
> >>
> >> ______________________________________________
> >> [hidden email] mailing list
> >> https://stat.ethz.ch/mailman/listinfo/r-devel
> >>
> >>  
> >
> >
>

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: how to document stuff most users don't want to see

baptiste auguie-5
If help was only displayed in the form of html pages, one could
perhaps mimic the javascript trick sometimes found in wikipedia, e.g.
"http://en.wikipedia.org/wiki/Mathematical_induction#Example" (see the
"show/hide" toggle at the bottom).

I don't see how this could work with plain text or pdf output.

Regards,

baptiste

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: how to document stuff most users don't want to see

Charles Geyer
In reply to this post by Duncan Murdoch
On Mon, Oct 05, 2009 at 02:03:51PM -0400, Duncan Murdoch wrote:

> On 10/5/2009 1:50 PM, Charles Geyer wrote:
> >The functions metrop and temper in the mcmc package have a debug = FALSE
> >argument that when TRUE adds a lot of debugging information to the returned
> >list.  This is absolutely necessary to test the functions, because one
> >generally knows nothing about the simulated distribution except what what
> >one learns from MCMC samples.  Hence you must expose all details of the
> >simulation to have any hope of checking that it is doing what it is
> >supposed
> >to do.  However, this information is of interested mostly (perhaps solely)
> >to developers.  So I didn't document it in the Rd files for these
> >functions.
> >
> >But it has ocurred to me that people might be interested in how these
> >functions
> >are validated, and I would like to document the debug output somewhere,
> >but I
> >don't want to clutter up the documentation that ordinary users see.  That
> >suggests a separate help page for debugging.  Looking at "Writing R
> >Extensions"
> >it doesn't seem like there is a type of Rd file for this purpose.  I
> >suppose
> >it could be added in (fairly long) sections titled "Debug Output" in
> >metrop.Rd
> >and temper.Rd or it could be put in a package help page (although that's
> >not
> >what that kind of page is really for).  Any other possibilities to
> >consider?
>
> I think writing it up in a vignette would probably be most appropriate.
>  You can link directly to a vignette from a man page (though not,
> unfortunately, vice versa).  For example, if you look at
> package?grid, you'll see a list that was generated by this code:
>
> Further information is available in the following
> \link{vignettes}:
> \tabular{ll}{
> \code{grid} \tab Introduction to \code{grid} (\url{../doc/grid.pdf})\cr
> \code{displaylist} \tab Display Lists in \code{grid}
> (\url{../doc/displaylist.pdf})\cr

So I decided to follow your advice mcmc_0.7-3.tar.gz just uploaded to CRAN
has such a vignette and such links in the appropriate Rd files.

Thanks

--
Charles Geyer
Professor, School of Statistics
University of Minnesota
[hidden email]

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel