[Rd] why is \alias{anRpackage} not mandatory?

[Duncan Murdoch]

Thomas Petzoldt wrote:
> Dear R developers,
>
> if one uses package.skeleton() to create a new package, then a file 
> anRpackage.Rd with the following entries is prepared:
>
> \name{anRpackage-package}
> \alias{anRpackage-package}
> \alias{anRpackage}
> \docType{package}
>
>
> Packages created this way have a definite entry or overview page, so:
>
> ?anRpackage
>
> gives new users of a certain package a pointer where to start reading.
>
> This is similar for packages which have the same name as their main 
> workhorse function, e.g. zoo or nlme, but there are many packages which 
> don't have an \alias{anRpackage}.
>
> "Writing R Extensions", sec. 2.1.4 says:
>
> "Packages may have an overview man page with an \alias pkgname-package, 
> e.g. `utils-package' for the utils package, when package?pkgname will 
> open that help page. If a topic named pkgname does not exist in another 
> Rd file, it is helpful to use this as an additional \alias."
>
> My question: what speaks against making this sentence more pronounced 
> and why not NOTE-ing a missing package alias in the package check?
>
>   
Not everybody likes the idea of the overview man page, so when I wrote 
that I left it weak.  Some of the disadvantages:

 - there are lots of packages without one, so this would create a lot of 
work for people to add them.

 - the ones that do exist tend to include outdated information.  People 
update the DESCRIPTION file but forget to update the corresponding 
information in the overview.

 - in general there's a lot of dissatisfaction with the Rd format, so 
there's reluctance to invest any more effort in it.

It would probably be a good idea to generate one automatically if not 
provided by the author, at build or install time:  this would address 
the first point.  I've been slowly working on some fixes that address 
the second point.  (The current idea is to use Sweave-like constructs to 
import things from the DESCRIPTION file at install time.)  There's no 
way to address the third point other than providing a better format, and 
I don't see any prospect of that happening.

Duncan Murdoch