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

[Gabor Grothendieck]

On 6/10/05, Duncan Murdoch <murdoch at stats.uwo.ca> wrote:
> Kurt Hornik wrote:
> >>>>>>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.
> >
> >
> > Duncan,
> >
> > I am not sure why you went ahead on this.
> 
> It seemed to me that most of the discussion focussed on one point
> (forcing extra work on people); this seems to be the only way to get
> discussion on any other aspect of the proposal.
> 
>  > 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.
> 
> The reason I went ahead was that I think this implementation is an
> improvement on INDEX files, though it is backwards compatible.  In
> several of the overviews I wrote I refer to the automatically generated
> INDEX file.  In cases where the INDEX was manually edited I recommend
> putting the content into the overview topic instead (but do not force
> this). I did it for the boot package (and I'll send the work to Brian if
> he's interested in incorporating it, since boot isn't a base package,
> and he's the maintainer); it wasn't that hard, but I think it was an
> improvement, in that the function names can be links to the function man
> pages, not just names to be copied and pasted.
> 
> In at least one case (the stats4 package) I think the INDEX file is
> almost completely useless, so I wrote the overview completely from
> scratch.  I'm not sure I got it right, comments or corrections to the
> content would of course be welcome too.
> 
> However, I'd really like to hear a clear explanation of why you think
> the current system is superior.  So far all that I've heard are messages
> like "this forces too much work on package writers", "we did this three
> years ago, why do it again?"  I've explained why I think this solution
> is better, and I've modified it to allow it to be anywhere from "zero
> cost" (ignore it) to "very low cost" (use the automatically generated
> overview), on up as far as a package writer wants to take it.
> 
> > 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.
> 
> The problem with that style is that it doesn't parse to a name, so it
> needs quotes to work with the help system.  For example,
> 
>  ?boot-PACKAGE

It would be invoked like this:

   package?boot

with the effect of giving help on boot-package.

By the way, note that this already works in R since foo?bar works generally
to give help on bar-foo thus the main issue is just whether packages actually
make use of it, whether R CMD CHECK regards it as mandatory or not and 
support tools such as promptPackage and links.  

The best situation would be that if one did:

   ?mypkg

that it would find all occurrences of

   whatever?mypkg

for each whatever and let the user pick the one desired.

By the way, its sometimes hard to know all the places to look for information
on a package.    It would be nice if library(help = mypkg) gave as comprehensive
a list as possible of the sources of information:

- the description file
- list the vignette(s)
- list the demo(s)
- have a set of files that it looks for: README, NEWS, ChangeLog, 
  WISHLIST, THANKS, CITATION and gives pointers to any that exist
- package?mypkg  (or whatever is decided on here)
- the CRAN task views it belongs to
- the bundle it belongs to
- whether it fully passed, passed with warnings or failed R CMD CHECK

Also it would be nice if one could get this information from the net all in
one place without installing the package since one often wants to investigate 
first.  Some, but not all, of this information is available at, e.g.

http://cran.r-project.org/src/contrib/Descriptions/boot.html