Kurt Hornik wrote:
Henrik Bengtsson writes:
Hi,
I would like to suggest a standard where all packages provide an Rd page
with the same name (or aliased) as the name of package so that
help(<package name>) or ?<package name> is always here. This especially
of interest to large packages with a large package index. This page
could explain the package in general and gives some hints on how to
start - not like extensive vignettes, but just to get started, e.g. list
the "most important" functions. This page could typically contain
information that is in the DESCRIPTION file (which contains valuable
information hardly every accessed by a general user), such as who is the
maintainer, how to report bugs and so on.
I think this is a good idea. One minor problem is that for some
packages that topic name is already in use for a function (e.g. boot).
For that reason, I'd suggest that there *also* be an alias called
"package.<package name>", and the <package name> topic should link to it.
How would this be different from the results of
help(package = <package name>)
?
1. It would work with ?, like other help topics.
2. It would give an overview. It's possible to do that in DESCRIPTION
or INDEX, but you don't get the same style as for other help files (e.g.
no links to other topics, at least in Windows).
We should work out what the topic headings should be and extend
package.skeleton() and prompt() to write a bare-bones file that suggests
the questions that need to be answered in the file. The headings I'd
suggest are:
\name
\title
\alias
\description (longer than the typical entry in the DESCRIPTION file)
\details (Should give a short guide to the main functions, should point
out the existence of external documentation like vignettes, etc.)
\author (could also describe maintainer, if different)
\references
\seealso (Should give references to related packages)
\examples
\keywords
There is some duplication of material from DESCRIPTION, but usually this
should be longer and more reader-friendly than that file.
I'd be happy to write the description of this in R Extensions, and write
the changes to prompt(), if we have agreement that this file should be
mandatory in 2.2.x or 2.3.x, and you'll write the checks for it. (I
think the check should just be for existence of aliases <package name>
and package.<package name>, and could perhaps just give a warning in
2.2.x.)
Duncan Murdoch
______________________________________________
R-devel@stat.math.ethz.ch mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
