[Rd] Suggestion: help(<package name>)
ggrothendieck at gmail.com
Tue Jun 7 17:33:49 CEST 2005
On 6/7/05, Robert Gentleman <rgentlem at fhcrc.org> 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.
> 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
'?' or 'help' documents topics, as I under it, not necessarily functions. For
Further, '?' has a type?topic syntax, as well.
Also, what is a wobbly?
> 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.
> Best wishes
> > 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
> > ______________________________________________
> > R-devel at stat.math.ethz.ch mailing list
> > https://stat.ethz.ch/mailman/listinfo/r-devel
> R-devel at stat.math.ethz.ch mailing list
More information about the R-devel