Rdpack (version 0.4-20)

insert_ref: Insert bibtex references in Rd and roxygen documentation

Description

Include references from bibtex files into R documentation using a macro. Function insert_ref is called behind the scenes at package built time.

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

Value

for insert_ref, a character string

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.

To insert references from a bibtex file in your package:

1. add the following line to file `DESCRIPTION':

RdMacros: Rdpack

(If the field 'RdMacros' is already present, add Rdpack to the list on that line.)

Create file "REFERENCES.bib" in subdirectory "inst/" of your package and put your bibtex references in it.

Then you can insert references in the documentation with \insertRef{key}{package}, where key is the bibtex key of the reference and package is an R package.

This works in manually written Rd files and in roxygen documentation chunks. The references will appear in the place where you put the macro, 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 current one. This means that you don't need to copy references from other packages to your "REFERENCES.bib" file. 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 roxygen documentation chunk might look like this:

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

The references are processed when the package is built. So, there is no need to depend/import/suggest package "Rdpack", it only needs to be installed on your machine.

References

\insertRefRpack:bibtexRdpack

\insertRefRbibtex

See Also

rebib

Examples

  insert_ref("R", package = "bibtex")