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

[Prof Brian Ripley]

On Sat, 6 Dec 2008, Berwin A Turlach wrote:

> G'day Brian,
>
> On Fri, 5 Dec 2008 15:35:00 +0000 (GMT)
> Prof Brian Ripley <ripley at stats.ox.ac.uk> wrote:
>
>> 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} {...

> [...]
>> 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.
>
> Which platform are we talking here?  I was using linux and "R CMD check
> fda", using R 2.8.0, on the command line said:

That writes to a file, and writes to a file are buffered.  Try R CMD 
INSTALL, where they are not.  We do recommend getting a clean install 
before R CMD check.

> [...]
> * checking for executable files ... OK
> * checking whether package 'fda' can be installed ... WARNING
> Found the following significant warnings:
>  Warning: missing text for item 'fd' in \describe
>  Warning: missing text for item 'fd' in \describe
>  Warning: missing text for item 'fdPar' in \describe
> See '/home/berwin/lang/R/Develop/Others/fda.Rcheck/00install.out' for
> details.
> * checking package directory ... OK
> [...]
>
> And 00install.out said:
>
> [...]
> Attaching package: 'zoo'
>
>
>        The following object(s) are masked from package:base :
>
>         as.Date.numeric
>
> ** help
> Warning: missing text for item 'fd' in \describe
> Warning: missing text for item 'fd' in \describe
> Warning: missing text for item 'fdPar' in \describe
> >>> Building/Updating help pages for package 'fda'
>     Formats: text html latex example
>  CSTR                              text    html    latex   example
>  CanadianWeather                   text    html    latex   example
> [...]
>
> I am not aware that either stdout or stderr are buffered on my linux
> box.

Wriitng to a file, stdout almost always is.

>
>> 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).
>
> But there is also nothing that explicitly forbid such whitespace, is
> it?  I guess this comes down to the question whether "everything is
> allowed that is not expressively forbidden" or "everything is forbidden
> unless it is expressively allowed".  Strangely enough, though I am
> German, I don't tend to subscribe to the latter philosophy.

It really doesn't matter: the author of the convertor (not me) decidedly 
to silently ignore arguments after whitespace so you get an incorrect 
conversion. I also added sentences to the documentation that say that 
explicitly.  But if I see documentation that says

\item{foo}{bar}

I don't see why anyone would be surprised that

\item {foo} {bar}

goes haywire.

> The language of Rd files, and the notation used, seems to have some
> clear roots in (La)TeX;  and in (La)TeX whitespace between arguments to

More like texinfo.

> macros is ignored.  So one may argue that it is a bit of a surprise
> that whitespace between arguments to \item matter here.
>
>> What we can do is detect the error, and I am about to commit code in
>> R-devel to do so.
>
> Thanks.  I am sure Spencer will be happy about this. :)
>
> Cheers,
>
> 	Berwin
>

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