[Rd] 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