[Rd] Warning: missing text for item ... in \describe?

[Prof Brian Ripley]

On Mon, 1 Dec 2008, Berwin A Turlach wrote:

> G'day Spencer,
>
> On Sun, 30 Nov 2008 22:31:54 -0800
> Spencer Graves <spencer.graves at pdf.com> wrote:
>
>> Hello:
>>
>>       What might be the problem generating messages like "Warning:
>> missing text for item ... in \describe" with "R CMD check" and "R CMD
>> install"?
>>
>>       With the current version of "fda" on R-Forge, I get the
>> following:
>>
>>
>> Warning: missing text for item 'fd' in \describe
>> Warning: missing text for item 'fdPar' in \describe
>
> fRegress.Rd, which contains
>
> \item{fd} { ...
> \item{fdPar} {...
>
> Apparently the space between the closing and the opening bracket leads
> to some confusion; remove the space and the warning goes away.
>
> I am not sure why an extra space here leads to problems, would be nicer
> if it would not.  If it have to lead to a problem, then it would be
> nice if the name of the .Rd files that produces the problem is actually
> mentioned. :)

Well, the warning/errors always come out just before the file with the 
problem (unless you have stdout buffered and stderr not).  So finding 
which file does not seem so hard.

This *is* an error: nothing in the description allows whitespace between 
arguments to \item (nor \section).  It seems that only a few people 
misread the documentation (sometimes even after their error is pointed out 
to them).  What we can do is detect the error, and I am about to commit 
code in R-devel to do so.

Note that we don't have a complete description of the Rd language, but 
three partial parsers (Rdconv, tools::Rdparse and from R-devel, parseRd). 
If Duncan M's work on parseRd comes to fruition we may have a grammar and 
a parser, but it is likely to be for 'Rd2' format since no one wants to 
enshrine all the quirks of the current format.

> Don't ask me how I found this, let us just say that long live
> find-grep-dired in emacs and perseverance (or should that be
> stubbornness?)
>
> HTH.
>
> Cheers,
>
> 	Berwin
>
> =========================== Full address =============================
> Berwin A Turlach                            Tel.: +65 6516 4416 (secr)
> Dept of Statistics and Applied Probability        +65 6516 6650 (self)
> Faculty of Science                          FAX : +65 6872 3919
> National University of Singapore
> 6 Science Drive 2, Blk S16, Level 7          e-mail: statba at nus.edu.sg
> Singapore 117546                    http://www.stat.nus.edu.sg/~statba
>
> ______________________________________________
> 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