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

From: Henrik Bengtsson <hb_at_maths.lth.se>
Date: Tue 07 Jun 2005 - 11:56:07 GMT

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
> -------------------------------------
>
>



R-devel@stat.math.ethz.ch mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel Received on Tue Jun 07 21:58:03 2005

This archive was generated by hypermail 2.1.8 : Mon 24 Oct 2005 - 22:26:58 GMT