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

From: Simon Urbanek <simon.urbanek_at_r-project.org>
Date: Mon, 06 Oct 2008 11:29:03 -0400

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



R-devel_at_r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel Received on Mon 06 Oct 2008 - 15:39:48 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 Tue 07 Oct 2008 - 08: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