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