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

From: Duncan Murdoch <murdoch_at_stats.uwo.ca>
Date: Fri 10 Jun 2005 - 12:17:50 GMT

On 6/10/2005 8:00 AM, Gabor Grothendieck wrote:

> On 6/10/05, Duncan Murdoch <murdoch@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



R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel Received on Fri Jun 10 22:21:38 2005

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