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

[Gabor Grothendieck]

Some examples are:
- be able to use brew package or similar alternative in place of Sweave
- provide a pdf regardless how it was generated
without ugly workarounds and still let the user get a list of all pdf
documents in
one place, e.g.
  library(help = mypackage)
should list the vignettes and other pdfs too so its all together and
there should
be some facility similar to vignettes() to easily access them.


On Mon, Oct 6, 2008 at 10:22 AM, Duncan Murdoch <murdoch at stats.uwo.ca> wrote:
> 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.

The change I would like to see in Sweave would be the ability to include
or exclude R and latex sections based on the results of the R code. That
would allow it to be used in conditional report generation and not just
documentation.  I know there are workarounds but they are ugly and
not satisfactory in my opinion.  Also passing arguments to
R CMD Sweave would be nice.