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

[Simon Urbanek]

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

Cheers,
S


> This is related to my first two points:  people have already done  
> this work so they are reluctant to do it again, and duplicate  
> information is a bad idea.
>
> I think the R help system is too fragmented:  it's hard to discover  
> all the different types of help that are already there (Rd files,  
> DESCRIPTION files, vignettes, the manuals, NEWS, CHANGES,  
> ChangeLogs, SVN logs, source comments, mailing lists, web pages and  
> publications, ...).  I think having a ?packagename man page is a  
> good place for a single starting point, and I consider packages  
> without one to be poorly documented.  But obviously, not everyone  
> agrees.
>
>>> - there are lots of packages without one, so this would create a  
>>> lot of work for people to add them.
>> No, I don't think that this is too much work. Positively speaking,  
>> it's one small contribution to bring more light into the  
>> exponentially growing haystack.
>
> I agree, and I even added these to all the packages under my  
> control: but there are hundreds of package authors, and some have  
> different priorities than you and me.
>
>> What about starting to advertise the use of \alias{anRpackage},  
>> i.e. a short article in R News and subsequently an email to the  
>> developers.
>
> I would have thought that putting this into NEWS and Writing R  
> Extensions was the right way to advertise it.  If people don't read  
> those, why would you think they'll read R News?  But more is better,  
> so go ahead and submit an article to R News.
>
> I don't like robot mailings, so I wouldn't appreciate an email on  
> this.  I don't recommend that you send one.
>
>
>>> - the ones that do exist tend to include outdated information.   
>>> People update the DESCRIPTION file but forget to update the  
>>> corresponding information in the overview.
>> This is in fact a problem. Suggestions:
>> - propose basic style guidelines (in an R-News article)
>> - allow variables in .Rd files (your idea to allow "Sweave like  
>> constructs" may be even better). In addition to entries from  
>> DESCRIPTION, one can think also about importing data from CITATION  
>> and possibly also from other resources.
>>> - in general there's a lot of dissatisfaction with the Rd format,  
>>> so there's reluctance to invest any more effort in it.
>> You are right, .Rd has its limitations, but as you say, there is  
>> nothing better available in the moment. (BTW: I heard rumours at  
>> useR! about discussions on a meta documentation format? Is there  
>> any public information about this??)
>
> I first heard proposals for a replacement format at DSC 2001.  I  
> don't know of anything concrete.
>
> Duncan Murdoch
>
>>> It would probably be a good idea to generate one automatically if  
>>> not provided by the author, at build or install time:  this would  
>>> address the first point.
>> A reasonable idea -- at least if combined with a motivating request  
>> to package authors to provide an own one.
>>> I've been slowly working on some fixes that address the second  
>>> point.  (The current idea is to use Sweave-like constructs to  
>>> import things from the DESCRIPTION file at install time.)  There's  
>>> no way to address the third point other than providing a better  
>>> format, and I don't see any prospect of that happening.
>> So if there are no advances in that direction I see no other choice  
>> than using the existing mechanisms! Recently, I had several  
>> contacts with package authors who were not even aware about the  
>> possibility of providing a package information .Rd file.
>>> Duncan Murdoch
>>>
>> Thanks, Thomas P.
>
> ______________________________________________
> R-devel at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel
>
>