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

[torsten at hothorn.de]

On Wed, 8 Jun 2005, Duncan Murdoch wrote:

> Torsten Hothorn 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'.
>
> I do occasionally, but usually it's a waste of time.  This proposal is
> intended to address that.
>
> > 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.
>
> As I pointed out, this is okay for people who know R already, but not so
> good for beginners.  The answer to the question "how do I get help on
> foo?" is too complex.
>
> > 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.
>
> What do you think of Henrik's suggestion to generate a help topic giving
> information equivalent to library(help=<pkg>)?  I think this would
> happen at install time (not build time as he said; no need to put this
> in the source tarballs).  If the <pkg>.package alias wasn't defined, the
> installer would automatically create one.
>
> If we had this in place, I'd strengthen the advice in R-Exts not to
> bother with a manually created INDEX file:  that information should go
> into a manually created <pkg>.package topic instead.

yes, this sounds reasonable - as long as ?<pkg>.package is a "link" to

library(help = <pkg>)

(or help(package = <pkg> as I learned only recently) when no
<pkg>.package.Rd file exists in <pkg>, this would be fine, of course.

Best,

Torsten

>
> Duncan Murdoch
>