This function uses utils::citation() and
utils::toBibtex() to create bib entries for R packages and
write them in a file. It can facilitate the auto-generation of bibliography
databases for R packages, and it is easy to regenerate all the citations
after updating R packages.
Package names. Packages which are not installed are ignored.
The (.bib) file to write. By default, or if NULL,
output is written to the R console.
Whether to fix some known problems in the citations, especially non-standard format of author names.
Width of lines in bibliography entries. If NULL, lines
will not be wrapped.
Prefix string for keys in BibTeX entries; by default, it is
R- unless option('knitr.bib.prefix') has been set to
another string.
A vector of path names of R libraries.
Use the URL field from the DESCRIPTION file.
See Details below.
A list containing the citations. Citations are also written to the
file as a side effect.
For a package, the keyword R-pkgname is used for its bib item, where
pkgname is the name of the package. Citation entries specified in the
CITATION file of the package are also included. The main purpose of
this function is to automate the generation of the package citation
information because it often changes (e.g. author, year, package version,
...).
There are at least two different uses for the URL in a reference list. You
might want to tell users where to go for more information; in that case, use
the default packageURL = TRUE, and the first URL listed in the
DESCRIPTION file will be used. Be careful: some authors don't put the
most relevant URL first. Alternatively, you might want to identify exactly
which version of the package was used in the document. If it was installed
from CRAN or some other repositories, the version number identifies it, and
packageURL = FALSE will use the repository URL (as used by
utils::citation()).
Some packages on CRAN do not have standard bib entries, which was once
reported by Michael Friendly at
https://stat.ethz.ch/pipermail/r-devel/2010-November/058977.html. I
find this a real pain, and there are no easy solutions except contacting
package authors to modify their DESCRIPTION files. Anyway, the argument
tweak has provided ugly hacks to deal with packages which are known
to be non-standard in terms of the format of citations; tweak = TRUE
is by no means intended to hide or modify the original citation
information. It is just due to the loose requirements on package authors
for the DESCRIPTION file. On one hand, I apologize if it really mangles the
information about certain packages; on the other, I strongly recommend
package authors to consider the Authors@R field (see the manual
Writing R Extensions) to make it easier for other people to cite R
packages. See knitr:::.tweak.bib for details of tweaks. Also note
this is subject to future changes since R packages are being updated. If
you want to contribute more tweaks, please edit the file
inst/misc/tweak_bib.csv in the source package.
if (FALSE) { # interactive()
write_bib(c("RGtk2", "gWidgets"), file = "R-GUI-pkgs.bib")
unlink("R-GUI-pkgs.bib")
write_bib(c("animation", "rgl", "knitr", "ggplot2"))
write_bib(c("base", "parallel", "MASS")) # base and parallel are identical
write_bib("cluster", prefix = "") # a empty prefix
write_bib("digest", prefix = "R-pkg-") # a new prefix
write_bib("digest", tweak = FALSE) # original version
# what tweak=TRUE does
str(knitr:::.tweak.bib)
}