[Rd] Rd: pdf manual: package information not on first page

[Duncan Murdoch]

On 26/06/2009 7:36 AM, Thorn Thaler wrote:
> Duncan Murdoch schrieb:
>> How did you produce the manual?  When I do R CMD Rd2dvi on a package, I 
>> get the package man page first.  There are other ways to produce the 
>> manual, and in some cases we may not control the sort order.
> 
> Well, I see. There is a misunderstanding regarding the term "package 
> documentation". What I meant (but probably didn't make clear enough ;) 
> by "package documentation" is the output generated from the file 
> "<package-name>-package.Rd", where I put some information about the 
> package itself. The idea was that if you type ?<package-name> you will 
> get a short overview of what the package is about.

Right, I understood that.  The code run when you install a package is 
intended to sort such pages to be first in the output, regardless of 
what you name them.

> When I ran "R CMD check" a pdf manual was created conveniently. Since 
> I'm new to package writing I was not aware that one has the possibility 
> to create another type of (pdf) package documentation via "R CMD 
> Rd2dvi". Rd2dvi puts a package summary on the very first page. The page 
> number on which the output from <package-name>-package.Rd itself appears 
> depends on the file name.

R CMD check runs R CMD Rd2dvi, and on my system (in R-devel, I didn't 
check older versions) it puts the package page first.  It uses a number 
of options that may be different from what you chose, but I don't think 
we have an option to control sort order for the man pages.


> However, the output from Rd2dvi looks much neater, so I'll be happy with 
> this version. Thanks for your input.
> 
> By the way, is it possible to exclude certain "Rd" files from the 
> pdftexing process? The reason why I'd like to do that is, that my 
> <package-name>-package.Rd file is mainly the same as the preamble 
> created by Rd2dvi (basically a list of the functions of the package). It 
> would be convenient to have such a file for the R inline help, but it is 
> unnecessary in the pdf manual. Any ideas? (however, i've to confess that 
> this is really a minor problem ;)

I don't think there's currently a simple way to do that. What I'd 
suggest is that you decide on what your most important form of 
documentation is (PDF vs HTML, etc.), and then optimize your Rd files 
for that form.  For example, there's no need to list all functions in 
the package man page:  they're listed in the contents listing that comes 
first, and since it is produced automatically, it's less likely to go 
out of date than your own manually edited listing.

Duncan Murdoch