Re: [Rd] ?foo to fall back to help(package="foo") [Was: why is \alias{anRpackage} not mandatory?]

From: Duncan Murdoch <murdoch_at_stats.uwo.ca>
Date: Mon, 06 Oct 2008 11:18:33 -0400

On 10/6/2008 11:00 AM, Simon Urbanek wrote:

> On Oct 6, 2008, at 8:47 , 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)
>>
> 
> Yes, but this is way too long to write - could we add a fall-back so  
> that if ?foo alias doesn't exist but package foo does then ?foo is  
> equivalent to help(package="foo")? At least for the way I use help it  
> would help a lot...

?foo and help("foo") return an object with a class whose print method displays the help. So doing this would require a new class with a different print method. It seems cleaner to me to ask people to provide the ?foo topic within the existing system, as we do now, or to produce the topic automatically at install time, so it works within the existing system.

Duncan Murdoch



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