Suggestion: help(<package name>)

On 6/7/2005 11:12 AM, Robert Gentleman wrote:

Robin Hankin wrote:

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.

Hi,
  Well, I pretty strenuously object. That is just what vignettes are 
for and the last thing I need is more wobbly's from R CMD check.

Function documentation should document functions. If you want to 
document something more substantial then please use the tools already 
provided to do that - and if you don't want to, and you want to make 
use of the tools for function documentation in some other way please 
don't try to impose your version of what should happen on others.

The current .Rd files don't just document functions, they also document 
data objects and classes.

But the main point here is that it's not good to have multiple 
disconnected sets of documentation for a package.  Users should be able 
to say the equivalent of "give me help on foo", and get help on foo, 
whether it's a function, a data object, a package, a method, a class, or 
whatever.  It's a bad design to force them to ask for the same sort of 
thing in different ways depending on the type of thing they're asking for.

If we had a way to link vignettes into the help system, then I'd think 
it would be perfectly acceptable for ?package to pop up a vignette for 
the package.  However, right now we have too many different types of 
ways to display help, and not all of them are capable of displaying 
vignettes.

Duncan Murdoch

Best wishes
   Robert

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

-- 
Robin Hankin
Uncertainty Analyst
National Oceanography Centre, Southampton
European Way, Southampton SO14 3ZH, UK
 tel  023-8059-7743