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

[Henrik Bengtsson]

Wolfgang Huber wrote:
>>>>>>> Henrik Bengtsson writes:
>>>
>>> I would like to suggest a standard where all packages provide an Rd 
>>> page with the same name (or aliased) as the name of package so that 
>>> help(<package name>) or ?<package name> is always here. This 
>>> especially of interest to large packages with a large package index. 
>>> This page could explain the package in general and gives some hints 
>>> on how to start - not like extensive vignettes, but just to get 
>>> started, e.g. list the "most important" functions.  
> 
> 
> But isn't that just what vignettes are there for?
> 
> And I think nobody has said that vignettes should be "extensive", and if 
> they end up being so, that is a problem of the package author, and 
> probably would end up being the same with yet another form of 
> documentation.


Yes, and you could call what I am suggestion a special type of 
"vignette".  But, I was more thinking of a very very short description 
page which is extremely easy to access and easy to write (I shouldn't 
have said "not like extensive vignettes" then, but rather "like 
extremely short vignettes").  Writing vignettes are easy, but apparently 
still not easy enough because not all packages have a vignette.  Also, 
it is hard to compete with the command ?<pkgname> when it comes to 
access and response time, especially if the vignette is a PDF file but 
even if it is a HTML page.  Also, an Rd file will be included in both 
the HTML help and the LaTeX manual.

If there would be a "standardized" main document page, which I think 
?<pkgname> is, but which could also apply vignette(<pkgname>), a new 
user would immediately know where to get the necessary information if 
running into problems or just want to try out a new package, e.g. 
install.packages("R.oo"), then library(R.oo) and ?R.oo (much on the 
shown page is automatically generated from DESCRIPTION files etc, but I 
did not want to suggest that because that requires much more).

Cheers

Henrik

> Best regards
>   Wolfgang
> 
> -------------------------------------
> Wolfgang Huber
> European Bioinformatics Institute
> European Molecular Biology Laboratory
> Cambridge CB10 1SD
> England
> Phone: +44 1223 494642
> Fax:   +44 1223 494486
> Http:  www.ebi.ac.uk/huber
> -------------------------------------
> 
>