Rdpack provides functions for manipulation of R documentation objects, including functions reprompt() and ereprompt() for updating existing Rd documentation for functions, methods and classes; Rd macros for citations and import of references from bibtex files for use in Rd files and roxygen2 comments (\insertRef, \insertCite, \insertAllCited); Rd macros for evaluating and inserting snippets of R code and the results of its evaluation (\printExample) or creating graphics on the fly (\insertFig); and many functions for manipulation of references and Rd files.

Installing Rdpack
Inserting Bibtex references and citations
Viewing Rd files
Using Rdpack::reprompt()
1. What it does
2. Reprompt and open in an editor
Inserting evaluated examples
1. Evaluating the examples in section Examples
Inserting figures/graphs/plots

Installing Rdpack

Install the latest stable version from CRAN:

install.packages("Rdpack")

You can also install the development version of Rdpack from Github:

library(devtools)
install_github("GeoBosh/Rdpack")

Inserting Bibtex references and citations

The simplest way to insert Bibtex references is with the Rd macro \insertRef. Just put \insertRef{key}{package} in the documentation to insert item with key key from file REFERENCES.bib in your package package. Alternatively, use one or more \insertCite{key}{package} commands to cite works from REFERENCES.bib, then issue a single \insertAllCited{} directive to produce a list of all cited references. For this to work the DESCRIPTION file of the package needs to be amended, see below the full details.

Preparation

To prepare a package for importing BibTeX references it is necessary to tell the package management tools that package Rdpack and its Rd macros are needed. The references should be put in file inst/REFERENCES.bib. These steps are enumerated below in somewhat more detail, see also the vignette Inserting_bibtex_references.

Add the following lines to file "DESCRIPTION":
```
Imports: Rdpack
RdMacros: Rdpack
```
Make sure the capitalisation of RdMacros: is as shown. If the field RdMacros: is already present, add "Rdpack" to the list on that line. Similarly for field "Imports:".
Add the following line to file "NAMESPACE":
```
importFrom(Rdpack,reprompt)
```
The equivalent line for roxygen2 is
```
#' @importFrom Rdpack reprompt
```
Create file REFERENCES.bib in subdirectory inst/ of your package and put the BibTeX references in it.

Inserting references

Once the steps outlined above are done, references can be inserted in the documentation as

\insertRef{key}{package}

where key is the bibtex key of the reference and package is your package. This works in Rd files and in roxygen documentation chunks.

Usually references are put in section references. In an Rd file this might look something like:

\references{
\insertRef{Rdpack:bibtex}{Rdpack}

\insertRef{R}{bibtex}
}

The equivalent roxygen2 documentation chunk would be:

#' @references
#' \insertRef{Rpackage:rbibutils}{Rdpack}
#'
#' \insertRef{R}{bibtex}

The first line above inserts the reference with key Rpackage:rbibutils in Rdpack's REFERENCES.bib. The second line inserts the reference labeled R in file REFERENCES.bib from package bibtex.

The example above demonstrates that references from other packages can be inserted (in this case bibtex), as well. This is strongly discouraged for released versions but is convenient during development. One relatively safe use is when the other package is also yours - this allows authors of multiple packages to not copy the same refences to each of their own packages.

For further details see the vignette Inserting_bibtex_references or open it from R:

vignette("Inserting_bibtex_references", package = "Rdpack")

(The latest version of the vignette is at Inserting_bibtex_references (development version on github).)

Inserting citations

Additional Rd macros are available for citations. They also can be used in both Rd and roxygen2 documentation.

\insertCite{key}{package} cites key and records it for use by \insertAllCited and \insertCited, see below. key can contain more keys separated by commas.

\insertCite{parseRd,Rpackage:rbibutils}{Rdpack} produces (Murdoch 2010; Boshnakov and Putman 2020) and \insertCite{Rpackage:rbibutils}{Rdpack} gives (Boshnakov and Putman 2020).

By default the citations are parenthesised: \insertCite{parseRd}{Rdpack} produces (Murdoch 2010). To get textual citations, like Murdoch (2010), put the string ;textual at the end of the key. The references in the last two sentences would be produced with \insertCite{parseRd}{Rdpack} and \insertCite{parseRd;textual}{Rdpack}, respectively. This also works with several citations, e.g.

\insertCite{parseRd,Rpackage:rbibutils;textual}{Rdpack} produces: Murdoch (2010); Boshnakov and Putman (2020).

The macro \insertNoCite{key}{package} records one or more references for \insertAllCited but does not cite it. Setting key to * will include all references from the specified package. For example, \insertNoCite{R}{bibtex} and \insertNoCite{*}{utils} record the specified references for inclusion by \insertAllCited.

\insertAllCited inserts all references cited with \insertCite or \insertNoCite. Putting this macro in the references section will keep it up to date automatically. The Rd section may look something like:

\insertAllCited{}

or, in roxygen2, the references chunk might look like this:

#' @references
#'   \insertAllCited{}

Don't align the backslash with the second 'e' of @references, since roxygen2 may interpret it as verbatim text, not macro.

\insertCited{} works like \insertAllCited but empties the reference list after finishing its work. This means that the second and subsequent \insertCited in the same help page will list only citations done since the preceding \insertCited. Prompted by issue 27 on github to allow separate reference lists for each method and the class in R6 documentation.

To mix the citations with other text, such as ``see also'' and ``chapter 3'', write the list of keys as a free text, starting it with the symbol @ and prefixing each key with it. The @ symbol will not appear in the output. For example, the following code

\insertCite{@see also @parseRd and @Rpackage:rbibutils}{Rdpack}
\insertCite{@see also @parseRd; @Rpackage:rbibutils}{Rdpack}
\insertCite{@see also @parseRd and @Rpackage:rbibutils;textual}{Rdpack}

produces:

(see also Murdoch 2010 and Boshnakov and Putman 2020)

(see also Murdoch 2010; Boshnakov and Putman 2020)

see also Murdoch (2010) and Boshnakov and Putman (2020)

With the parenthesised citations, if you need markup for the text before or after the citations, say see also in italic, put ;nobrackets<sup><a id="fnr.1" class="footref" href="#fn.1">1</a></sup> at the end of the first argument of the Rd macro, take out the part containing markup, and put the parentheses were suitable. For example,

(\emph{see also} \insertCite{@@parseRd and @Rpackage:rbibutils;nobrackets}{Rdpack})

(in markdown, use _see also_ in place of \emph{see also}). This gives:

(see also Murdoch 2010 and Boshnakov and Putman 2020)

—

\insertCiteOnly{key}{package} is as \insertCite but does not include the key in the list of references for \insertAllCited.

Changing the style of references

Bibliography styles for lists of references are supported from <span class="underline">Rdpack (>= 0.8)</span>. Currently the only alternative offered is to use long names (Georgi N. Boshnakov) in place of the default style (Boshnakov GN). More comprehensive alternatives can be included if needed or requested.

To cause all lists of references produced by \insertAllCited in a package to appear with full names, add .onLoad() function to your package. If you don't have .onLoad(), just copy the following definition:

.onLoad <- function(lib, pkg){
    Rdpack::Rdpack_bibstyles(package = pkg, authors = "LongNames")
    invisible(NULL)
}

If you already have

Rdpack

Install / Use

README

Table of Contents