From simon.urbanek at r-project.org  Mon Oct  6 17:29:03 2008
From: simon.urbanek at r-project.org (Simon Urbanek)
Date: Mon, 6 Oct 2008 11:29:03 -0400
Subject: [Rd] ?foo to fall back to help(package="foo") [Was: why is
	\alias{anRpackage} not mandatory?]
In-Reply-To: <48EA2C49.4090005@stats.uwo.ca>
References: <48E9DE58.6070303@tu-dresden.de> <48E9E9E3.90905@stats.uwo.ca>
	<48E9FF28.6060207@tu-dresden.de> <48EA08C9.7050702@stats.uwo.ca>
	<E3BB2C40-8536-4F89-A9BB-2EEE92E252B2@r-project.org>
	<48EA2C49.4090005@stats.uwo.ca>
Message-ID: <D10345B1-804D-4854-AAD3-04D2CA9F965B@r-project.org>


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



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