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?
Thomas Petzoldt
--
Thomas Petzoldt
Technische Universitaet Dresden
Institut fuer Hydrobiologie
01062 Dresden
GERMANY
http://tu-dresden.de/Members/thomas.petzoldt
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
Dear R Developers,
first of all, many thanks for the constructive discussion. My question
was related to the use of existing mechanisms that (in my opinion) would
help to make package documentation more user-friendly. I agree that
additional restrictions/requirements on packages that do not not have
explicit objectives on performance or validity have to be avoided.
Thomas Petzoldt
--------------------------------------------------------------------
Summary and Wish-list
1 A recommendation to provide a file "foo-package.Rd" and an
\alias{foo} was already given in "Writing R Extensions".
2 In order to ensure consistency between foo-package.Rd, DESCRIPTION and
other sources of information, a mechanism to use variables and/or macros
in .Rd format is desirable.
3 There may be reasons, where manual creation and maintenance of
foo-package.Rd is not wanted, i.e. work load or danger of information
inconsistency. For such cases, an automated mechanism during package
installation may be helpful.
Already existing functions like
library(help="foo")
or
promptPackage("foo", final=TRUE)
can do the job but may require extensions (hyperlinks).
4 The standard help format on Windows .chm should also find a way to
provide hyperlinks to package vignettes (and other pdfs), either
directly in the package index (as in html) or in foo-package.Rd