[Rd] Two documentation questions

[Prof Brian Ripley]

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