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

[Robin Hankin]

The reason I like .Rd files is that I can run the examples easily and, 
as Martin points out,
one does not need to learn a new syntax.

How about adding the following to R-exts:

"We encourage the package developer to include a file named 
foo.package.Rd in the "man"
directory, to provide a terse overview of the foo package.  This Rd 
file is intended to be
the first port of call for a new user of the package, and should 
provide (or point to)
working examples of the package's functionality.  It may also provide 
details or rationale
for the package's structure, if non-standard; and perhaps document 
other features of
the package that might escape a new user's notice.

See package foo for an example"

and package.skeleton() could be modified to  write a skeleton version 
of foo.package.Rd
and put it in the man directory.

best wishes everyone

rksh


Duncan writes:
>
> 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.)
>

Martin:

> And as much as I do like (and read) the vignettes that are
> available, I also do agree that writing one other *.Rd file is
> easier for many new package authors than to write a
> vignette -- the package author already had to learn *.Rd syntax
> anyway -- and it's nice to be able to produce something where
> hyperlinks to the other existing reference material (ie. help
> pages) just works out of the box.
>

Duncan again:

> Currently R has 3 types of help:  the .Rd files in the man directory 
> (which are converted into plain text, HTML, compiled HTML, LaTex, DVI, 
> PDF, etc), the vignettes, and unstructured files in inst/doc.  We 
> currently require .Rd files for every function and data object.  
> Adding a requirement to also document the package that way is not all 
> that much of a burden, and will automatically give all those output 
> formats I listed above.  It will help to solve the often-complained 
> about problem   of packages that contain no overview at all.  
> (Requiring a vignette and giving a way to display it would also do 
> that, but I think requiring a .Rd file is less of a burden, and for 
> anyone who has gone to the trouble of creating a vignette, gives a 
> natural place for a link to it.  Vignettes aren't used as much as they 
> should be,  because they are hidden away where users don't see them.)

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