From murdoch at stats.uwo.ca  Thu Jun  9 21:29:25 2005
From: murdoch at stats.uwo.ca (Duncan Murdoch)
Date: Thu Jun  9 21:29:33 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: <42A89895.6090905@stats.uwo.ca>

>> > 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 Murdoch


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