[Rd] Links to non-vignette documentation

[Duncan Murdoch]

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