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

[Duncan Murdoch]

Henrik Bengtsson wrote:
> 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").

I really like this "zero cost" option.  I think it addresses the main 
problem with the proposal (all the work for package writers that it 
creates), while keeping the main benefit (a standard place for package 
help *within the help system*).

It might be tricky to implement (the build tools aren't all in R and 
aren't consistent across platforms), but it seems like a reasonable 
compromise to me.

Duncan Murdoch

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