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

[Gabor Grothendieck]

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

'?' or 'help' documents topics, as I under it, not necessarily functions.  For
example,

?iris
?Startup

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
>   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
> >>
> >> ______________________________________________
> >> 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
> https://stat.ethz.ch/mailman/listinfo/r-devel
>