I don't want to gripe here, but I would like to know the best method for
submitting suggestions and patches to the documentation.
It looks like for many help items, we need to track from the html file
which help.search("*")/help("*") presents, back to the
authoritiative
documentation file from which they are generated. It seems the
installation process discards much of the .../{package}/man/*.Rd files, so
to build patches to the original documentation requires a download and
extraction from the source.
Is there a way to retain the authoritiative files, patch them, re-install
the patched documentation, and perhaps produce a useable patch for the
package maintainers?
Something like
R CMD INSTALL --docs-only pixmap_mine_0.4-1.tar.gz
# to rebuild the documentation
or
R CMD INSTALL --keep-docs --library=/usr/lib/R/library \
utils.xx.yy.tar.gz # to keep the authoritative documentation
with a:
diff -ru pixmap/man pixmap_mine/man >pixmap_doc.patch
... as a convenient way to deliver the document criticism, correction, or
elaboration to the package maintainers.
As it is, one has to either download, patch and reinstall the packages, or
edit the .../help/, .../html/, derived files directly to make minor
improvements in the documentation.
I apologise for the complaining, but I did spend too much time today
rediscovering that 'pixmap' is a package for computing images, (I was
off-line, and knew there was something in R that read, plotted, or wrote
graphics files) and a small change like the patch to utils/help/methods
attached would also have saved me some time. R does many things, but the
documentation is hard to patch and improve.
And back to my subject:
Is producing patches against the authoritative documentation the
recommended way to improve the documentation?
Dave
--
Dave Forrest
drf at vims.edu (804)684-7900w
drf5n at maplepark.com (804)642-0662h
http://maplepark.com/~drf5n/
-------------- next part --------------
diff -ur R-1.9.1-dist/src/library/utils/man/methods.Rd
R-1.9.1/src/library/utils/man/methods.Rd
--- R-1.9.1-dist/src/library/utils/man/methods.Rd 2003-12-09 02:24:25.000000000
-0500
+++ R-1.9.1/src/library/utils/man/methods.Rd 2004-08-24 23:33:44.000000000 -0400
@@ -47,7 +47,8 @@
The original \code{methods} function was written by Martin Maechler.
}
\seealso{
- \code{\link{S3Methods}}, \code{\link[base]{class}}, \code{\link{getS3method}}
+ \code{\link{S3Methods}}, \code{\link[base]{class}},
\code{\link{getS3method}},
+ \code{\link[methods]{showMethods}}
}
\references{
Chambers, J. M. (1992)
