More intensive checking of R help files

We have been working on handling Rd (R help) files with R rather than Perl
scripts.  As part of that work, Duncan has written a parser which has
revealed many problems in package help files, and we have added its checks
to 'R CMD check' in the R-devel version of R.

You can see the results for CRAN packages as part of the daily check at
http://cran.r-project.org/web/checks/check_summary.html: they will show up
as 'WARN' in the first two columns: click on the link to see the details for
the package you are interested in.

The dialect of Rd markup for which the parser checks differs in some ways
from that described previously: see
http://developer.r-project.org/parseRd.pdf for a current description:
however almost all the errors found are errors under the existing
description in 'Writing R Extensions'.

The main difference is that \code is in the new version intended for valid R
code and not fragments of R code or other languages (such as SQL).  This
means that quotes (' " `) must balance inside \code, and that can lead to
run-on errors (so if a parse error is found, quoted strings extending over
more than one line are reported). \samp and where appropriate \kbd,
\command, \options ... provide possible alternatives.

Another issue is that it was never intended to allow fragments of LaTeX in
Rd files, and these only worked in latex (rather than text or HTML)
conversion. Not all of these are parse errors, but they often lead to
warnings about 'unknown macros'.  Using \eqn{} would resolve almost all of
these and lead to more readable help.

The CRAN master will from now on be mentioning these warnings when handling
submissions.

It would be helpful if package maintainers could look at and fix the errors
as soon as possible.


Brian Ripley and Duncan Murdoch

--
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