Re: [Rd] Links to non-vignette documentation

From: Duncan Murdoch <murdoch_at_stats.uwo.ca>
Date: Fri 24 Feb 2006 - 19:11:13 GMT

On 2/24/2006 11:42 AM, hadley wickham wrote:
>> > When was this form of package documentation created? How are users
>> > supposed to know it exists? I couldn't find any pointers to it from
>> > ?help, ?library or from help(package=XXX).
>>
>> It's described in the Writing R Extensions Manual, in Writing R
>> Documentation Files, Rd Format, Documenting Packages (section 2.1.4 in
>> the PDF).
>
> That's great for developers, but how are users supposed to find out?

I think users would be disappointed if they tried using package?foo right now, because mostly it tells you there's no such man page. First you need a few more developers to follow the recommendations, before it really makes sense to advertise the feature.

An alternative approach would be for R CMD check to warn developers who don't have such a man page. That would encourage adoption of this convention, but there were quite a few objections when I suggested it. It does put a load on package authors.

Another alternative would be for a default package man page to be built if the developer didn't supply one; that's probably a good idea, but not one I have time to act on before 2.3.x, so it's not coming soon.

If you feel like writing some patches to the documentation in the appropriate places, and it looks as though they won't mislead readers, please do so, and I'll review and commit them. If you want to revise the package build scripts, you're going to need to find someone else to commit them; I will not have enough time to review things that could cause that much trouble if you get it wrong.

Duncan Murdoch



R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel Received on Sat Feb 25 06:27:07 2006

This archive was generated by hypermail 2.1.8 : Fri 24 Feb 2006 - 22:15:50 GMT