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
______________________________________________
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
