Warning: missing text for item ... in \describe?
1) Having run tests on CRAN and BioC overnight, the results are quite
depressing. There are 112 packages on CRAN and a score on BioC with
incorrectly rendered help pages because of spaces after \item{foo}. In
two cases (fields and MANOR) the text skipped is invalid, so it is not
simply a case of ignoring the whitespace.
2) On the original subject line, I found a different reason. E.g. I get
the message on distrMod, which has (sqrt-methods.Rd, also
solve-methods.Rd)
\section{Methods}{\describe{
\item{sqrt}{\code{signature(x = "PosSemDefSymmMatrix")}: produces a
symmetric, p.s.d. matrix \eqn{y} such that \eqn{x = y^2}}
}}
That is rendered incorrectly, and the issue is that \eqn is a one- or
two-argument macro and the trailing } confuses the Rdconv code. That is
an Rdconv bug which is proving very tricky to fix. In any case a fix will
only apply to future versions of R, so the packages affected (at least
distr, geepack, geoR, psychometric, robustbase, uroot) need to be altered.
Note that grammatical help files will almost always have punctation at the
end of an item (even a space will do), and all the examples appropriate
punctuation is missing.
On Sat, 6 Dec 2008, Berwin A Turlach wrote:
G'day Brian, On Fri, 5 Dec 2008 17:32:58 +0000 (GMT) Prof Brian Ripley <ripley at stats.ox.ac.uk> wrote: [...]
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.
Indeed, forgot about that. Thanks for reminding me. With R CMD INSTALL the messages are right next to the help files with the problems.
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.
Well, I was. :) And I guess anybody who knows that the TeX parser does not care about whitespaces between arguments to macros but forgets that .Rd files are not directly parsed by the TeX parser would have been surprised too. Use of whitespace and indentation is pretty much a matter of taste and personal style to improve readability; and while there are languages where they matter (Python, makefiles, &c), and some projects (including R) have style-guides, usually a developer is left with a lot of flexibility to suit her or his style. But I guess only Spencer knows why a whitespace at this place was desirable and/or improved readability. 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