Work with bibtex references in Rd documentation

Work with bibtex references in Rd documentation.

Usage

rebib(infile, outfile, ...)

inspect_Rdbib(rdo, force = FALSE, ...)

Arguments

infile: name of the Rd file to update, a character string.
outfile: a filename for the updated Rd object.
...: further arguments to be passed to get_bibentries, see `Details'.
rdo: an Rd object.
force: if TRUE, re-insert previously imported references. Otherwise do not change such references.

Details

inspect_Rdbib takes an Rd object and processes the references as specified below.

The user level function is rebib. It parses the Rd file infile, calls inspect_Rdbib to process the references, and writes the modified Rd object to file outfile. If outfile is missing it is set to the basename of infile. If outfile is the empty string, "", then outfile is set to infile.

The default Bibtex file is "REFERENCES.bib" in the current working directory. Arguments "..." can be used to change the name of the bib file and its location. Argument bibfile can be used to overwrite the default name of the bib file. Argument package can be used to specify that the bib file should be taken from the root of the installation directory of package package, see get_bibentries for details.

The following scheme can be used for incorporation of bibliographic references from BibTeX files. Note however, that usually it is more convenient to use the approach based on Rd macros like \insertRef, see insert_ref and the vignette(s).

The Bibtex key for each reference is put in a comment line in the references section, as in


    \references{
        % bibentry: key1

        % bibentry: key2

        ...
    }

At least one space after the colon, ':', is required, spaces before "bibentry:" are ignored.

Then run rebib() on the file, see the example section for a way to run rebib() on all files in one go.

Each reference is inserted immediately after the comment line specifying it and a matching comment line marking its end is inserted.

Before inserting a reference, a check for the matching ending line is made, and if such a line is found, the reference is not inserted. This means that to add new references it is sufficient to give their keys, as described above and run the function again. References that are already there will not be duplicated.

The inserted reference may also be edited, if necessary. As long as the two comment lines enclosing it are not removed, the reference will not be overwritten by subsequent calls of the functions described here. Any text outside the markers delineating references inserted by this mechanism is left unchanged, including references inserted by other means.

To include all references from the bib file, the following line can be used:


    % bibentry:all

Notice that there is no space after the colon in this case. In this case a marker is put after the last reference and the whole thing is considered one block. So, if the end marker is present and force is FALSE, none will will be changed. Otherwise, if force is TRUE, the whole block of references will be removed and all references currently in the bib file will be inserted.

The main purpose of bibentry:all is for use in a package overview file. The reference section in the file "package-package" generated by promptPackageSexpr uses this feature (but the user still needs to call rebib to insert the references).

Value

for inspect_Rdbib, the modified Rd object.

rebib is used mainly for the side effect of creating a file with the references updated. It returns the Rd object created by parsing and modifying the Rd file.

Author

Georgi N. Boshnakov

Examples

if (FALSE) { # \dontrun{
# update references in all Rd files in the package's 'man' directory
#
rdnames <- dir(path = "./man", pattern=".*[.]Rd$", full.names=TRUE)
lapply(rdnames, function(x) rebib(x, package="Rdpack"))
} # }