From Torsten.Hothorn at rzmail.uni-erlangen.de  Wed Jun  8 09:37:02 2005
From: Torsten.Hothorn at rzmail.uni-erlangen.de (Torsten Hothorn)
Date: Wed Jun  8 09:41:14 2005
Subject: [Rd] Suggestion: help(<package name>)
In-Reply-To: <42A6687A.3000804@stats.uwo.ca>
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>
Message-ID: <Pine.LNX.4.51.0506080918210.12890@artemis.imbe.med.uni-erlangen.de>


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'.

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.

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.

Best,

Torsten


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