# [Rd] Two documentation questions

Prof Brian Ripley ripley at stats.ox.ac.uk
Thu Mar 5 12:30:28 CET 2009

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

> 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