Re: [Rd] Suggestion: help(<package name>)

From: Kurt Hornik <>
Date: Fri 10 Jun 2005 - 05:20:46 GMT

>>>>> Duncan Murdoch writes:

>>> > On Tue, 7 Jun 2005, Duncan Murdoch wrote:
>>> >
>>> > [...]
>>> >
>>> >
>>> >>My proposal (modified following the suggestions I've heard so far) is as
>>> >>follows:
>>> >>
>>> >>  - to check that a couple of help topic aliases exist (<pkg>.package
>>> >>and <pkg>)
>>> >>  - to recommend that <pkg>.package contain general information about
>>> >>the package, and that <pkg> be an alias for it, if it isn't used for
>>> >>some other purpose.
>>> >>  - to write promptPackage() to help create an initial version of
>>> >><pkg>.package.Rd.  It can get some information from the DESCRIPTION
>>> >>file; perhaps it could go looking for a vignette, or the INDEX, or
>>> >>  - to modify the other help system tools to make use of this (e.g. the
>>> >>package:<pkg> heading on a page would become a link to the <pkg>.package
>>> >>alias, etc.)

> I've now committed some of this to R-devel, and I invite comments. I've
> abandoned the idea of the check, which seems too controversial. I've
> done the second and third items, but not the 4th.

> I wrote about a dozen of these files this afternoon as I was refining
> promptPackage. It is very quick to generate a basic man page using
> promptPackage with an option saying you want a final version. Manually
> editing this file, running it through checks, etc. took me around 10-20
> minutes per package.

> I only did the base packages, and they probably have less in their
> overview than most contributors would want, so someone starting from
> nothing would probably take longer --- but many packages already have
> the text written somewhere, and they just need to add an alias to an Rd
> file, or perhaps reformat an INDEX file.


I am not sure why you went ahead on this. My understanding was that there was considerable opposition to introducing a convention for package documentation intermediate between providing package meta data in the DESCRIPTION file and providing vignettes, given in particular that we already have such an additional mechanism (INDEX files) for historic reasons.

I also object particularly to the naming convention. Rd documentation objects are identified by their NAME (as indicated in their \name meta data), not the name of the file used for their serialization into Rd format. IF we want to have such a mechanism, then at least let it work on a topic-style alias of the form PACKAGE-package, which would be consistent with what we do for S4 classes and methods.

-k mailing list Received on Fri Jun 10 15:24:27 2005

This archive was generated by hypermail 2.1.8 : Mon 20 Feb 2006 - 03:21:08 GMT