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

From: Gabor Grothendieck <ggrothendieck_at_gmail.com>
Date: Tue, 07 Oct 2008 10:16:20 -0400

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.



R-devel_at_r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel Received on Tue 07 Oct 2008 - 14:18:42 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 - 15:30:18 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