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