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

[Duncan Murdoch]

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