From h.wickham at gmail.com  Mon Oct  6 15:55:14 2008
From: h.wickham at gmail.com (hadley wickham)
Date: Mon, 6 Oct 2008 08:55:14 -0500
Subject: [Rd] why is \alias{anRpackage} not mandatory?
In-Reply-To: <48EA15B5.8020800@tu-dresden.de>
References: <48E9DE58.6070303@tu-dresden.de> <48E9E9E3.90905@stats.uwo.ca>
	<48E9FF28.6060207@tu-dresden.de>
	<f8e6ff050810060559j19623c5ew8f8e3f47811088c0@mail.gmail.com>
	<48EA15B5.8020800@tu-dresden.de>
Message-ID: <f8e6ff050810060655p25baba3bw6ab54af0ef35acfa@mail.gmail.com>

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

Hadley


-- 
http://had.co.nz/



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