R: Insert bibtex references in Rd and roxygen2 documentation

insert_ref {Rdpack} | R Documentation

## Insert bibtex references in Rd and roxygen2 documentation

### Description

Package Rdpack provides Rd macros for inserting references and citations from bibtex files into R documentation. Function insert_ref() is the workhorse behind this mechanism. The description given in this page should be sufficient, for more details see the vignette.

### Usage

    insert_ref(key, package = NULL, ...)

### Arguments

`key` | the bibtex key of the reference, a character string.
`package` | the package in which to look for the the bibtex file.
`...` | further arguments to pass on to `bibtex::read.bib`

### Details

`insert_ref` extracts a reference from a bibtex file, converts it to Rd format and returns a single string with embedded newline characters. It is the workhorse in the provided mechanism but most users do not even need to know about `insert_ref`.

The documentation of a package using the mechanism provided here relies on the Rd macro `\insertRef`. The description below assumes that Rdpack has been added to file DESCRIPTION, as described in `Rdpack-package` and the vignettes.

References can be inserted in documentation using the syntax `\insertRef{key}{package}`, where `key` is the bibtex key of the reference and `package` is an R package containing file `"REFERENCES.bib"` from which the reference should be taken.

This works in manually written Rd files and in ‘roxygen2’ documentation chunks. The references will appear in the place where the macro is put, usually in a dedicated references section (`\references` in Rd files, `@references` in roxygen chunks).

Argument 'package' can be any installed R package, not necessarily the one of the documentation object. This works for packages that have `"REFERENCES.bib"` in their installation directory and for the default packages.

For example, the references in the references section of this help page are generated by the following lines in the Rd file:

        \insertRef{Rpack:bibtex}{Rdpack}

        \insertRef{R}{bibtex}

A roxygen2 documentation chunk might look like this:

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

The first reference has label `Rpack:bibtex` and is taken from file `"REFERENCES.bib"` in package Rdpack. The second reference is from the file with the same name in package bibtex.

For more details see vignette: `vignette("Inserting_bibtex_references", package = "Rdpack")`

The references are processed when the package is built.

From version 0.6-1 of Rdpack, additional Rd macros are available for citations. They can be used in Rd and roxygen2 documentation.

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

`\insertCite{parseRd,Rpack:bibtex}{Rdpack}` | (Murdoch 2010; Francois 2014)
`\insertCite{Rpack:bibtex}{Rdpack}` | (Francois 2014)

By default the citations are parenthesised (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 were produced with `\insertCite{parseRd}{Rdpack}` and `\insertCite{parseRd;textual}{Rdpack}`, respectively. This also works with several citations, e.g.
`\insertCite{parseRd,Rpack:bibtex;textual}{Rdpack}` produces: Murdoch (2010); Francois (2014).

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

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 @Rpack:bibtex}{Rdpack}

      \insertCite{@see also @parseRd; @Rpack:bibtex}{Rdpack}

      \insertCite{@see also @parseRd and @Rpack:bibtex;textual}{Rdpack}

produces:

(see also Murdoch 2010 and Francois 2014)
(see also Murdoch 2010; Francois 2014)
see also Murdoch (2010) and Francois (2014)

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

### Value

for `insert_ref`, a character string

### Author(s)

Georgi N. Boshnakov

### References

For illustrative purposes there are two sets of citation below The first set of references is obtained with `\insertRef` for each reference:

Romain Francois (2014). bibtex: bibtex parser. R package version 0.4.0, https://CRAN.R-project.org/package=bibtex.

R Development Core Team (2009). R: A Language and Environment for Statistical Computing. R Foundation for Statistical Computing, Vienna, Austria. ISBN 3-900051-07-0, https://www.R-project.org.

—-

The following references are obtained with a single `\insertAllCited{}`:

Romain Francois (2014). bibtex: bibtex parser. R package version 0.4.0, https://CRAN.R-project.org/package=bibtex.

Duncan Murdoch (2010). “Parsing Rd files.” https://developer.r-project.org/parseRd.pdf.

### See Also

`Rdpack-package` for overview, the vignettes

### Examples

      cat(insert_ref("R", package = "bibtex"), sep ="\n")

[Package Rdpack version 0.10-1 Index]