[Rd] Two documentation questions

[Kevin R. Coombes]

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).
>