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