% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/citation.R
\name{pkg_bib}
\alias{pkg_bib}
\title{Generate BibTeX bibliography databases for R packages}
\usage{
pkg_bib(
  x = .packages(),
  file = "",
  tweak = TRUE,
  width = NULL,
  prefix = getOption("xfun.bib.prefix", "R-"),
  lib.loc = NULL,
  packageURL = TRUE,
  date = c("none", "package", "today")
)
}
\arguments{
\item{x}{Package names. Packages which are not installed are ignored.}

\item{file}{The (\file{.bib}) file to write. By default, or if \code{NULL}, output
is written to the R console.}

\item{tweak}{Whether to fix some known problems in the citations, especially
non-standard format of author names.}

\item{width}{Width of lines in bibliography entries. If \code{NULL}, lines will
not be wrapped.}

\item{prefix}{Prefix string for keys in BibTeX entries; by default, it is
\verb{R-} unless \code{option('xfun.bib.prefix')} has been set to another string.}

\item{lib.loc}{A vector of path names of R libraries.}

\item{packageURL}{Use the \code{URL} field from the \file{DESCRIPTION} file. See
Details below.}

\item{date}{The way to include a date of the form \verb{(retrieved YYYY-mm-dd)} in
the \code{note} field of bib entries. For \code{date = 'none'}, no date is included.
For \code{date = 'package'}, the \code{\link[=packageDate]{packageDate()}} of the package is included. For
\code{date = 'today'}, \code{\link[=Sys.Date]{Sys.Date()}} is included. Alternatively, you can provide
a date directly, e.g., \verb{date = '2025-04-01'.}}
}
\value{
A list containing the citations. Citations are also written to the
\code{file} as a side effect.
}
\description{
Call \code{\link[utils:citation]{utils::citation()}} and \code{\link[utils:toLatex]{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.
}
\details{
For a package, the keyword \code{R-pkgname} is used for its bib item, where
\code{pkgname} is the name of the package. Citation entries specified in the
\file{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., the author, year, package
version, and so on).

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 \code{packageURL = TRUE}, and the first URL listed in the
\file{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
\code{packageURL = FALSE} will use the repository URL (as used by
\code{\link[utils:citation]{utils::citation()}}).
}
\note{
Some packages on CRAN do not have standard bib entries, which was once
reported by Michael Friendly at
\url{https://stat.ethz.ch/pipermail/r-devel/2010-November/058977.html}. I
find this a pain, and there are no easy solutions except contacting package
authors to modify their DESCRIPTION files. The argument \code{tweak} has
provided hacks to deal with known packages with non-standard bib entries;
\code{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 \code{Authors@R} field (see the
manual \emph{Writing R Extensions}) to make it easier for other people to cite R
packages.
}
\examples{
pkg_bib(c("base", "MASS", "xfun"))
pkg_bib("cluster", prefix = "R-pkg-")  # a different prefix
pkg_bib("xfun", date = "package")
}
\author{
Yihui Xie and Michael Friendly
}
