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

[Gabor Grothendieck]

On Tue, Oct 7, 2008 at 9:46 AM, Duncan Murdoch <murdoch at stats.uwo.ca> wrote:
> On 07/10/2008 9:11 AM, Gabor Grothendieck wrote:
>>
>> 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.
>
> The inst/doc directory can already have an index.html file to list all the
> documents there.  This will be automatically produced from the vignettes if
> it doesn't exist, but if you have other files, you can write it manually.
>
> This shows up in the HTML help system.  It would be better if it showed up
> in all help formats, but there are other ways to do that, e.g. creating an
> Rd help page pointing to those files.
>

That's good to know but I assume you are pointing out what is
available so we know as we still need to address the fragmentation.

In particular, CHM, not HTML, is the default help format under Windows so
having it in HTML will not be useful for most Windows users.
I generally do create a mypackage-package.Rd file but that's less
reliable for user since they can't be sure a package has one and
since its manually done it can become inconsistent more easily.

Also the pdf's should appear in auto-generated web pages of this sort:
http://cran.r-project.org/web/packages/zoo/index.html
in addition to the library(help = ...) page.

To me Sweave is ok for documentation but there is a learning curve
and it can't be used for reports that have conditional processing
(e.g. a report full of tables for which data is missing in some reports
so you want to eliminate those sections and the corresponding
text for those runs) without ugly workarounds which means those tend
to be written
in plain R.
Thus one can't  benefit from Sweave as much as desirable. Thus the one
other place that one might leverage your knowledge of Sweave over a
sufficiently
large set of tasks is unavailable.  I also find that despite Stangle
that debugging with
Sweave can be onerous at times.  What I would really like is one tool that
would do it all.  If the only time you use Sweave is when you create packages
there is  going to be a long time between usages and you are bound to forget
but if it can be used more widely it would be better.