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

From: Duncan Murdoch <murdoch_at_stats.uwo.ca>
Date: Mon, 06 Oct 2008 10:22:38 -0400

On 10/6/2008 9:55 AM, 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.
> 

>>> 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.
> 

>>> 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.

Vignettes have R code in them and a way to extract it, so it's misleading to call something that's just a .pdf file a vignette. But I imagine there could be other ways to mix R code with documentation besides the existing Sweave formats. The most obvious way to add another one is to write another Sweave driver. I think it would require changes to the base of R to allow for Sweave drivers in packages, working with files that don't have extensions (R|r|S|s)(nw|tex), but in principle I don't see any real objection to adding that.

Duncan Murdoch



R-devel_at_r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel Received on Mon 06 Oct 2008 - 14:26:52 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 Tue 07 Oct 2008 - 14:00:17 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