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 <[EMAIL PROTECTED]> 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, [EMAIL PROTECTED]
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
______________________________________________
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
