[Rd] Checking your package's help files

[Prof Brian Ripley]

It seems that many package authors do not proofread the help installed 
with their packages.  The Rd converter is not a parser, and it will 
silently produce incorrect results on incorrect input (and some correct 
input).

Here are a few hints about some common errors:

1) When you run R CMD check you get a PDF manual at 
<pkg>.Rcheck/<pkg>-manual.pdf.  Read through it looking for missing/empty 
and mis-formatted entries.


2) Try installing the package under a current R-devel (as of today). 
This will report on errors of the form

\item{foo} {item text}

with, NB, invalid space between the two arguments.   Earlier versions of 
R assume that the item had no text and so '{item text}' is never 
processed (not even checked for validity).  This results in at best 
missing information and at worse nonsense.


3) Grep the installed help for internal constructs, e.g.

grep nornal-bracket <installed-package>/help/*

Three ways I have found such constructs to appear in the processed files:

a) If you see 'eqnnormal-bracket' then you have a one-argument \eqn (or 
possibly \deqn) command immediately followed by }.  This is correct Rd but 
mis-processed in earlier versions of R.  In all the cases I have seen it 
comes from grammatically incorrect help files of the form

\item{foo}{... \eqn{x}}

where the item should end in ',' or '.'.  But if you don't want to do 
that, at least use a space before the brace.  I found this in packages
distrMod, flexclust, geepack, geoR, psychometric, robustbase and uroot.

b) Many packages have help files with 'normal-bracket' at the end of a 
processed \value section.  In all the cases I looked at, this results from 
using \itemize{} inside \value -- that does not work as \value is 
implicitly an itemize environment.

c) Using markup in verbatim-like environments will lead to nonsensical 
output: it seems the most common error is to use \code inside \examples. 
What markup is allowed where is not very well defined: Duncan Murdoch has 
started to document this at http://developer.r-project.org/parseRd.pdf but 
that currently is more a description of what should happen, not what has 
been implemented.

These issues are not rare (except 3a): about 10% of CRAN packages have 
them.

-- 
Brian D. Ripley,                  ripley at stats.ox.ac.uk
Professor of Applied Statistics,  http://www.stats.ox.ac.uk/~ripley/
University of Oxford,             Tel:  +44 1865 272861 (self)
1 South Parks Road,                     +44 1865 272866 (PA)
Oxford OX1 3TG, UK                Fax:  +44 1865 272595