From murdoch at stats.uwo.ca  Wed Jun  8 19:20:49 2005
From: murdoch at stats.uwo.ca (Duncan Murdoch)
Date: Wed Jun  8 19:23:04 2005
Subject: [Rd] Suggestion: help(<package name>)
In-Reply-To: <Pine.LNX.4.51.0506081633120.22022@artemis.imbe.med.uni-erlangen.de>
References: <42A57F5D.7080505@maths.lth.se>	<17061.32946.976628.961120@beren.wu-wien.ac.at>	<42A58EDF.80701@stats.uwo.ca>	<1f269abbabca01e19ee3cdbabc9d14f6@soc.soton.ac.uk>	<42A5B96B.9030701@fhcrc.org>
	<42A5BB9D.3000301@stats.uwo.ca>	<42A5C465.3090505@fhcrc.org>
	<42A5C789.3060101@stats.uwo.ca>	<42A5D279.3010501@fhcrc.org>	<Pine.LNX.4.61.0506071823460.5947@gannet.stats>	<42A6687A.3000804@stats.uwo.ca>	<Pine.LNX.4.51.0506080918210.12890@artemis.imbe.med.uni-erlangen.de>	<42A6DA63.7020301@stats.uwo.ca>
	<Pine.LNX.4.51.0506081633120.22022@artemis.imbe.med.uni-erlangen.de>
Message-ID: <42A728F1.8080503@stats.uwo.ca>

On 6/8/2005 10:36 AM, torsten@hothorn.de wrote:
> 
> 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.

No, that wouldn't work.  We have no reliable way for an HTML file to 
tell R to do anything, and one way to get to this topic should be 
through a URL to the HTML version of the help file.  What I was planning 
was to generate a <pkg>.package.Rd file at install time, with 
information equivalent to the result of library(help = <pkg>).

This will tend to be ugly, because there is no way to know whether the 
user has edited the INDEX file; since it already has ascii formatting 
built in, it won't look like very good HTML.   The part that 
library(help = <pkg>) gets from the DESCRIPTION file could have better 
formatting because that information is available in structured form.
I haven't looked at the vignette information yet.

It would probably be desirable in the long run to change the behaviour 
of library(help = <pkg>) to just call help(), but that loses the return 
result, so I wouldn't suggest doing it right away.

Duncan Murdoch


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