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

[Charles Geyer]

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
charlie at stat.umn.edu