[Rd] More intensive checking of R help files

[Henrik Bengtsson]

Hi,

this sounds all good.  One comment below:

On Fri, Jan 9, 2009 at 1:25 AM, Prof Brian Ripley <ripley at stats.ox.ac.uk> wrote:
>
> 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.

Then what is the plan for all statements like:

\code{\link[lattice]{panel.xyplot}}

/Henrik

>
> 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
>
> ______________________________________________
> R-devel at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel
>