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

[Robin Hankin]

My 0.02:

I use Misc.Rd for the purpose that Duncan suggests.  I put things like 
details and rationale for package
organization, pointers to the most important function(s) in the 
package,  and perhaps function descriptors
for ubiquitous functions that don't warrant their own helppage, but 
need documentation [in
the case of gsl, this would be strictify() and process.args(), which 
every user needs to know].

It would be *great* to be required to put in "package.gsl.R"  (or 
should that be "gsl.package.Rd"?)
for this purpose.  Then maybe R CMD check could check for its presence 
and throw a wobbly
if it isn't there.

Some packages have so  much material that it's difficult to know where 
the "meat" of the functionality lies,
and Duncan's suggestion would help greatly in these circumstances.

best wishes

rksh


On Jun 7, 2005, at 01:11 pm, Duncan Murdoch wrote:

> Kurt Hornik wrote:
>>>>>>> Henrik Bengtsson writes:
>>> Hi,
>>> I would like to suggest a standard where all packages provide an Rd 
>>> page with the same name (or aliased) as the name of package so that 
>>> help(<package name>) or ?<package name> is always here. This 
>>> especially of interest to large packages with a large package index. 
>>> This page could explain the package in general and gives some hints 
>>> on how to start - not like extensive vignettes, but just to get 
>>> started, e.g. list the "most important" functions.  This page could 
>>> typically contain information that is in the DESCRIPTION file (which 
>>> contains valuable information hardly every accessed by a general 
>>> user), such as who is the maintainer, how to report bugs and so on.
>
> I think this is a good idea.  One minor problem is that for some 
> packages that topic name is already in use for a function (e.g. boot). 
> For that reason, I'd suggest that there *also* be an alias called 
> "package.<package name>", and the <package name> topic should link to 
> it.
>> How would this be different from the results of
>> 	help(package = <package name>)
>> ?
>
>
> 1.  It would work with ?, like other help topics.
>
> 2.  It would give an overview.  It's possible to do that in 
> DESCRIPTION or INDEX, but you don't get the same style as for other 
> help files (e.g. no links to other topics, at least in Windows).
>
>
>
> We should work out what the topic headings should be and extend 
> package.skeleton() and prompt() to write a bare-bones file that 
> suggests the questions that need to be answered in the file.  The 
> headings I'd suggest are:
>
> \name
> \title
> \alias
> \description (longer than the typical entry in the DESCRIPTION file)
> \details (Should give a short guide to the main functions, should 
> point out the existence of external documentation like vignettes, 
> etc.)
> \author (could also describe maintainer, if different)
> \references
> \seealso (Should give references to related packages)
> \examples
> \keywords
>
> There is some duplication of material from DESCRIPTION, but usually 
> this should be longer and more reader-friendly than that file.
>
> I'd be happy to write the description of this in R Extensions, and 
> write the changes to prompt(), if we have agreement that this file 
> should be mandatory in 2.2.x or 2.3.x, and you'll write the checks for 
> it.  (I think the check should just be for existence of aliases 
> <package name> and package.<package name>, and could perhaps just give 
> a warning in 2.2.x.)
>
> Duncan Murdoch
>
> ______________________________________________
> R-devel at stat.math.ethz.ch mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel
>
>
--
Robin Hankin
Uncertainty Analyst
National Oceanography Centre, Southampton
European Way, Southampton SO14 3ZH, UK
  tel  023-8059-7743