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

[Prof Brian Ripley]

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