install.packages('Rdpack')Rdpack may be help authors of Rpackages to keep their
documentation up to date during development. Although base R and
package methods have functions for creation of skeleton
documentation, if a function gets a new argument or a generic gets a
new method, then updating existing documentation is somewhat
inconvenient. This package provides functions that update parts of the
Rd documentation that can be dealt with automatically and leave manual
changes untouched. For example, usage sections for functions are
updated and if there are undescribed arguments, additional items are
put in the `arguments' section.
Another set of functions is for management of bibliographic
references.
The main functions provided by this package are
reprompt, promptPackageSexpr, and
rebib.
reprompt produces a skeleton documentation for the
requested object, similarly to functions like prompt,
promptMethods, and promptClass. Unlike those functions,
reprompt updates existing documentation (installed or in
an Rd object or file) and produces a skeleton from scratch as a last
resort only. If the documentation object describes more than one
function, all descriptions are updated. Basically,
reprompt updates things that are generated
automatically, leaving manual editing untouched.
The typical use of reprompt is with one argument, as in
reprompt(infile = "./Rdpack/man/reprompt.Rd")
reprompt(reprompt)
reprompt("reprompt")
reprompt updates the documentation of all objects described in
the Rd object or file, and writes the updated Rd file in the current
working directory, see reprompt for details.
promptPackageSexpr creates a skeleton for a
package overview in file promptPackage does.
For example, the source of this help page is file
`Rdpack-package.Rd'. It was initially produced using
promptPackageSexpr("Rdpack")
The factual information at the beginning of this help topic (the index
above, the version and other stuff that can be determined
automatically) is kept automatically up to date.
rebib updates the bibliographic references in an Rd
file. Rdpack uses a simple scheme for inclusion of
bibliographic references. The key for each reference is in a TeX comment
line, as in:
\references{
...
% bibentry: key1
% bibentry: key2
...
}
rebib puts each reference after the line containing its
key. It does nothing if the reference has been put by a previous call
of rebib. If the Bibtex entry for some references changes, it
may be necessary to update them in the Rd file, as well. Call
rebib with force = TRUE to get this effect. There is
also a facility to include all references from the Bibtex file, see
the documentation of rebib for details.
The Bibtex source for the references is by default a file
"REFERENCES.bib" located in the root of the package installation
folder.
Note that there are other, more sophisticated, approaches to keeping
documentation and code in synchron, for example package reprompt, with one argument (the doc file or the object to be
updated) to update all sorts of Rd documentation files. Some may find
that this is all they need and not bother with the rest of this
documentation.
Other functions that may be useful are Rdo2Rdf, Rdapply
and Rd_combo. Here is also brief information about some more
technical functions that may be helpful in certain circumstances.
c_Rd concatenates Rd pieces, character strings and lists
to create a larger Rd piece or a complete Rd object.
list_Rd is similar to c_Rd but provides
additional features for convenient assembling of Rd objects.
parse_Rdpiece is technical function for parsing pieces
of Rd source text but it has an argument to return formatted help text
which may be useful when one wishes to show it to the user.
Rdo_set_section can be used to set a section, such as
"