Re: [Rd] why is \alias{anRpackage} not mandatory?

From: Thomas Petzoldt <Thomas.Petzoldt_at_tu-dresden.de>
Date: Mon, 06 Oct 2008 16:34:57 +0200

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_at_r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel Received on Mon 06 Oct 2008 - 14:43:51 GMT

Archive maintained by Robert King, hosted by the discipline of statistics at the University of Newcastle, Australia.
Archive generated by hypermail 2.2.0, at Mon 06 Oct 2008 - 15:30:16 GMT.

Mailing list information is available at https://stat.ethz.ch/mailman/listinfo/r-devel. Please read the posting guide before posting to the list.

list of date sections of archive