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

From: A.J. Rossini <blindglobe_at_gmail.com>
Date: Wed 08 Jun 2005 - 07:59:24 GMT

On 6/8/05, Torsten Hothorn <Torsten.Hothorn@rzmail.uni-erlangen.de> wrote:
>
> 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.)
> >
>
> as a package author who already provides help pages for general package
> descriptions (`?multcomp' and `?coin' work and, if I remember correctly,
> Martin suggested to include the advertisement this way) I must
> admit that I never say `?foo' when I'm interested in a global overview
> about a new package `foo'.
>
> Instead, `library(help = foo)' gives what I want to see, namely the title
> and description of a package and all documented topics. One may argue that
> asking `library' for help is not the most obvious thing to do. But people
> able to recall that fitting an ANOVA model requires `aov' and comparing
> two models needs `anova' should be able to have `library' in mind for
> general package information.
>
> So, for me having infrastructure for _automatically_ generated overviews
> is very nice, but _forcing_ package authors to provide additional
> meta-information would be less welcome.

I'm in the Robert/Brian school of thought -- this can be solved with better DESCRIPTIONS, or by explicitly writing such a file (which one can already do), or through better advertisement / incorporation of the vignette tools.

Requiring anything additional is a PITA. Sure, it doesn't look like much time, but it is. "much" is in the eye of the beholder.

Perhaps one thing to do is to map

   ?<pkgname>.package
to

   library(help=pkgname)
as was previously suggested, and let authors put information in the DESCRIPTION, perhaps with a lead towards the right help file to use to get more.

best,
-tony

"Commit early,commit often, and commit in a repository from which we can easily roll-back your mistakes" (AJR, 4Jan05).

A.J. Rossini
blindglobe@gmail.com



R-devel@stat.math.ethz.ch mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel Received on Wed Jun 08 18:07:18 2005

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