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

[Thomas Petzoldt]

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