% $Id: biblatex.tex,v 0.9a 2010/03/19 19:52:15 lehman beta $ \documentclass{ltxdockit}[2010/02/12] \usepackage{btxdockit} \usepackage[latin9]{inputenc} \usepackage[american]{babel} \usepackage[strict,babel=once]{csquotes} \usepackage{tabularx} \usepackage{booktabs} \usepackage{shortvrb} \MakeAutoQuote{«}{»} \MakeAutoQuote*{<}{>} \MakeShortVerb{\|} \rcsid{$Id: biblatex.tex,v 0.9a 2010/03/19 19:52:15 lehman beta $} \newcommand*{\BiblatexHome}{http://sourceforge.net/projects/biblatex/} \newcommand*{\BiblatexOnCTAN}{http://www.ctan.org/tex-archive/macros/latex/exptl/biblatex/} \titlepage{% title={The \sty{biblatex} package}, subtitle={Programmable bibliographies and citations}, url={\BiblatexHome}, author={Philipp Lehman}, email={plehman@gmx.net}, revision={\rcsrevision}, date={\rcstoday}} \hypersetup{% pdftitle={The biblatex package}, pdfsubject={Programmable bibliographies and citations}, pdfauthor={Philipp Lehman}, pdfkeywords={tex, latex, bibtex, bibliography, references, citation}} % tables \newcolumntype{H}{>{\sffamily\bfseries\spotcolor}l} \newcolumntype{P}{>{\raggedright}p{100pt}} \newcolumntype{O}{>{\raggedright\ttfamily}p{40pt}} \newcolumntype{S}{>{\raggedright\ttfamily}X} \newcolumntype{N}{>{\sffamily\bfseries\spotcolor}r} \newcolumntype{n}{>{\raggedleft\let\\\tabularnewline}p{50pt}} \providecommand*{\numtablesetup}{\tablesetup} \newcommand*{\sorttablesetup}{% \tablesetup \setlength{\tabcolsep}{1pt}% \def\new{\ensuremath\rightarrow}% \def\alt{\ensuremath\hookrightarrow}% \def\str##1{\mbox{\displayverbfont##1}}% \def\altstr##1{\hfill\alt\hspace{2\tabcolsep}% \str{##1}\hspace*{2\tabcolsep}}% \let\fld\bibfield} % markup and misc \setcounter{secnumdepth}{4} % hyphenation \hyphenation{% star-red bib-lio-gra-phy white-space } \begin{document} \printtitlepage \tableofcontents \section{Introduction} \label{int} This document is a systematic reference manual for the \sty{biblatex} package. Look at the sample documents which ship with this package to get a first impression.\fnurl{\BiblatexOnCTAN/doc/examples} For a quick start guide, browse \secref{int:abt, bib:typ, bib:fld, bib:use, use:opt, use:xbx, use:bib, use:cit, use:use}. \subsection{About} \label{int:abt} This package provides advanced bibliographic facilities for use with \latex in conjunction with \bibtex. The package is a complete reimplementation of the bibliographic facilities provided by \latex. It redesigns the way in which \latex interacts with \bibtex at a fairly fundamental level. With \sty{biblatex}, \bibtex is only used to sort the bibliography and to generate labels. Instead of being implemented in \file{bst} files, the formatting of the bibliography is entirely controlled by \latex macros, hence the name \sty{biblatex}. Good working knowledge in \latex should be sufficient to design new bibliography and citation styles. There is no need to learn \bibtex's postfix stack language. This package also supports subdivided bibliographies, multiple bibliographies within one document, and separate lists of bibliographic shorthands. Bibliographies may be subdivided into parts and\slash or segmented by topics. Just like the bibliography styles, all citation commands may be freely defined. The package is completely localized and can interface with the \sty{babel} package. Please refer to \tabref{bib:fld:tab1} for a list of languages currently supported by this package. \subsection{License} Copyright \textcopyright\ 2006--2010 Philipp Lehman. Permission is granted to copy, distribute and\slash or modify this software under the terms of the \lppl, version 1.3.\fnurl{http://www.ctan.org/tex-archive/macros/latex/base/lppl.txt} This package is author"=maintained. \subsection[Feedback]{Feedback and Acknowledgments} \label{int:feb} Please use the \sty{biblatex} project page on SourceForge to report bugs and submit feature requests.\fnurl{http://sourceforge.net/projects/biblatex/} There are two trackers on this page: \texttt{Bugs} for bug reports and \texttt{Features} for feature requests.\fnurl{http://sourceforge.net/tracker2/?group_id=244752} Select a tracker, then click on to submit your report or request. I may consider implementing a new feature if the request is reasonable, seems to be relevant to a considerable number of users, and complies with the architecture and philosophy of \sty{biblatex}. Before making a feature request, please ensure that you have thoroughly studied this manual. If you do not want to report a bug or request a feature but are simply in need of assistance, you might want to consider posting your question on the \texttt{comp.text.tex} newsgroup. I can not provide end-user support by email or via the project page. The language modules of this package include contributions by (in the order of submission): Ignacio Fernández Galván (Spanish), Enrico Gregorio (Italian), Johannes Wilm (Danish and Norwegian), Per Starbäck, Carl-Gustav Werner, Filip Åsblom (Swedish), Augusto Ritter Stoffel (Portuguese/Brazilian), Alexander van Loon (Dutch), Apostolos Syropoulos (Greek), Hannu Väisänen (Finnish). \subsection{Prerequisites} \label{int:pre} This section gives an overview of all resources required by this package and discusses compatibility issues. \subsubsection{Requirements} \label{int:pre:req} The resources listed in this section are strictly required for \sty{biblatex} to function. The package will not work if they are not available. \begin{marglist} \item[\etex] The \sty{biblatex} package requires \etex. \tex distributions have been shipping \etex binaries for quite some time, the popular distributions use them by default these days. The \sty{biblatex} package checks if it is running under \etex. Simply try compiling your documents as you usually do, the chances are that it just works. If you get an error message, try compiling the document with \bin{elatex} instead of \bin{latex} or \bin{pdfelatex} instead of \bin{pdflatex}, respectively. \item[\bibtex] By default, the \sty{biblatex} package uses \bibtex as a database backend. While a legacy \bibtex binary is sufficient to run \sty{biblatex}, using \bin{bibtex8} is recommended. If your \tex distribution does not ship with \bin{bibtex8}, you can get it from \acr{CTAN}.\fnurl{http://www.ctan.org/tex-archive/biblio/bibtex/8-bit/} \item[Biber] Biber is the next"=generation backend of \sty{biblatex}. It is currently under development but may already be used instead of \bibtex. You only need one backend, either \bibtex or Biber. Biber is available from SourceForge.\fnurl{http://biblatex-biber.sourceforge.net/} \item[etoolbox] This \latex package, which is loaded automatically, provides generic programming facilities required by \sty{biblatex}. It is readily available from \acr{CTAN}.\fnurl{http://www.ctan.org/tex-archive/macros/latex/contrib/etoolbox/} \end{marglist} Apart from the above resources, \sty{biblatex} also requires the standard \latex packages \sty{keyval} and \sty{ifthen} as well as the \sty{url} package. These package are included in all common \tex distributions and will be loaded automatically. If the \opt{bibencoding} package option is enabled, the \sty{inputenc} package is required in addition to that. Note that \sty{inputenc} is not loaded automatically. \subsubsection{Recommended packages} \label{int:pre:rec} The packages listed in this section are not required for \sty{biblatex} to function, but they provide recommended additional functions or enhance existing features. The package loading order does not matter. \begin{marglist} \item[babel] The \sty{babel} package provides the core architecture for multilingual typesetting. If you are writing in a language other than American English, using this package is strongly recommended. If loaded, \sty{biblatex} package will detect \sty{babel} automatically. \item[csquotes] If this package is available, \sty{biblatex} will use its language sensitive quotation facilities to enclose certain titles in quotation marks. If not, \sty{biblatex} uses quotes suitable for American English as a fallback. When writing in any other language, loading \sty{csquotes} is strongly recommended.\fnurl{http://www.ctan.org/tex-archive/macros/latex/contrib/csquotes/} \end{marglist} \subsubsection{Compatible classes and packages} \label{int:pre:cmp} The \sty{biblatex} package provides dedicated compatibility code for the classes and packages listed in this section. \begin{marglist} \item[hyperref] The \sty{hyperref} package transforms citations into hyperlinks. See the \opt{hyperref} and \opt{backref} package options in \secref{use:opt:pre} for further details. When using the \sty{hyperref} package, it is preferable to load it after \sty{biblatex}. \item[showkeys] The \sty{showkeys} package prints the internal keys of, among other things, citations in the text and items in the bibliography. The package loading order does not matter. \item[memoir] When using the \sty{memoir} class, the default bibliography headings are adapted such that they blend well with the default layout of this class. See \secref{use:cav:mem} for further usage hints. \item[\acr{KOMA}-Script] When using any of the \sty{scrartcl}, \sty{scrbook}, or \sty{scrreprt} classes, the default bibliography headings are adapted such that they blend with the default layout of these classes. See \secref{use:cav:scr} for further usage hints. \end{marglist} \subsubsection{Incompatible packages} \label{int:pre:inc} The packages listed in this section are not compatible with \sty{biblatex}. Since it reimplements the bibliographic facilities of \latex from the ground up, \sty{biblatex} naturally conflicts with all packages modifying the same facilities. This is not specific to \sty{biblatex}. Some of the packages listed below are also incompatible with each other for the same reason. \begin{marglist} % FIXME: complete list % % amsrefs % apacite % drftcite % footbib % multibbl % overcite \item[babelbib] The \sty{babelbib} package provides support for multilingual bibliographies. This is a standard feature of \sty{biblatex}. Use the \bibfield{hyphenation} field and the package option \opt{babel} for similar functionality. Note that \sty{biblatex} automatically adjusts to the main document language if \sty{babel} is loaded. You only need the above mentioned features if you want to switch languages on a per"=entry basis within the bibliography. See \secref{bib:fld:spc, use:opt:pre} for details. Also see \secref{use:lng}. \item[backref] The \sty{backref} package creates back references in the bibliography. See the package options \opt{hyperref} and \opt{backref} in \secref{use:opt:pre} for comparable functionality. \item[bibtopic] The \sty{bibtopic} package provides support for bibliographies subdivided by topic, type, or other criteria. For bibliographies subdivided by topic, see the category feature in \secref{use:bib:cat} and the corresponding filters in \secref{use:bib:bib}. Alternatively, you may use the \bibfield{keywords} field in conjunction with the \opt{keyword} and \opt{notkeyword} filters for comparable functionality, see \secref{bib:fld:spc, use:bib:bib} for details. For bibliographies subdivided by type, use the \opt{type} and \opt{nottype} filters. Also see \secref{use:use:div} for examples. \item[bibunits] The \sty{bibunits} package provides support for multiple partial (\eg per chapter) bibliographies. See \sty{chapterbib}. \item[chapterbib] The \sty{chapterbib} package provides support for multiple partial bibliographies. Use the \env{refsection} environment and the \opt{section} filter for comparable functionality. Alternatively, you might also want to use the \env{refsegment} environment and the \opt{segment} filter. See \secref{use:bib:sec, use:bib:seg, use:bib:bib} for details. Also see \secref{use:use:mlt} for examples. \item[cite] The \sty{cite} package automatically sorts numeric citations and can compress a list of consecutive numbers to a range. It also makes the punctuation used in citations configurable. For sorted and compressed numeric citations, see the \opt{sortcites} package option in \secref{use:opt:pre} and the \texttt{numeric-comp} citation style in \secref{use:xbx:cbx}. For configurable punctuation, see \secref{use:fmt}. \item[citeref] Another package for creating back references in the bibliography. See \sty{backref}. \item[inlinebib] The \sty{inlinebib} package is designed for traditional citations given in footnotes. For comparable functionality, see the verbose citation styles in \secref{use:xbx:cbx}. \item[jurabib] Originally designed for citations in law studies and (mostly German) judicial documents, the \sty{jurabib} package also provides features aimed at users in the humanities. In terms of the features provided, there are some similarities between \sty{jurabib} and \sty{biblatex} but the approaches taken by both packages are quite different. Since both \sty{jurabib} and \sty{biblatex} are full"=featured packages, the list of similarities and differences is too long to be discussed here. \item[mcite] The \sty{mcite} package provides support for the grouping of multiple citations, \ie multiple items can be cited as a single reference and listed as a single block in the bibliography. The citation groups are defined as the items are cited. This only works with unsorted bibliographies. The \sty{biblatex} package also supports grouped citations, which are called or in this manual, but the approach is different. With \sty{biblatex}, reference sets are defined in the \sty{bib} file and cited just like any other entry. See the entry type \bibtype{set} in \secref{bib:typ:blx} and \secref{use:use:set} for details. \item[mciteplus] A significantly enhanced reimplementation of the \sty{mcite} package which supports grouping in sorted bibliographies. See \sty{mcite}. \item[multibib] The \sty{multibib} package provides support for bibliographies subdivided by topic or other criteria. See \sty{bibtopic}. \item[natbib] The \sty{natbib} package supports numeric and author"=year citation schemes, incorporating sorting and compression code found in the \sty{cite} package. It also provides additional citation commands and several configuration options. See the \texttt{numeric} and \texttt{author-year} citation styles and their variants in \secref{use:xbx:cbx}, the \opt{sortcites} package option in \secref{use:opt:pre}, the citation commands in \secref{use:cit}, and the facilities discussed in \secref{use:bib:hdg, use:bib:nts, use:fmt} for comparable functionality. Also see \secref{use:cit:nat}. \item[splitbib] The \sty{splitbib} package provides support for bibliographies subdivided by topic. See \sty{bibtopic}. \end{marglist} \section{Database guide} \label{bib} This part of the manual documents the \bibtex interface of this package. Note that you can not use \sty{biblatex} in conjunction with arbitrary \file{bst} files because the package depends on a special \bibtex interface. \subsection{Entry types} \label{bib:typ} This section gives an overview of the entry types supported by \sty{biblatex} along with the fields supported by each type. \subsubsection{Regular types} \label{bib:typ:blx} The lists below indicate the fields supported by each entry type. Note that the mapping of fields to an entry type is ultimately at the discretion of the bibliography style. The lists below therefore serve two purposes. They indicate the fields supported by the standard styles which ship with this package and they also serve as a model for custom styles. Note that the fields are not strictly required in all cases, see \secref{bib:use:key} for details. The fields marked as are optional in a technical sense. Bibliographical formatting rules usually require more than just the fields. The standard styles will generally not perform any formal validity checks, but custom styles may do so. Generic fields like \bibfield{abstract} and \bibfield{annotation} or \bibfield{label} and \bibfield{shorthand} are not included in the lists below because they are independent of the entry type. The special fields discussed in \secref{bib:fld:spc}, which are also independent of the entry type, are not included in the lists either. \begin{typelist} \typeitem{article} An article in a journal, magazine, newspaper, or other periodical which forms a self"=contained unit with its own title. The title of the periodical is given in the \bibfield{journaltitle} field. If the issue has its own title in addition to the main title of the periodical, it goes in the \bibfield{issuetitle} field. Note that \bibfield{editor} and related fields refer to the journal while \bibfield{translator} and related fields refer to the article. \reqitem{author, title, journaltitle, year/date} \optitem{translator, annotator, commentator, subtitle, titleaddon, editor, editora, editorb, editorc, journalsubtitle, issuetitle, issuesubtitle, language, origlanguage, series, volume, number, eid, issue, date, month, year, pages, version, note, issn, addendum, pubstate doi, eprint, eprinttype, url, urldate} \typeitem{book} A book with one or more authors where the authors share credit for the work as a whole. Note that this entry type also covers the function of the \bibtype{inbook} type of traditional \bibtex, see \secref{bib:use:inb} for details. \reqitem{author, title, year/date} \optitem{editor, editora, editorb, editorc, translator, annotator, commentator, introduction, foreword, afterword, subtitle, titleaddon, maintitle, mainsubtitle, maintitleaddon, language, origlanguage, volume, part, edition, volumes, series, number, note, publisher, location, isbn, chapter, pages, pagetotal, addendum, pubstate doi, eprint, eprinttype, url, urldate} \typeitem{inbook} A part of a book which forms a self"=contained unit with its own title. Note that the profile of this entry type is different from standard \bibtex, see \secref{bib:use:inb}. \reqitem{author, title, booktitle, year/date} \optitem{bookauthor, editor, editora, editorb, editorc, translator, annotator, commentator, introduction, foreword, afterword, subtitle, titleaddon, maintitle, mainsubtitle, maintitleaddon, booksubtitle, booktitleaddon, language, origlanguage, volume, part, edition, volumes, series, number, note, publisher, location, isbn, chapter, pages, addendum, pubstate doi, eprint, eprinttype, url, urldate} \typeitem{bookinbook} Similar to \bibtype{inbook} but intended for items originally published as a stand-alone book. A typical example are books reprinted in the collected works of an author. \typeitem{suppbook} Supplemental material in a \bibtype{book}. This type is closely related to the \bibtype{inbook} entry type. While \bibtype{inbook} is primarily intended for a part of a book with its own title (\eg a single essay in a collection of essays by the same author), this type is provided for elements such as prefaces, introductions, forewords, afterwords, etc. which often have a generic title only. Style guides may require such items to be formatted differently from other \bibtype{inbook} items. The standard styles will treat this entry type as an alias of \bibtype{inbook}. \typeitem{booklet} A book"=like work without a formal publisher or sponsoring institution. Use the field \bibfield{howpublished} to supply publishing information in free format, if applicable. The field \bibfield{type} may be useful as well. \reqitem{author/editor, title, year/date} \optitem{subtitle, titleaddon, language, howpublished, type, note, location, chapter, pages, pagetotal, addendum, pubstate doi, eprint, eprinttype, url, urldate} \typeitem{collection} A book with multiple, self"=contained contributions by distinct authors which have their own title. The work as a whole has no overall author but it will usually have an editor. \reqitem{editor, title, year/date} \optitem{editora, editorb, editorc, translator, annotator, commentator, introduction, foreword, afterword, subtitle, titleaddon, maintitle, mainsubtitle, maintitleaddon, language, origlanguage, volume, part, edition, volumes, series, number, note, publisher, location, isbn, chapter, pages, pagetotal, addendum, pubstate doi, eprint, eprinttype, url, urldate} \typeitem{incollection} A contribution to a collection which forms a self"=contained unit with a distinct author and title. The \bibfield{author} refers to the \bibfield{title}, the \bibfield{editor} to the \bibfield{booktitle}, \ie the title of the collection. \reqitem{author, editor, title, booktitle, year/date} \optitem{editora, editorb, editorc, translator, annotator, commentator, introduction, foreword, afterword, subtitle, titleaddon, maintitle, mainsubtitle, maintitleaddon, booksubtitle, booktitleaddon, language, origlanguage, volume, part, edition, volumes, series, number, note, publisher, location, isbn, chapter, pages, addendum, pubstate doi, eprint, eprinttype, url, urldate} \typeitem{suppcollection} Supplemental material in a \bibtype{collection}. This type is similar to \bibtype{suppbook} but related to the \bibtype{collection} entry type. The standard styles will treat this entry type as an alias of \bibtype{incollection}. \typeitem{manual} Technical or other documentation, not necessarily in printed form. The \bibfield{author} or \bibfield{editor} is omissible in terms of \secref{bib:use:key}. \reqitem{author/editor, title, year/date} \optitem{subtitle, titleaddon, language, edition, type, series, number, version, note, organization, publisher, location, isbn, chapter, pages, pagetotal, addendum, pubstate doi, eprint, eprinttype, url, urldate} \typeitem{misc} A fallback type for entries which do not fit into any other category. Use the field \bibfield{howpublished} to supply publishing information in free format, if applicable. The field \bibfield{type} may be useful as well. \bibfield{author}, \bibfield{editor}, and \bibfield{year} are omissible in terms of \secref{bib:use:key}. \reqitem{author/editor, title, year/date} \optitem{subtitle, titleaddon, language, howpublished, type, version, note, organization, location, date, month, year, addendum, pubstate doi, eprint, eprinttype, url, urldate} \typeitem{online} An online resource. \bibfield{author}, \bibfield{editor}, and \bibfield{year} are omissible in terms of \secref{bib:use:key}. This entry type is intended for sources such as web sites which are intrinsicly online resources. Note that all entry types support the \bibfield{url} field. For example, when adding an article from a journal which happens to be available online, use the \bibtype{article} type and its \bibfield{url} field. \reqitem{author/editor, title, year/date, url} \optitem{subtitle, titleaddon, language, version, note, organization, date, month, year, addendum, pubstate urldate} \typeitem{patent} A patent or patent request. The number or record token is given in the \bibfield{number} field. Use the \bibfield{type} field to specify the type and the \bibfield{location} field to indicate the scope of the patent, if different from the scope implied by the \bibfield{type}. Note that the \bibfield{location} field is treated as a key list with this entry type, see \secref{bib:fld:typ} for details. \reqitem{author, title, number, year/date} \optitem{holder, subtitle, titleaddon, type, version, location, note, date, month, year addendum, pubstate url, urldate} \typeitem{periodical} An entire issue of a periodical, such as a special issue of a journal. The title of the periodical is given in the \bibfield{title} field. If the issue has its own title in addition to the main title of the periodical, it goes in the \bibfield{issuetitle} field. The \bibfield{editor} is omissible in terms of \secref{bib:use:key}. \reqitem{editor, title, year/date} \optitem{editora, editorb, editorc, subtitle, issuetitle, issuesubtitle, language, series, volume, number, issue, date, month, year, note, issn, addendum, pubstate doi, eprint, eprinttype, url, urldate} \typeitem{suppperiodical} Supplemental material in a \bibtype{periodical}. This type is similar to \bibtype{suppbook} but related to the \bibtype{periodical} entry type. The role of this entry type may be more obvious if you bear in mind that the \bibtype{article} type could also be called \bibtype{inperiodical}. This type may be useful when referring to items such as regular columns, obituaries, letters to the editor, etc. which only have a generic title. Style guides may require such items to be formatted differently from articles in the strict sense of the word. The standard styles will treat this entry type as an alias of \bibtype{article}. \typeitem{proceedings} The proceedings of a conference. This type is similar to \bibtype{collection}. It supports an optional \bibfield{organization} field which holds the sponsoring institution. The \bibfield{editor} is omissible in terms of \secref{bib:use:key}. \reqitem{editor, title, year/date} \optitem{subtitle, titleaddon, maintitle, mainsubtitle, maintitleaddon, eventtitle, eventdate, venue, language, volume, part, volumes, series, number, note, organization, publisher, location, month, isbn, chapter, pages, pagetotal, addendum, pubstate doi, eprint, eprinttype, url, urldate} \typeitem{inproceedings} An article in a conference proceedings. This type is similar to \bibtype{incollection}. It supports an optional \bibfield{organization} field. \reqitem{author, editor, title, booktitle, year/date} \optitem{subtitle, titleaddon, maintitle, mainsubtitle, maintitleaddon, booksubtitle, booktitleaddon, eventtitle, eventdate, venue, language, volume, part, volumes, series, number, note, organization, publisher, location, month, isbn, chapter, pages, addendum, pubstate doi, eprint, eprinttype, url, urldate} \typeitem{reference} Works of reference such as encyclopedias and dictionaries. This is a more specific variant of the generic \bibtype{collection} entry type. The standard styles will treat this entry type as an alias of \bibtype{collection}. \typeitem{inreference} Articles in a work of reference. This is a more specific variant of the generic \bibtype{incollection} entry type. The standard styles will treat this entry type as an alias of \bibtype{incollection}. \typeitem{report} A technical report, research report, or white paper published by a university or some other institution. Use the \bibfield{type} field to specify the type of report. The sponsoring institution goes in the \bibfield{institution} field. \reqitem{author, title, type, institution, year/date} \optitem{subtitle, titleaddon, language, number, version, note, location, month, isrn, chapter, pages, pagetotal, addendum, pubstate doi, eprint, eprinttype, url, urldate} \typeitem{set} A reference set. This entry type is special, see \secref{use:use:set} for details. \reqitem{entryset, crossref} \optitem{all} \typeitem{thesis} A thesis written for an educational institution to satisfy the requirements for a degree. Use the \bibfield{type} field to specify the type of thesis. \reqitem{author, title, type, institution, year/date} \optitem{subtitle, titleaddon, language, note, location, month, chapter, pages, pagetotal, addendum, pubstate doi, eprint, eprinttype, url, urldate} \typeitem{unpublished} A work with an author and a title which has not been formally published, such as a manuscript or the script of a talk. Use the fields \bibfield{howpublished} and \bibfield{note} to supply additional information in free format, if applicable. \reqitem{author, title, year/date} \optitem{subtitle, titleaddon, language, howpublished, note, date, month, year, addendum, pubstate url, urldate} \typeitem{custom[a--f]} Custom types for special bibliography styles. Not used by the standard styles. \end{typelist} \subsubsection{Type aliases} \label{bib:typ:als} The entry types listed in this section are provided for backwards compatibility with traditional \bibtex styles. These aliases are resolved by \bibtex as the data is exported. Bibliography styles will see the entry type the alias points to, not the alias name. All unknown entry types are generally exported as \bibtype{misc}. \begin{typelist} \typeitem{conference} A legacy alias of \bibtype{inproceedings}. \typeitem{electronic} An alias of \bibtype{online}. \typeitem{mastersthesis} Similar to \bibtype{thesis} except that the \bibfield{type} field is optional and defaults to the localized term . You may still use the \bibfield{type} field to override that. \typeitem{phdthesis} Similar to \bibtype{thesis} except that the \bibfield{type} field is optional and defaults to the localized term . You may still use the \bibfield{type} field to override that. \typeitem{techreport} Similar to \bibtype{report} except that the \bibfield{type} field is optional and defaults to the localized term . You may still use the \bibfield{type} field to override that. \typeitem{www} An alias of \bibtype{online}, provided for \sty{jurabib} compatibility. \end{typelist} \subsubsection{Unsupported types} \label{bib:typ:ctm} The types in this section are similar to the custom types \bibtype{customa} to \bibtype{customf}, \ie they will be exported from the \file{bib} file under their proper name rather than as \bibtype{misc} entries. This may be useful in custom bibliography styles. The standard bibliography styles provide no dedicated support for these types. When using the standard styles, they will either be ignored or treated as aliases of a related generic type (see below for details). \begin{typelist} \typeitem{artwork} Works of the visual arts such as paintings, sculpture, and installations. This type is currently ignored by the standard styles. \typeitem{audio} Audio recordings, typically on audio \acr{CD}, \acr{DVD}, audio casette, or similar media. This type is currently ignored by the standard styles. See also \bibtype{music}. \typeitem{commentary} Commentaries which have a status different from regular books, such as legal commentaries. This type is currently ignored by the standard styles. \typeitem{image} Images, pictures, photographs, and similar media. This type is currently ignored by the standard styles. \typeitem{jurisdiction} Court decisions, court recordings, and similar things. This type is currently ignored by the standard styles. \typeitem{legislation} Laws, bills, legislative proposals, and similar things. This type is currently ignored by the standard styles. \typeitem{legal} Legal documents such as treaties. This type is currently ignored by the standard styles. \typeitem{letter} Personal correspondence such as letters, emails, memoranda, etc. This type is currently ignored by the standard styles. \typeitem{movie} Motion pictures. This type is currently ignored by the standard styles. See also \bibtype{video}. \typeitem{music} Musical recordings. This is a more specific variant of \bibtype{audio}. This type is currently ignored by the standard styles. \typeitem{performance} Musical and theatrical performances as well as other works of the performing arts. This type refers to the event as opposed to a recording, a score, or a printed play. This type is currently ignored by the standard styles. \typeitem{review} Reviews of some other work. This is a more specific variant of the \bibtype{article} type. The standard styles will treat this entry type as an alias of \bibtype{article}. \typeitem{software} Computer software. This type is currently ignored by the standard styles. \typeitem{standard} National and international standards issued by a standards body such as the International Organization for Standardization. This type is currently ignored by the standard styles. \typeitem{video} Audiovisual recordings, typically on \acr{DVD}, \acr{VHS} casette, or similar media. This type is currently ignored by the standard styles. See also \bibtype{movie}. \end{typelist} \subsection{Entry fields} \label{bib:fld} This section gives an overview of the fields supported by \sty{biblatex}. See \secref{bib:fld:typ} for an introduction to the data types supported by this package and \secref{bib:fld:dat, bib:fld:spc} for the actual field listings. \subsubsection{Data types} \label{bib:fld:typ} In \file{bib} files all bibliographic data is specified in fields. Some of those fields, for example \bibfield{author} and \bibfield{editor}, may contain a list of items. This list structure is implemented by \bibtex via the keyword <|and|>, which is used to separate the individual items in the list. The \sty{biblatex} package implements three distinct data types to handle bibliographic data: name lists, literal lists, and fields. There are also several list and field subtypes. This section gives an overview of the data types supported by this package. See \secref{bib:fld:dat, bib:fld:spc} for information about the mapping of \bibtex's fields to \sty{biblatex}'s data types. \begin{description} \item[Name lists] are parsed and split up into the individual items at the \texttt{and} delimiter. Each item in the list is then dissected into four name components: the first name, the name prefix (von, van, of, da, de, della, \dots), the last name, and the name suffix (junior, senior, \dots). Name lists may be truncated in the \file{bib} file with the keyword <\texttt{and others}>. Typical examples of name lists are \bibfield{author} and \bibfield{editor}. \item[Literal lists] are parsed and split up into the individual items at the \texttt{and} delimiter but not dissected further. Literal lists may be truncated in the \file{bib} file with the keyword <\texttt{and others}>. There are two subtypes: \begin{description} \item[Literal lists] in the strict sense are handled as described above. The individual items are simply printed as is. Typical examples of such literal lists are \bibfield{publisher} and \bibfield{location}. \item[Key lists] are a variant of literal lists which may hold printable data or localization keys. For each item in the list, a test is performed to determine whether it is a known localization key (the localization keys defined by default are listed in \secref{aut:lng:key}). If so, the localized string is printed. If not, the item is printed as is. A typical example of a key list is \bibfield{language}. \end{description} \end{description} \begin{description} \item[Fields] are usually printed as a whole. There are several subtypes: \begin{description} \item[Literal fields] are printed as is. Typical examples of literal fields are \bibfield{title} and \bibfield{note}. \item[Range fields] are literal fields with one special feature: all dashes are normalized and replaced by the command \cmd{bibrangedash}. Any number of consecutive dashes will only yield a single range dash. A typical example of a range field is the \bibfield{pages} field. \item[Integer fields] hold unformatted integers which may be converted to ordinals or strings as they are printed. A typical example is the \bibfield{month} field. \item[Date fields] hold a date specification in \texttt{yyyy-mm-dd} format or a date range in \texttt{yyyy-mm-dd/yyyy-mm-dd} format. Date fields are special in that the date is parsed and split up into its components. See \secref{bib:use:dat} for details. A typical example is the \bibfield{date} field. \item[Verbatim fields] are processed in verbatim mode and may contain special characters. Typical examples of verbatim fields are \bibfield{url} and \bibfield{doi}. \item[Key fields] may hold printable data or localization keys. A test is performed to determine whether the value of the field is a known localization key (the localization keys defined by default are listed in \secref{aut:lng:key}). If so, the localized string is printed. If not, the value is printed as is. A typical example is the \bibfield{type} field. \item[Special fields] are fields which require a special format not mentioned above. The field description will include details on the required format in this case. Typical examples are the fields \bibfield{hyphenation}, \bibfield{keywords}, and \bibfield{gender} from \secref{bib:fld:spc}. \end{description} \end{description} The data type of a field will usually not change, regardless of the type of entry it is used in. However, there are a few special cases. The field descriptions in \secref{bib:fld:dat} include the details or pointers to the relevant sections in this manual in such cases. For example, the \bibfield{location} field, which is a literal list by default, is treated as a key list when used in \bibtype{patent} entries. The \bibfield{series} field, which is a literal field by default, is handled in a special way when used in \bibtype{article} entries, see \secref{bib:use:ser} for details. \subsubsection{Data fields} \label{bib:fld:dat} The fields listed in this section are the regular ones holding printable data. The name on the left is the name of the field, as used by both \bibtex and \sty{biblatex}. The \sty{biblatex} data type is given to the right of the name. See \secref{bib:fld:typ} for explanation of the various data types. \begin{fieldlist} \fielditem{abstract}{literal} This field is intended for recording abstracts in a \file{bib} file, to be printed by a special bibliography style. It is not used by all standard bibliography styles. \fielditem{addendum}{literal} Miscellaneous bibliographic data to be printed at the end of the entry. This is similar to the \bibfield{note} field except that it is printed at the end of the bibliography entry. \listitem{afterword}{name} The author(s) of an afterword to the work. If the author of the afterword is identical to the \bibfield{editor} and\slash or \bibfield{translator}, the standard styles will automatically concatenate these fields in the bibliography. See also \bibfield{introduction} and \bibfield{foreword}. \fielditem{annotation}{literal} This field may be useful when implementing a style for annotated bibliographies. It is not used by all standard bibliography styles. Note that this field is completely unrelated to \bibfield{annotator}. The \bibfield{annotator} is the author of annotations which are part of the work cited. \listitem{annotator}{name} The author(s) of annotations to the work. If the annotator is identical to the \bibfield{editor} and\slash or \bibfield{translator}, the standard styles will automatically concatenate these fields in the bibliography. See also \bibfield{commentator}. \listitem{author}{name} The author(s) of the \bibfield{title}. \fielditem{authortype}{key} The type of author. This field will affect the string (if any) used to introduce the author. Not used by the standard bibliography styles. \listitem{bookauthor}{name} The author(s) of the \bibfield{booktitle}. \fielditem{bookpagination}{key} If the work is published as part of another one, this is the pagination scheme of the enclosing work, \ie \bibfield{bookpagination} relates to \bibfield{pagination} like \bibfield{booktitle} to \bibfield{title}. The value of this field will affect the formatting of the \bibfield{pages} and \bibfield{pagetotal} fields. The key should be given in the singular form. Possible keys are \texttt{page}, \texttt{column}, \texttt{line}, \texttt{verse}, \texttt{section}, and \texttt{paragraph}. See also \bibfield{pagination} as well as \secref{bib:use:pag}. \fielditem{booksubtitle}{literal} The subtitle related to the \bibfield{booktitle}. If the \bibfield{subtitle} field refers to a work which is part of a larger publication, a possible subtitle of the main work is given in this field. See also \bibfield{subtitle}. \fielditem{booktitle}{literal} If the \bibfield{title} field indicates the title of a work which is part of a larger publication, the title of the main work is given in this field. See also \bibfield{title}. \fielditem{booktitleaddon}{literal} An annex to the \bibfield{booktitle}, to be printed in a different font. \fielditem{chapter}{literal} A chapter or section or any other unit of a work. \listitem{commentator}{name} The author(s) of a commentary to the work. Note that this field is intended for commented editions which have a commentator in addition to the author. If the work is a stand"=alone commentary, the commentator should be given in the \bibfield{author} field. If the commentator is identical to the \bibfield{editor} and\slash or \bibfield{translator}, the standard styles will automatically concatenate these fields in the bibliography. See also \bibfield{annotator}. \fielditem{date}{date} The publication date. See also \bibfield{month} and \bibfield{year} as well as \secref{bib:use:dat}. \fielditem{doi}{verbatim} The Digital Object Identifier of the work. \fielditem{edition}{integer or literal} The edition of a printed publication. This must be an integer, not an ordinal. Don't say |edition={First}| or |edition={1st}| but |edition={1}|. The bibliography style converts this to a language dependent ordinal. It is also possible to give the edition as a literal string, for example «Third, revised and expanded edition». \listitem{editor}{name} The editor(s) of the \bibfield{title}, \bibfield{booktitle}, or \bibfield{maintitle}, depending on the entry type. Use the \bibfield{editortype} field to specifiy the role if it is different from <\texttt{editor}>. See \secref{bib:use:edr} for further hints. \listitem{editora}{name} A secondary editor performing a different editorial role, such as compiling, redacting, etc. Use the \bibfield{editoratype} field to specifiy the role. See \secref{bib:use:edr} for further hints. \listitem{editorb}{name} Another secondary editor performing a different role. Use the \bibfield{editorbtype} field to specifiy the role. See \secref{bib:use:edr} for further hints. \listitem{editorc}{name} Another secondary editor performing a different role. Use the \bibfield{editorctype} field to specifiy the role. See \secref{bib:use:edr} for further hints. \fielditem{editortype}{key} The type of editorial role performed by the \bibfield{editor}. Roles supported by default are \texttt{editor}, \texttt{compiler}, \texttt{founder}, \texttt{continuator}, \texttt{redactor}, \texttt{collaborator}. The role <\texttt{editor}> is the default. In this case, the field is omissible. See \secref{bib:use:edr} for further hints. \fielditem{editoratype}{key} Similar to \bibfield{editortype} but referring to the \bibfield{editora} field. See \secref{bib:use:edr} for further hints. \fielditem{editorbtype}{key} Similar to \bibfield{editortype} but referring to the \bibfield{editorb} field. See \secref{bib:use:edr} for further hints. \fielditem{editorctype}{key} Similar to \bibfield{editortype} but referring to the \bibfield{editorc} field. See \secref{bib:use:edr} for further hints. \fielditem{eid}{literal} The electronic identifier of an \bibtype{article}. \fielditem{eprint}{verbatim} The identifier of an online publication. This is roughly comparable to a \acr{doi}. See \secref{use:use:epr} for details. \fielditem{eprinttype}{literal} The type of \bibfield{eprint} identifier. See \secref{use:use:epr} for details. \fielditem{eventdate}{date} The date of a conference, a symposium, or some other event in \bibtype{proceedings} and \bibtype{inproceedings} entries. This field may also be useful for the custom types listed in \secref{bib:typ:ctm}. See also \bibfield{eventtitle} and \bibfield{venue} as well as \secref{bib:use:dat}. \fielditem{eventtitle}{literal} The title of a conference, a symposium, or some other event in \bibtype{proceedings} and \bibtype{inproceedings} entries. This field may also be useful for the custom types listed in \secref{bib:typ:ctm}. Note that this field holds the plain title of the event. Things like «Proceedings of the Fifth XYZ Conference» go into the \bibfield{titleaddon} or \bibfield{booktitleaddon} field, respectively. See also \bibfield{eventdate} and \bibfield{venue}. \fielditem{file}{verbatim} A local link to a \acr{pdf} or other version of the work. Not used by the standard bibliography styles. \listitem{foreword}{name} The author(s) of a foreword to the work. If the author of the foreword is identical to the \bibfield{editor} and\slash or \bibfield{translator}, the standard styles will automatically concatenate these fields in the bibliography. See also \bibfield{introduction} and \bibfield{afterword}. \listitem{holder}{name} The holder(s) of a \bibtype{patent}, if different from the \bibfield{author}. Not that corporate holders need to be wrapped in an additional set of braces, see \secref{bib:use:inc} for details. This list may also be useful for the custom types listed in \secref{bib:typ:ctm}. \fielditem{howpublished}{literal} A publication notice for unusual publications which do not fit into any of the common categories. \fielditem{indextitle}{literal} A title to use for indexing instead of the regular \bibfield{title} field. This field may be useful if you have an entry with a title like «An Introduction to \dots» and want that indexed as «Introduction to \dots, An». Style authors should note that \sty{biblatex} automatically copies the value of the \bibfield{title} field to \bibfield{indextitle} if the latter field is undefined. \listitem{institution}{literal} The name of a university or some other institution, depending on the entry type. Traditional \bibtex uses the field name \bibfield{school} for theses, which is supported as an alias. See also \secref{bib:fld:als, bib:use:and}. \listitem{introduction}{name} The author(s) of an introduction to the work. If the author of the introduction is identical to the \bibfield{editor} and\slash or \bibfield{translator}, the standard styles will automatically concatenate these fields in the bibliography. See also \bibfield{foreword} and \bibfield{afterword}. \fielditem{isan}{literal} The International Standard Audiovisual Number of an audiovisual work. Not used by the standard bibliography styles. \fielditem{isbn}{literal} The International Standard Book Number of a book. \fielditem{ismn}{literal} The International Standard Music Number for printed music such as musical scores. Not used by the standard bibliography styles. \fielditem{isrn}{literal} The International Standard Technical Report Number of a technical report. \fielditem{issn}{literal} The International Standard Serial Number of a periodical. \fielditem{issue}{literal} The issue of a journal. This field is intended for journals whose individual issues are identified by a designation such as or rather than the month or a number. Since the placement of \bibfield{issue} is similar to \bibfield{month} and \bibfield{number}, this field may also be useful with double issues and other special cases. See also \bibfield{month}, \bibfield{number}, and \secref{bib:use:iss}. \fielditem{issuesubtitle}{literal} The subtitle of a specific issue of a journal or other periodical. \fielditem{issuetitle}{literal} The title of a specific issue of a journal or other periodical. \fielditem{iswc}{literal} The International Standard Work Code of a musical work. Not used by the standard bibliography styles. \fielditem{journalsubtitle}{literal} The subtitle of a journal, a newspaper, or some other periodical. \fielditem{journaltitle}{literal} The name of a journal, a newspaper, or some other periodical. \fielditem{label}{literal} A designation to be used by the citation style as a substitute for the regular label if any data required to generate the regular label is missing. For example, when an author"=year citation style is generating a citation for an entry which is missing the author or the year, it may fall back to \bibfield{label}. See \secref{bib:use:key} for details. Note that, in contrast to \bibfield{shorthand}, \bibfield{label} is only used as a fallback. See also \bibfield{shorthand}. \listitem{language}{key} The language(s) of the work. Languages may be specified literally or as localization keys. If localization keys are used, the prefix \texttt{lang} is omissible. See also \bibfield{origlanguage} and compare \bibfield{hyphenation} in \secref{bib:fld:spc}. \fielditem{library}{literal} This field may be useful to record information such as a library name and a call number. This may be printed by a special bibliography style if desired. Not used by the standard bibliography styles. \listitem{location}{literal} The place(s) of publication, \ie the location of the \bibfield{publisher} or \bibfield{institution}, depending on the entry type. Traditional \bibtex uses the field name \bibfield{address}, which is supported as an alias. See also \secref{bib:fld:als, bib:use:and}. With \bibtype{patent} entries, this list indicates the scope of a patent and is treated as a key list. This list may also be useful for the custom types listed in \secref{bib:typ:ctm}. \fielditem{mainsubtitle}{literal} The subtitle related to the \bibfield{maintitle}. See also \bibfield{subtitle}. \fielditem{maintitle}{literal} The main title of a multi"=volume book, such as \emph{Collected Works}. If the \bibfield{title} or \bibfield{booktitle} field indicates the title of a single volume which is part of multi"=volume book, the title of the complete work is given in this field. \fielditem{maintitleaddon}{literal} An annex to the \bibfield{maintitle}, to be printed in a different font. \fielditem{month}{integer} The publication month. This must be an integer, not an ordinal or a string. Don't say |month={January}| but |month={1}|. The bibliography style converts this to a language dependent string or ordinal where required. See also \bibfield{date} as well as \secref{bib:use:iss, bib:use:dat}. \fielditem{nameaddon}{literal} An addon to be printed immediately after the author name in the bibliography. Not used by the standard bibliography styles. This field may be useful to add an alias or pen name (or give the real name if the pseudonym is commonly used to refer to that author). \fielditem{note}{literal} Miscellaneous bibliographic data which does not fit into any other field. The \bibfield{note} field may be used to record bibliographic data in a free format. Publication facts such as «Reprint of the edition London 1831» are typical candidates for the \bibfield{note} field. See also \bibfield{addendum}. \fielditem{number}{literal} The number of a journal or the volume\slash number of a book in a \bibfield{series}. See also \bibfield{issue} as well as \secref{bib:use:ser, bib:use:iss}. With \bibtype{patent} entries, this is the number or record token of a patent or patent request. \listitem{organization}{literal} The organization(s) that published a \bibtype{manual} or an \bibtype{online} resource, or sponsored a conference. See also \secref{bib:use:and}. \fielditem{origdate}{date} If the work is a translation, a reprint, or something similar, the publication date of the original edition. Not used by the standard bibliography styles. See also \bibfield{date}. \fielditem{origlanguage}{key} If the work is a translation, the language of the original work. See also \bibfield{language}. \listitem{origlocation}{literal} If the work is a translation, a reprint, or something similar, the \bibfield{location} of the original edition. Not used by the standard bibliography styles. See also \bibfield{location} and \secref{bib:use:and}. \listitem{origpublisher}{literal} If the work is a translation, a reprint, or something similar, the \bibfield{publisher} of the original edition. Not used by the standard bibliography styles. See also \bibfield{publisher} and \secref{bib:use:and}. \fielditem{origtitle}{literal} If the work is a translation, the \bibfield{title} of the original work. Not used by the standard bibliography styles. See also \bibfield{title}. \fielditem{pages}{range} One or more page numbers or page ranges. If the work is published as part of another one, such as an article in a journal or a collection, this field holds the relevant page range in that other work. It may also be used to limit the reference to a specific part of a work (a chapter in a book, for example). \fielditem{pagetotal}{literal} The total number of pages of the work. \fielditem{pagination}{key} The pagination of the work. The value of this field will affect the formatting the \prm{postnote} argument to a citation command. The key should be given in the singular form. Possible keys are \texttt{page}, \texttt{column}, \texttt{line}, \texttt{verse}, \texttt{section}, and \texttt{paragraph}. See also \bibfield{bookpagination} as well as \secref{bib:use:pag, use:cav:pag}. \fielditem{part}{literal} The number of a partial volume. This field applies to books only, not to journals. It may be used when a logical volume consists of two or more physical ones. In this case the number of the logical volume goes in the \bibfield{volume} field and the number of the part of that volume in the \bibfield{part} field. See also \bibfield{volume}. \listitem{publisher}{literal} The name(s) of the publisher(s). See also \secref{bib:use:and}. \fielditem{pubstate}{key} The publication state of the work, \eg or (to a journal). Known states are \texttt{inpress} and \texttt{submitted}. \fielditem{reprinttitle}{literal} The title of a reprint of the work. Not used by the standard styles. \fielditem{series}{literal} The name of a publication series, such as «Studies in \dots», or the number of a journal series. A publication series is usually numbered. The number or volume of a book in a series is given in the \bibfield{number} field. Note that the \bibtype{article} entry type makes use of the \bibfield{series} field as well, but handles it in a special way. See \secref{bib:use:ser} for details. \listitem{shortauthor}{name} The author(s) of the work, given in an abbreviated form. This field is mainly intended for abbreviated forms of corporate authors, see \secref{bib:use:inc} for details. \listitem{shorteditor}{name} The editor(s) of the work, given in an abbreviated form. This field is mainly intended for abbreviated forms of corporate editors, see \secref{bib:use:inc} for details. \fielditem{shorthand}{literal} A special designation to be used by the citation style instead of the usual label. This field is intended for citation aliasing. If defined, it overrides the default label. If any of the cited bibliography entries includes a \bibfield{shorthand} field, \sty{biblatex} automatically builds a list of shorthands which may be printed in addition to the regular bibliography; see \secref{use:bib:los} for details. See also \bibfield{label}. \fielditem{shorthandintro}{literal} The verbose citation styles which comes with this package use a phrase like «henceforth cited as [shorthand]» to introduce shorthands on the first citation. If the \bibfield{shorthandintro} field is defined, it overrides the standard phrase. Note that the alternative phrase must include the shorthand. \fielditem{shortjournal}{literal} A short version or an acronym of the \bibfield{journaltitle}. Not used by the standard bibliography styles. \fielditem{shortseries}{literal} A short version or an acronym of the \bibfield{series} field. Not used by the standard bibliography styles. \fielditem{shorttitle}{literal} The title in an abridged form. This field is usually not included in the bibliography. It is intended for citations in author"=title format. If present, the author"=title citation styles use this field instead of \bibfield{title}. \fielditem{subtitle}{literal} The subtitle of the work. \fielditem{title}{literal} The title of the work. \fielditem{titleaddon}{literal} An annex to the \bibfield{title}, to be printed in a different font. \listitem{translator}{name} The translator(s) of the \bibfield{title} or \bibfield{booktitle}, depending on the entry type. If the translator is identical to the \bibfield{editor}, the standard styles will automatically concatenate these fields in the bibliography. \fielditem{type}{key} The type of a \bibfield{manual}, \bibfield{patent}, \bibfield{report}, or \bibfield{thesis}. This field may also be useful for the custom types listed in \secref{bib:typ:ctm}. \fielditem{url}{verbatim} The \acr{URL} of an online publication. \fielditem{urldate}{date} The access date of the address specified in the \bibfield{url} field. See also \secref{bib:use:dat}. \fielditem{venue}{literal} The location of a conference, a symposium, or some other event in \bibtype{proceedings} and \bibtype{inproceedings} entries. This field may also be useful for the custom types listed in \secref{bib:typ:ctm}. Note that the \bibfield{location} list holds the place of publication. It therefore corresponds to the \bibfield{publisher} and \bibfield{institution} lists. The location of the event is given in the \bibfield{venue} field. See also \bibfield{eventdate} and \bibfield{eventtitle}. \fielditem{version}{literal} The revision number of a piece of software, a manual, etc. \fielditem{volume}{literal} The volume of a multi"=volume book or a periodical. See also \bibfield{part}. \fielditem{volumes}{literal} The total number of volumes of a multi"=volume work. Depending on the entry type, this field refers to \bibfield{title} or \bibfield{maintitle}. \fielditem{year}{literal} The year of publication. See also \bibfield{date} and \secref{bib:use:dat}. \end{fieldlist} \subsubsection{Special fields} \label{bib:fld:spc} The fields listed in this section do not hold printable data but serve a different purpose. They apply to all entry types. \begin{fieldlist} \fielditem{crossref}{entry key} This field holds an entry key for \bibtex's cross"=referencing feature. It is used internally by \bibtex. Child entries with a \bibfield{crossref} field inherit all data from the parent entry specified in the \bibfield{crossref} field. If the number of child entries referencing a specific parent entry hits a certain threshold, the parent entry is automatically added to the bibliography even if it has not been cited explicitly. This threshold is settable on the command"=line as \bibtex is launched and defaults to 2.\footnote{Also see the \opt{mincrossrefs} package option in \secref{use:opt:pre}.} Style authors should note that whether or not the \bibfield{crossref} fields of the child entries are defined on the \sty{biblatex} level depends on the availability of the parent entry. If the parent entry is available, the \bibfield{crossref} fields of the child entries will be defined. If not, the child entries still inherit the data from the parent entry but their \bibfield{crossref} fields will be undefined. Whether the parent entry is added to the bibliography implicitly because of the threshold or explicitly because it has been cited does not matter. See also \bibfield{xref}. \fielditem{entryset}{comma"=separated values} This field is specific to \bibtype{set} parent entries and the child entries of the reference set. In the parent entry, it is a comma"=separated list of entry keys which make up a reference set. In the child entries, it is the entry key of the parent. See \secref{use:use:set} for details. \fielditem{entrysubtype}{identifier} This field, which is not used by the standard styles, may be used to specify a subtype of an entry type. This may be useful for bibliography styles which support a finer"=grained set of entry types. \fielditem{execute}{code} A special field which holds arbitrary \tex code to be executed whenever the data of the respective entry is accessed. This may be useful to handle special cases. Conceptually, this field is comparable to the hooks \cmd{AtEveryBibitem}, \cmd{AtEveryLositem}, and \cmd{AtEveryCitekey} from \secref{aut:fmt:hok}, except that it is definable on a per"=entry basis in the \file{bib} file. Any code in this field is executed automatically immediately after these hooks. \fielditem{gender}{\opt{sf}, \opt{sm}, \opt{sn}, \opt{pf}, \opt{pm}, \opt{pn}, \opt{pp}} The gender of the author or the gender of the editor, if there is no author. The following identifiers are supported: \opt{sf} (feminine singular, a single female name), \opt{sm} (masculine singular, a single male name), \opt{sn} (neuter singular, a single neuter name), \opt{pf} (feminine plural, a list of female names), \opt{pm} (masculine plural, a list of male names), \opt{pn} (neuter plural, a list of neuter names), \opt{pp} (plural, a mixed gender list of names). This information is only required by special bibliography and citation styles and only in certain languages. For example, a citation style may replace recurrent author names with a term such as . If the Latin word is used, as is custom in English and French, there is no need to specify the gender. In German publications, however, such key terms are usually given in German and in this case they are gender"=sensitive. \begin{table} \tablesetup \begin{tabularx}{\columnwidth}{@{}P@{}P@{}X@{}} \toprule \multicolumn{1}{@{}H}{Language} & \multicolumn{1}{@{}H}{Region/Dialect} & \multicolumn{1}{@{}H}{Babel Identifiers} \\ \cmidrule(r){1-1}\cmidrule(r){2-2}\cmidrule{3-3} Danish & Denmark & \opt{danish} \\ Dutch & Netherlands & \opt{dutch} \\ English & USA & \opt{american}, \opt{USenglish}, \opt{english} \\ & United Kingdom & \opt{british}, \opt{UKenglish} \\ & Canada & \opt{canadian} \\ & Australia & \opt{australian} \\ & New Zealand & \opt{newzealand} \\ Finnish & Finland & \opt{finnish} \\ French & France, Canada & \opt{french}, \opt{francais}, \opt{canadien} \\ German & Germany & \opt{german}, \opt{ngerman} \\ & Austria & \opt{austrian}, \opt{naustrian} \\ Greek & Greece & \opt{greek} \\ Italian & Italy & \opt{italian} \\ Norwegian & Norway & \opt{norsk}, \opt{nynorsk} \\ Portuguese& Brazil & \opt{brazil} \\ & Portugal & \opt{portuges} \\ Spanish & Spain & \opt{spanish} \\ Swedish & Sweden & \opt{swedish} \\ \bottomrule \end{tabularx} \caption{Supported Languages} \label{bib:fld:tab1} \end{table} \fielditem{hyphenation}{identifier} The language of the bibliography entry. The identifier must be a language name known to the \sty{babel} package. This information may be used to switch hyphenation patterns and localize strings in the bibliography. Note that the language names are case sensitive. The languages currently supported by this package are given in \tabref{bib:fld:tab1}. Note that \sty{babel} treats the identifier \opt{english} as an alias of \opt{british} or \opt{american}, depending on the babel version. The \sty{biblatex} package always treats it as an alias of \opt{american}. It is preferable to use the language identifiers \opt{american} and \opt{british} to avoid any possible confusion. Compare \bibfield{language} in \secref{bib:fld:dat}. \fielditem{indexsorttitle}{literal} The title used when sorting the index. In contrast to \bibfield{indextitle}, this field is used for sorting only. The printed title in the index is the \bibfield{indextitle} or the \bibfield{title} field. This field may be useful if the title contains special characters or commands which interfere with the sorting of the index. Consider this example: \begin{lstlisting}[style=bibtex]{} title = {The \LaTeX\ Companion}, indextitle = {\LaTeX\ Companion, The}, indexsorttitle = {LATEX Companion}, \end{lstlisting} % Style authors should note that \sty{biblatex} automatically copies the value of either the \bibfield{indextitle} or the \bibfield{title} field to \bibfield{indexsorttitle} if the latter field is undefined. \fielditem{keywords}{comma-separated values} A comma"=separated list of keywords. These keywords are intended for the bibliography filters (see \secref{use:bib:bib, use:use:div}), they are usually not printed. Note that spaces after commas are ignored. \fielditem{options}{comma-separated \keyval options} A comma"=separated list of entry options in \keyval notation. This field is used to set options on a per"=entry basis. See \secref{use:opt:bib} for details. Note that citation and bibliography styles may define additional entry options. \fielditem{presort}{string} A field used to modify the sorting order of the bibliography. This field is the first thing the sorting algorithm considers when sorting the bibliography, hence it may be used to drastically change the sorting order. This field is only used internally by \bibtex. The default value of this string is |mm|, hence you may use the values |aa| through |ml| to move an entry towards the top of the list and |mn| through |zz| to move it towards the bottom. This may be useful when creating subdivided bibliographies with the bibliography filters. Please refer to \secref{use:srt} for an in-depth explanation of the sorting process. \fielditem{sortkey}{literal} A field used to modify the sorting order of the bibliography. Think of this field as the master sort key. If present, \sty{biblatex} uses this field during sorting and ignores everything else, except for the \bibfield{presort} field. This field is only used internally during sorting. Please refer to \secref{use:srt} for an in-depth explanation of the sorting process. \listitem{sortname}{name} A name or a list of names used to modify the sorting order of the bibliography. If present, this list is used instead of \bibfield{author} or \bibfield{editor} when sorting the bibliography. It is only used internally during sorting. Please refer to \secref{use:srt} for an in-depth explanation of the sorting process. \fielditem{sorttitle}{literal} A field used to modify the sorting order of the bibliography. If present, this field is used instead of the \bibfield{title} field when sorting the bibliography. It is only used internally during sorting. The \bibfield{sorttitle} field may come in handy if you have an entry with a title like «An Introduction to\dots» and want that alphabetized under rather than . In this case, you could put «Introduction to\dots» in the \bibfield{sorttitle} field. Please refer to \secref{use:srt} for an in-depth explanation of the sorting process. \fielditem{sortyear}{literal} A field used to modify the sorting order of the bibliography. If present, this field is used instead of the \bibfield{year} field when sorting the bibliography. It is only used internally during sorting. Please refer to \secref{use:srt} for an in-depth explanation of the sorting process. \fielditem{xref}{entry key} This field provides an alternative cross"=referencing mechanism. It differs from \bibfield{crossref} in that the child entry will not inherit any data from the parent entry specified in the \bibfield{xref} field. If the number of child entries referencing a specific parent entry hits a certain threshold, the parent entry is automatically added to the bibliography even if it has not been cited explicitly. This threshold is settable with the \opt{mincrossrefs} package option from \secref{use:opt:pre}. Style authors should note that whether or not the \bibfield{xref} fields of the child entries are defined on the \sty{biblatex} level depends on the availability of the parent entry. If the parent entry is available, the \bibfield{xref} fields of the child entries will be defined. If not, their \bibfield{xref} fields will be undefined. Whether the parent entry is added to the bibliography implicitly because of the threshold or explicitly because it has been cited does not matter. Please refer to \secref{bib:cav:ref} for further explanation. See also \bibfield{crossref}. \end{fieldlist} \subsubsection{Custom fields} \label{bib:fld:ctm} The fields listed in this section are intended for special bibliography styles. They are not used by the standard bibliography styles. \begin{fieldlist} \listitem{name{[a--c]}}{name} Custom lists for special bibliography styles. Not used by the standard bibliography styles. \fielditem{name{[a--c]}type}{key} Similar to \bibfield{authortype} and \bibfield{editortype} but referring to the fields \bibfield{name{[a--c]}}. Not used by the standard bibliography styles. \listitem{list{[a--f]}}{literal} Custom lists for special bibliography styles. Not used by the standard bibliography styles. \fielditem{user{[a--f]}}{literal} Custom fields for special bibliography styles. Not used by the standard bibliography styles. \fielditem{verb{[a--c]}}{literal} Similar to the custom fields above except that these are verbatim fields. Not used by the standard bibliography styles. \end{fieldlist} \subsubsection{Field aliases} \label{bib:fld:als} The aliases listed in this section are provided for backwards compatibility with traditional \bibtex and other applications based on traditional \bibtex styles. Note that these aliases are immediately resolved as the \file{bib} file is processed. All bibliography and citation styles must use the names of the fields they point to, not the alias. In \file{bib} files, you may use either the alias or the field name but not both at the same time. \begin{fieldlist} \listitem{address}{literal} An alias of \bibfield{location}, see \secref{bib:fld:dat}. Traditional \bibtex uses the slightly misleading field name \bibfield{address} for the place of publication, \ie the location of the publisher. This package uses \bibfield{location} for that, but \bibfield{address} is supported as an alias. See also \secref{bib:use:and}. \fielditem{annote}{literal} An alias of \bibfield{annotation}, provided for \sty{jurabib} compatibility. \fielditem{journal}{literal} An alias of \bibfield{journaltitle}, see \secref{bib:fld:dat}. \fielditem{key}{literal} An alias of \bibfield{sortkey}, see \secref{bib:fld:spc}. \fielditem{pdf}{verbatim} An alias of \bibfield{file}, see \secref{bib:fld:dat}. This alias is provided for JabRef compatibility. \listitem{school}{literal} An alias of \bibfield{institution}, see \secref{bib:fld:dat}. The \bibfield{institution} field is used by traditional \bibtex for technical reports whereas the \bibfield{school} field holds the institution associated with theses. This package employs \bibfield{institution} in both cases, but \bibfield{school} is supported as an alias. See also \secref{bib:use:and}. \end{fieldlist} \subsection{Usage notes} \label{bib:use} The entry types and fields supported by this package should for the most part be intuitive to use for anyone familiar with \bibtex. However, apart from the additional types and fields provided by this package, some of the familiar ones are handled in a way which is in need of explanation. This package includes some compatibility code for \file{bib} files which were generated with a traditional \bibtex style in mind. Unfortunately, it is not possible to handle all legacy files automatically because \sty{biblatex}'s data model is slightly different from traditional \bibtex. Therefore, such \file{bib} files will most likely require editing in order to work properly with this package. In sum, the following items are different from traditional \bibtex styles: \begin{itemize} \setlength{\itemsep}{0pt} \item The entry type \bibtype{inbook}. See \secref{bib:typ:blx, bib:use:inb} for details. \item The fields \bibfield{institution}, \bibfield{organization}, and \bibfield{publisher} as well as the aliases \bibfield{address} and \bibfield{school}. See \secref{bib:fld:dat, bib:fld:als, bib:use:and} for details. \item The handling of certain types of titles. See \secref{bib:use:ttl} for details. \item The field \bibfield{series}. See \secref{bib:fld:dat, bib:use:ser} for details. \item The fields \bibfield{year} and \bibfield{month}. See \secref{bib:fld:dat, bib:use:dat, bib:use:iss} for details. \item The field \bibfield{edition}. See \secref{bib:fld:dat} for details. \item The field \bibfield{key}. See \secref{bib:use:key} for details. \end{itemize} Users of the \sty{jurabib} package should note that the \bibfield{shortauthor} field is treated as a name list by \sty{biblatex}, see \secref{bib:use:inc} for details. \subsubsection{The entry type \bibtype{inbook}} \label{bib:use:inb} Use the \bibtype{inbook} entry type for a self"=contained part of a book with its own title only. It relates to \bibtype{book} just like \bibtype{incollection} relates to \bibtype{collection}. See \secref{bib:use:ttl} for examples. If you want to refer to a chapter or section of a book, simply use the \bibfield{book} type and add a \bibfield{chapter} and\slash or \bibfield{pages} field. Whether a bibliography should at all include references to chapters or sections is controversial because a chapter is not a bibliographic entity. \subsubsection{Missing and omissible data} \label{bib:use:key} The fields marked as in \secref{bib:typ:blx} are not strictly required in all cases. The bibliography styles which ship with this package can get by with as little as a \bibfield{title} field for most entry types. A book published anonymously, a periodical without an explicit editor, or a software manual without an explicit author should pose no problem as far as the bibliography is concerned. Citation styles, however, may have different requirements. For example, an author"=year citation scheme obviously requires an \bibfield{author}\slash \bibfield{editor} and a \bibfield{year} field. You may generally use the \bibfield{label} field to provide a substitute for any missing data required for citations. How the \bibfield{label} field is employed depends on the citation style. The author"=year citation styles which come with this package use the \bibfield{label} field as a fallback if either the \bibfield{author}\slash \bibfield{editor} or the \bibfield{year} is missing. The numeric styles, on the other hand, do not use it at all since the numeric scheme is independent of the available data. The author"=title styles ignore it as well, because the bare \bibfield{title} is usually sufficient to form a unique citation and a title is expected to be available in any case. The \bibfield{label} field may also be used to override the non"=numeric portion of the automatically generated \bibfield{labelalpha} field used by alphabetic citation styles. See \secref{aut:bbx:fld} for details. Note that traditional \bibtex styles support a \bibfield{key} field which is used for alphabetizing if both \bibfield{author} and \bibfield{editor} are missing. The \sty{biblatex} package treats \bibfield{key} as an alias of \bibfield{sortkey}. In addition to that, it offers very fine-grained sorting controls, see \secref{bib:fld:spc, use:srt} for details. The \sty{natbib} package employs the \bibfield{key} field as a fallback label for citations. Use the \bibfield{label} field instead. \subsubsection{Corporate authors and editors} \label{bib:use:inc} Corporate authors and editors are given in the \bibfield{author} or \bibfield{editor} field, respectively. Note that they should be wrapped in an extra pair of curly braces to prevent \bibtex from treating them as personal names which are to be dissected into their components. Use the \bibfield{shortauthor} field if you want to give an abbreviated form of the name or an acronym for use in citations. \begin{lstlisting}[style=bibtex]{} author = {{National Aeronautics and Space Administration}}, shortauthor = {NASA}, \end{lstlisting} % The default citation styles will use the short name in all citations while the full name is printed in the bibliography. For corporate editors, use the corresponding fields \sty{editor} and \sty{shorteditor}. Since all of these fields are treated as name lists, it is possible to mix personal names and corporate names, provided that the names of all corporations and institutions are wrapped in braces. \begin{lstlisting}[style=bibtex]{} editor = {{National Aeronautics and Space Administration} and Doe, John}, shorteditor = {NASA and Doe, John}, \end{lstlisting} % Users switching from the \sty{jurabib} package to \sty{biblatex} should note that the \bibfield{shortauthor} field is treated as a name list. \subsubsection{Literal lists} \label{bib:use:and} The fields \bibfield{institution}, \bibfield{organization}, \bibfield{publisher}, and \bibfield{location} are literal lists in terms of \secref{bib:fld}. This also applies to \bibfield{origlocation}, \bibfield{origpublisher} and to the field aliases \bibfield{address} and \bibfield{school}. All of these fields may contain a list of items separated by the keyword <|and|>. If such fields contains a literal <|and|>, it must be wrapped in braces. \begin{lstlisting}[style=bibtex]{} publisher = {William Reid {and} Company}, institution = {Office of Information Management {and} Communications}, organization = {American Society for Photogrammetry {and} Remote Sensing and American Congress on Surveying {and} Mapping}, \end{lstlisting} % Note the difference between a literal <|{and}|> and the list separator <|and|> in the above examples. Legacy files which have not been updated for use with \sty{biblatex} will still work if these fields do not contain a literal . However, note that you will miss out on the additional features of literal lists in this case, such as configurable formatting and automatic truncation. \subsubsection{Titles} \label{bib:use:ttl} The following examples demonstrate how to handle different types of titles. Let's start with a five"=volume work which is referred to as a whole: \begin{lstlisting}[style=bibtex]{} @Book{works, author = {Shakespeare, William}, title = {Collected Works}, volumes = {5}, ... \end{lstlisting} % The individual volumes of a multi"=volume work usually have a title of their own. Suppose the fourth volume of the \emph{Collected Works} includes Shakespeare's sonnets and we are referring to this volume only: \begin{lstlisting}[style=bibtex]{} @Book{sonnets, author = {Shakespeare, William}, maintitle = {Collected Works}, title = {Sonnets}, volume = {4}, ... \end{lstlisting} % If the individual volumes do not have a title, we put the main title in the \bibfield{title} field and include a volume number: \begin{lstlisting}[style=bibtex]{} @Book{sonnets, author = {Shakespeare, William}, title = {Collected Works}, volume = {4}, ... \end{lstlisting} % In the next example, we are referring to a part of a volume, but this part is a self"=contained work with its own title. The respective volume also has a title and there is still the main title of the entire edition: \begin{lstlisting}[style=bibtex]{} @InBook{lear, author = {Shakespeare, William}, bookauthor = {Shakespeare, William}, maintitle = {Collected Works}, booktitle = {Tragedies}, title = {King Lear}, volume = {1}, pages = {53-159}, ... \end{lstlisting} % Suppose the first volume of the \emph{Collected Works} includes a reprinted essay by a well"=known scholar. This is not the usual introduction by the editor but a self"=contained work. The \emph{Collected Works} also have a separate editor: \begin{lstlisting}[style=bibtex]{} @InBook{stage, author = {Expert, Edward}, title = {Shakespeare and the Elizabethan Stage}, bookauthor = {Shakespeare, William}, editor = {Bookmaker, Bernard}, maintitle = {Collected Works}, booktitle = {Tragedies}, volume = {1}, pages = {7-49}, ... \end{lstlisting} % See \secref{bib:use:ser} for further examples. \subsubsection{Editorial roles} \label{bib:use:edr} The type of editorial role performed by an editor in one of the \bibfield{editor} fields (\ie \bibfield{editor}, \bibfield{editora}, \bibfield{editorb}, \bibfield{editorc}) may be specified in the corresponding \bibfield{editor...type} field. The following roles are supported by default. The role <\texttt{editor}> is the default. In this case, the \bibfield{editortype} field is omissible. \begin{marglist} \setlength{\itemsep}{0pt} \item[editor] The main editor. This is the most generic editorial role and the default value. \item[compiler] Similar to \texttt{editor} but used if the task of the editor is mainly compiling. \item[founder] The founding editor of a periodical or a comprehensive publication project such as a edition or a long"=running legal commentary. \item[continuator] An editor who continued the work of the founding editor (\texttt{founder}) but was subsequently replaced by the current editor (\texttt{editor}). \item[redactor] A secondary editor whose task is redacting the work. \item[collaborator] A secondary editor or a consultant to the editor. \end{marglist} % For example, if the task of the editor is compiling, you may indicate that in the corresponding \bibfield{editortype} field: \begin{lstlisting}[style=bibtex]{} @Collection{..., editor = {Editor, Edward}, editortype = {compiler}, ... \end{lstlisting} % There may also be secondary editors in addition to the main editor: \begin{lstlisting}[style=bibtex]{} @Book{..., author = {...}, editor = {Editor, Edward}, editora = {Redactor, Randolph}, editoratype = {redactor}, editorb = {Consultant, Conrad}, editorbtype = {collaborator}, ... \end{lstlisting} % Periodicals or long"=running publication projects may see several generations of editors. For example, there may be a founding editor in addition to the current editor: \begin{lstlisting}[style=bibtex]{} @Book{..., author = {...}, editor = {Editor, Edward}, editora = {Founder, Frederic}, editoratype = {founder}, ... \end{lstlisting} % Note that only the \bibfield{editor} is considered in citations and when sorting the bibliography. If an entry is typically cited by the founding editor (and sorted accordingly in the bibliography), the founder goes into the \bibfield{editor} field and the current editor moves to one of the \bibfield{editor...} fields: \begin{lstlisting}[style=bibtex]{} @Collection{..., editor = {Founder, Frederic}, editortype = {founder}, editora = {Editor, Edward}, ... \end{lstlisting} % You may add more roles by initializing and defining a new localization key whose name corresponds to the identifier in the \bibfield{editor...type} field. See \secref{use:lng,aut:lng:cmd} for details. \subsubsection{Publication and journal series} \label{bib:use:ser} The \bibfield{series} field is used by traditional \bibtex styles both for the main title of a multi"=volume work and for a publication series, \ie a loosely related sequence of books by the same publisher which deal with the same general topic or belong to the same field of research. This may be ambiguous. This package introduces a \bibfield{maintitle} field for multi"=volume works and employs \bibfield{series} for publication series only. The volume or number of a book in the series goes in the \bibfield{number} field in this case: \begin{lstlisting}[style=bibtex]{} @Book{..., author = {Expert, Edward}, title = {Shakespeare and the Elizabethan Age}, series = {Studies in English Literature and Drama}, number = {57}, ... \end{lstlisting} % The \bibtype{article} entry type makes use of the \bibfield{series} field as well, but handles it in a special way. First, a test is performed to determine whether the value of the field is an integer. If so, it will be printed as an ordinal. If not, another test is performed to determine whether it is a localization key. If so, the localized string is printed. If not, the value is printed as is. Consider the following example of a journal published in numbered series: \begin{lstlisting}[style=bibtex]{} @Article{..., journal = {Journal Name}, series = {3}, volume = {15}, number = {7}, year = {1995}, ... \end{lstlisting} % This entry will be printed as «\emph{Journal Name}. 3rd ser. 15.7 (1995)». Some journals use designations such as «old series» and «new series» instead of a number. Such designations may be given in the \bibfield{series} field as well, either as a literal string or as a localization key. Consider the following example which makes use of the localization key \texttt{newseries}: \begin{lstlisting}[style=bibtex]{} @Article{..., journal = {Journal Name}, series = {newseries}, volume = {9}, year = {1998}, ... \end{lstlisting} % This entry will be printed as «\emph{Journal Name}. New ser. 9 (1998)». See \secref{aut:lng:key} for a list of localization keys defined by default. \subsubsection{Date specifications} \label{bib:use:dat} \begin{table} \tablesetup \begin{tabularx}{\columnwidth}{@{}>{\ttfamily}llX@{}} \toprule \multicolumn{1}{@{}H}{Date Specification} & \multicolumn{2}{H}{Formatted Date (Examples)} \\ \cmidrule(l){2-3} & \multicolumn{1}{H}{Short Format} & \multicolumn{1}{H}{Long Format} \\ \cmidrule{1-1}\cmidrule(l){2-2}\cmidrule(l){3-3} 1850 & 1850 & 1850 \\ 1997/ & 1997-- & 1997-- \\ 1967-02 & 02/1967 & February 1967 \\ 2009-01-31 & 31/01/2009 & 31st January 2009 \\ 1988/1992 & 1988--1992 & 1988--1992 \\ 2002-01/2002-02 & 01/2002--02/2002 & January 2002--February 2002 \\ 1995-03-30/1995-04-05 & 30/03/1995--05/04/1995 & 30th March 1995--5th April 1995 \\ \bottomrule \end{tabularx} \caption{Date Specifications} \label{bib:use:tab1} \end{table} The date fields \bibfield{date}, \bibfield{origdate}, \bibfield{eventdate}, and \bibfield{urldate} require a date specification in \texttt{yyyy-mm-dd} format. Date ranges are given as \texttt{yyyy-mm-dd\slash yyyy-mm-dd}. Partial dates are valid provided that date components are omitted at the end only. You may specify an open ended date range by giving the range separator and omitting the end date (\eg \texttt{yyyy/}). See \tabref{bib:use:tab1} for some examples of valid date specifications and the formatted date autmatically generated by \sty{biblatex}. The formatted date is language specific and will be adapted automatically. If there is no \bibfield{date} field in an entry, \sty{biblatex} will also consider the fields \bibfield{year} and \bibfield{month} for backwards compatibility with traditional \bibtex. Style author should note that date fields like \bibfield{date} or \bibfield{origdate} are only available in the \file{bib} file. All dates are parsed and dissected into their components as the \file{bib} file is processed. The date components are made available to styles by way of the special fields discussed in \secref{aut:bbx:fld:dat}. \subsubsection{Years, months and journal issues} \label{bib:use:iss} The fields \bibfield{year} and \bibfield{month} are integer fields. The bibliography style converts the month to a language dependent string, ordinal, or date as required. For backwards compatibility, you may also use the following three"=letter abbreviations in the \bibfield{month} field: \texttt{jan}, \texttt{feb}, \texttt{mar}, \texttt{apr}, \texttt{may}, \texttt{jun}, \texttt{jul}, \texttt{aug}, \texttt{sep}, \texttt{oct}, \texttt{nov}, \texttt{dec}. Note that these abbreviations are \bibtex strings which must be given without any braces or quotes. When using them, don't say |month={jan}| or |month="jan"| but |month=jan|. It is not possible to specify a month such as |month={8/9}|. Use the \bibfield{date} field for date ranges instead. Quarterly journals are typically identified by a designation such as or which should be given in the \bibfield{issue} field. The placement of the \bibfield{issue} field in \bibtype{article} entries is similar to and overrides the \bibfield{month} field. \subsubsection{Pagination} \label{bib:use:pag} When specifying a page or page range, either in the \bibfield{pages} field of an entry or in the \prm{postnote} argument to a citation command, it is convenient to have \sty{biblatex} add prefixes like or automatically and this is indeed what this package does by default. However, some works may use a different pagination scheme or may not be cited by page but rather by verse or line number. This is when the \bibfield{pagination} and \bibfield{bookpagination} fields come into play. As an example, consider the following entry: \begin{lstlisting}[style=bibtex]{} @InBook{key, title = {...}, pagination = {verse}, booktitle = {...}, bookpagination = {page}, pages = {53--65}, ... \end{lstlisting} % The \bibfield{bookpagination} field affects the formatting of the \bibfield{pages} and \bibfield{pagetotal} fields in the list of references. Since \texttt{page} is the default, this field is omissible in the above example. In this case, the page range will be formatted as . Suppose that, when quoting from this work, it is customary to use verse numbers rather than page numbers in citations. This is reflected by the \bibfield{pagination} field, which affects the formatting of the \prm{postnote} argument to any citation command. With a citation like |\cite[17]{key}|, the postnote will be formatted as . Setting the \bibfield{pagination} field to \texttt{section} would yield <\S~17>. See \secref{use:cav:pag} for further usage instructions. The \bibfield{pagination} and \bibfield{bookpagination} fields are key fields. This package will try to use their value as a localization key, provided that the key is defined. Always use the singular form of the key name in \file{bib} files, the plural is formed automatically. The keys \texttt{page}, \texttt{column}, \texttt{line}, \texttt{verse}, \texttt{section}, and \texttt{paragraph} are predefined, with \texttt{page} being the default. The string <\texttt{none}> has a special meaning when used in a \bibfield{pagination} or \bibfield{bookpagination} field. It suppresses the prefix for the respective entry. If there are no predefined localization keys for the pagination scheme required by a certain entry, you can simply add them. See the commands \cmd{NewBibliographyString} and \cmd{DefineBibliographyStrings} in \secref{use:lng}. You need to define two bibliography strings for each additional pagination scheme: the singular form (whose localization key corresponds to the value of the \bibfield{pagination} field) and the plural form (whose localization key must be the singular plus the letter <\texttt{s}>). See the predefined keys in \secref{aut:lng:key} for examples. \subsection{Hints and caveats} \label{bib:cav} This section provides some additional hints concerning the \bibtex interface of this package. It also addresses some common problems. \subsubsection{Cross referencing} \label{bib:cav:ref} \bibtex's \bibfield{crossref} field provides a handy cross-referencing mechanism which inherits data missing in a child entry from the corresponding parent entry indicated by the value of the \bibfield{crossref} field. Unfortunately, this mechanism is static and uses a one-on-one field mapping. This reduces its usefulness significantly because it will cause problems in quite a few cases. For example, the \bibfield{subtitle} of a cross-referenced \bibtype{collection} entry may end up in the \bibfield{subtitle} field, rather than in the \bibfield{booksubtitle} field, of the corresponding \bibtype{incollection} child entry. It is possible to work around this problem by including an empty \bibfield{subtitle} in the child entry. This package also provides an alternative cross-referencing mechanism. The \bibfield{xref} field differs from \bibfield{crossref} in that the child entry will not inherit \emph{any} data from the parent entry specified in the \bibfield{xref} field. This implies that child entries must include all bibliographic data. The \bibfield{xref} field is merely a pointer which may be used by bibliography styles which format child entries in a special way (see \secref{aut:cav:mif} for an example). If the parent entry is referenced by a certain number of child entries, \sty{biblatex} will automatically execute the equivalent of a \cmd{nocite} command to request it from \bibtex. The threshold is controlled by the \opt{mincrossrefs} package option from \secref{use:opt:pre}. Style authors should note that whether or not the \bibfield{xref} fields of the child entries are defined on the \sty{biblatex} level depends on the availability of the parent entry. If the parent entry is available, the \bibfield{xref} fields of the child entries will be defined. If not, their \bibfield{xref} fields will be undefined. Whether the parent entry is added to the bibliography implicitly because of the threshold or because it has been cited explicitly in the document does not matter. \subsubsection{\bibtex capacity issues} \label{bib:cav:btx} A venerable tool originally developed in the 1980s, \bibtex uses static memory allocation, much to the dismay of users working with large bibliographical databases. With a large \file{bib} file which contains several hundred entries, \bibtex is very likely to run out of memory. The number of entries it can cope with depends on the number of fields defined by the \bibtex style (\file{bst}). Style files which define a considerable number of fields, such as \path{biblatex.bst}, are more likely to trigger such problems. Unfortunately, traditional \bibtex does not output a clear error message when it runs out of memory but exposes a rather cryptical kind of faulty behavior. The warning messages printed in this case look like this: \begin{lstlisting}[style=plain]{} Warning--I'm ignoring Jones1995's extra "year" field --line 422 of file huge.bib Warning--I'm ignoring Jones1995's extra "volume" field --line 423 of file huge.bib \end{lstlisting} % These warning messages could indeed indicate that the entry \texttt{Jones1995} is faulty because it includes two \bibfield{year} and two \bibfield{volume} fields. If that is not the case and the \file{bib} file is fairly large, this is most likely a capacity issue. What makes these warnings so confusing is that they are not tied to a specific entry. If you remove the allegedly faulty entry, a different one will trigger similar warnings. This is one reason why switching to \file{bibtex8}, the 8-bit implementation of \bibtex, is advisable. Alas, \file{bibtex8} is a venerable tool as well and will also run out of memory with its default capacity. Switching from traditional \bibtex to \file{bibtex8} is still an improvement because the capacity of the latter may be increased at run"=time via command"=line switches and it also prints unambiguous error messages, for example: \begin{table} \numtablesetup \begin{tabularx}{\columnwidth}{@{}S@{}Srnnn@{}} \toprule \multicolumn{1}{@{}H}{Parameter} & \multicolumn{1}{@{}H}{Switch} & \multicolumn{4}{@{}H}{Capacity} \\ \cmidrule{3-6} && \multicolumn{1}{@{}H}{Default} & \multicolumn{1}{@{}N}{\texttt{-{}-big}} & \multicolumn{1}{@{}N}{\texttt{-{}-huge}} & \multicolumn{1}{@{}N@{}}{\texttt{-{}-wolfgang}} \\ \cmidrule(r){1-1}\cmidrule(r){2-2}\cmidrule{3-6} max\_cites & -{}-mcites & 750 & 2000 & 5000 & 7500 \\ max\_ent\_ints & -{}-mentints & 3000 & 4000 & 5000 & 7500 \\ max\_ent\_strs & -{}-mentstrs & 3000 & 6000 & 10000 & 10000 \\ max\_fields & -{}-mfields & 17250 & 30000 & 85000 & 125000 \\ max\_strings & -{}-mstrings & 4000 & 10000 & 19000 & 30000 \\ pool\_size & -{}-mpool & 65530 & 130000 & 500000 & 750000 \\ wiz\_fn\_space & -{}-mwizfuns & 3000 & 6000 & 10000 & 10000 \\ hash\_prime & & 4253 & 8501 & 16319 & 30011 \\ hash\_size & & 5000 & 10000 & 19000 & 35000 \\ \bottomrule \end{tabularx} \caption[Capacity of \bin{bibtex8}]{Capacity and Switches of \bin{bibtex8}} \label{bib:cav:tab1} \end{table} \begin{lstlisting}[style=plain]{} 17289 fields: Sorry---you've exceeded BibTeX's total number of fields 17250 \end{lstlisting} % \Tabref{bib:cav:tab1} gives an overview of the various capacity parameters of \file{bibtex8} and the command"=line switches used to increase their default values. There are two ways to increase the capacity on the command"=line. You may use a high"=level switch like |--huge| to select a different set of defaults or low"=level switches such as |--mfields| to modify a single parameter. The first thing you should always do is run \file{bibtex8} with the |--wolfgang| switch. Don't even bother trying anything else. With a very large database, however, even that capacity may be too small. In this case, you need to resort to the low"=level switches. Here is an example of a set of switches which should cope with a \file{bib} file containing about 1000 entries: \begin{lstlisting}[style=plain]{} bibtex8 --wolfgang --mcites 30000 --mentints 30000 --mentstrs 40000 --mfields 250000 --mstrings 35000 --mpool 750000 --csfile csfile.csf auxfile \end{lstlisting} % When taking a closer look at \tabref{bib:cav:tab1}, you will notice that there are two parameters which can not be modified directly, |hash_prime| and |hash_size|. Increasing these values is only possible with the high"=level switches. That is why the above command includes the |--wolfgang| switch in addition to the low"=level switches. This situation is very unfortunate because the hash size effectively sets a cap on some other parameters. For example, |max_strings| can not be greater than |hash_size|. If you hit this cap, all you can do is recompile \file{bibtex8} with a larger capacity. Also note that the |wiz_fn_space| parameter is not related to the \file{bib} file but to the memory requirements of the \file{bst} file. \file{biblatex.bst} needs a value of about 6000. The value 10000 implicitly used by the |--wolfgang| switch is fine. Note that Biber, the next"=generation database backend of \sty{biblatex}, eliminates all of the above limitations. \subsubsection{\bibtex sorting and encoding issues} \label{bib:cav:enc} Traditional \bibtex can only alphabetize Ascii characters correctly. If the bibliographic data includes non"=Ascii characters, they have to be given in Ascii notation. For example, instead of typing a letter like <ä> directly, you need to input it as |\"a|, using an accent command and the Ascii letter. This Ascii notation needs to be wrapped in a pair of curly braces. Traditional \bibtex will then ignore the accent and use the Ascii letter for sorting. Here are a few examples: \begin{lstlisting}[style=bibtex,upquote]{} author = {S<<{\'a}>>nchez, Jos<<{\'e}>>}, editor = {Ma<<{\ss}>>mann, R<<{\"u}>>diger}, translator = {Ferdi<<{\`e}>>re, Fr<<{\c{c}}>>ois}, title = {<<{\OE}>>uvres compl<<{\`e}>>tes}, \end{lstlisting} % Apart from it being inconvenient, there are two major issues with this convention. One subtle problem is that the extra set of braces suppresses the kerning on both sides of all non"=Ascii letters. But first and foremost, simply ignoring all accents may not be the correct way to handle them. For example, in Danish, the letter <å> is the very last letter of the alphabet, so it should be alphabetized after . \bibtex will sort it like an . The <æ> ligature and the letter <ø> are also sorted after in this language. There are similar cases in Norwegian. In Swedish, the letter <ö> is the very last letter of the alphabet and the letters <å> and <ä> are also alphabetized after , rather than like an . What's more, even the sorting of Ascii characters is done in a rather peculiar way by traditional \bibtex because the sorting algorithm uses Ascii codepage order (\texttt{0-9,A-Z,a-z}). This implies that the lowercase letter would end up after the uppercase , which is not even acceptable in the language \bibtex was originally designed for. The traditional \file{bst} files work around this problem by converting all strings used for sorting to lowercase, \ie sorting is effectively case"=insensitive. These are the major reasons why switching to \file{bibtex8}, the 8-bit implementation of \bibtex, is advisable. \file{bibtex8} can sort in a case"=sensitive way and it can handle (single byte) non"=Ascii characters properly, provided that you supply it with a suitable \file{csf} file and give the |--csfile| switch on the command line. This also implies that it is possible to apply language specific sorting rules to the bibliography. The \sty{biblatex} package comes with \file{csf} files for some common Western European encodings. \bin{bibtex8} also ships with a few \file{csf} files. Note that \file{biblatex.bst} can not detect if it is running under traditional \bibtex or \file{bibtex8}, hence the \opt{bibtex8} package option. By default, sorting is case-insensitive since this is required for traditional \bibtex. If the \opt{bibtex8} package option is enabled, sorting is case-sensitive. Since \file{bibtex8} is backwards compatible with traditional \bibtex, it is possible to mix 8-bit input and Ascii notation. This is useful if the encoding used in the \file{bib} file does not cover all required characters. There are also a few marginal cases in which the Ascii notation scheme would yield better sorting results. A typical example is the ligature <½>. \file{bibtex8} will handle this ligature like a single character. Depending on the sorting scheme defined in the \file{csf} file, it could be treated like an or alphabetized after the letter but it can not be sorted as . The Ascii notation (|\oe|) is equivalent to during sorting: \begin{lstlisting}[style=bibtex,upquote]{} title = {<<¼>>uvres compl<<è>>tes}, title = {<<{\OE}>>uvres compl<<è>>tes}, \end{lstlisting} % Sometimes even that is not sufficient and further tricks are required. For example, the letter <ß> in German is particularly tricky. This letter is essentially alphabetized as but after . For example, a name like would be alphabetized as follows: Basmann\slash Bassmann\slash Baßmann\slash Bastmann. In this case, the Ascii notation (|\ss|) would yield slightly better sorting results than <ß> in conjunction with a \file{csf} file which treats <ß> like : \begin{lstlisting}[style=bibtex,upquote]{} author = {Ba<<{\ss}>>mann, Paul}, \end{lstlisting} % To get it absolutely right, however, you need to resort to the \bibfield{sortname} field: \begin{lstlisting}[style=bibtex,upquote]{} author = {Ba<<ß>>mann, Paul}, sortname = {Ba<>mann, Paul}, \end{lstlisting} % Not only \bibtex, \tex needs to know about the encoding as well. When using non"=Ascii characters in a \file{bib} file, load the \sty{inputenc} package and specify the encoding as usual. The \sty{biblatex} package is also capable of handling conflicting encodings in \file{tex} and \file{bib} files, provided that you specify the encoding of the \file{bib} file with the \opt{bibencoding} package option. Here are a few typical cases along with the relevant lines from the document preamble: \begin{itemize} \setlength{\itemsep}{0pt} \item Ascii notation in both the \file{tex} and the \file{bib} file: \begin{lstlisting}[style=latex]{} \usepackage{biblatex} \end{lstlisting} \item Latin\,1 encoding (\acr{ISO}-8859-1) in the \file{tex} file, Ascii notation in the \file{bib} file: \begin{lstlisting}[style=latex]{} \usepackage[latin1]{inputenc} \usepackage{biblatex} \end{lstlisting} \item Latin\,9 encoding (\acr{ISO}-8859-15) in both the \file{tex} and the \file{bib} file: \begin{lstlisting}[style=latex]{} \usepackage[latin9]{inputenc} \usepackage[bibencoding=inputenc,backend=bibtex8]{biblatex} \end{lstlisting} \item \acr{utf-8} encoding in the \file{tex} file, Latin\,1 (\acr{ISO}-8859-1) in the \file{bib} file: \begin{lstlisting}[style=latex]{} \usepackage[utf8]{inputenc} \usepackage[bibencoding=latin1,backend=bibtex8]{biblatex} \end{lstlisting} \item Using \acr{utf-8} encoding in both the \file{tex} and the \file{bib} file is not possible with traditional \bibtex or \bin{bibtex8} since neither of them is capable of handling multi"=byte encodings such as \acr{utf-8}. In this case, you need to use a single"=byte encoding such as Latin 1 (see above) or resort to Ascii notation in the \file{bib} file: \begin{lstlisting}[style=latex]{} \usepackage[utf8]{inputenc} \usepackage{biblatex} \end{lstlisting} \item When using Biber as the database backend, it is possible to have a transparent \acr{utf-8} workflow, \ie to use \acr{utf-8} encoding in both the \file{tex} and the \file{bib} file: \begin{lstlisting}[style=latex]{} \usepackage[utf8]{inputenc} \usepackage[backend=biber]{biblatex} \end{lstlisting} \end{itemize} When using a non"=Ascii encoding in the \file{bib} file, it is important to understand what \sty{biblatex} can do for you and what requires manual intervention. The package takes care of the \latex side, \ie it ensures that the bibliographic data is interpreted correctly as it is imported from the \file{bbl} file, provided that the \opt{bibencoding} package option is set properly and the \sty{inputenc} package is available. However, the \bibtex side demands attention, too. As mentioned above, you have to use \bin{bibtex8} and you need to supply it with a matching \file{csf} file. \bibtex needs to know about the encoding of the \file{bib} file to be able to alphabetize the entries correctly. Unfortunately, there is no way for \sty{biblatex} to pass this information to \bin{bibtex8} automatically. The only way is setting the |--csfile| switch on the command line when executing \bin{bibtex8}. When using Biber, see the Biber manual for instructions. \subsubsection{Editors and compiler scripts} \label{bib:cav:ide} As outlined in \secref{use:use:int}, this package requires at least two \latex runs and one \bibtex run to incorporate a new reference. If the document contains any \env{refsection} environments or the \bibfield{xref} field is used, additional \bibtex runs are required. In order to inform users which steps need to be taken, this package writes human-readable messages to the transcript file. These messages are discussed in \secref{use:use:aux}. In addition to that, it also outputs requests intended for \latex editors and compiler scripts which parse the transcript file to find out whether a \bibtex run and\slash or an additional \latex run is required.\footnote{Apart from that, \sty{biblatex} outputs the usual warnings traditionally issued by \latex, such as «Citation \dots\unkern\ undefined» or «There were undefined references». \latex editors and compiler scripts which do not explicitly support this package should therefore work reasonably well as long as \sty{biblatex} only uses the main \file{aux} file. However, if the document contains any \env{refsection} environments, which require additional \file{aux} files, dedicated \sty{biblatex} support is indispensable.} The remainder of this section discusses the format of such requests. It is primarily relevant to readers interested in adding dedicated \sty{biblatex} support to an editor or a compiler script. All requests are made in a generic format suitable for adoption by other \latex packages which also need to communicate with external tools. Request always start with the string \texttt{REQ:} and end with \texttt{:REQ}. There are two sub-formats, a terse one and a verbose one. Terse requests are given on one line and consist of two columns separated by a colon. The first column is the priority of the request, the second column indicates the application to be run. The application is identified by its generic name, for example \texttt{latex} rather than \texttt{pdfelatex}. \begin{lstlisting}[style=highlight]{} REQ:<>:<>:REQ \end{lstlisting} % Verbose requests span multiple lines. The first line is similar to terse requests and indicates the priority and the generic name of the requested application. The part which differs from terse requests consists of lines which start with a keyword followed by an equal sign. The remaining part of the line is a value assigned to the keyword. \begin{lstlisting}[style=highlight]{} REQ:<>:<>: binary=<> option=<