1% File src/library/utils/man/cite.Rd
2% Part of the R package, https://www.R-project.org
3% Copyright 2012-2015 R Core Team
4% Distributed under GPL 2 or later
5
6\name{cite}
7\alias{cite}
8\alias{citeNatbib}
9\title{Cite a Bibliography Entry}
10\description{
11Cite a \code{bibentry} object in text.  The \code{cite()} function
12uses the \code{cite()} function from the default
13\code{\link{bibstyle}} if present, or \code{citeNatbib()} if not.
14\code{citeNatbib()} uses a style similar to that used by the LaTeX
15package \pkg{natbib}.
16}
17\usage{
18cite(keys, bib, ...)
19citeNatbib(keys, bib, textual = FALSE, before = NULL, after = NULL,
20           mode = c("authoryear", "numbers", "super"),
21           abbreviate = TRUE, longnamesfirst = TRUE,
22           bibpunct = c("(", ")", ";", "a", "", ","), previous)
23}
24\arguments{
25  \item{keys}{
26A character vector of keys of entries to cite.  May contain multiple keys in
27a single entry, separated by commas.
28}
29  \item{bib}{
30A \code{"\link{bibentry}"} object containing the list of documents in which
31to find the keys.
32}
33  \item{...}{
34Additional arguments to pass to the \code{cite()} function for the
35default style.
36}
37  \item{textual}{
38Produce a \dQuote{textual} style of citation, i.e.\sspace{}what \code{\\citet} would
39produce in LaTeX.
40}
41  \item{before}{
42Optional text to display before the citation.
43}
44  \item{after}{
45Optional text to display after the citation.
46}
47  \item{mode}{
48The \dQuote{mode} of citation.
49}
50  \item{abbreviate}{
51Whether to abbreviate long author lists.
52}
53  \item{longnamesfirst}{
54If \code{abbreviate == TRUE}, whether to leave the first citation long.
55}
56  \item{bibpunct}{
57A vector of punctuation to use in the citation, as used in \pkg{natbib}.  See
58the Details section.
59}
60  \item{previous}{
61A list of keys that have been previously cited, to be used when
62\code{abbreviate == TRUE} and \code{longnamesfirst == TRUE}
63}
64}
65\details{
66Argument names are chosen based on the documentation for the LaTeX \pkg{natbib}
67package.  See that documentation for the interpretation of the
68\code{bibpunct} entries.
69
70The entries in \code{bibpunct} are as follows:
71\enumerate{
72\item The left delimiter.
73\item The right delimiter.
74\item The separator between references within a citation.
75\item An indicator of the \dQuote{mode}:  \code{"n"} for numbers,
76\code{"s"} for superscripts, anything else for author-year.
77\item Punctuation to go between the author and year.
78\item Punctuation to go between years when authorship is suppressed.
79}
80Note that if \code{mode} is specified, it overrides the
81mode specification in \code{bibpunct[4]}.  Partial matching is used for
82\code{mode}.
83
84The defaults for \code{citeNatbib} have been chosen to match the JSS style, and
85by default these are used in \code{cite}.  See \code{\link{bibstyle}}
86for how to set a different default style.
87}
88\value{
89A single element character string is returned, containing the citation.
90}
91\author{
92Duncan Murdoch
93}
94\examples{
95## R reference
96rref <- bibentry(
97   bibtype = "Manual",
98   title = "R: A Language and Environment for Statistical Computing",
99   author = person("R Core Team"),
100   organization = "R Foundation for Statistical Computing",
101   address = "Vienna, Austria",
102   year = 2013,
103   url = "https://www.R-project.org/",
104   key = "R")
105
106## References for boot package and associated book
107bref <- c(
108   bibentry(
109     bibtype = "Manual",
110     title = "boot: Bootstrap R (S-PLUS) Functions",
111     author = c(
112       person("Angelo", "Canty", role = "aut",
113         comment = "S original"),
114       person(c("Brian", "D."), "Ripley", role = c("aut", "trl", "cre"),
115         comment = "R port, author of parallel support",
116         email = "ripley@stats.ox.ac.uk")
117     ),
118     year = "2012",
119     note = "R package version 1.3-4",
120     url = "https://CRAN.R-project.org/package=boot",
121     key = "boot-package"
122   ),
123
124   bibentry(
125     bibtype = "Book",
126     title = "Bootstrap Methods and Their Applications",
127     author = as.person("Anthony C. Davison [aut], David V. Hinkley [aut]"),
128     year = "1997",
129     publisher = "Cambridge University Press",
130     address = "Cambridge",
131     isbn = "0-521-57391-2",
132     url = "http://statwww.epfl.ch/davison/BMA/",
133     key = "boot-book"
134   )
135)
136
137## Combine and cite
138refs <- c(rref, bref)
139cite("R, boot-package", refs)
140
141## Cite numerically
142savestyle <- tools::getBibstyle()
143tools::bibstyle("JSSnumbered", .init = TRUE,
144         fmtPrefix = function(paper) paste0("[", paper$.index, "]"),
145         cite = function(key, bib, ...)
146         	citeNatbib(key, bib, mode = "numbers",
147         	    bibpunct = c("[", "]", ";", "n", "", ","), ...)
148         )
149cite("R, boot-package", refs, textual = TRUE)
150refs
151
152## restore the old style
153tools::bibstyle(savestyle, .default = TRUE)
154}
155\keyword{ utilities }
156\keyword{ documentation }
157