1% File src/library/utils/man/citation.Rd
2% Part of the R package, https://www.R-project.org
3% Copyright 1995-2017 R Core Team
4% Distributed under GPL 2 or later
5
6\name{citation}
7\alias{CITATION}
8\alias{citation}
9\alias{readCitationFile}
10\title{Citing R and R Packages in Publications}
11\description{
12  How to cite \R and \R packages in publications.
13}
14\usage{
15citation(package = "base", lib.loc = NULL, auto = NULL)
16readCitationFile(file, meta = NULL)
17}
18\arguments{
19  \item{package}{a character string with the name of a single package.
20    An error occurs if more than one package name is given.}
21  \item{lib.loc}{a character vector with path names of \R libraries, or
22    the directory containing the source for \code{package}, or
23    \code{NULL}.  The default value of \code{NULL} corresponds to all
24    libraries currently known.  If the default is used, the loaded
25    packages are searched before the libraries.}
26  \item{auto}{a logical indicating whether the default citation
27    auto-generated from the package \file{DESCRIPTION} metadata should
28    be used or not, or \code{NULL} (default), indicating that a
29    \file{CITATION} file is used if it exists, or an object of class
30    \code{"\link{packageDescription}"} with package metadata (see
31    below).}
32  \item{file}{a file name.}
33  \item{meta}{a list of package metadata as obtained by
34    \code{\link{packageDescription}}, or \code{NULL} (the default).}
35}
36\details{
37  The \R core development team and the very active community of package
38  authors have invested a lot of time and effort in creating \R as it is
39  today.  Please give credit where credit is due and cite \R and \R
40  packages when you use them for data analysis.
41
42  Execute function \code{citation()} for information on how to cite the
43  base R system in publications.  If the name of a non-base package is
44  given, the function either returns the information contained in the
45  \file{CITATION} file of the package (using \code{readCitationFile}
46  with \code{meta} equal to \code{packageDescription(package, lib.loc)})
47  or auto-generates citation information from the \file{DESCRIPTION}
48  file.
49
50  In \R >= 2.14.0, one can use a \samp{Authors@R} field in
51  \file{DESCRIPTION} to provide (\R code giving) a
52  \code{\link{person}} object with a refined, machine-readable
53  description of the package \dQuote{authors} (in particular specifying
54  their precise roles).  Only those with an author role will be
55  included in the auto-generated citation.
56
57  If only one reference is given, the print method for the object
58  returned by \code{citation()} shows both a text version and a BibTeX
59  entry for it, if a package has more than one reference then only the
60  text versions are shown.  The BibTeX versions can be obtained using
61  function \code{toBibtex()} (see the examples below).
62
63  The \file{CITATION} file of an R package should be placed in the
64  \file{inst} subdirectory of the package source.  The file is an R
65  source file and may contain arbitrary R commands including
66  conditionals and computations.  Function \code{readCitationFile()} is
67  used by \code{citation()} to extract the information in
68  \file{CITATION} files.  The file is \code{source()}ed by the R
69  parser in a temporary environment and all resulting bibliographic
70  objects (specifically, of class \code{"\link{bibentry}"}) are
71  collected.
72
73  Traditionally, the \file{CITATION} file contained zero or more calls
74  to \code{citHeader}, then one or more calls to \code{\link{citEntry}},
75  and finally zero or more calls to \code{citFooter}, where in fact
76  \code{citHeader} and \code{citFooter} are simply wrappers to
77  \code{\link{paste}}, with their \code{\dots} argument passed on to
78  \code{\link{paste}} as is.  The \code{"\link{bibentry}"} class
79  makes for improved representation and manipulation of bibliographic
80  information (in fact, the old mechanism is implemented using the new
81  one), and one can write \file{CITATION} files using the unified
82  \code{\link{bibentry}} interface.
83
84  One can include an auto-generated package citation in the
85  \file{CITATION} file via \code{citation(auto = meta)}.
86
87  \code{readCitationFile} makes use of the \code{Encoding} element (if
88  any) of \code{meta} to determine the encoding of the file.
89}
90\value{
91  An object of class \code{"citation"}, inheriting from class
92  \code{"\link{bibentry}"}; see there, notably for the
93  \code{\link{print}} and \code{\link{format}} methods.
94}
95\seealso{
96  \code{\link{bibentry}}
97}
98\keyword{misc}
99\examples{
100## the basic R reference
101citation()
102
103## references for a package -- might not have these installed
104if(nchar(system.file(package = "lattice"))) citation("lattice")
105if(nchar(system.file(package = "foreign"))) citation("foreign")
106
107## extract the bibtex entry from the return value
108x <- citation()
109toBibtex(x)
110
111\donttest{
112## A citation with more than one bibentry:
113cm <- tryCatch(citation("mgcv"),
114               error = function(e) {
115                 warning("Recommended package 'mgcv' is not installed properly")
116                 stop(e$message) })
117cm # short entries (2-3 lines each)
118print(cm, bibtex = TRUE) # each showing its bibtex code
119}%dont
120}
121