On Wed, 4 Mar 2009, Terry Therneau wrote:
> 1. I often like to put bits of the output into the manual pages. (We can
> have a discussion of the value of this elsewhere -- I think it is sometimes
> a good thing.)
I presume you mean in the \examples section of the .Rd files, not
elsewhere in the help.
> In R I need to surround these with \dontrun{} for the sake of the tester,
> which is fine. But the printed output contains
> ## Not run
> and
> ## End (not run)
'printed output'? We have conversion to text, HTML, latex and .R, and
they are all done separately. I guess you are only concerned with
conversion to latex?
> comments, which defeats the purpose of the lines by breaking them off from
> the their context. How do I turn these off? For printing \dontrun should
> be a no-op.
I'm not sure why it 'should'. Conversion to latex is not just for
printing, nor is \dontrun primarily for output. Indeed, at one point
a couple of months ago the parseRd function required what was in
\dontrun to be valid R code.
I certainly find having the \dontrun material in the package PDF
manual helpful on occasion.
> Or at least I should have the option of making it so -- I'm rather
> opinionated about the format of things I prepare for teaching purposes.
> You can assume medium Tex skills in answering; my book is in Latex but I
> don't create my own formats.
If you mean conversion to latex, you could either alter Rdconv.pm
or post-process the output: this is in a verbatim-like section so it
would not be easy to do so in LaTeX. If I did this often I would be
adding some markup for this purpose, but post-processing in R should
be easy (and tools:::massageExamples (in R-devel) does so).
> 2. In the pdf for the survival package, or at least the one
> generated by R CMD check, the entries are in a random order. Can I
> fix this? It makes reading the document to look for errors rather
> challenging. (That is, when I'm looking at a particular Rd file,
> and want to see what it turned out to be.)
They should not be 'random'. E.g.
http://cran.r-project.org/web/packages/survival/survival.pdf is not:
it is in alphabetical order (C locale), and that is what I see for R
CMD check in 2.8.1 (but in the collation order of the locale; this is
done by Perl so depends on what it thinks is appropriate).
This is one of the things that is changing for R 2.9.0, and hence in
current R-devel. R CMD check will always uses R CMD Rd2dvi, and that
produces PDF manuals in alphabetic order of the Rd files, in the
current locale (I think Rd2dvi was always in C collation in earlier
versions).
R CMD check was more a check of the latex conversion of the files, not
a final manual (it got bundles wrong, for example, omitted the
DESCRIPTIOM and did not check that the index worked). R-devel it does
produce a standard package manual, and the collation is by R.
Collation is a messy area with lots of OS-dependent errors. That's
why in R-devel we have moved almost all this to R code, where we can
control it (and can replace the OS's collation services by ICU if
available). And relevant to you is
> sort(c("Surv", "surv", "survdiff"))
[1] "surv" "Surv" "survdiff"
which is what ICU thinks is right in English (and for one set of
English rules, it is -- further it allows you to tune them).
--
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