1% File src/library/utils/man/bibentry.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{bibentry}
7\title{Bibliography Entries}
8\alias{bibentry}
9\alias{print.bibentry}
10\alias{format.bibentry}
11\alias{sort.bibentry}
12\alias{print.citation}
13\alias{format.citation}
14\description{
15  Functionality for representing and manipulating bibliographic
16  information in enhanced BibTeX style.
17}
18\usage{
19bibentry(bibtype, textVersion = NULL, header = NULL, footer = NULL,
20         key = NULL, \dots, other = list(),
21         mheader = NULL, mfooter = NULL)
22
23\method{print}{bibentry}(x, style = "text", .bibstyle, \dots)
24
25\method{format}{bibentry}(x, style = "text", .bibstyle = NULL,
26       citation.bibtex.max = getOption("citation.bibtex.max", 1),
27       bibtex = length(x) <= citation.bibtex.max,
28       sort = FALSE, macros = NULL, \dots)
29
30\method{sort}{bibentry}(x, decreasing = FALSE, .bibstyle = NULL, drop = FALSE, \dots)
31
32\method{print}{citation}(x, style = "citation", \dots)
33\method{format}{citation}(x, style = "citation", \dots)
34}
35\arguments{
36  \item{bibtype}{a character string with a BibTeX entry type.
37    See \bold{Entry Types} for details.
38  }
39  \item{textVersion}{a character string with a text representation of
40    the reference to optionally be employed for printing.  It is
41    recommended to leave this unspecified if
42    \code{format(x, style = "text")}
43    works correctly.  Only if special LaTeX macros (e.g., math
44    formatting) or special characters (e.g., with accents) are
45    necessary, a \code{textVersion} should be provided.
46  }
47  \item{header}{a character string with optional header text.}
48  \item{footer}{a character string with optional footer text.}
49  \item{key}{a character string giving the citation key for the entry.}
50  \item{\dots}{for \code{bibentry}: arguments of the form
51    \code{\var{tag}=\var{value}} giving the fields of the entry, with
52    \var{tag} and \var{value} the name and value of the field,
53    respectively.  Arguments with empty values are dropped.
54    See \bold{Entry Fields} for details.
55
56    For the \code{print()} method, extra arguments to pass to the
57    renderer which typically includes the \code{format()} method.
58
59    For the \code{citation} class methods, arguments passed to the next
60    method, i.e., the corresponding \code{bibentry} one.
61  }
62  \item{other}{a list of arguments as in \code{\dots} (useful in
63    particular for fields named the same as formals of
64    \code{bibentry}).}
65  \item{mheader}{a character string with optional \dQuote{outer} header
66    text.}
67  \item{mfooter}{a character string with optional \dQuote{outer} footer
68    text.}
69  \item{x}{an object inheriting from class \code{"bibentry"}.}
70  \item{style}{an optional character string specifying the print style.
71    If present, must be a unique abbreviation (with case ignored) of the available
72    styles, see \bold{Details}.}
73  \item{decreasing}{logical, passed to \code{\link{order}} indicating
74    the sort direction.}
75  \item{.bibstyle}{a character string naming a bibliography style.}
76  \item{citation.bibtex.max}{(\emph{deprecated}, use
77    \code{bibtex = T|F}
78    instead!) a number, say \eqn{m}, indicating that the bibtex
79    code should be given in addition to the formatted tex \emph{when}
80    there are not more than \eqn{m} entries.  The default is taken as
81    \code{\link{getOption}("citation.bibtex.max", 1)} which is \code{1}
82    typically.  For example, to see no bibtex at all, you can change the
83    default by \code{\link{options}(citation.bibtex.max = 0)}.}
84  \item{bibtex}{logical indicating if bibtex code should be given
85    additionally; currently applies only to \code{style = "citation"}.
86    The default depends on on the number of (bib) entries and
87    \code{\link{getOption}("citation.bibtex.max")}.}
88  \item{sort}{logical indicating if bibentries should be sorted, using
89    \code{\link[tools]{bibstyle}(.bibstyle)$sortKeys(x)}.}
90  \item{macros}{a character string or an object with already loaded Rd
91    macros, see \bold{Details}.}
92  \item{drop}{logical used as \code{x[ ..., drop=drop]} inside the
93    \code{sort()} method.}
94}
95\details{
96  The bibentry objects created by \code{bibentry} can represent an
97  arbitrary positive number of references.  One can use \code{c()} to
98  combine bibentry objects, and hence in particular build a multiple
99  reference object from single reference ones.  Alternatively, one can
100  use \code{bibentry} to directly create a multiple reference object by
101  \dQuote{vectorizing} the given arguments, i.e., use character vectors
102  instead of character strings.
103
104  The \code{\link{print}} method for bibentry objects provides a choice
105  between seven different styles:
106  plain text (style \code{"text"}),
107  BibTeX (\code{"Bibtex"}),
108  a mixture of plain text and BibTeX as traditionally used for citations
109  (\code{"citation"}),
110  HTML (\code{"html"}),
111  LaTeX (\code{"latex"}),
112  R code (\code{"R"}),
113  and a simple copy of the \code{textVersion} elements (style
114  \code{"textVersion"}).
115  The \code{"text"}, \code{"html"} and \code{"latex"} styles make use
116  of the \code{.bibstyle} argument using the \code{\link{bibstyle}}
117  function.  In addition, one can use the \code{macros} argument to
118  provide additional (otherwise unknown, presumably LaTeX-style) Rd
119  macros, either by giving the path to a file with Rd macros to be
120  loaded via \code{\link[tools]{loadRdMacros}}, or an object with macros
121  already loaded.
122
123  When printing bibentry objects in citation style, a
124  \code{header}/\code{footer} for each item can be displayed as well as
125  a \code{mheader}/\code{mfooter} for the whole vector of references.
126
127  The \code{\link{print}} method is based on a \code{\link{format}}
128  method which provides the same styles, and for formatting as R code
129  a choice between giving a character vector with one \code{bibentry()}
130  call for each bibentry (as commonly used in \file{CITATION} files), or
131  a character string with one collapsed call, obtained by combining the
132  individual calls with \code{c()} if there is more than one bibentry.
133  This can be controlled by setting the option \code{collapse} to
134  \code{FALSE} (default) or \code{TRUE}, respectively.  (Printing in R
135  style always collapses to a single call.)  Further, for the
136  \code{"citation"} style, \code{format()}'s optional argument
137  \code{citation.bibtex.max} (with default
138  \code{\link{getOption}("citation.bibtex.max")} which defaults to 1)
139  determines for up to how many citation bibentries text style is shown
140  together with bibtex, automatically.
141
142  It is possible to subscript bibentry objects by their keys (which are
143  used for character subscripts if the names are \code{NULL}).
144
145  There is also a \code{\link{toBibtex}} method for direct conversion to
146  BibTeX.
147}
148\value{
149  \code{bibentry} produces an object of class \code{"bibentry"}.
150}
151\section{Entry Types}{
152  \code{bibentry} creates \code{"bibentry"} objects, which are modeled
153  after BibTeX entries.  The entry should be a valid BibTeX entry type,
154  e.g.,
155  \describe{
156    \item{Article:}{An article from a journal or magazine.}
157    \item{Book:}{A book with an explicit publisher.}
158    \item{InBook:}{A part of a book, which may be a chapter (or section
159      or whatever) and/or a range of pages.}
160    \item{InCollection:}{A part of a book having its own title.}
161    \item{InProceedings:}{An article in a conference proceedings.}
162    \item{Manual:}{Technical documentation like a software manual.}
163    \item{MastersThesis:}{A Master's thesis.}
164    \item{Misc:}{Use this type when nothing else fits.}
165    \item{PhdThesis:}{A PhD thesis.}
166    \item{Proceedings:}{The proceedings of a conference.}
167    \item{TechReport:}{A report published by a school or other
168      institution, usually numbered within a series.}
169    \item{Unpublished:}{A document having an author and title, but not
170      formally published.}
171  }
172}
173\section{Entry Fields}{
174  The \code{\dots} argument of \code{bibentry} can be any number of
175  BibTeX fields, including
176  \describe{
177    \item{address:}{The address of the publisher or other type of
178      institution.}
179
180    \item{author:}{The name(s) of the author(s), either as a
181      \code{\link{person}} object, or as a character string which
182      \code{\link{as.person}} correctly coerces to such.}
183
184    \item{booktitle:}{Title of a book, part of which is being cited.}
185    \item{chapter:}{A chapter (or section or whatever) number.}
186
187    \item{doi:}{The DOI
188      (\url{https://en.wikipedia.org/wiki/Digital_Object_Identifier})
189      for the reference.}
190
191    \item{editor:}{Name(s) of editor(s), same format as \code{author}.}
192
193    \item{institution:}{The publishing institution of a technical report.}
194
195    \item{journal:}{A journal name.}
196
197    \item{note:}{Any additional information that can help the reader.
198      The first word should be capitalized.}
199
200    \item{number:}{The number of a journal, magazine, technical report,
201      or of a work in a series.}
202
203    \item{pages:}{One or more page numbers or range of numbers.}
204
205    \item{publisher:}{The publisher's name.}
206
207    \item{school:}{The name of the school where a thesis was written.}
208
209    \item{series:}{The name of a series or set of books.}
210
211    \item{title:}{The work's title.}
212
213    \item{url:}{A URL for the reference.
214      (If the URL is an expanded DOI, we recommend to use the \samp{doi}
215      field with the unexpanded DOI instead.)}
216
217    \item{volume:}{The volume of a journal or multi-volume book.}
218
219    \item{year:}{The year of publication.}
220  }
221}
222\seealso{
223  \code{\link{person}}
224}
225\examples{
226## R reference
227rref <- bibentry(
228   bibtype = "Manual",
229   title = "R: A Language and Environment for Statistical Computing",
230   author = person("R Core Team"),
231   organization = "R Foundation for Statistical Computing",
232   address = "Vienna, Austria",
233   year = 2014,
234   url = "https://www.R-project.org/")
235
236## Different printing styles
237print(rref)
238print(rref, style = "Bibtex")
239print(rref, style = "citation")
240print(rref, style = "html")
241print(rref, style = "latex")
242print(rref, style = "R")
243
244## References for boot package and associated book
245bref <- c(
246   bibentry(
247     bibtype = "Manual",
248     title = "boot: Bootstrap R (S-PLUS) Functions",
249     author = c(
250       person("Angelo", "Canty", role = "aut",
251         comment = "S original"),
252       person(c("Brian", "D."), "Ripley", role = c("aut", "trl", "cre"),
253         comment = "R port, author of parallel support",
254         email = "ripley@stats.ox.ac.uk")
255     ),
256     year = "2012",
257     note = "R package version 1.3-4",
258     url = "https://CRAN.R-project.org/package=boot",
259     key = "boot-package"
260   ),
261
262   bibentry(
263     bibtype = "Book",
264     title = "Bootstrap Methods and Their Applications",
265     author = as.person("Anthony C. Davison [aut], David V. Hinkley [aut]"),
266     year = "1997",
267     publisher = "Cambridge University Press",
268     address = "Cambridge",
269     isbn = "0-521-57391-2",
270     url = "http://statwww.epfl.ch/davison/BMA/",
271     key = "boot-book"
272   )
273)
274
275## Combining and subsetting
276c(rref, bref)
277bref[2]
278bref["boot-book"]
279
280## Extracting fields
281bref$author
282bref[1]$author
283bref[1]$author[2]$email
284
285## Convert to BibTeX
286toBibtex(bref)
287
288## Format in R style
289## One bibentry() call for each bibentry:
290writeLines(paste(format(bref, "R"), collapse = "\n\n"))
291## One collapsed call:
292writeLines(format(bref, "R", collapse = TRUE))
293}
294\keyword{ utilities }
295\keyword{ documentation }
296