Section 1.4 of Writing R Extensions says: In addition to the help files in Rd format, R packages allow the inclusion of documents in arbitrary other formats. The standard location for these is subdirectory inst/doc of a source package, the contents will be copied to subdirectory doc when the package is installed. Pointers from package help indices to the installed documents are automatically created. Documents in inst/doc can be in arbitrary format, however we strongly recommend to provide them in PDF format, such that users on all platforms can easily read them. Where are these pointers created? I have a package with a pdf file (introduction.pdf) in inst/doc but I can't find a link to it from the documentation (eg. from help.start() or help(package=...) Is there anyway to have my pdf documentation listed under vignettes other than making it a sweave file? Hadley
On 2/23/2006 11:53 AM, hadley wickham wrote:> Section 1.4 of Writing R Extensions says: > > In addition to the help files in Rd format, R packages allow the > inclusion of documents in arbitrary other formats. The standard > location for these is subdirectory inst/doc of a source package, the > contents will be copied to subdirectory doc when the package is > installed. Pointers from package help indices to the installed > documents are automatically created. Documents in inst/doc can be in > arbitrary format, however we strongly recommend to provide them in PDF > format, such that users on all platforms can easily read them. > > Where are these pointers created? I have a package with a pdf file > (introduction.pdf) in inst/doc but I can't find a link to it from the > documentation (eg. from help.start() or help(package=...) > > Is there anyway to have my pdf documentation listed under vignettes > other than making it a sweave file?A manually written inst/doc/index.html file will be linked into the help system. I don't know if the sentence about pointers being created is true otherwise. 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