[Rd] Links to non-vignette documentation
murdoch at stats.uwo.ca
Fri Feb 24 20:11:13 CET 2006
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.
More information about the R-devel