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

[Thomas Petzoldt]

Duncan Murdoch wrote:
> On 06/10/2008 8:06 AM, Thomas Petzoldt wrote:
>> 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?
> 
> We already require one in the DESCRIPTION file for all packages, which 
> you can see with
> 
> library(help=packagename)
> 
> This is related to my first two points:  people have already done this 
> work so they are reluctant to do it again, and duplicate information is 
> a bad idea.


I agree, and I also don't like duplicate inconsistent "information", but 
simply try the following:

options(htmlhelp=TRUE)
library(help="base")

The result is now displayed in text format and new users don't know how 
to proceed. I say new users, because an experienced user knows what to 
do ... and if nothing helps he makes a grep over the sources.

> I think the R help system is too fragmented:  it's hard to discover all 
> the different types of help that are already there (Rd files, 
> DESCRIPTION files, vignettes, the manuals, NEWS, CHANGES, ChangeLogs, 
> SVN logs, source comments, mailing lists, web pages and publications, 
> ...).  I think having a ?packagename man page is a good place for a 
> single starting point, and I consider packages without one to be poorly 
> documented.  But obviously, not everyone agrees.

*I* agree -- completely with the that paragraph.

>>> - 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.
> 
> I agree, and I even added these to all the packages under my control: 
> but there are hundreds of package authors, and some have different 
> priorities than you and me.

O.K., I see, so I suggest to add an additional motivating sentence to:

http://developer.r-project.org/Rds.html

and possibly an automatism that shows (or converts) the output of

library(help="foo")

to a formatted page in the appropriate help format (e.g. html).

>> 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.
> 
> I would have thought that putting this into NEWS and Writing R 
> Extensions was the right way to advertise it.  If people don't read 
> those, why would you think they'll read R News?  But more is better, so 
> go ahead and submit an article to R News.

People like me may read "Writing R Extensions" several times and then 
have a look into some of the most prominent packages and get insecure, 
as only few use this mechanism.

> I don't like robot mailings, so I wouldn't appreciate an email on this. 
>  I don't recommend that you send one.

Beware, not at all! But I think it was good to open this thread on 
r-devel  :-)

>>
>>> - 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:
>>
>> - propose basic style guidelines (in an R-News article)
>> - allow variables in .Rd files (your idea to allow "Sweave like 
>> constructs" may be even better). In addition to entries from 
>> DESCRIPTION, one can think also about importing data from CITATION and 
>> possibly also from other resources.
>>
>>> - 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??)
> 
> I first heard proposals for a replacement format at DSC 2001.  I don't 
> know of anything concrete.
> 
> Duncan Murdoch

Not concrete. I don't even know if these rumours were related to 
something like Roxygen, extensions of a new DESCRIPTION format handling 
more automated processing on CRAN (e.g. evaluation by Taskview authors) 
or discussion about the list of keywords, but I'm sure that there are 
several points that need strategic discussion between core and "the 
developer base", including a pragmatic way to finalize conclusions.

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

Thomas P.