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

[Henrik Bengtsson]

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