Warning: missing text for item ... in \describe?

G'day Brian,

On Fri, 5 Dec 2008 15:35:00 +0000 (GMT)

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