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

[Berwin A Turlach]

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:

[...]
* 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.

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

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