[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:00:51 -0400

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

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