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

[Simon Urbanek]

On Oct 6, 2008, at 11:18 , Duncan Murdoch wrote:

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

... which doesn't seem to work - that's why we have the discussion ;).


> or to produce the topic automatically at install time, so it works  
> within the existing system.
>

... which if ok with me - that would fit the bill ...

Thanks,
Simon