On Oct 6, 2008, at 8:47 , Duncan Murdoch wrote:
On 06/10/2008 8:06 AM, Thomas Petzoldt wrote:
Duncan Murdoch wrote:
Thomas Petzoldt wrote:
Dear R developers,
if one uses package.skeleton() to create a new package, then a
file anRpackage.Rd with the following entries is prepared:
\name{anRpackage-package}
\alias{anRpackage-package}
\alias{anRpackage}
\docType{package}
Packages created this way have a definite entry or overview page,
so:
?anRpackage
gives new users of a certain package a pointer where to start
reading.
This is similar for packages which have the same name as their
main workhorse function, e.g. zoo or nlme, but there are many
packages which don't have an \alias{anRpackage}.
"Writing R Extensions", sec. 2.1.4 says:
"Packages may have an overview man page with an \alias pkgname-
package, e.g. `utils-package' for the utils package, when package?
pkgname will open that help page. If a topic named pkgname does
not exist in another Rd file, it is helpful to use this as an
additional \alias."
My question: what speaks against making this sentence more
pronounced and why not NOTE-ing a missing package alias in the
package check?
Not everybody likes the idea of the overview man page, so when I
wrote that I left it weak. Some of the disadvantages:
You speak about the disadvantages but there are, of course, obvious
advantages. Almost all scientific papers start with an abstract,
why not requesting one for software packages, at least for new ones?
We already require one in the DESCRIPTION file for all packages,
which you can see with
library(help=packagename)
Yes, but this is way too long to write - could we add a fall-back so
that if ?foo alias doesn't exist but package foo does then ?foo is
equivalent to help(package="foo")? At least for the way I use help it
would help a lot...
Cheers,
S
This is related to my first two points: people have already done
this work so they are reluctant to do it again, and duplicate
information is a bad idea.
I think the R help system is too fragmented: it's hard to discover
all the different types of help that are already there (Rd files,
DESCRIPTION files, vignettes, the manuals, NEWS, CHANGES,
ChangeLogs, SVN logs, source comments, mailing lists, web pages and
publications, ...). I think having a ?packagename man page is a
good place for a single starting point, and I consider packages
without one to be poorly documented. But obviously, not everyone
agrees.
- there are lots of packages without one, so this would create a
lot of work for people to add them.
No, I don't think that this is too much work. Positively speaking,
it's one small contribution to bring more light into the
exponentially growing haystack.
I agree, and I even added these to all the packages under my
control: but there are hundreds of package authors, and some have
different priorities than you and me.
What about starting to advertise the use of \alias{anRpackage},
i.e. a short article in R News and subsequently an email to the
developers.
I would have thought that putting this into NEWS and Writing R
Extensions was the right way to advertise it. If people don't read
those, why would you think they'll read R News? But more is better,
so go ahead and submit an article to R News.
I don't like robot mailings, so I wouldn't appreciate an email on
this. I don't recommend that you send one.
- the ones that do exist tend to include outdated information.
People update the DESCRIPTION file but forget to update the
corresponding information in the overview.
This is in fact a problem. Suggestions:
- propose basic style guidelines (in an R-News article)
- allow variables in .Rd files (your idea to allow "Sweave like
constructs" may be even better). In addition to entries from
DESCRIPTION, one can think also about importing data from CITATION
and possibly also from other resources.
- in general there's a lot of dissatisfaction with the Rd format,
so there's reluctance to invest any more effort in it.
You are right, .Rd has its limitations, but as you say, there is
nothing better available in the moment. (BTW: I heard rumours at
useR! about discussions on a meta documentation format? Is there
any public information about this??)
I first heard proposals for a replacement format at DSC 2001. I
don't know of anything concrete.
Duncan Murdoch
It would probably be a good idea to generate one automatically if
not provided by the author, at build or install time: this would
address the first point.
A reasonable idea -- at least if combined with a motivating request
to package authors to provide an own one.
I've been slowly working on some fixes that address the second
point. (The current idea is to use Sweave-like constructs to
import things from the DESCRIPTION file at install time.) There's
no way to address the third point other than providing a better
format, and I don't see any prospect of that happening.
So if there are no advances in that direction I see no other choice
than using the existing mechanisms! Recently, I had several
contacts with package authors who were not even aware about the
possibility of providing a package information .Rd file.
Duncan Murdoch
Thanks, Thomas P.
______________________________________________
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
______________________________________________
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
