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.)
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)
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. 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.
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.)
Terry Therneau
Two documentation questions
4 messages · Terry Therneau, Gabor Grothendieck, Brian Ripley +1 more
Perhaps you could just place the output in comments. print(5) # 5 head(BOD, 2) # Time demand # 1 1 8.3 # 2 2 10.3
On Wed, Mar 4, 2009 at 8:38 PM, Terry Therneau <therneau at mayo.edu> 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.)
?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)
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. ?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.
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.)
? Terry Therneau
______________________________________________ R-devel at r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
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
Prof Brian Ripley wrote:
On Wed, 4 Mar 2009, Terry Therneau wrote: [SNIP]
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).
I think the key point here is "alphabetical order of the .Rd files". If
you do not choose the names of those files carefully, the PDF file
produced by R CMD check may indeed appear to be random....
-- Kevin
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).