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

[Duncan Murdoch]

On 6/10/2005 8:00 AM, Gabor Grothendieck wrote:
> 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.

Okay, I get it.  That's a good change.  I'll put it in unless I hear 
objections very soon.  (I'm going to be away from tomorrow through 
Thursday, so I might appear to be ignoring objections if I don't see 
them in time.)
> 
> 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.

Or even find multiple occurences of the same alias with the same 
whatever; I agree, but that's a bigger change to the help system than I 
feel like making now.

> 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

I think that's a good suggestion, but I'll leave its implementation to 
someone else.

Duncan Murdoch