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

From: Thomas Petzoldt <Thomas.Petzoldt_at_tu-dresden.de>
Date: Mon, 06 Oct 2008 14:06:00 +0200

Duncan Murdoch wrote:
> Thomas Petzoldt wrote:

>> Dear R developers,
>>
>> if one uses package.skeleton() to create a new package, then a file 
>> anRpackage.Rd with the following entries is prepared:
>>
>> \name{anRpackage-package}
>> \alias{anRpackage-package}
>> \alias{anRpackage}
>> \docType{package}
>>
>>
>> Packages created this way have a definite entry or overview page, so:
>>
>> ?anRpackage
>>
>> gives new users of a certain package a pointer where to start reading.
>>
>> This is similar for packages which have the same name as their main 
>> workhorse function, e.g. zoo or nlme, but there are many packages 
>> which don't have an \alias{anRpackage}.
>>
>> "Writing R Extensions", sec. 2.1.4 says:
>>
>> "Packages may have an overview man page with an \alias 
>> pkgname-package, e.g. `utils-package' for the utils package, when 
>> package?pkgname will open that help page. If a topic named pkgname 
>> does not exist in another Rd file, it is helpful to use this as an 
>> additional \alias."
>>
>> My question: what speaks against making this sentence more pronounced 
>> and why not NOTE-ing a missing package alias in the package check?
>>
>>   

> Not everybody likes the idea of the overview man page, so when I wrote
> that I left it weak. Some of the disadvantages:

You speak about the disadvantages but there are, of course, obvious advantages. Almost all scientific papers start with an abstract, why not requesting one for software packages, at least for new ones?

> - there are lots of packages without one, so this would create a lot of
> work for people to add them.

No, I don't think that this is too much work. Positively speaking, it's one small contribution to bring more light into the exponentially growing haystack.

What about starting to advertise the use of \alias{anRpackage}, i.e. a short article in R News and subsequently an email to the developers.

> - the ones that do exist tend to include outdated information. People
> update the DESCRIPTION file but forget to update the corresponding
> information in the overview.

This is in fact a problem. Suggestions:

> - in general there's a lot of dissatisfaction with the Rd format, so
> there's reluctance to invest any more effort in it.

You are right, .Rd has its limitations, but as you say, there is nothing better available in the moment. (BTW: I heard rumours at useR! about discussions on a meta documentation format? Is there any public information about this??)

> It would probably be a good idea to generate one automatically if not
> provided by the author, at build or install time: this would address
> the first point.

A reasonable idea -- at least if combined with a motivating request to package authors to provide an own one.

> I've been slowly working on some fixes that address
> the second point. (The current idea is to use Sweave-like constructs to
> import things from the DESCRIPTION file at install time.) There's no
> way to address the third point other than providing a better format, and
> I don't see any prospect of that happening.

So if there are no advances in that direction I see no other choice than using the existing mechanisms! Recently, I had several contacts with package authors who were not even aware about the possibility of providing a package information .Rd file.

> Duncan Murdoch
>

Thanks, Thomas P.



R-devel_at_r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel Received on Mon 06 Oct 2008 - 12:09:59 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 Mon 06 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