[Rd] how to document stuff most users don't want to see

[William Dunlap]

> -----Original Message-----
> From: Patrick Burns [mailto:pburns at pburns.seanet.com] 
> Sent: Tuesday, October 06, 2009 12:53 AM
> To: spencerg
> Cc: William Dunlap; charlie at stat.umn.edu; r-devel at r-project.org
> 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
> patrick at burns-stat.com
> +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: r-devel-bounces at r-project.org 
> >>> [mailto:r-devel-bounces at r-project.org] On Behalf Of Charles Geyer
> >>> Sent: Monday, October 05, 2009 10:51 AM
> >>> To: r-devel at r-project.org
> >>> 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
> >>> charlie at stat.umn.edu
> >>>
> >>> ______________________________________________
> >>> R-devel at r-project.org mailing list
> >>> https://stat.ethz.ch/mailman/listinfo/r-devel
> >>>
> >>>     
> >>
> >> ______________________________________________
> >> R-devel at r-project.org mailing list
> >> https://stat.ethz.ch/mailman/listinfo/r-devel
> >>
> >>   
> > 
> > 
>