[Rd] More intensive checking of R help files

[Prof Brian Ripley]

On Thu, 15 Jan 2009, Henrik Bengtsson wrote:

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

No plan, no change.  That is valid R code with markup.

And please do note that we gave you a reference to answer such 
questions from!



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

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