hadley wickham wrote:
It may not be much work for you, but I find any additional
requirements to the package format to be a real pain. I have ~10
packages on CRAN and having to go through and add this extra
information all at once is a big hassle. R releases tend to happen in
the middle of the US academic semester when I have a lot of other
things on my plate.
O.K., but the discussion with Duncan shows:
- the required information is already available (in DESCRIPTION),
- one can think about ways to generate the page automatically for existing
packages,
- the intro can be short and should link to other pages or PDFs,
- one should avoid doubling and inconsistency.
I'm obviously not going to object if it's done automatically, and I
already strive to avoid doubling and inconsistency by producing most
my documentation algorithmically. I think you are being cavalier by
not caring about the extra work you want package authors to do.
Sorry if my question was misunderstood this way, but I have not
requested additional work, I simply asked "why is \alias{anRpackage} not
mandatory?"
The answer was, that they are problems with inconsistencies that can be
technically solved and that it may be too much work for some package
authors with lots of packages (can also be solved with technical means),
but that other users and developers would enjoy it to have such a
starting point.
O.K., I agree that the suggestion of NOTE-ing a missing
\alias{anRpackage} during package check was a bad idea (currently ;-),
but that one can think about a combination of a technical means and an
optional entry, analogously to the CITATION file.
Additionally, I find that rdoc is the wrong format for lengthy
explanation and exposition - a pdf is much better - and I think that
the packages already have a abstract: the description field in
DESCRIPTION.
o.k., but abstract may be (technically) in the wrong format and does not
point to the other relevant parts of the package documentation.
Then I don't think you should call what you want an abstract.
Some sort of abstract, overview or, more precise, an *entry point*.
The main problem with vignettes at the moment is that
they must be sweave, a format which I don't really like. I wish I
could supply my own pdf + R code file produced using whatever tools I
choose.
I like Sweave, and it is also possible to include your own PDFs and R files
and then to reference them in anRpackage.Rd.
Yes, but they're not vignettes - which means they're not listed under
vignette() and it's yet another place for people to look for
documentation.
You are right, they are not vignettes in the strict sense, but they can
be listed in the help index of the package, the place where the majority
of "normal R users" starts to look.
ThPe
______________________________________________
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
