[Rd] More intensive checking of R help files

[Prof Brian Ripley]

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