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
