It seems that it comes down to two things: 1) a standard Rd topic or
alias <pkg>.package, and 2) enforcing this standard with R CMD check.
Pro's and con's for (1):
Pros:
- Easy to find overview information on a package, that is, you know
*where* to find it.
- Allows a packages to link to another package.
- Shows up in the HTML index page.
- The <pkg>.package.html can be included on the CRAN package overview.
This can then also become the author's "webpage" (kiosk?) for the
package including installation instructions, license, future plans etc.
Searchable on the web (==you can get information before trying to
download/install, which sometimes fails; catch 22.)
Cons:
- Conflicts with other topic of the same name.
- "Just another vignette" (?)
Pro's and con's for (2):
Pros:
- Guarantees that a package can link to another package.
- Standard immediately adopted.
Cons:
- Requires more maintainance.
- Without automatic tools, redundancy is introduced (more maintainance).
My comments:
I think it is hard to argue that a standard similar to (1) is unwanted.
Also, I don't think anyone has objected on this. The objection has been
on (2). So my suggestion is that one writes up a standard on (1) and
*ask* developers to follow it.
If enforcement by R CMD check (2) was implemented too, then I think it
only requires a single \alias{<pkg>.package} in any of the Rd files,
because as far as I understand it at least one is required. This would
not require much work ("almost cheap"). This would guarantee a link at
least to something. A more advanced version is that the <pkg>.package.Rd
file is automatically created by R CMD build if missing ("zero cost").
To follow up on Gabor's suggestion to add more R CMD check granuality
than errors and warnings. Using classes and the "new" exception
handling, one could introduce a warning class called "Suggestion"
(CranSuggestion), which gives suggestions to the user, but not enforce
them (warning are not allowed on CRAN).
To extend this idea further, one could add non-enforced checks if a
package follows certain standardizations or not. I can image such
checks to be plugins to R CMD check or standalone. Other solutions may
also used. For instance, R CMD checkRCC could check a package against
the coding convention RCC (http://www.maths.lth.se/help/R/RCC/).
Supplementary or complementary standards can provide their own checks.
Such tools would be helpful for large projects to conform to the same
standards, but not enforcing them. Packages following certain standards
could then advertize this to help the user and other developers
utilizing their packages and so.
To summarize, I think it is good if you can communicate that you follow
a certain standard, and it is even better if more peoples are using the
same standard. I agree, that enforced standards are painful, if you
disagree with them (or find the unnecessary).
Cheers
Henrik
Robin Hankin wrote:
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
______________________________________________
R-devel@stat.math.ethz.ch mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
