From ripley at stats.ox.ac.uk  Thu Dec 11 16:54:11 2008
From: ripley at stats.ox.ac.uk (Prof Brian Ripley)
Date: Thu, 11 Dec 2008 15:54:11 +0000 (GMT)
Subject: [Rd] Checking your package's help files
In-Reply-To: <alpine.LFD.2.00.0812071023060.26715@gannet.stats.ox.ac.uk>
References: <alpine.LFD.2.00.0812071023060.26715@gannet.stats.ox.ac.uk>
Message-ID: <alpine.LFD.2.00.0812111552070.3218@gannet.stats.ox.ac.uk>

The check summaries now available at

http://cran.r-project.org/web/checks/check_summary.html

will indicate most of the problems being detected in CRAN packages: look 
at the log (click on the link) for your package in the first or second 
column.

On Sun, 7 Dec 2008, Prof Brian Ripley wrote:

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

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



[Rd] Checking your package's help files
Prof Brian Ripley