summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/biblatex/biblatex.tex
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2010-09-06 22:29:57 +0000
committerKarl Berry <karl@freefriends.org>2010-09-06 22:29:57 +0000
commit240dbb5ee820f2e77e4106bf872f363540c413e2 (patch)
tree3921b3f18013915f30f418d31199a3770604a0db /Master/texmf-dist/doc/latex/biblatex/biblatex.tex
parent6892558c73756d9f24023e6269e025fa6f3cf15d (diff)
biblatex 0.9d (4sep10)
git-svn-id: svn://tug.org/texlive/trunk@19592 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex/biblatex/biblatex.tex')
-rw-r--r--Master/texmf-dist/doc/latex/biblatex/biblatex.tex1008
1 files changed, 577 insertions, 431 deletions
diff --git a/Master/texmf-dist/doc/latex/biblatex/biblatex.tex b/Master/texmf-dist/doc/latex/biblatex/biblatex.tex
index 30dd748f13d..008aa423da0 100644
--- a/Master/texmf-dist/doc/latex/biblatex/biblatex.tex
+++ b/Master/texmf-dist/doc/latex/biblatex/biblatex.tex
@@ -1,9 +1,9 @@
-% $Id: biblatex.tex,v 0.9a 2010/03/19 19:52:15 lehman beta $
+% $Id: biblatex.tex,v 0.9d 2010/09/03 20:11:58 lehman beta $
\documentclass{ltxdockit}[2010/02/12]
\usepackage{btxdockit}
\usepackage[latin9]{inputenc}
\usepackage[american]{babel}
-\usepackage[strict,babel=once]{csquotes}
+\usepackage[strict]{csquotes}
\usepackage{tabularx}
\usepackage{booktabs}
\usepackage{shortvrb}
@@ -11,14 +11,14 @@
\MakeAutoQuote*{<}{>}
\MakeShortVerb{\|}
-\rcsid{$Id: biblatex.tex,v 0.9a 2010/03/19 19:52:15 lehman beta $}
+\rcsid{$Id: biblatex.tex,v 0.9d 2010/09/03 20:11:58 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},
+ title={The \sty{biblatex} Package},
+ subtitle={Programmable Bibliographies and Citations},
url={\BiblatexHome},
author={Philipp Lehman},
email={plehman@gmx.net},
@@ -26,8 +26,8 @@
date={\rcstoday}}
\hypersetup{%
- pdftitle={The biblatex package},
- pdfsubject={Programmable bibliographies and citations},
+ pdftitle={The biblatex Package},
+ pdfsubject={Programmable Bibliographies and Citations},
pdfauthor={Philipp Lehman},
pdfkeywords={tex, latex, bibtex, bibliography, references, citation}}
@@ -68,6 +68,7 @@
\printtitlepage
\tableofcontents
+\listoftables
\section{Introduction}
\label{int}
@@ -75,7 +76,7 @@
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}
+\subsection[About]{About \sty{biblatex}}
\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.
@@ -94,10 +95,12 @@ 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),
+Augusto Ritter Stoffel (Brazilian),
Alexander van Loon (Dutch),
Apostolos Syropoulos (Greek),
-Hannu Väisänen (Finnish).
+Hannu Väisänen (Finnish),
+Prokopis (Greek),
+Mateus Araújo (Brazilian).
\subsection{Prerequisites}
\label{int:pre}
@@ -121,13 +124,16 @@ By default, the \sty{biblatex} package uses \bibtex as a database backend. While
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/}
+This \latex package, which is loaded automatically, provides generic programming facilities required by \sty{biblatex}. It is available from \acr{CTAN}.\fnurl{http://www.ctan.org/tex-archive/macros/latex/contrib/etoolbox/}
+
+\item[logreq]
+This \latex package, which is also loaded automatically, provides a frontend for writing machine-readable messages to an auxiliary log file. It is available from \acr{CTAN}.\fnurl{http://www.ctan.org/tex-archive/macros/latex/contrib/logreq/}
\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}
+\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.
@@ -142,7 +148,7 @@ If this package is available, \sty{biblatex} will use its language sensitive quo
\end{marglist}
-\subsubsection{Compatible classes and packages}
+\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.
@@ -163,14 +169,14 @@ When using any of the \sty{scrartcl}, \sty{scrbook}, or \sty{scrreprt} classes,
\end{marglist}
-\subsubsection{Incompatible packages}
+\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
+% FIXME: complete the list
%
% amsrefs
% apacite
@@ -178,6 +184,7 @@ The packages listed in this section are not compatible with \sty{biblatex}. Sinc
% footbib
% multibbl
% overcite
+% bibtopicprefix
\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}.
@@ -221,19 +228,22 @@ The \sty{natbib} package supports numeric and author"=year citation schemes, inc
\item[splitbib]
The \sty{splitbib} package provides support for bibliographies subdivided by topic. See \sty{bibtopic}.
+\item[ucs]
+The \sty{ucs} package provides support for \acr{utf-8} encoded input. Either use \sty{inputenc}'s standard \file{utf8} module or a Unicode enabled engine such as \xelatex instead.
+
\end{marglist}
-\section{Database guide}
+\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}
+\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}
+\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 <required> fields are not strictly required in all cases, see \secref{bib:use:key} for details. The fields marked as <optional> are optional in a technical sense. Bibliographical formatting rules usually require more than just the <required> 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.
@@ -245,21 +255,21 @@ The lists below indicate the fields supported by each entry type. Note that the
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}
+\optitem{translator, annotator, commentator, subtitle, titleaddon, editor, editora, editorb, editorc, journalsubtitle, issuetitle, issuesubtitle, language, origlanguage, series, volume, number, eid, issue, month, pages, version, note, issn, addendum, pubstate, doi, eprint, eprintclass, 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}
+\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, eprintclass, 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}
+\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, eprintclass, eprinttype, url, urldate}
\typeitem{bookinbook}
@@ -274,21 +284,21 @@ Supplemental material in a \bibtype{book}. This type is closely related to the \
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}
+\optitem{subtitle, titleaddon, language, howpublished, type, note, location, chapter, pages, pagetotal, addendum, pubstate, doi, eprint, eprintclass, 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}
+\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, eprintclass, 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}
+\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, eprintclass, eprinttype, url, urldate}
\typeitem{suppcollection}
@@ -299,35 +309,35 @@ Supplemental material in a \bibtype{collection}. This type is similar to \bibtyp
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}
+\optitem{subtitle, titleaddon, language, edition, type, series, number, version, note, organization, publisher, location, isbn, chapter, pages, pagetotal, addendum, pubstate, doi, eprint, eprintclass, 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}
+\optitem{subtitle, titleaddon, language, howpublished, type, version, note, organization, location, date, month, year, addendum, pubstate, doi, eprint, eprintclass, 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}
+\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}
+\optitem{holder, subtitle, titleaddon, type, version, location, note, date, month, year, addendum, pubstate, doi, eprint, eprintclass, eprinttype, 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}
+\optitem{editora, editorb, editorc, subtitle, issuetitle, issuesubtitle, language, series, volume, number, issue, date, month, year, note, issn, addendum, pubstate, doi, eprint, eprintclass, eprinttype, url, urldate}
\typeitem{suppperiodical}
@@ -338,14 +348,14 @@ Supplemental material in a \bibtype{periodical}. This type is similar to \bibtyp
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}
+\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, eprintclass, 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}
+\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, eprintclass, eprinttype, url, urldate}
\typeitem{reference}
@@ -360,7 +370,7 @@ Articles in a work of reference. This is a more specific variant of the generic
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}
+\optitem{subtitle, titleaddon, language, number, version, note, location, month, isrn, chapter, pages, pagetotal, addendum, pubstate, doi, eprint, eprintclass, eprinttype, url, urldate}
\typeitem{set}
@@ -374,14 +384,14 @@ A reference set. This entry type is special, see \secref{use:use:set} for detail
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}
+\optitem{subtitle, titleaddon, language, note, location, month, chapter, pages, pagetotal, addendum, pubstate, doi, eprint, eprintclass, 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}
+\optitem{subtitle, titleaddon, language, howpublished, note, location, date, month, year, addendum, pubstate, url, urldate}
\typeitem{custom[a--f]}
@@ -389,7 +399,7 @@ Custom types for special bibliography styles. Not used by the standard styles.
\end{typelist}
-\subsubsection{Type aliases}
+\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}.
@@ -422,7 +432,7 @@ An alias of \bibtype{online}, provided for \sty{jurabib} compatibility.
\end{typelist}
-\subsubsection{Unsupported types}
+\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).
@@ -491,12 +501,12 @@ Audiovisual recordings, typically on \acr{DVD}, \acr{VHS} casette, or similar me
\end{typelist}
-\subsection{Entry fields}
+\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}
+\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.
@@ -541,7 +551,7 @@ In \file{bib} files all bibliographic data is specified in fields. Some of those
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}
+\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.
@@ -654,11 +664,15 @@ 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.
+The electronic identifier of an online publication. This is roughly comparable to a \acr{doi} but specific to a certain archive, repository, service, or system. See \secref{use:use:epr} for details. Also see \bibfield{eprinttype} and \bibfield{eprintclass}.
+
+\fielditem{eprintclass}{literal}
+
+Additional information related to the resource indicated by the \bibfield{eprinttype} field. This could be a section of an archive, a path indicating a service, a classification of some sort, etc. See \secref{use:use:epr} for details. Also see \bibfield{eprint} and \bibfield{eprinttype}.
\fielditem{eprinttype}{literal}
-The type of \bibfield{eprint} identifier. See \secref{use:use:epr} for details.
+The type of \bibfield{eprint} identifier, \eg the name of the archive, repository, service, or system the \bibfield{eprint} field refers to. See \secref{use:use:epr} for details. Also see \bibfield{eprint} and \bibfield{eprintclass}.
\fielditem{eventdate}{date}
@@ -838,7 +852,7 @@ 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.
+The name of a publication series, such as «Studies in \dots», or the number of a journal series. Books in a publication series are 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}
@@ -918,7 +932,7 @@ The year of publication. See also \bibfield{date} and \secref{bib:use:dat}.
\end{fieldlist}
-\subsubsection{Special fields}
+\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.
@@ -1027,7 +1041,7 @@ This field provides an alternative cross"=referencing mechanism. It differs from
\end{fieldlist}
-\subsubsection{Custom fields}
+\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.
@@ -1056,7 +1070,7 @@ Similar to the custom fields above except that these are verbatim fields. Not us
\end{fieldlist}
-\subsubsection{Field aliases}
+\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.
@@ -1065,31 +1079,39 @@ The aliases listed in this section are provided for backwards compatibility with
\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}.
+An alias of \bibfield{location}, provided for \bibtex compatibility. Traditional \bibtex uses the slightly misleading field name \bibfield{address} for the place of publication, \ie the location of the publisher, while \sty{biblatex} uses the generic field name \bibfield{location}. See \secref{bib:fld:dat,bib:use:and}.
\fielditem{annote}{literal}
-An alias of \bibfield{annotation}, provided for \sty{jurabib} compatibility.
+An alias of \bibfield{annotation}, provided for \sty{jurabib} compatibility. See \secref{bib:fld:dat}.
+
+\fielditem{archiveprefix}{literal}
+
+An alias of \bibfield{eprinttype}, provided for arXiv compatibility. See \secref{bib:fld:dat,use:use:epr}.
\fielditem{journal}{literal}
-An alias of \bibfield{journaltitle}, see \secref{bib:fld:dat}.
+An alias of \bibfield{journaltitle}, provided for \bibtex compatibility. See \secref{bib:fld:dat}.
\fielditem{key}{literal}
-An alias of \bibfield{sortkey}, see \secref{bib:fld:spc}.
+An alias of \bibfield{sortkey}, provided for \bibtex compatibility. 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.
+An alias of \bibfield{file}, provided for JabRef compatibility. See \secref{bib:fld:dat}.
+
+\fielditem{primaryclass}{literal}
+
+An alias of \bibfield{eprintclass}, provided for arXiv compatibility. See \secref{bib:fld:dat,use:use:epr}.
\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}.
+An alias of \bibfield{institution}, provided for \bibtex compatibility. The \bibfield{institution} field is used by traditional \bibtex for technical reports whereas the \bibfield{school} field holds the institution associated with theses. The \sty{biblatex} package employs the generic field name \bibfield{institution} in both cases. See \secref{bib:fld:dat,bib:use:and}.
\end{fieldlist}
-\subsection{Usage notes}
+\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.
@@ -1108,12 +1130,12 @@ This package includes some compatibility code for \file{bib} files which were ge
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}}
+\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}
+\subsubsection{Missing and Omissible Data}
\label{bib:use:key}
The fields marked as <required> 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.
@@ -1122,39 +1144,50 @@ You may generally use the \bibfield{label} field to provide a substitute for any
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}
+\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.
+Corporate authors and editors are given in the \bibfield{author} or \bibfield{editor} field, respectively. Note that they must 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}},
+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}
+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}
+\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.
+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 they contain 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},
+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 <and>. However, note that you will miss out on the additional features of literal lists in this case, such as configurable formatting and automatic truncation.
+Note the difference between a literal <|{and}|> and the list separator <|and|> in the above examples. You may also wrap the entire name 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}
+%
+Legacy files which have not been updated for use with \sty{biblatex} will still work if these fields do not contain a literal <and>. 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}
@@ -1221,7 +1254,7 @@ Suppose the first volume of the \emph{Collected Works} includes a reprinted essa
%
See \secref{bib:use:ser} for further examples.
-\subsubsection{Editorial roles}
+\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.
@@ -1281,7 +1314,7 @@ Note that only the \bibfield{editor} is considered in citations and when sorting
%
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}
+\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:
@@ -1320,7 +1353,7 @@ This entry will be printed as «\emph{Journal Name}. 3rd ser. 15.7 (1995)». Some
%
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}
+\subsubsection{Date Specifications}
\label{bib:use:dat}
\begin{table}
@@ -1347,12 +1380,12 @@ This entry will be printed as «\emph{Journal Name}. New ser. 9 (1998)». See \sec
\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}.
+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}. See this section and \tabref{aut:bbx:fld:tab1} on page~\pageref{aut:bbx:fld:tab1} for further information.
-\subsubsection{Years, months and journal issues}
+\subsubsection{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 <Spring> or <Summer> 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.
+The \bibfield{month} field is an integer field. The bibliography style converts the month to a language"=dependent string 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 <Spring> or <Summer> 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}
@@ -1373,17 +1406,17 @@ The \bibfield{bookpagination} field affects the formatting of the \bibfield{page
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}
+\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}
+\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}
+\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:
@@ -1440,7 +1473,7 @@ bibtex8 --wolfgang --mcites 30000 --mentints 30000 --mentstrs 40000
%
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}
+\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:
@@ -1526,88 +1559,24 @@ Not only \bibtex, \tex needs to know about the encoding as well. When using non"
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}
+\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.
+This section is in the process of being rewritten to match the new script interface used by \sty{biblatex}. For the time being, see the documentation of the \sty{logreq} package\fnurl{http://www.ctan.org/tex-archive/macros/latex/contrib/logreq/} and the Biblatex Developer's Wiki for a draft spec.\fnurl{http://sourceforge.net/apps/mediawiki/biblatex/index.php?title=Workflow_Automation}
-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}.
+% FIXME: update!
-\begin{lstlisting}[style=highlight]{}
-REQ:<<priority>>:<<application>>: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:<<priority>>:<<application>>:
-binary=<<binary>>
-option=<<option>>
-infile=<<infile>>
-:REQ
-\end{lstlisting}
-%
-Whenever this package requests a \bibtex run it will also request an additional \latex run, but not vice versa. \latex requests use the terse format, \bibtex requests require the verbose one. This package uses three different keywords in \bibtex requests. The \texttt{binary} keyword indicates the name of the requested binary. This may be different from the generic name. The \texttt{option} keyword indicates a command"=line option to be passed to the binary. This keyword may occur zero or multiple times. The \texttt{infile} keyword indicates the name of the \file{aux} file without the file suffix. As an example, consider a \latex file named \path{example.tex} with some citations and a bibliography. In this case, the following requests are written to the console and the transcript file:
-
-\begin{lstlisting}[style=plain]{}
-REQ:2:bibtex:
-binary=bibtex
-infile=example
-:REQ
-\end{lstlisting}
-
-\begin{lstlisting}[style=plain,aboveskip=0pt]{}
-REQ:1:latex:REQ
-\end{lstlisting}
-%
-As the priority indicates, \bibtex should be run first and \latex afterwards (a higher number indicates a higher priority). Now consider a source file named \path{example.tex} with two \env{refsection} environments:
-
-\begin{lstlisting}[style=plain]{}
-REQ:2:bibtex:
-binary=bibtex
-infile=example1-blx
-:REQ
-\end{lstlisting}
-
-\begin{lstlisting}[style=plain,aboveskip=0pt]{}
-REQ:2:bibtex:
-binary=bibtex
-infile=example2-blx
-:REQ
-\end{lstlisting}
-
-\begin{lstlisting}[style=plain,aboveskip=0pt]{}
-REQ:1:latex:REQ
-\end{lstlisting}
-%
-Note that the package options discussed in \secref{use:opt:pre} affect the format of all \bibtex requests. For example, setting \kvopt{mincrossrefs}{5} yields the following options:
-
-\begin{lstlisting}[style=plain]{}
-binary=bibtex
-option=-min-crossrefs=5
-\end{lstlisting}
-%
-The \opt{backend} option affects the name of the requested binary and the format of the command"=line arguments. For example, the package options \kvopt{backend}{bibtex8}, \kvopt{mincrossrefs}{5}, and \kvopt{bibencoding}{latin9} yield the following options:
-
-\begin{lstlisting}[style=plain]{}
-binary=bibtex8
-option=--min_crossrefs 5
-option=--csfile latin9.csf
-\end{lstlisting}
-%
-When parsing the values assigned to keys like \texttt{option} and \texttt{infile}, keep in mind that they are terminated by the end of the line. In theory, they may contain any Ascii character except newline and carriage return.
-
-\section{User guide}
+\section{User Guide}
\label{use}
This part of the manual documents the user interface of the \sty{biblatex} package. The user guide covers everything you need to know in order to use \sty{biblatex} with the default styles that come with this package. You should read the user guide first in any case. If you want to write your own citation and\slash or bibliography styles, continue with the author guide afterwards.
-\subsection{Package options}
+\subsection{Package Options}
\label{use:opt}
All package options are given in \keyval notation. The value \texttt{true} is omissible with all boolean keys. For example, giving \opt{sortcites} without a value is equivalent to \kvopt{sortcites}{true}.
-\subsubsection{Load-time options}
+\subsubsection{Load-time Options}
\label{use:opt:ldt}
The following options must be used as \sty{biblatex} is loaded, \ie in the optional argument to \cmd{usepackage}.
@@ -1632,7 +1601,7 @@ Loads a compatibility style for the \sty{natbib} package in addition to the main
\end{optionlist}
-\subsubsection{Preamble options}
+\subsubsection{Preamble Options}
\label{use:opt:pre:beg}
\label{use:opt:pre}
@@ -1640,7 +1609,7 @@ The following options may be used in the optional argument to \cmd{usepackage} a
\begin{optionlist}
-\optitem[nty]{sorting}{\opt{nty}, \opt{nyt}, \opt{nyvt}, \opt{anyt}, \opt{anyvt}, \opt{ynt}, \opt{ydnt}, \opt{debug}, \opt{none}}
+\optitem[nty]{sorting}{\opt{nty}, \opt{nyt}, \opt{nyvt}, \opt{anyt}, \opt{anyvt}, \opt{ynt}, \opt{ydnt}, \opt{none}, \opt{debug}}
The sorting order of the bibliography. Unless stated otherwise, the entries are sorted in ascending order. The following choices are available:
@@ -1652,12 +1621,16 @@ The sorting order of the bibliography. Unless stated otherwise, the entries are
\item[anyvt] Sort by alphabetic label, name, year, volume, title.
\item[ynt] Sort by year, name, title.
\item[ydnt] Sort by year (descending), name, title.
-\item[debug] Sort by entry key. This is intended for debugging only.
\item[none] Do not sort at all. All entries are processed in citation order.
+\item[debug] Sort by entry key. This is intended for debugging only.
\end{valuelist}
Please refer to \secref{use:srt} for an in"=depth explanation of the above sorting options as well as the fields considered in the sorting process. Using any of the <alphabetic> sorting orders only makes sense in conjunction with a bibliography style which prints the corresponding labels. Note that some bibliography styles initialize this package option to a value different from the package default (\opt{nty}). See \secref{use:xbx:bbx} for details.
+\boolitem[true]{sortcase}
+
+Whether to sort the bibliography and the list of shorthands in a case"=sensitive way. Note that case"=sensitive sorting is only supported by the \bin{bibtex8} and Biber backends. Sorting is always case"=insensitive with legacy \bibtex. See the \opt{backend} option for details.
+
\optitem[los]{sortlos}{\opt{bib}, \opt{los}}
The sorting order of the list of shorthands. The following choices are available:
@@ -1669,7 +1642,7 @@ The sorting order of the list of shorthands. The following choices are available
\boolitem[false]{sortcites}
-Whether to sort the labels if multiple entry keys are passed to a citation command. If this option is enabled, names and labels are sorted according to the sorting order of the bibliography. This feature works with all citation styles.
+Whether to sort citations if multiple entry keys are passed to a citation command. If this option is enabled, citations are sorted according to the sorting order of the bibliography. This feature works with all citation styles.
\intitem[3]{maxnames}
@@ -1734,6 +1707,10 @@ Swedish & Sweden & \opt{swedish} \\
\label{use:opt:tab1}
\end{table}
+\boolitem[true]{clearlang}
+
+If this option is enabled, \sty{biblatex} will automatically clear the \bibfield{language} field of all entries whose language matches the \sty{babel} language of the document (or the language specified explicitly with the \opt{language} option) in order to omit redundant language specifications. The language mappings required by this feature are provided by the \cmd{DeclareRedundantLanguages} command from \secref{aut:lng:cmd}.
+
\optitem[none]{babel}{\opt{none}, \opt{hyphen}, \opt{other}, \opt{other*}}
This option controls which language environment is used if the \sty{babel} package is loaded and a bibliography entry includes a \bibfield{hyphenation} field (see \secref{bib:fld:spc}). Note that \sty{biblatex} automatically adjusts to the main document language if \sty{babel} is loaded. In multilingual documents, it will also continually adjust to the current language as far as citations and the default language of the bibliography is concerned. This option is for switching languages on a per"=entry basis within the bibliography. The possible choices are:
@@ -1750,7 +1727,7 @@ Enclose the entry in a \env{hyphenrules} environment. This will load hyphenation
Enclose the entry in an \env{otherlanguage} environment. This will load hyphenation patterns for the specified language, enable all extra definitions which \sty{babel} and \sty{biblatex} provide for the respective language, and translate key terms such as <editor> and <volume>. The extra definitions include localizations of the date format, of ordinals, and similar things.
\item[other*]
-Enclose the entry in an \env{otherlanguage*} environment. This is similar to \env{otherlanguage} except that the translations are not used.
+Enclose the entry in an \env{otherlanguage*} environment. Please note that \sty{biblatex} treats \env{otherlanguage*} like \env{otherlanguage} but other packages may make a distinction in this case.
\end{valuelist}
@@ -1863,7 +1840,7 @@ This option automatically executes the \cmd{citereset} command from \secref{use:
Whether to use long or abbreviated strings in citations and in the bibliography. This option affects the localization modules. If this option is enabled, key terms such as <editor> are abbreviated. If not, they are written out.
-\optitem[comp]{date}{\opt{short}, \opt{long}, \opt{terse}, \opt{comp}}
+\optitem[comp]{date}{\opt{short}, \opt{long}, \opt{terse}, \opt{comp}, \opt{iso8601}}
This option controls the basic format of printed date specifications. The following choices are available:
@@ -1882,31 +1859,38 @@ January 21, 2010--January 30, 2010\par
\item[comp] Use the long format with compact ranges, for example:\par
21st--30th January 2010\par
January 21--30, 2010\par
+\item[iso8601] Use extended \acr{ISO-8601} format (\texttt{yyyy-mm-dd}), for example:\par
+2010-01-01\par
+2010-01-21/2010-01-30
\end{valuelist}
%
As seen in the above examples, the actual date format is language specific. Note that the month name in all long formats is responsive to the \opt{abbreviate} package option. The leading zeros in all short formats may be controlled separately with the \opt{datezeros} package option.
-\optitem[comp]{origdate}{\opt{short}, \opt{long}, \opt{terse}, \opt{comp}}
+\optitem[comp]{origdate}{\opt{short}, \opt{long}, \opt{terse}, \opt{comp}, \opt{iso8601}}
Similar to the \opt{date} option but controls the format of the \bibfield{origdate}.
-\optitem[comp]{eventdate}{\opt{short}, \opt{long}, \opt{terse}, \opt{comp}}
+\optitem[comp]{eventdate}{\opt{short}, \opt{long}, \opt{terse}, \opt{comp}, \opt{iso8601}}
Similar to the \opt{date} option but controls the format of the \bibfield{eventdate}.
-\optitem[short]{urldate}{\opt{short}, \opt{long}, \opt{terse}, \opt{comp}}
+\optitem[short]{urldate}{\opt{short}, \opt{long}, \opt{terse}, \opt{comp}, \opt{iso8601}}
Similar to the \opt{date} option but controls the format of the \bibfield{urldate}.
-\optitem{alldates}{\opt{short}, \opt{long}, \opt{terse}, \opt{comp}}
+\optitem{alldates}{\opt{short}, \opt{long}, \opt{terse}, \opt{comp}, \opt{iso8601}}
Sets all of the above date options to the same value.
\boolitem[true]{datezeros}
-This option controls whether short dates are printed with leading zeros.
+This option controls whether \texttt{short} and \texttt{terse} dates are printed with leading zeros.
+
+\boolitem[true]{dateabbrev}
+
+This option controls whether \texttt{long} and \texttt{comp} dates are printed with long or abbreviated month names. The option is similar to the generic \opt{abbreviate} option but specific to the date formatting.
-\boolitem[false]{defernums}
+\boolitem[false]{defernumbers}
In contrast to standard \latex, the numeric labels generated by this package are normally assigned to the full list of references at the beginning of the document body. If this option is enabled, numeric labels (\ie the \bibfield{labelnumber} field discussed in \secref{aut:bbx:fld}) are assigned the first time an entry is printed in any bibliography. See \secref{use:cav:lab} for further explanation.
@@ -1916,7 +1900,7 @@ This option enables an alternative mechanism for dealing with unit punctuation a
\optitem[abs]{arxiv}{\opt{abs}, \opt{ps}, \opt{pdf}, \opt{format}}
-Path selector for arXiv links. If hyperlink support is enabled, this option controls which version of the document any arXiv \bibfield{eprint} links will point to. The following choices are available:
+Path selector for arXiv links. If hyperlink support is enabled, this option controls which version of the document the arXiv \bibfield{eprint} links will point to. The following choices are available:
\begin{valuelist}
\item[abs] Link to the abstract page.
@@ -1933,11 +1917,11 @@ Specifies the database backend. The following backends are supported:
\begin{valuelist}
-\item[bibtex] Legacy \bibtex. With legacy \bibtex, sorting is case"=insensitive and only supports Ascii encoding.
+\item[bibtex] Legacy \bibtex. Traditional \bibtex supports Ascii encoding only. Sorting is always case"=insensitive, regardless of the \opt{sortcase} option.
-\item[bibtex8] \bin{bibtex8}, the 8-bit implementation of \bibtex. With \bin{bibtex8}, sorting is case"=sensitive and supports 8-bit encodings such as Latin~1.
+\item[bibtex8] \bin{bibtex8}, the 8-bit implementation of \bibtex, supports Ascii and 8-bit encodings, such as Latin~1. Depending on the \opt{sortcase} option, case"=sensitive sorting is supported.
-\item[biber] Biber, the next"=generation database backend of \sty{biblatex}. With Biber, sorting is case"=sensitive and supports 8-bit encodings as well as \utf.
+\item[biber] Biber, the next"=generation database backend of \sty{biblatex}, supports Ascii, 8-bit encodings, and \utf. Depending on the \opt{sortcase} option, case"=sensitive sorting is supported.
\end{valuelist}
@@ -1969,7 +1953,7 @@ Note that \kvopt{bibencoding}{inputenc} and \kvopt{bibencoding}{\prm{encoding}}
\end{optionlist}
-\subsubsection{Style options}
+\subsubsection{Style Options}
\label{use:opt:bbx}
The following options are provided by the standard styles (as opposed to the core package). Technically, they are preamble options like those in \secref{use:opt:pre}.
@@ -1994,12 +1978,13 @@ This option controls whether \bibfield{eprint} information is printed.
\end{optionlist}
-\subsubsection{Entry options}
+\subsubsection{Entry Options}
\label{use:opt:bib}
Entry options are package options which can be adjusted on a per"=entry basis in the \bibfield{options} field from \secref{bib:fld:spc}.
-\paragraph{Hybrid entry/preamble options}
+\paragraph{Hybrid Entry/Preamble Options}
+\label{use:opt:bib:hyb}
The following options are settable on a per"=entry basis in the \bibfield{options} field. In addition to that, they may also be used in the optional argument to \cmd{usepackage} as well as in the configuration file and the document preamble. This is useful if you want to change the default behavior globally.
@@ -2033,7 +2018,8 @@ Whether the name prefix (von, van, of, da, de, della, etc.) is considered when p
\end{optionlist}
-\paragraph{Dedicated entry options}
+\paragraph{Dedicated Entry Options}
+\label{use:opt:bib:ded}
The following options are only settable on a per"=entry basis in the \bibfield{options} field. They are not available globally.
@@ -2057,7 +2043,7 @@ Setting this option is equivalent to \opt{skipbib}, \opt{skiplos}, and \opt{skip
\end{optionlist}
-\subsubsection{Internal options}
+\subsubsection{Internal Options}
\label{use:opt:pre:end}
\label{use:opt:int}
@@ -2122,7 +2108,7 @@ Note that this tracker is disabled in all floats, see \secref{aut:cav:flt}.
\optitem[false]{opcittracker}{\opt{true}, \opt{false}, \opt{context}, \opt{strict}, \opt{constrict}}
-This option controls the <opcit> tracker which is required by the \cmd{ifopcit} test from \secref{aut:aux:tst}. This feature is similar to the <ibidem> tracker except that it tracks citations on a per-author/editor basis, \ie \cmd{ifopcit} will yield \texttt{true} if the cited item is the same as the last one by this author or editor. The possible choices are:
+This option controls the <opcit> tracker which is required by the \cmd{ifopcit} test from \secref{aut:aux:tst}. This feature is similar to the <ibidem> tracker except that it tracks citations on a per-author/editor basis, \ie \cmd{ifopcit} will yield \texttt{true} if the cited item is the same as the last one by this author\slash editor. The possible choices are:
\begin{valuelist}
\item[true] Enable the tracker in global mode.
@@ -2186,7 +2172,7 @@ Whether to set the \cnt{uniquename} counter, see \secref{aut:aux:tst} for detail
\end{optionlist}
-\subsubsection{Legacy options}
+\subsubsection{Legacy Options}
The following legacy option may be used globally in the optional argument to \cmd{documentclass} or locally in the optional argument to \cmd{usepackage}:
@@ -2197,20 +2183,20 @@ This option is provided for backwards compatibility with the standard LaTeX docu
\end{optionlist}
-\subsection{Global customization}
+\subsection{Global Customization}
\label{use:cfg}
Apart from writing new citation and bibliography styles, there are numerous ways to customize the styles which ship with this package. Customization will usually take place in the preamble, but there is also a configuration file for permanent adaptions. The configuration file may also be used to initialize the package options to a value different from the package default.
-\subsubsection{Configuration file}
+\subsubsection{Configuration File}
\label{use:cfg:cfg}
If available, this package will load the configuration file \path{biblatex.cfg}. This file is read at the end of the package, immediately after the citation and bibliography styles have been loaded.
-\subsubsection{Executing package options}
+\subsubsection{Executing Package Options}
\label{use:cfg:opt}
-The load-time package options in \secref{use:opt:ldt} must be given in the optional argument to \cmd{usepackage}. All package options in \secref{use:opt:pre:beg}--\ref{use:opt:pre:end}, however, may also be given in the preamble. The options are executed with the following command:
+The load-time package options in \secref{use:opt:ldt} must be given in the optional argument to \cmd{usepackage}. The package options in \secref{use:opt:pre:beg}--\ref{use:opt:pre:end}, except those in \secref{use:opt:bib:ded}, may also be given in the preamble. The options are executed with the following command:
\begin{ltxsyntax}
\cmditem{ExecuteBibliographyOptions}{key=value,\,\dots}
@@ -2218,12 +2204,12 @@ The load-time package options in \secref{use:opt:ldt} must be given in the optio
This command may also be used in the configuration file to modify the default setting of a package option.
\end{ltxsyntax}
-\subsection{Standard styles}
+\subsection{Standard Styles}
\label{use:xbx}
This section provides a short description of all bibliography and citation styles which ship with the \sty{biblatex} package. If you want to write your own styles, see \secref{aut}.
-\subsubsection{Citation styles}
+\subsubsection{Citation Styles}
\label{use:xbx:cbx}
The citation styles which come with this package implement several common citation schemes. All standard styles cater for the \bibfield{shorthand} field and support hyperlinks as well as indexing.
@@ -2270,31 +2256,34 @@ A variant of the \texttt{authortitle} style which replaces repeated citations by
A style combining the features of \texttt{authortitle-comp} and \texttt{authortitle-ibid}. The style will set the following package options at load time: \kvopt{autocite}{footnote}, \kvopt{ibidtracker}{constrict}, \kvopt{pagetracker}{true}, \kvopt{sortcites}{true}. This style also provides an additional preamble option called \opt{ibidpage}. See the style example for details.
\item[authortitle-terse]
-A terse variant of the \texttt{authortitle} style which only prints the title if the bibliography contains more than one work by the respective author or editor. This style will make use of the \bibfield{shorttitle} field, if available. It is suitable for in-text citations as well as citations given in footnotes. The style will set the following package options at load time: \kvopt{autocite}{inline}, \kvopt{singletitle}{true}, \kvopt{uniquename}{true}.
+A terse variant of the \texttt{authortitle} style which only prints the title if the bibliography contains more than one work by the respective author\slash editor. This style will make use of the \bibfield{shorttitle} field, if available. It is suitable for in-text citations as well as citations given in footnotes. The style will set the following package options at load time: \kvopt{autocite}{inline}, \kvopt{singletitle}{true}, \kvopt{uniquename}{true}.
\item[authortitle-tcomp]
A style combining the features of \texttt{authortitle-comp} and \texttt{authortitle-terse}. This style will make use of the \bibfield{shorttitle} field, if available. It is suitable for in-text citations as well as citations given in footnotes. The style will set the following package options at load time: \kvopt{autocite}{inline}, \kvopt{sortcites}{true}, \kvopt{singletitle}{true}, \kvopt{uniquename}{true}.
+\item[authortitle-ticomp]
+A style combining the features of \texttt{authortitle-icomp} and \texttt{authortitle-terse}. In other words: a variant of the \texttt{authortitle-tcomp} style with an \emph{ibidem} feature. This style is suitable for in-text citations as well as citations given in footnotes. It will set the following package options at load time: \kvopt{autocite}{inline}, \kvopt{ibidtracker}{constrict}, \kvopt{pagetracker}{true}, \kvopt{sortcites}{true}, \kvopt{singletitle}{true}, \kvopt{uniquename}{true}. This style also provides an additional preamble option called \opt{ibidpage}. See the style example for details.
+
\item[verbose]
-A verbose citation style which prints a full citation similar to a bibliography entry when an entry is cited for the first time, and a short citation afterwards. If available, the \bibfield{shorttitle} field is used in all short citations. If the \bibfield{shorthand} field is defined, the shorthand is introduced on the first citation and used as the short citation thereafter. This style may be used without a list of references and shorthands since all bibliographic data is provided on the first citation. It is intended for citations given in footnotes. The style will set the following package options at load time: \kvopt{autocite}{footnote}, \kvopt{citetracker}{context}.
+A verbose citation style which prints a full citation similar to a bibliography entry when an entry is cited for the first time, and a short citation afterwards. If available, the \bibfield{shorttitle} field is used in all short citations. If the \bibfield{shorthand} field is defined, the shorthand is introduced on the first citation and used as the short citation thereafter. This style may be used without a list of references and shorthands since all bibliographic data is provided on the first citation. It is intended for citations given in footnotes. The style will set the following package options at load time: \kvopt{autocite}{footnote}, \kvopt{citetracker}{context}. This style also provides an additional preamble option called \opt{citepages}. See the style example for details.
\item[verbose-ibid]
-A variant of the \texttt{verbose} style which replaces repeated citations by the abbreviation \emph{ibidem} unless the citation is the first one on the current page or double-page spread, or the \emph{ibidem} would be ambiguous in the sense of \kvopt{ibidtracker}{strict}. This style is intended for citations given in footnotes. The style will set the following package options at load time: \kvopt{autocite}{footnote}, \kvopt{citetracker}{context}, \kvopt{ibidtracker}{constrict}, \kvopt{pagetracker}{true}. This style also provides an additional preamble option called \opt{ibidpage}. See the style example for details.
+A variant of the \texttt{verbose} style which replaces repeated citations by the abbreviation \emph{ibidem} unless the citation is the first one on the current page or double-page spread, or the \emph{ibidem} would be ambiguous in the sense of \kvopt{ibidtracker}{strict}. This style is intended for citations given in footnotes. The style will set the following package options at load time: \kvopt{autocite}{footnote}, \kvopt{citetracker}{context}, \kvopt{ibidtracker}{constrict}, \kvopt{pagetracker}{true}. This style also provides additional preamble options called \opt{ibidpage} and \opt{citepages}. See the style example for details.
\item[verbose-note]
-This style is similar to the \texttt{verbose} style in that it prints a full citation similar to a bibliography entry when an entry is cited for the first time, and a short citation afterwards. In contrast to the \texttt{verbose} style, the short citation is a pointer to the footnote with the full citation. If the bibliography contains more than one work by the respective author or editor, the pointer also includes the title. If available, the \bibfield{shorttitle} field is used in all short citations. If the \bibfield{shorthand} field is defined, it is handled as with the \texttt{verbose} style. This style may be used without a list of references and shorthands since all bibliographic data is provided on the first citation. It is exclusively intended for citations given in footnotes. The style will set the following package options at load time: \kvopt{autocite}{footnote}, \kvopt{citetracker}{context}, \kvopt{singletitle}{true}. This style also provides an additional preamble option called \opt{pageref} which adds the page to the footnote number pointing to the full citation if it is located on a different page. This option. See the style example for details.
+This style is similar to the \texttt{verbose} style in that it prints a full citation similar to a bibliography entry when an entry is cited for the first time, and a short citation afterwards. In contrast to the \texttt{verbose} style, the short citation is a pointer to the footnote with the full citation. If the bibliography contains more than one work by the respective author\slash editor, the pointer also includes the title. If available, the \bibfield{shorttitle} field is used in all short citations. If the \bibfield{shorthand} field is defined, it is handled as with the \texttt{verbose} style. This style may be used without a list of references and shorthands since all bibliographic data is provided on the first citation. It is exclusively intended for citations given in footnotes. The style will set the following package options at load time: \kvopt{autocite}{footnote}, \kvopt{citetracker}{context}, \kvopt{singletitle}{true}. This style also provides additional preamble options called \opt{pageref} and \opt{citepages}. See the style example for details.
\item[verbose-inote]
-A variant of the \texttt{verbose"=note} style which replaces repeated citations by the abbreviation \emph{ibidem} unless the citation is the first one on the current page or double-page spread, or the \emph{ibidem} would be ambiguous in the sense of \kvopt{ibidtracker}{strict}. This style is exclusively intended for citations given in footnotes. It will set the following package options at load time: \kvopt{autocite}{footnote}, \kvopt{citetracker}{context}, \kvopt{ibidtracker}{constrict}, \kvopt{singletitle}{true}, \kvopt{pagetracker}{true}. This style also provides two additional preamble options called \opt{ibidpage} and \opt{pageref}. See the style example for details.
+A variant of the \texttt{verbose"=note} style which replaces repeated citations by the abbreviation \emph{ibidem} unless the citation is the first one on the current page or double-page spread, or the \emph{ibidem} would be ambiguous in the sense of \kvopt{ibidtracker}{strict}. This style is exclusively intended for citations given in footnotes. It will set the following package options at load time: \kvopt{autocite}{footnote}, \kvopt{citetracker}{context}, \kvopt{ibidtracker}{constrict}, \kvopt{singletitle}{true}, \kvopt{pagetracker}{true}. This style also provides additional preamble options called \opt{ibidpage}, \opt{pageref}, and \opt{citepages}. See the style example for details.
\item[verbose-trad1]
-This style implements a traditional citation scheme. It is similar to the \texttt{verbose} style in that it prints a full citation similar to a bibliography entry when an item is cited for the first time, and a short citation afterwards. Apart from that, it uses the scholarly abbreviations \emph{ibidem}, \emph{idem}, \emph{op.~cit.}, and \emph{loc.~cit.} to replace recurrent authors, titles, and page numbers in repeated citations in a special way. If the \bibfield{shorthand} field is defined, the shorthand is introduced on the first citation and used as the short citation thereafter. This style may be used without a list of references and shorthands since all bibliographic data is provided on the first citation. It is intended for citations given in footnotes. The style will set the following package options at load time: \kvopt{autocite}{footnote}, \kvopt{citetracker}{context}, \kvopt{ibidtracker}{constrict}, \kvopt{idemtracker}{constrict}, \kvopt{opcittracker}{context}, \kvopt{loccittracker}{context}. This style also provides two additional preamble options called \opt{ibidpage} and \opt{strict}. See the style example for details.
+This style implements a traditional citation scheme. It is similar to the \texttt{verbose} style in that it prints a full citation similar to a bibliography entry when an item is cited for the first time, and a short citation afterwards. Apart from that, it uses the scholarly abbreviations \emph{ibidem}, \emph{idem}, \emph{op.~cit.}, and \emph{loc.~cit.} to replace recurrent authors, titles, and page numbers in repeated citations in a special way. If the \bibfield{shorthand} field is defined, the shorthand is introduced on the first citation and used as the short citation thereafter. This style may be used without a list of references and shorthands since all bibliographic data is provided on the first citation. It is intended for citations given in footnotes. The style will set the following package options at load time: \kvopt{autocite}{footnote}, \kvopt{citetracker}{context}, \kvopt{ibidtracker}{constrict}, \kvopt{idemtracker}{constrict}, \kvopt{opcittracker}{context}, \kvopt{loccittracker}{context}. This style also provides additional preamble options called \opt{ibidpage}, \opt{strict}, and \opt{citepages}. See the style example for details.
\item[verbose-trad2]
-Another traditional citation scheme. It is also similar to the \texttt{verbose} style but uses scholarly abbreviations like \emph{ibidem} and \emph{idem} in repeated citations. In contrast to the \texttt{verbose-trad1} style, the logic of the \emph{op.~cit.} abbreviations is different in this style and \emph{loc.~cit.} is not used at all. It is in fact more similar to \texttt{verbose-ibid} and \texttt{verbose-inote} than to \texttt{verbose-trad1}. The style will set the following package options at load time: \kvopt{autocite}{footnote}, \kvopt{citetracker}{context}, \kvopt{ibidtracker}{constrict}, \kvopt{idemtracker}{constrict}. This style also provides two additional preamble options called \opt{ibidpage} and \opt{strict}. See the style example for details.
+Another traditional citation scheme. It is also similar to the \texttt{verbose} style but uses scholarly abbreviations like \emph{ibidem} and \emph{idem} in repeated citations. In contrast to the \texttt{verbose-trad1} style, the logic of the \emph{op.~cit.} abbreviations is different in this style and \emph{loc.~cit.} is not used at all. It is in fact more similar to \texttt{verbose-ibid} and \texttt{verbose-inote} than to \texttt{verbose-trad1}. The style will set the following package options at load time: \kvopt{autocite}{footnote}, \kvopt{citetracker}{context}, \kvopt{ibidtracker}{constrict}, \kvopt{idemtracker}{constrict}. This style also provides additional preamble options called \opt{ibidpage}, \opt{strict}, and \opt{citepages}. See the style example for details.
\item[verbose-trad3]
-Yet another traditional citation scheme. It is similar to the \texttt{verbose-trad2} style but uses the scholarly abbreviations \emph{ibidem} and \emph{op.~cit.} in a slightly different way. The style will set the following package options at load time: \kvopt{autocite}{footnote}, \kvopt{citetracker}{context}, \kvopt{ibidtracker}{constrict}, \kvopt{loccittracker}{constrict}. This style also provides an additional preamble option called \opt{strict}. See the style example for details.
+Yet another traditional citation scheme. It is similar to the \texttt{verbose-trad2} style but uses the scholarly abbreviations \emph{ibidem} and \emph{op.~cit.} in a slightly different way. The style will set the following package options at load time: \kvopt{autocite}{footnote}, \kvopt{citetracker}{context}, \kvopt{ibidtracker}{constrict}, \kvopt{loccittracker}{constrict}. This style also provides additional preamble options called \opt{strict} and \opt{citepages}. See the style example for details.
\item[reading]
A citation style which goes with the bibliography style by the same name. It simply loads the \texttt{authortitle} style.
@@ -2313,7 +2302,7 @@ This style prints the entry key rather than some kind of label. It is intended f
\end{marglist}
-\subsubsection{Bibliography styles}
+\subsubsection{Bibliography Styles}
\label{use:xbx:bbx}
All bibliography styles which come with this package use the same basic format for the individual bibliography entries. They only differ in the kind of label printed in the bibliography and the overall formatting of the list of references. There is a matching bibliography style for every citation style. Note that some bibliography styles are not mentioned below because they simply load a more generic style. For example, the bibligraphy style \texttt{authortitle-comp} will load the \texttt{authortitle} style.
@@ -2327,7 +2316,7 @@ This style prints a numeric label similar to the standard bibliographic faciliti
This style prints an alphabetic label similar to the \path{alpha.bst} style of traditional \bibtex. It is intended for use in conjunction with an alphabetic citation style. Note that the \bibfield{shorthand} field overrides the default label. The style will set the following package options at load time: \kvopt{labelalpha}{true}, \kvopt{sorting}{anyt}.
\item[authoryear]
-This style differs from the other styles in that the publication date is not printed towards the end of the entry but rather after the author or editor. It is intended for use in conjunction with an author"=year citation style. Recurring author and editor names are replaced by a dash unless the entry is the first one on the current page or double-page spread. This style also provides an additional preamble option called \opt{dashed} which controls this feature. See the style example for details. The style will set the following package options at load time: \kvopt{labelyear}{true}, \kvopt{sorting}{nyt}, \kvopt{pagetracker}{true}.
+This style differs from the other styles in that the publication date is not printed towards the end of the entry but rather after the author\slash editor. It is intended for use in conjunction with an author"=year citation style. Recurring author and editor names are replaced by a dash unless the entry is the first one on the current page or double-page spread. This style also provides an additional preamble option called \opt{dashed} which controls this feature. See the style example for details. The style will set the following package options at load time: \kvopt{labelyear}{true}, \kvopt{sorting}{nyt}, \kvopt{pagetracker}{true}.
\item[authortitle]
This style does not print any label at all. It is intended for use in conjunction with an author"=title citation style. Recurring author and editor names are replaced by a dash unless the entry is the first one on the current page or double-page spread. This style also provides an additional preamble option called \opt{dashed} which controls this feature. See the style example for details. The style will set the following package options at load time: \kvopt{pagetracker}{true}.
@@ -2352,7 +2341,7 @@ This style prints all bibliographic data in tabular format. It is intended for d
\end{marglist}
-\subsection{Sorting options}
+\subsection{Sorting Options}
\label{use:srt}
\begin{table}
@@ -2405,7 +2394,7 @@ nyvt &\bibfield{presort}&\new&\bibfield{sortname}
&\altstr{mm}\\
\bottomrule
\end{tabularx}
-\caption{Alphabetic Sorting Schemes I}
+\caption[Alphabetic Sorting I]{Alphabetic Sorting Schemes I}
\label{use:srt:tab1}
\end{table}
@@ -2454,7 +2443,7 @@ anyvt &\bibfield{presort}&\new&\bibfield{labelalpha}
&\altstr{mm}\\
\bottomrule
\end{tabularx}
-\caption{Alphabetic Sorting Schemes II}
+\caption[Alphabetic Sorting II]{Alphabetic Sorting Schemes II}
\label{use:srt:tab2}
\end{table}
@@ -2498,14 +2487,14 @@ ydnt &\bibfield{presort}&\new&\bibfield{sortyear} (desc.)
&\altstr{mm}\\
\bottomrule
\end{tabularx}
-\caption{Chronological Sorting Schemes}
+\caption[Chronological Sorting]{Chronological Sorting Schemes}
\label{use:srt:tab3}
\end{table}
-\subsection{Bibliography commands}
+\subsection{Bibliography Commands}
\label{use:bib}
-\subsubsection{The bibliography}
+\subsubsection{The Bibliography}
\label{use:bib:bib}
\begin{ltxsyntax}
@@ -2602,6 +2591,18 @@ Print only entries not assigned to category \prm{category}. This option may be u
Print only entries matching the filter \prm{name}, as defined with \cmd{defbibfilter}. See \secref{use:bib:flt} for details.
+\valitem{prefixnumbers}{string}
+
+This option applies to numerical citation\slash bibliography styles only and requires that the \opt{defernumbers} option from \secref{use:opt:pre} be enabled globally. Setting this option will implicitly enable \opt{resetnumbers} for the current bibliography. The option assigns the \prm{string} as a prefix to all entries in the respective bibliography. For example, if the \prm{string} is \texttt{A}, the numerical labels printed will be \texttt{[A1]}, \texttt{[A2]}, \texttt{[A3]}, etc. This is useful for subdivided numerical bibliographies where each subbibliography uses a different prefix. The \prm{string} is available to styles in the \bibfield{prefixnumber} field of all affected entries. See \secref{aut:bbx:fld:lab} for details.
+
+\boolitem{resetnumbers}
+
+This option applies to numerical citation\slash bibliography styles only and requires that the \opt{defernumbers} option from \secref{use:opt:pre} be enabled globally. If enabled, it will reset the numerical labels assigned to the entries in the respective bibliography, \ie the numbering will restart at~1. Use this option with care as \sty{biblatex} can not guarantee unique labels globally if they are reset manually.
+
+\boolitem{omitnumbers}
+
+This option applies to numerical citation\slash bibliography styles only and requires that the \opt{defernumbers} option from \secref{use:opt:pre} be enabled globally. If enabled, \sty{biblatex} will not assign a numerical label to the entries in the respective bibliography. This is useful when mixing a numerical subbibliography with one or more subbibliographies using a different scheme (\eg author-title or author-year).
+
\end{optionlist*}
\begin{ltxsyntax}
@@ -2624,7 +2625,7 @@ This command prints a bibliography heading defined with \cmd{defbibheading}. It
\end{ltxsyntax}
-\subsubsection{The list of shorthands}
+\subsubsection{The List of Shorthands}
\label{use:bib:los}
If any entry includes a \bibfield{shorthand} field, \sty{biblatex} automatically builds a list of shorthands which may be printed in addition to the regular bibliography. The following command prints the list of shorthands.
@@ -2633,11 +2634,11 @@ If any entry includes a \bibfield{shorthand} field, \sty{biblatex} automatically
\cmditem{printshorthands}[key=value,\,\dots]
-This command prints the list of shorthands. It takes one optional argument, which is a list of options given in \keyval notation. Valid options are all options supported by \cmd{printbibliography}, see \secref{use:bib:bib} for details. If there are any \env{refsection} environments in the document, the list of shorthands will be local to these environments; see \secref{use:bib:sec} for details. By default, this command uses the heading \texttt{shorthands}. See \secref{use:bib:hdg} for details.
+This command prints the list of shorthands. It takes one optional argument, which is a list of options given in \keyval notation. Valid options are all options supported by \cmd{printbibliography} (\secref{use:bib:bib}) except \opt{prefixnumbers}, \opt{resetnumbers}, and \opt{omitnumbers}. If there are any \env{refsection} environments in the document, the list of shorthands will be local to these environments; see \secref{use:bib:sec} for details. By default, this command uses the heading \texttt{shorthands}. See \secref{use:bib:hdg} for details.
\end{ltxsyntax}
-\subsubsection{Bibliography sections}
+\subsubsection{Bibliography Sections}
\label{use:bib:sec}
The \env{refsection} environment is used in the document body to mark a reference section. This environment is useful if you want separate, independent bibliographies and lists of shorthands in each chapter, section, or any other part of a document.
@@ -2654,7 +2655,7 @@ This command is similar to the \env{refsection} environment except that it is a
\end{ltxsyntax}
-\subsubsection{Bibliography segments}
+\subsubsection{Bibliography Segments}
\label{use:bib:seg}
The \env{refsegment} environment is used in the document body to mark a reference segment. This environment is useful if you want one global bibliography which is subdivided by chapter, section, or any other part of the document.
@@ -2671,7 +2672,7 @@ This command is similar to the \env{refsegment} environment except that it is a
\end{ltxsyntax}
-\subsubsection{Bibliography categories}
+\subsubsection{Bibliography Categories}
\label{use:bib:cat}
Bibliography categories allow you to split the bibliography into multiple parts dedicated to different topics or different types of references, for example primary and secondary sources. See \secref{use:use:div} for usage examples.
@@ -2689,7 +2690,7 @@ Assigns a \prm{key} to a \prm{category}, to be used in conjunction with the \opt
\end{ltxsyntax}
-\subsubsection{Bibliography headings and environments}
+\subsubsection{Bibliography Headings and Environments}
\label{use:bib:hdg}
\begin{ltxsyntax}
@@ -2762,7 +2763,7 @@ Similar to \texttt{shorthands} above but uses \cmd{chapter} or \cmd{section} to
\end{valuelist*}
-\subsubsection{Bibliography notes}
+\subsubsection{Bibliography Notes}
\label{use:bib:nts}
The following command defines the note \prm{name}, to be used via the \opt{prenote} and \opt{postnote} options of \cmd{printbibliography} and \cmd{printshorthands}:
@@ -2775,51 +2776,66 @@ The \prm{text} may be any arbitrary piece of text, possibly spanning several par
\end{ltxsyntax}
-\subsubsection{Bibliography filters}
+\subsubsection{Bibliography Filters}
\label{use:bib:flt}
The following command defines the custom filter \prm{name}, to be used via the \opt{filter} option of \cmd{printbibliography}:
\begin{ltxsyntax}
-\cmditem{defbibfilter}{name}{code}
+\cmditem{defbibfilter}{name}{expression}
-The \prm{code} is a test with boolean operators given in the syntax of the \sty{ifthen} package. The following atomic tests are available in custom filters:
+The \prm{expression} is a complex test based on the logical operators \texttt{and}, \texttt{or}, \texttt{not}, the group separator \texttt{(...)}, and the following atomic tests:
-\cmditem{segment}{integer}
+\end{ltxsyntax}
+
+\begin{optionlist}
+
+\valitem{segment}{integer}
Matches all entries cited in reference segment \prm{integer}.
-\cmditem{type}{type}
+\valitem{type}{type}
Matches all entries whose entry type is \prm{type}.
-\cmditem{subtype}{type}
+\valitem{subtype}{type}
Matches all entries whose \bibfield{entrysubtype} is \prm{type}.
-\cmditem{keyword}{keyword}
+\valitem{keyword}{keyword}
-Matches all entries whose \bibfield{keywords} field includes \prm{keyword}.
+Matches all entries whose \bibfield{keywords} field includes \prm{keyword}. If the \prm{keyword} contains spaces, it needs to be wrapped in braces.
-\cmditem{category}{category}
+\valitem{category}{category}
Matches all entries assigned to \prm{category} with \cmd{addtocategory}.
-\end{ltxsyntax}
+\end{optionlist}
-Custom filters are local to the selected reference section. Use the \texttt{section} filter of \cmd{printbibliography} to select a different section. This is not possible from within a custom filter. Here is an example of a filter definition:
+Here is an example of a filter expression:
+
+\begin{lstlisting}[style=latex,keywords={and,or,not,type,keyword}]{}
+\defbibfilter{example}{%
+ ( type=book or type=inbook )
+ and keyword=abc
+ and not keyword={x y z}
+}
+\end{lstlisting}
+%
+This filter will match all entries whose entry type is either \bibtype{book} or \bibtype{inbook} and whose \bibfield{keywords} field includes the keyword <\texttt{abc}> but not <\texttt{x y z}>. As seen in the above example, all elements are separated by whitespace (spaces, tabs, or line endings). There is no spacing around the equal sign. The logical operators are evaluated with the \cmd{ifboolexpr} command from the \sty{etoolbox} package. See the \sty{etoolbox} manual for details about the syntax. The syntax of the \cmd{ifthenelse} command from the \sty{ifthen} package, which has been employed in older versions of \sty{biblatex}, is still supported. This is the same test using \sty{ifthen}-like syntax:
\begin{lstlisting}[style=ifthen,morekeywords={\\type,\\keyword}]{}
\defbibfilter{example}{%
\( \type{book} \or \type{inbook} \)
\and \keyword{abc}
- \and \not \keyword{xyz}}
+ \and \not \keyword{x y z}
+}
\end{lstlisting}
%
-Note the grouping commands \cmd{(} and \cmd{)} as well as the boolean operators \cmd{and}, \cmd{or}, and \cmd{not}. All spaces in this example are optional. This filter matches all entries whose entry type is either \texttt{book} or \texttt{inbook} and whose \bibfield{keywords} field includes the keyword <abc> but not <xyz>.
+Note that custom filters are local to the reference section in which they are used. Use the \texttt{section} filter of \cmd{printbibliography} to select a different section. This is not possible from within a custom filter.
-\subsubsection{Legacy commands}
+\subsubsection{Legacy Commands}
In standard \latex, the following command selects the \file{bst} file to be used by \bibtex.
@@ -2831,7 +2847,7 @@ Since \sty{biblatex} interfaces with \bibtex in a different way, this command wi
\end{ltxsyntax}
-\subsection{Citation commands}
+\subsection{Citation Commands}
\label{use:cit}
All citation commands generally take one mandatory and two optional arguments. The \prm{prenote} is text to be printed at the beginning of the citation. This is usually a notice such as <see> or <compare>. The \prm{postnote} is text to be printed at the very end of the citation. This is usually a page number. If only one of these arguments is given, it is taken as a postnote. If you want to specify a prenote but no postnote, you need to leave the second optional argument empty, as in |\cite[see][]{key}|. The \prm{key} argument to all citation commands is mandatory. This is the entry key or a comma"=separated list of keys corresponding to the entry keys in the \sty{bib} file. In sum, all basic citations commands listed further down have the following syntax:
@@ -2844,7 +2860,7 @@ If the \opt{autopunct} package option from \secref{use:opt:pre} is enabled, they
\end{ltxsyntax}
-\subsubsection{Standard commands}
+\subsubsection{Standard Commands}
\label{use:cit:std}
The following commands are defined by the citation style. Citation styles may provide any arbitrary number of specialized commands, but these are the standard commands typically provided by general-purpose styles.
@@ -2868,7 +2884,7 @@ These command use a format similar to \cmd{cite} but put the entire citation in
\end{ltxsyntax}
-\subsubsection{Style-specific commands}
+\subsubsection{Style-specific Commands}
\label{use:cit:cbx}
The following additional citation commands are only provided by some of the citation styles which ship with this package.
@@ -2894,7 +2910,7 @@ This command, which is only provided by the numeric styles, prints numeric citat
\end{ltxsyntax}
-\subsubsection{Qualified citation lists}
+\subsubsection{Qualified Citation Lists}
\label{use:cit:mlt}
This package supports a class of special citation commands called <multicite> commands. The point of these commands is that their argument is a list of citations where each item forms a fully qualified citation with a pre- and\slash or postnote. This is particularly useful with parenthetical citations and citations given in footnotes. It is also possible to assign a pre- and\slash or postnote to the entire list. The multicite commands are built on top of backend commands like \cmd{parencite} and \cmd{footcite}. The citation style provides a multicite definition with \cmd{DeclareMultiCiteCommand} (see \secref{aut:cbx:cbx}). The following example illustrates the syntax of multicite commands:
@@ -2954,7 +2970,7 @@ The multicite version of \cmd{supercite}. This command is only provided by the n
\end{ltxsyntax}
-\subsubsection{Style-independent commands}
+\subsubsection{Style-independent Commands}
\label{use:cit:aut}
Sometimes it is desirable to give the citations in the source file in a format that is not tied to a specific citation style and can be modified globally in the preamble. The format of the citations is easily changed by loading a different citation style. However, when using commands such as \cmd{parencite} or \cmd{footcite}, the way the citations are integrated with the text is still effectively hard"=coded. The idea behind the \cmd{autocite} command is to provide higher"=level citation markup which makes global switching from inline citations to citations given in footnotes (or as superscripts) possible. The \cmd{autocite} command is built on top of backend commands like \cmd{parencite} and \cmd{footcite}. The citation style provides an \cmd{autocite} definition with \cmd{DeclareAutoCiteCommand} (see \secref{aut:cbx:cbx}). This definition may be activated with the \opt{autocite} package option from \secref{use:opt:pre}. The citation style will usually initialize this package option to a value which is suitable for the style, see \secref{use:xbx:cbx} for details. Note that there are certain limits to high"=level citation markup. For example, inline author-year citation schemes often integrate citations so tightly with the text that it is virtually impossible to automatically convert them to footnotes. The \cmd{autocite} command is only applicable in cases in which you would normally use \cmd{parencite} or \cmd{footcite} (or \cmd{supercite}, with a numeric style). The citations should be given at the end of a sentence or a partial sentence, immediately preceding the terminal punctuation mark, and they should not be a part of the sentence in a grammatical sense (like \cmd{textcite}, for example).
@@ -2969,7 +2985,7 @@ In contrast to other citation commands, the \cmd{autocite} command does not only
\cmditem*{autocite*}[prenote][postnote]{key}
\cmditem*{Autocite*}[prenote][postnote]{key}
-The starred variants of \cmd{autocite} do not behave differently from from the regular ones. The asterisk is simply passed on to the backend command. For example, if \cmd{autocite} is configured to use \cmd{parencite}, then \cmd{autocite*} will execute \cmd{parencite*}.
+The starred variants of \cmd{autocite} do not behave differently from the regular ones. The asterisk is simply passed on to the backend command. For example, if \cmd{autocite} is configured to use \cmd{parencite}, then \cmd{autocite*} will execute \cmd{parencite*}.
\cmditem{autocites}(pre)(post)[pre][post]{key}|...|[pre][post]{key}
\cmditem{Autocites}(pre)(post)[pre][post]{key}|...|[pre][post]{key}
@@ -2978,7 +2994,7 @@ This is the multicite version of \cmd{autocite}. It also detects and moves punct
\end{ltxsyntax}
-\subsubsection{Text commands}
+\subsubsection{Text Commands}
\label{use:cit:txt}
The following commands are provided by the core of \sty{biblatex}. They are intended for use in the flow of text. Note that all text commands are exluded from citation tracking.
@@ -3013,7 +3029,7 @@ This command wraps the \prm{text} in context sensitive brackets.
\end{ltxsyntax}
-\subsubsection{Special commands}
+\subsubsection{Special Commands}
\label{use:cit:spc}
The following special commands are also provided by the core of \sty{biblatex}.
@@ -3073,7 +3089,7 @@ Similar to \cmd{notecite} but the notes are printed in a footnote.
\end{ltxsyntax}
-\subsubsection{Low-level commands}
+\subsubsection{Low-level Commands}
\label{use:cit:low}
The following commands are also provided by the core of \sty{biblatex}. They grant access to all lists and fields at a lower level.
@@ -3094,7 +3110,7 @@ The \prm{format} is a formatting directive defined with \cmd{DeclareFieldFormat}
\end{ltxsyntax}
-\subsubsection{Miscellaneous commands}
+\subsubsection{Miscellaneous Commands}
\label{use:cit:msc}
The commands in this section are little helpers related to citations.
@@ -3143,12 +3159,12 @@ Similar to \cmd{RN} but prints a lowercase Roman numeral. The formatting applied
\end{ltxsyntax}
-\subsubsection{Compatibility commands for \sty{natbib}}
+\subsubsection{Compatibility Commands for \sty{natbib}}
\label{use:cit:nat}
If the \opt{natbib} package option is enabled, \sty{biblatex} will load a \sty{natbib} compatibility style in addition to the main citation style. The compatibility style defines aliases for the citation commands provided by the \sty{natbib} package, version~7. This includes aliases for the core citation commands \cmd{citet} and \cmd{citep} as well as the variants \cmd{citealt} and \cmd{citealp}. The starred variants of these commands, which print the full author list, are also supported. The \cmd{cite} command, which is handled in a particular way by \sty{natbib}, is not treated in a special way. The text commands (\cmd{citeauthor}, \cmd{citeyear}, etc.) are also supported, as are all commands which capitalize the name prefix (\cmd{Citet}, \cmd{Citep}, \cmd{Citeauthor}, etc.). Aliasing with \cmd{defcitealias}, \cmd{citetalias}, and \cmd{citepalias} is possible as well. Note that the compatibility commands will not emulate the citation format of the \sty{natbib} package. They merely map \sty{natbib}'s commands to functionally equivalent facilities of the \sty{biblatex} package. The citation format depends on the main citation style. However, the compatibility style will adapt \cmd{nameyeardelim} to match the default style of the \sty{natbib} package.
-\subsection{Localization commands}
+\subsection{Localization Commands}
\label{use:lng}
The \sty{biblatex} package provides translations for key terms such as <edition> or <volume> as well as definitions for language specific features such as the date format and ordinals. These definitions, which are loaded automatically, may be modified or extended in the document preamble or the configuration file with the commands introduced in this section.
@@ -3168,7 +3184,7 @@ This command is used to define bibliography strings. The \prm{language} must be
}
\end{lstlisting}
%
-A complete list of all keys supported by default is given is \secref{aut:lng:key}. Note that all expressions should be capitalized as they usually are when used in the middle of a sentence. The \sty{biblatex} package will automatically capitalize the first word when required at the beginning of a sentence. Expressions intended for use in headings should be capitalized in a way that is suitable for titling. See \secref{aut:lng:cmd} for further details.
+A complete list of all keys supported by default is given is \secref{aut:lng:key}. Note that all expressions should be capitalized as they usually are when used in the middle of a sentence. The \sty{biblatex} package will automatically capitalize the first word when required at the beginning of a sentence. Expressions intended for use in headings should be capitalized in a way that is suitable for titling. In contrast to \cmd{DeclareBibliographyStrings}, \cmd{DefineBibliographyStrings} overrides both the full and the abbreviated version of the string. See \secref{aut:lng:cmd} for further details.
\cmditem{DefineBibliographyExtras}{language}{code}
@@ -3197,12 +3213,12 @@ list of key names. The keys listed in \secref{aut:lng:key} are defined by defaul
\end{ltxsyntax}
-\subsection{Formatting commands}
+\subsection{Formatting Commands}
\label{use:fmt}
The commands and facilities presented in this section may be used to adapt the format of citations and the bibliography.
-\subsubsection{Generic commands and hooks}
+\subsubsection{Generic Commands and Hooks}
\label{use:fmt:fmt}
The commands in this section may be redefined with \cmd{renewcommand} in the document preamble. Note that all commands starting with \cmd{mk\dots} take one argument. All of these commands are defined in \path{biblatex.def} to make it easier to look up the defaults.
@@ -3306,9 +3322,13 @@ Similar to \cmd{multicitedelim}, but used by the \cmd{supercite} command only. T
Similar to \cmd{multicitedelim}, but used by certain citation styles when <compressing> multiple citations. The default definition is a comma plus an interword space.
+\csitem{nametitledelim}
+
+The delimiter printed between the author\slash editor and the title by author-title and some verbose citation styles. The default definition is a comma plus an interword space.
+
\csitem{nameyeardelim}
-The delimiter printed between the author\slash editor and the year by author-year citation styles. The default is an interword space.
+The delimiter printed between the author\slash editor and the year by author-year citation styles. The default definition is an interword space.
\csitem{labelalphaothers}
@@ -3340,7 +3360,7 @@ Similar to \cmd{mkbibnamelast}, but intended for the name affix.
\end{ltxsyntax}
-\subsubsection{Language-specific commands}
+\subsubsection{Language-specific Commands}
\label{use:fmt:lng}
The commands in this section are language specific. When redefining them, you need to wrap the new definition in a \cmd{DeclareBibliographyExtras} command, see \secref{use:lng} for details. Note that all commands starting with \cmd{mk\dots} take one or more arguments.
@@ -3395,7 +3415,7 @@ Similar to \cmd{mkbibordinal}, but intended for use with the term <series>.
\end{ltxsyntax}
-\subsubsection{Lengths and counters}
+\subsubsection{Lengths and Counters}
\label{use:fmt:len}
The length registers and counters in this section may be changed in the document preamble with \cmd{setlength} and \cmd{setcounter}, respectively.
@@ -3440,7 +3460,7 @@ This counter holds a penalty which affects the line"=breaking of names. This pen
\end{ltxsyntax}
-\subsubsection{All-purpose commands}
+\subsubsection{All-purpose Commands}
\label{use:fmt:aux}
The commands in this section are all-purpose text commands which are generally available, not only in citations and the bibliography.
@@ -3507,7 +3527,7 @@ This will yield <¼uvres> or <½uvres>.
\end{ltxsyntax}
-\subsection[Language notes]{Language-specific notes}
+\subsection[Language notes]{Language-specific Notes}
\label{use:loc}
The facilities discussed in this section are specific to certain localization modules.
@@ -3558,38 +3578,9 @@ Similar to \cmd{forceE} but enforces <y>.
\subsubsection{Greek}
\label{use:loc:grk}
-The Greek localization module requires \utf support. It will not work with any other encoding. Generally speaking, the \sty{biblatex} package is compatible with
-
-\begin{enumerate}
-
-\item \latex with the \sty{inputenc} package,
-
-\begin{lstlisting}[style=latex]{}
-\usepackage[utf8]{inputenc}
-\end{lstlisting}
-
-\item \latex with \sty{inputenc} and the \sty{ucs} package,
-
-\begin{lstlisting}[style=latex]{}
-\usepackage{ucs}
-\usepackage[utf8x]{inputenc}
-\end{lstlisting}
-
-\item \xelatex.
-
-\end{enumerate}
-
-Since \sty{inputenc}'s standard \file{utf8} module is missing glyph mappings for Greek, this leaves Greek users with a choice of either 2) or 3). If you choose 2), make sure to preload the Greek Unicode range:
-
-\begin{lstlisting}[style=latex]{}
-\usepackage{ucs}
-\usepackage[utf8x]{inputenc}
-\PreloadUnicodePage{3}
-\end{lstlisting}
-%
-You may also use \cmd{PrerenderUnicode} if you prefer that. See the section about «Known problems» in the \sty{ucs} manual for details. Note that you may need to load additional packages which set up Greek fonts. As a rule of thumb, a setup which works for regular Greek documents should also work with \sty{biblatex}. However, there is one fundamental limitation. As of this writing, \sty{biblatex} has no support for switching scripts. Greek titles in the bibliography should work fine, provided that you use Biber as a backend, but English and other titles in the bibliography may be rendered in Greek letters. If you need multi-script bibliographies, using \xelatex is the only sensible choice.
+The Greek localization module requires \utf support. It will not work with any other encoding. Generally speaking, the \sty{biblatex} package is compatible with the \sty{inputenc} package and with \xelatex. The \sty{ucs} package will not work. Since \sty{inputenc}'s standard \file{utf8} module is missing glyph mappings for Greek, this leaves Greek users with \xelatex. Note that you may need to load additional packages which set up Greek fonts. As a rule of thumb, a setup which works for regular Greek documents should also work with \sty{biblatex}. However, there is one fundamental limitation. As of this writing, \sty{biblatex} has no support for switching scripts. Greek titles in the bibliography should work fine, provided that you use Biber as a backend, but English and other titles in the bibliography may be rendered in Greek letters. If you need multi-script bibliographies, using \xelatex is the only sensible choice.
-\subsection{Usage notes}
+\subsection{Usage Notes}
\label{use:use}
The following sections give a basic overview of the \sty{biblatex} package and discuss some typical usage scenarios.
@@ -3622,9 +3613,9 @@ With traditional \bibtex, the \cmd{bibliography} command serves two purposes. It
\end{enumerate}
-Whenever a reference to a work which has not been cited before is added, this procedure must be repeated. This is also the case if the last reference to a work which has been cited before is removed because some citation labels may change in this case. In contrast to traditional \bibtex, there is normally no need to run \bin{latex} twice after running \bin{bibtex} as far as the handling of bibliographic data is concerned.\footnote{That is, unless the \opt{defernums} package option is enabled. This option requires two \latex runs after the data has been exported to the \file{bbl} file by \bibtex.} Note that this only applies to the most basic case. Using the \bibfield{xref} field or the \bibfield{entryset} field may require an additional \latex/\bibtex/\latex cycle. Some other facilities provided by \sty{biblatex} may also require an additional \bin{latex} run to get certain references and the page tracking right. In this case, the usual warning messages such as «There were undefined references» and «Label(s) may have changed. Rerun to get cross-references right» will be printed.
+Whenever a reference to a work which has not been cited before is added, this procedure must be repeated. This is also the case if the last reference to a work which has been cited before is removed because some citation labels may change in this case. In contrast to traditional \bibtex, there is normally no need to run \bin{latex} twice after running \bin{bibtex} as far as the handling of bibliographic data is concerned.\footnote{That is, unless the \opt{defernumbers} package option is enabled. This option requires two \latex runs after the data has been exported to the \file{bbl} file by \bibtex.} Note that this only applies to the most basic case. Using the \bibfield{xref} field or the \bibfield{entryset} field may require an additional \latex/\bibtex/\latex cycle. Some other facilities provided by \sty{biblatex} may also require an additional \bin{latex} run to get certain references and the page tracking right. In this case, the usual warning messages such as «There were undefined references» and «Label(s) may have changed. Rerun to get cross-references right» will be printed. When using Biber as a backend, the workflow is essentially the same.
-\subsubsection{Auxiliary files}
+\subsubsection{Auxiliary Files}
\label{use:use:aux}
By default, the \sty{biblatex} package uses the main \file{aux} file only. Even if there are citation commands in a file included via \cmd{include}, which has its own \file{aux} file, you only need to run \bibtex on the main \file{aux} file. If you are using \env{refsection} environments in a document (see \secref{use:use:mlt}) \sty{biblatex} will create one additional \file{aux} file for every \env{refsection} environment. In this case, you also need to run \bin{bibtex} on each additional \file{aux} file. The name of the additional \file{aux} files is the base name of the main input file with the string \file{-blx} and a running number appended at the end. The \sty{biblatex} package issues a warning listing the files which require an additional \bibtex run. With the basic example presented in \secref{use:use:int}, it would issue the following warning:
@@ -3645,11 +3636,11 @@ Package biblatex Warning: Please (re)run BibTeX on the file(s):
(biblatex) and rerun LaTeX afterwards.
\end{lstlisting}
%
-Apart from these \file{aux} files, \sty{biblatex} uses an additional \file{bib} file with the same suffix to pass certain control parameters to \bibtex. In the example above, this file would be named \path{example-blx.bib}. In the event of a file name conflict, you can change the suffix by redefining the macro \cmd{blxauxsuffix} in the document preamble. When using Biber, \sty{biblatex} would write a control file named \path{example.bcf} and ignore \cmd{blxauxsuffix}.
+Apart from these \file{aux} files, \sty{biblatex} uses an additional \file{bib} file with the same suffix to pass certain control parameters to \bibtex. In the example above, this file would be named \path{example-blx.bib}. In the event of a file name conflict, you can change the suffix by redefining the macro \cmd{blxauxsuffix} in the document preamble. When using Biber, \sty{biblatex} writes a control file named \path{example.bcf} and ignores \cmd{blxauxsuffix}. There is also no auxiliary \file{bib} file in this case.
Note that \sty{biblatex} will not overwrite any files it did not create. All auxiliary files created automatically by this package start with a special signature line. Before overwriting a file (excluding the main \file{aux} file, which is managed by \latex), \sty{biblatex} inspects the first line of the file to make sure that there is no file name conflict. If the file in question is missing the signature line, \sty{biblatex} will immediately issue an error message and abort before opening the output stream. In this case you should delete any spurious files accidentally left in the working directory. If the error persists, there may be a file name conflict with a file found in one of the \tex installation trees. Since the installation trees usually do not contain any \file{aux} files and the string \file{-blx} is fairly exotic in the name of a \file{bib} file, this is rather unlikely but theoretically possible. If you find out that this is indeed the case, you should redefine \cmd{blxauxsuffix} permanently in the \sty{biblatex} configuration file, \path{biblatex.cfg.}
-\subsubsection{Multiple bibliographies}
+\subsubsection{Multiple Bibliographies}
\label{use:use:mlt}
In a collection of articles by different authors, such as a conference proceedings volume for example, it is very common to have one bibliography for each article rather than a global one for the entire book. In the example below, each article would be presented as a separate \cmd{chapter} with its own bibliography. Note that \sty{biblatex} creates one additional \file{aux} file for every \env{refsection} environment. These files have to be processed by \bibtex as well, see \secref{use:use:aux} for details.
@@ -3742,7 +3733,7 @@ The use of \env{refsegment} is similar to \env{refsection} and there is also a c
%
This is equivalent to giving one \cmd{printbibliography} command for every segment.
-\subsubsection{Subdivided bibliographies}
+\subsubsection{Subdivided Bibliographies}
\label{use:use:div}
It is very common to subdivide a bibliography by certain criteria. For example, you may want to list printed and online resources separately or divide a bibliography into primary and secondary sources. The former case is straightforward because you can use the entry type as a criterion for the \opt{type} and \opt{nottype} filters of \cmd{printbibliography}. The next example also demonstrates how to generate matching subheadings for the two parts of the bibliography.
@@ -3855,7 +3846,7 @@ It is still a good idea to declare all categories used in the bibliography expli
%
The handling of the headings is different from \cmd{bibbysection} and \cmd{bibbysegment} in this case. \cmd{bibbycategory} uses the name of the current category as a heading name. This is equivalent to passing \texttt{heading=\prm{category}} to \cmd{printbibliography} and implies that you need to provide a matching heading for every category.
-\subsubsection{Reference sets}
+\subsubsection{Reference Sets}
\label{use:use:set}
A reference set is a group of entries which are cited as a single reference and listed as a single item in the bibliography. Using an example borrowed from the \sty{mcite} manual, the following three references
@@ -3925,101 +3916,88 @@ If you want to refer to an item as part of a set in one document and as a stand-
%
In the above example, use the key <\texttt{set1}> when citing the entire reference set (including \texttt{subkey1}) and <\texttt{key1}> when citing the article as a stand-alone reference. Style authors should also see \secref{aut:cav:set} for further information.
-\subsubsection{Electronic publishing information}
+\subsubsection{Electronic Publishing Information}
\label{use:use:epr}
-There are two fields which hold electronic publishing information, \bibfield{eprint} and \bibfield{eprinttype}. The \bibfield{eprint} field is a verbatim field similar to \bibfield{doi} which holds the identifier of the item. The optional \bibfield{eprinttype} field may be used to record a resource name, \ie the name of the site or electronic archive. If the \bibfield{eprinttype} field is available, the standard styles will use it as a literal label. With the following example, they would print «Resource: identifier» rather than the generic «eprint: identifier»:
+The \sty{biblatex} package provides three fields for electronic publishing information: \bibfield{eprint}, \bibfield{eprinttype}, and \bibfield{eprintclass}. The \bibfield{eprint} field is a verbatim field similar to \bibfield{doi} which holds the identifier of the item. The \bibfield{eprinttype} field holds the resource name, \ie the name of the site or electronic archive. The optional \bibfield{eprintclass} field is intended for additional information specific to the resource indicated by the \bibfield{eprinttype} field. This could be a section, a path, classification information, etc. If the \bibfield{eprinttype} field is available, the standard styles will use it as a literal label. In the following example, they would print «Resource: identifier» rather than the generic «eprint: identifier»:
\begin{lstlisting}[style=bibtex]{}
-@Online{...,
- <<eprint>> = {<<identifier>>},
- <<eprinttype>> = {<<Resource>>},
- ...
+<<eprint>> = {<<identifier>>},
+<<eprinttype>> = {<<Resource>>},
\end{lstlisting}
%
-The standard styles feature dedicated support for a few online archives. For arXiv references, put the identifier in the \bibfield{eprint} field and the string \texttt{arxiv} (all lowercase) in the \bibfield{eprinttype} field:
+The standard styles feature dedicated support for a few online archives. For arXiv references, put the identifier in the \bibfield{eprint} field and the string \texttt{arxiv} in the \bibfield{eprinttype} field:
\begin{lstlisting}[style=bibtex]{}
-@Online{...,
- <<eprint>> = {<<0706.0001>>},
- <<eprinttype>> = {<<arxiv>>},
- ...
+<<eprint>> = {<<math/0307200v3>>},
+<<eprinttype>> = {<<arxiv>>},
\end{lstlisting}
%
-For papers submitted prior to April 1, 2007, which use the old arXiv identifier scheme, include all classification information such as the archive name and the subject class in the eprint field:
+For papers which use the new identifier scheme (April 2007 and later) add the primary classification in the \bibfield{eprintclass} field:
\begin{lstlisting}[style=bibtex]{}
-@Online{...,
- eprint = {<<hep-th/>>9603067},
- ...
-
-@Online{...,
- eprint = {<<math.GT/>>0309136},
- ...
+eprint = {1008.2849v1},
+eprinttype = {arxiv},
+<<eprintclass>> = {<<cs.DS>>},
\end{lstlisting}
%
-If hyperlinks are enabled, the \bibfield{eprint} field will be transformed into a link to \nolinkurl{arxiv.org}. See the package option \opt{arxiv} in \secref{use:opt:pre} for further details.
+There are two aliases which ease the integration of arXiv entries. \bibfield{archiveprefix} is treated as an alias of \bibfield{eprinttype}; \bibfield{primaryclass} is an alias of \bibfield{eprintclass}. If hyperlinks are enabled, the eprint identifier will be transformed into a link to \nolinkurl{arxiv.org}. See the package option \opt{arxiv} in \secref{use:opt:pre} for further details.
-For \acr{JSTOR} references, put the stable \acr{JSTOR} number in the \bibfield{eprint} field and the string \texttt{jstor} (all lowercase) in the \bibfield{eprinttype} field:
+For \acr{JSTOR} references, put the stable \acr{JSTOR} number in the \bibfield{eprint} field and the string \texttt{jstor} in the \bibfield{eprinttype} field:
\begin{lstlisting}[style=bibtex]{}
-@Online{...,
- <<eprint>> = {<<number>>},
- <<eprinttype>> = {<<jstor>>},
- ...
+<<eprint>> = {<<number>>},
+<<eprinttype>> = {<<jstor>>},
\end{lstlisting}
%
When using \acr{JSTOR}'s export feature to export citations in \bibtex format, \acr{JSTOR} uses the \bibfield{url} field by default (where the \prm{number} is a unique and stable identifier):
\begin{lstlisting}[style=bibtex]{}
-@Online{...,
- url = {http://www.jstor.org/stable/<<number>>},
- ...
+url = {http://www.jstor.org/stable/<<number>>},
\end{lstlisting}
%
While this will work as expected, full \acr{URL}s tend to clutter the bibliography. With the \bibfield{eprint} fields, the standard styles will use the more readable «\acr{JSTOR}: \prm{number}» format which also supports hyperlinks. The \prm{number} becomes a clickable link if \sty{hyperref} support is enabled.
-For PubMed references, put the stable PubMed identifier in the \bibfield{eprint} field and the string \texttt{pubmed} (all lowercase) in the \bibfield{eprinttype} field. This means that:
+For PubMed references, put the stable PubMed identifier in the \bibfield{eprint} field and the string \texttt{pubmed} in the \bibfield{eprinttype} field. This means that:
\begin{lstlisting}[style=bibtex]{}
-@Online{...,
- url = {http://www.ncbi.nlm.nih.gov/pubmed/<<pmid>>},
- ...
+url = {http://www.ncbi.nlm.nih.gov/pubmed/<<pmid>>},
\end{lstlisting}
%
becomes:
\begin{lstlisting}[style=bibtex]{}
-@Online{...,
- <<eprint>> = {<<pmid>>},
- <<eprinttype>> = {<<pubmed>>},
- ...
+<<eprint>> = {<<pmid>>},
+<<eprinttype>> = {<<pubmed>>},
\end{lstlisting}
%
and the standard styles will print «\acr{PMID}: \prm{pmid}» instead of the lengthy \acr{URL}. If hyperref support is enabled, the \prm{pmid} will be a clickable link to PubMed.
-For Google Books references, put Google's identifier in the \bibfield{eprint} field and the string \texttt{googlebooks} (all lowercase) in the \bibfield{eprinttype} field. This means that, for example:
+For handles (\acr{HDL}s), put the handle in the \bibfield{eprint} field and the string \texttt{hdl} in the \bibfield{eprinttype} field:
\begin{lstlisting}[style=bibtex]{}
-@Online{...,
- url = {http://books.google.com/books?id=<<XXu4AkRVBBoC>>},
- ...
+<<eprint>> = {<<handle>>},
+<<eprinttype>> = {<<hdl>>},
+\end{lstlisting}
+%
+For Google Books references, put Google's identifier in the \bibfield{eprint} field and the string \texttt{googlebooks} in the \bibfield{eprinttype} field. This means that, for example:
+
+\begin{lstlisting}[style=bibtex]{}
+url = {http://books.google.com/books?id=<<XXu4AkRVBBoC>>},
\end{lstlisting}
%
would become:
\begin{lstlisting}[style=bibtex]{}
-@Online{...,
- <<eprint>> = {<<XXu4AkRVBBoC>>},
- <<eprinttype>> = {<<googlebooks>>},
- ...
+<<eprint>> = {<<XXu4AkRVBBoC>>},
+<<eprinttype>> = {<<googlebooks>>},
\end{lstlisting}
%
and the standard styles would print «Google Books: |XXu4AkRVBBoC|» instead of the full \acr{URL}. If hyperref support is enabled, the identifier will be a clickable link to Google Books.\footnote{Note that the Google Books \acr{id} seems to be a bit of an <internal> value. As of this writing, there does not seem to be any way to search for an \acr{id} on Google Books. You may prefer to use the \bibfield{url} in this case.}
Note that \bibfield{eprint} is a verbatim field. Always give the identifier in its unmodified form. For example, there is no need to replace |_| with |\_|. Also see \secref{aut:cav:epr} on how to add dedicated support for other eprint resources.
-\subsubsection{External abstracts and annotations}
+\subsubsection{External Abstracts and Annotations}
\label{use:use:prf}
Styles which print the fields \bibfield{abstract} and\slash or \bibfield{annotation} may support an alternative way of adding abstracts or annotations to the bibliography. Instead of including the text in the \file{bib} file, it may also be stored in an external \latex file. For example, instead of saying
@@ -4040,12 +4018,12 @@ This is an abstract of entry `key1'.
%
The name of the external file must be the entry key prefixed with \texttt{bibabstract-} or \texttt{bibannotation-}, respectively. You can change these prefixes by redefining \cmd{bibabstractprefix} and \cmd{bibannotationprefix}. Note that this feature needs to be enabled explicitly by setting the package option \opt{loadfiles} from \secref{use:opt:pre}. The option is disabled by default for performance reasons. Also note that any \bibfield{abstract} and \bibfield{annotation} fields in the \file{bib} file take precedence over the external files. Using external files is strongly recommended if you have long abstracts or a lot of annotations since this may increase memory requirements significantly. It is also more convenient to edit the text in a dedicated \latex file. Style authors should see \secref{aut:cav:prf} for further information.
-\subsection{Hints and caveats}
+\subsection{Hints and Caveats}
\label{use:cav}
This section provides additional usage hints and addresses some common problems and potential misconceptions.
-\subsubsection{Usage with \acr{KOMA}-Script classes}
+\subsubsection{Usage with \acr{KOMA}-Script Classes}
\label{use:cav:scr}
When using \sty{biblatex} in conjunction with one of the \sty{scrbook}, \sty{scrreprt}, or \sty{scrartcl} classes, the headings \texttt{bibliography} and \texttt{shorthands} from \secref{use:bib:hdg} are responsive to the bibliography"=related options of these classes.\footnote{This applies to the traditional syntax of these options (\opt{bibtotoc} and \opt{bibtotocnumbered}) as well as to the \keyval syntax introduced in \acr{KOMA}-Script 3.x, \ie to \kvopt{bibliography}{nottotoc}, \kvopt{bibliography}{totoc}, and \kvopt{bibliography}{totocnumbered}, The global \kvopt{toc}{bibliography} and \kvopt{toc}{bibliographynumbered} options as well as their aliases are detected as well. In any case, the options must be set globally in the optional argument to \cmd{documentclass}.} You can override the default headings by using the \opt{heading} option of \cmd{printbibliography}, \cmd{printbibheading} and \cmd{printshorthands}. See \secref{use:bib:bib, use:bib:los, use:bib:hdg} for details. All default headings are adapted at load-time such that they blend with the behavior of these classes. If one of the above classes is detected, \sty{biblatex} will also provide the following additional tests which may be useful in custom heading definitions:
@@ -4062,7 +4040,7 @@ Expands to \prm{true} if the class would add the bibliography to the table of co
\end{ltxsyntax}
-\subsubsection{Usage with the Memoir class}
+\subsubsection{Usage with the Memoir Class}
\label{use:cav:mem}
When using \sty{biblatex} with the \sty{memoir} class, most class facilites for adapting the bibliography have no effect. Use the corresponding facilities of this package instead (\secref{use:bib:bib, use:bib:hdg, use:bib:nts}). Instead of redefining \sty{memoir}'s \cmd{bibsection}, use the \opt{heading} option of \cmd{printbibliography} and \cmd{defbibheading} (\secref{use:bib:bib, use:bib:hdg}). Instead of \cmd{prebibhook} and \cmd{postbibhook}, use the \opt{prenote} and \opt{postnote} options of \cmd{printbibliography} and \cmd{defbibnote} (\secref{use:bib:bib, use:bib:nts}). All default headings are adapted at load-time such that they blend well with the default layout of this class. The default headings \texttt{bibliography} and \texttt{shorthands} (\secref{use:bib:hdg}) are also responsive to \sty{memoir}'s \cmd{bibintoc} and \cmd{nobibintoc} switches. The length register \len{bibitemsep} is used by \sty{biblatex} in a way similar to \sty{memoir} (\secref{use:fmt:len}). This section also introduces some additional length registers which correspond to \sty{memoir}'s \cmd{biblistextra}. Lastly, \cmd{setbiblabel} does not map to a single facility of the \sty{biblatex} package since the style of all labels in the bibliography is controlled by the bibliography style. See \secref{aut:bbx:env} in the author section of this manual for details. If the \sty{memoir} class is detected, \sty{biblatex} will also provide the following additional test which may be useful in custom heading definitions:
@@ -4075,7 +4053,7 @@ Expands to \prm{true} or \prm{false}, depending on \sty{memoir}'s \cmd{bibintoc}
\end{ltxsyntax}
-\subsubsection{Page numbers in citations}
+\subsubsection{Page Numbers in Citations}
\label{use:cav:pag}
If the \prm{postnote} argument to a citation command is a page number or page range, \sty{biblatex} will automatically prefix it with <p.> or <pp.> by default. This works reliably in typical cases, but sometimes manual intervention may be required. In this case, it is important to understand how this argument is handled in detail. First, \sty{biblatex} checks if the postnote is an Arabic or Roman numeral (case insensitive). If this test succeeds, the postnote is considered as a single page or other number which will be prefixed with <p.> or some other string which depends on the \sty{pagination} field (see \secref{bib:use:pag}). If it fails, a second test is performed to find out if the postnote is a range or a list of Arabic or Roman numerals. If this test succeeds, the postnote will be prefixed with <pp.> or some other string in the plural form. If it fails as well, the postnote is printed as is. Note that both tests expand the \prm{postnote}. All commands used in this argument must therefore be robust or prefixed with \cmd{protect}. Here are a few examples of \prm{postnote} arguments which will be correctly recognized as a single number, a range of numbers, or a list of numbers, respectively:
@@ -4141,17 +4119,17 @@ It is possible to suppress the prefix on a per"=entry basis by setting the \bibf
%
The \prm{postnote} argument is handled as a field and the formatting of this field is controlled by a field formatting directive which may be freely redefined. The above definition will simply print the postnote as is. See \secref{aut:cbx:fld, aut:bib:fmt} in the author guide for further details.
-\subsubsection{Bibliography filters and citation labels}
+\subsubsection{Bibliography Filters and Citation Labels}
\label{use:cav:lab}
-The citation labels generated by this package are assigned to the full list of references before it is split up by any bibliography filters. They are guaranteed to be unique across the entire document (or a \env{refsection} environment), no matter how many bibliography filters you are using. When using a numeric citation scheme, however, this will most likely lead to discontinuous numbering in split bibliographies. Use the \opt{defernums} package option to avoid this problem. If this option is enabled, numeric labels are assigned the first time an entry is printed in any bibliography.
+The citation labels generated by this package are assigned to the full list of references before it is split up by any bibliography filters. They are guaranteed to be unique across the entire document (or a \env{refsection} environment), no matter how many bibliography filters you are using. When using a numeric citation scheme, however, this will most likely lead to discontinuous numbering in split bibliographies. Use the \opt{defernumbers} package option to avoid this problem. If this option is enabled, numeric labels are assigned the first time an entry is printed in any bibliography.
-\subsubsection{Active characters in bibliography headings}
+\subsubsection{Active Characters in Bibliography Headings}
\label{use:cav:act}
Packages using active characters, such as \sty{babel}, \sty{csquotes}, or \sty{underscore}, usually do not make them active until the beginning of the document body to avoid interference with other packages. A typical example of such an active character is the Ascii quote |"|, which is used by various language modules of the \sty{babel} package. If shorthands such as |"<| and |"a| are used in the argument to \cmd{defbibheading} and the headings are defined in the document preamble, the non-active form of the characters is saved in the heading definition. When the heading is typeset, they do not function as a command but are simply printed literally. The most straightforward solution consists in moving \cmd{defbibheading} after |\begin{document}|. Alternatively, you may use \sty{babel}'s \cmd{shorthandon} and \cmd{shorthandoff} commands to temporarily make the shorthands active in the preamble. The above also applies to bibliography notes and the \cmd{defbibnote} command.
-\subsubsection{Grouping in reference sections and segments}
+\subsubsection{Grouping in Reference Sections and Segments}
\label{use:cav:grp}
All \latex environments enclosed in \cmd{begin} and \cmd{end} form a group. This may have undesirable side effects if the environment contains anything that does not expect to be used within a group. This issue is not specific to \env{refsection} and \env{refsegment} environments, but it obviously applies to them as well. Since these environments will usually enclose much larger portions of the document than a typical \env{itemize} or similar environment, they are simply more likely to trigger problems related to grouping. If you observe any malfunctions after adding \env{refsection} environments to a document (for example, if anything seems to be <trapped> inside the environment), try the following syntax instead:
@@ -4165,7 +4143,7 @@ All \latex environments enclosed in \cmd{begin} and \cmd{end} form a group. This
%
This will not from a group, but otherwise works as usual. As far as \sty{biblatex} is concerned, it does not matter which syntax you use. The alternative syntax is also supported by the \env{refsegment} environment. Note that the commands \cmd{newrefsection} and \cmd{newrefsegment} do not form a group. See \secref{use:bib:sec, use:bib:seg} for details.
-\section{Author guide}
+\section{Author Guide}
\label{aut}
This part of the manual documents the author interface of the \sty{biblatex} package. The author guide covers everything you need to know in order to write new citation and bibliography styles or localization modules. You should read the user guide first before continuing with this part of the manual.
@@ -4268,7 +4246,7 @@ In order to streamline the whole procedure, \sty{biblatex} essentially employs t
\item Run \bin{bibtex}: \bibtex supplies those entries from the \file{bib} file which were requested by the \cmd{citation} commands in the \file{aux} file. However, it does not write a printable bibliography to the \file{bbl} file, but rather a structured representation of the bibliographic data. Just like an \file{aux} file, this \file{bbl} file does not print anything when read in. It merely puts data in memory.
-\item Run \bin{latex}: Starting with the second run, the \file{bbl} file is processed right at the beginning of the document body, just like an \file{aux} file. From this point on, all bibliographic data is available in memory so that all citations can be printed right away.\footnote{If the \opt{defernums} package option is enabled \sty{biblatex} uses an alogrithm similar to the traditional procedure to generate numeric lables. In this case, the numbers are assigned as the bibliography is printed and then cycled through the \file{aux} file. It will take an additional \latex run for them to be picked up in citations.} The citation commands have access to the complete bibliographic data, not only to a predefined label. The bibliography is generated from memory using the same data and may be filtered or split as required.
+\item Run \bin{latex}: Starting with the second run, the \file{bbl} file is processed right at the beginning of the document body, just like an \file{aux} file. From this point on, all bibliographic data is available in memory so that all citations can be printed right away.\footnote{If the \opt{defernumbers} package option is enabled \sty{biblatex} uses an alogrithm similar to the traditional procedure to generate numeric lables. In this case, the numbers are assigned as the bibliography is printed and then cycled through the \file{aux} file. It will take an additional \latex run for them to be picked up in citations.} The citation commands have access to the complete bibliographic data, not only to a predefined label. The bibliography is generated from memory using the same data and may be filtered or split as required.
\end{enumerate}
@@ -4306,12 +4284,12 @@ With \sty{biblatex}, this entry is essentially exported in the following format:
%
As you can see, the data is presented in a structured format that resembles the structure of a \file{bib} file to some extent. At this point, no decision concerning the final format of the bibliography entry has been made. The formatting of the bibliography and all citations is controlled by \latex macros, which are defined in bibliography and citation style files.
-\subsection{Bibliography styles}
+\subsection{Bibliography Styles}
\label{aut:bbx}
A bibliography style is a set of macros which print the entries in the bibliography. Such styles are defined in files with the suffix \file{bbx}. The \sty{biblatex} package loads the selected bibliography style file at the end of the package. Note that a small repertory of frequently used macros shared by several of the standard bibliography styles is included in \path{biblatex.def}. This file is loaded at the end of the package as well, prior to the selected bibliography style.
-\subsubsection{Bibliography style files}
+\subsubsection{Bibliography Style Files}
\label{aut:bbx:bbx}
Before we go over the individual components of a bibliography style, consider this example of the overall structure of a typical \file{bbx} file:
@@ -4372,7 +4350,7 @@ Similar to \cmd{DeclareBibliographyOption} but defines options which are settabl
\end{ltxsyntax}
-\subsubsection{Bibliography environments}
+\subsubsection{Bibliography Environments}
\label{aut:bbx:env}
Apart from defining bibliography drivers, the bibliography style is also responsible for the environments which control the layout of the bibliography and the list of shorthands. These environments are defined with \cmd{defbibenvironment}. By default, \cmd{printbibliography} uses the environment \opt{bibliography}. Here is a definition suitable for a bibliography style which does not print any labels in the bibliography:
@@ -4425,7 +4403,7 @@ The list of shorthands is handled in a similar way. \cmd{printshorthands} uses t
{\item}
\end{lstlisting}
-\subsubsection{Bibliography drivers}
+\subsubsection{Bibliography Drivers}
\label{aut:bbx:drv}
Before we go over the commands which form the data interface of the \sty{biblatex} package, it may be instructive to have a look at the structure of a bibliography driver. Note that the example given below is greatly simplified, but still functional. For the sake of readability, we omit several fields which may be part of a \bibtype{book} entry and also simplify the handling of those which are considered. The main point is to give you an idea of how a driver is structured. For information about the mapping of \bibtex's fields to \sty{biblatex}'s data types, see \secref{bib:fld}.
@@ -4476,12 +4454,12 @@ Formatting directives for names are similar to those for literal lists, but the
%
The above directive reverses the name of the first author («Last, First») and prints the remaining names in their regular sequence («First Last»). Note that the only component which is guaranteed to be available is the last name, hence we have to check which parts of the name are actually present. If a certain component of a name is not available, the corresponding argument will be blank. As with directives for literal lists, the separator to be inserted between the indivdual items in the list is also handled by the formatting directive, hence we have to check whether we are in the middle of the list or at the end when inserting it. This is what the second \cmd{ifthenelse} test does.
-\subsubsection{Special fields}
+\subsubsection{Special Fields}
\label{aut:bbx:fld}
The following lists and fields are used by \sty{biblatex} to pass data to bibliography drivers and citation commands. They are not used in \file{bib} files but defined automatically by the package. From the perspective of a bibliography or citation style, they are not different from the fields in a \file{bib} file.
-\paragraph{Generic fields}
+\paragraph{Generic Fields}
\label{aut:bbx:fld:gen}
\begin{fieldlist}
@@ -4536,7 +4514,7 @@ This field holds the initial letter of the string used during sorting. This is u
\end{fieldlist}
-\paragraph{Fields for use in citation labels}
+\paragraph{Fields for Use in Citation Labels}
\label{aut:bbx:fld:lab}
\begin{fieldlist}
@@ -4555,7 +4533,11 @@ The name to be printed in citations. This list is a copy of either the \bibfield
\fielditem{labelnumber}{literal}
-The number of the bibliography entry, as required by numeric citation schemes. If the \bibfield{shorthand} field is used, \sty{biblatex} does not assign a number to the respective entry. In this case \bibfield{labelnumber} is the shorthand rather than a number. Numeric styles must use the value of this field instead of a counter. Note that this field needs to be requested with the package option \opt{labelnumber}, see \secref{use:opt:int} for details. Also see the package option \opt{defernums} in \secref{use:opt:pre}.
+The number of the bibliography entry, as required by numeric citation schemes. If the \bibfield{shorthand} field is defined, \sty{biblatex} does not assign a number to the respective entry. In this case \bibfield{labelnumber} is the shorthand rather than a number. Numeric styles must use the value of this field instead of a counter. Note that this field needs to be requested with the package option \opt{labelnumber}, see \secref{use:opt:int} for details. Also see the package option \opt{defernumbers} in \secref{use:opt:pre}.
+
+\fielditem{prefixnumber}{literal}
+
+If the \opt{prefixnumbers} option of \cmd{printbibliography} has been set in order to prefix all entries in a subbibliography with a fixed string, this string is available in the \bibfield{prefixnumber} field of all affected entries. If no prefix has been set, the \bibfield{prefixnumber} field of the respective entry is undefined. See the \opt{prefixnumbers} option of \cmd{printbibliography} in \secref{use:bib:bib} for details. If the \bibfield{shorthand} field is defined, \sty{biblatex} does not assign the prefix to the \bibfield{prefixnumber} field of the respective entry. In this case, the \bibfield{prefixnumber} field is undefined.
\fielditem{labeltitle}{literal}
@@ -4571,36 +4553,28 @@ The author"=year citation scheme usually requires a letter to be appended to the
\end{fieldlist}
-\paragraph{Date component fields}
+\paragraph{Date Component Fields}
\label{aut:bbx:fld:dat}
-See \tabref{aut:bbx:fld:tab1} for an overview of how the date fields in \file{bib} files are related to the date fields provided by the style interface.
-
-\begin{fieldlist}
-
-\fielditem{day}{integer}
-
-This field holds the day component of the \bibfield{date} field. If the date is a range, it holds the day component of the start date.
-
-\fielditem{month}{integer}
+See \tabref{aut:bbx:fld:tab1} for an overview of how the date fields in \file{bib} files are related to the date fields provided by the style interface. When testing for a field like \bibfield{origdate} in a style, use code like:
-This field is the \bibfield{month} as given in the database file or it holds the month component of the \bibfield{date} field. If the date is a range, it holds the month component of the start date.
-
-\fielditem{year}{integer}
-
-This field is the \bibfield{year} as given in the database file or it holds the year component of the \bibfield{date} field. If the date is a range, it holds the year component of the start date.
-
-\fielditem{endday}{integer}
-
-If the date specification in the \bibfield{date} field is a range, this field holds the day component of the end date.
-
-\fielditem{endmonth}{integer}
-
-If the date specification in the \bibfield{date} field is a range, this field holds the month component of the end date.
+\begin{ltxcode}
+<<\iffieldundef>>{orig<<year>>}{...}{...}
+\end{ltxcode}
+%
+This will tell you if the corresponding date is defined at all. This test:
-\fielditem{endyear}{integer}
+\begin{ltxcode}
+<<\iffieldundef>>{orig<<endyear>>}{...}{...}
+\end{ltxcode}
+%
+will tell you if the corresponding date is defined and a (fully specified) range. This test:
-If the date specification in the \bibfield{date} field is a range, this field holds the year component of the end date. A blank (but defined) \bibfield{endyear} component indicates an open ended \bibfield{date} range.
+\begin{ltxcode}
+<<\iffieldequalstr>>{orig<<endyear>>}{}{...}{...}
+\end{ltxcode}
+%
+will tell you if the corresponding date is defined and an open"=ended range. Open"=ended ranges are indicated by an empty \texttt{endyear} component (as opposed to an undefined \texttt{endyear} component). See \secref{bib:use:dat} and \tabref{bib:use:tab1} on page~\pageref{bib:use:tab1} for further examples.
\begin{table}
\tablesetup
@@ -4650,6 +4624,32 @@ eventdate & 1995-01-31/1995-02-05 & eventday & 31 \\
\label{aut:bbx:fld:tab1}
\end{table}
+\begin{fieldlist}
+
+\fielditem{day}{integer}
+
+This field holds the day component of the \bibfield{date} field. If the date is a range, it holds the day component of the start date.
+
+\fielditem{month}{integer}
+
+This field is the \bibfield{month} as given in the database file or it holds the month component of the \bibfield{date} field. If the date is a range, it holds the month component of the start date.
+
+\fielditem{year}{integer}
+
+This field is the \bibfield{year} as given in the database file or it holds the year component of the \bibfield{date} field. If the date is a range, it holds the year component of the start date.
+
+\fielditem{endday}{integer}
+
+If the date specification in the \bibfield{date} field is a range, this field holds the day component of the end date.
+
+\fielditem{endmonth}{integer}
+
+If the date specification in the \bibfield{date} field is a range, this field holds the month component of the end date.
+
+\fielditem{endyear}{integer}
+
+If the date specification in the \bibfield{date} field is a range, this field holds the year component of the end date. A blank (but defined) \bibfield{endyear} component indicates an open ended \bibfield{date} range.
+
\fielditem{origday}{integer}
This field holds the day component of the \bibfield{origdate} field. If the date is a range, it holds the day component of the start date.
@@ -4724,12 +4724,12 @@ If the date specification in the \bibfield{urldate} field is a range, this field
\end{fieldlist}
-\subsection{Citation styles}
+\subsection{Citation Styles}
\label{aut:cbx}
A citation style is a set of commands such as \cmd{cite} which print different types of citations. Such styles are defined in files with the suffix \file{cbx}. The \sty{biblatex} package loads the selected citation style file at the end of the package. Note that a small repertory of frequently used macros shared by several of the standard citation styles is also included in \path{biblatex.def}. This file is loaded at the end of the package as well, prior to the selected citation style. It also contains the definitions of the commands from \secref{use:cit:txt}.
-\subsubsection{Citation style files}
+\subsubsection{Citation Style Files}
\label{aut:cbx:cbx}
Before we go over the individual commands available in citation style files, consider this example of the overall structure of a typical \file{cbx} file:
@@ -4787,7 +4787,7 @@ This command provides definitions for the \cmd{autocite} and \cmd{autocites} com
\end{ltxsyntax}
-\subsubsection{Special fields}
+\subsubsection{Special Fields}
\label{aut:cbx:fld}
The following fields are used by \sty{biblatex} to pass data to citation commands. They are not used in \file{bib} files but defined automatically by the package. From the perspective of a citation style, they are not different from the fields in a \file{bib} file. See also \secref{aut:bbx:fld}.
@@ -4804,12 +4804,12 @@ The \prm{postnote} argument passed to a citation command. This field is specific
\end{fieldlist}
-\subsection{Data interface}
+\subsection{Data Interface}
\label{aut:bib}
The data interface are the facilities used to format and print all bibliographic data. These facilities are available in both bibliography and citation styles.
-\subsubsection{Data commands}
+\subsubsection{Data Commands}
\label{aut:bib:dat}
This section introduces the main data interface of the \sty{biblatex} package. These are the commands doing most of the work, \ie they actually print the data provided in lists and fields.
@@ -4898,7 +4898,7 @@ This command is intended for use in bibliography drivers handling \bibtype{set}
\end{ltxsyntax}
-\subsubsection{Formatting directives}
+\subsubsection{Formatting Directives}
\label{aut:bib:fmt}
This section introduces the commands used to define the formatting directives required by the data commands from \secref{aut:bib:dat}. Note that all standard formats are defined in \path{biblatex.def} to make it easier to look up the defaults.
@@ -4969,12 +4969,12 @@ Declares \prm{alias} to be an alias of the name list format \prm{format}. If an
\end{ltxsyntax}
-\subsection{Auxiliary commands}
+\subsection{Auxiliary Commands}
\label{aut:aux}
The facilities in this section are intended for analyzing and saving bibliographic data rather than formatting and printing it.
-\subsubsection{Data commands}
+\subsubsection{Data Commands}
\label{aut:aux:dat}
The commands in this section grant low"=level access to the unformatted bibliographic data. They are not intended for typesetting but rather for things like saving data to a temporary macro so that it may be used in a comparison later.
@@ -5053,7 +5053,7 @@ Clears the \prm{name list} within a local scope. A list cleared this way is trea
\end{ltxsyntax}
-\subsubsection{Stand-alone tests}
+\subsubsection{Stand-alone Tests}
\label{aut:aux:tst}
The commands in this section are various kinds of stand"=alone tests for use in bibliography and citation styles.
@@ -5154,7 +5154,7 @@ Expands to \prm{true} if the \opt{usetranslator} option is enabled (either globa
\cmditem{ifsingletitle}{true}{false}
-Expands to \prm{true} if there is only one work by the author or editor in the bibliography, and to \prm{false} otherwise. Note that this feature needs to be enabled explicitly with the package option \opt{singletitle}.
+Expands to \prm{true} if there is only one work by the author\slash editor in the bibliography, and to \prm{false} otherwise. Note that this feature needs to be enabled explicitly with the package option \opt{singletitle}.
\cmditem{ifandothers}{list}{true}{false}
@@ -5298,37 +5298,50 @@ The current nesting level of parentheses and\slash or brackets. This information
\end{ltxsyntax}
-\subsubsection{Tests with \cmd{ifthenelse}}
+\subsubsection{Tests with \cmd{ifboolexpr} and \cmd{ifthenelse}}
\label{aut:aux:ife}
-The tests introduced in \secref{aut:aux:tst} may also be used in the first argument of the \cmd{ifthenelse} command provided by the \sty{ifthen} package. The syntax of the tests is slightly different in this case: the \prm{true} and \prm{false} arguments are omitted from the test itself and passed to the \cmd{ifthenelse} command instead. Note that the use of this command implies processing overhead. If you do not need any boolean operators, it is more efficient to use the stand"=alone tests from \secref{aut:aux:tst}.
+The tests introduced in \secref{aut:aux:tst} may also be used with the \cmd{ifboolexpr} command provided by the \sty{etoolbox} package and the \cmd{ifthenelse} command provided by the \sty{ifthen} package. The syntax of the tests is slightly different in this case: the \prm{true} and \prm{false} arguments are omitted from the test itself and passed to the \cmd{ifboolexpr} or \cmd{ifthenelse} command instead. Note that the use of these commands implies some processing overhead. If you do not need any boolean operators, it is more efficient to use the stand"=alone tests from \secref{aut:aux:tst}.
\begin{ltxsyntax}
-\cmditem{ifthenelse}{tests}{true}{false}
+\cmditem{ifboolexpr}{expression}{true}{false}
-This command allows for complex tests with boolean operators and grouping:
+\sty{etoolbox} command which allows for complex tests with boolean operators and grouping:
\begin{lstlisting}[style=ifthen]{}
-\ifthenelse{\( \ifnameundef{editor} \and \not \iflistundef{location} \)
- \or
- \iffieldundef{year}}
+\ifboolexpr{ (
+ test {\ifnameundef{editor}}
+ and
+ not test {\iflistundef{location}}
+ )
+ or test {\iffieldundef{year}}
+ }
{...}
{...}
\end{lstlisting}
-%
-Of course the generic tests provided by the \sty{ifthen} package itself may be used alongside the additional ones provided by \sty{biblatex}. In case it is not obvious: the generic test in the example below is |>|, the greater-than sign. \cmd{value} is a standard \latex command which returns the value of a counter.
+
+\cmditem{ifthenelse}{tests}{true}{false}
+
+\sty{ifthen} command which allows for complex tests with boolean operators and grouping:
\begin{lstlisting}[style=ifthen]{}
-\ifthenelse{\value{editor}>1 \or \ifandothers{editor}}
+\ifthenelse{ \(
+ \ifnameundef{editor}
+ \and
+ \not \iflistundef{location}
+ \)
+ \or \iffieldundef{year}
+ }
{...}
{...}
\end{lstlisting}
+%
+The additional tests provided by \sty{biblatex} are only available when \cmd{ifboolexpr} or \cmd{ifthenelse} are used in citation commands and in the bibliography.
-The additional tests provided by \sty{biblatex} are only available when \cmd{ifthenelse} is used in citation commands and in the bibliography.
\end{ltxsyntax}
-\subsubsection{Miscellaneous commands}
+\subsubsection{Miscellaneous Commands}
\label{aut:aux:msc}
The section introduced miscellaneous commands and little helpers for use in bibliography and citation styles.
@@ -5338,12 +5351,12 @@ The section introduced miscellaneous commands and little helpers for use in bibl
\cmditem{newbibmacro}{name}[arguments][optional]{definition}
\cmditem*{newbibmacro*}{name}[arguments][optional]{definition}
-Defines a macro to be executed via \cmd{usebibmacro} later. The syntax of this command is similar to \cmd{newcommand} except that \prm{name} may contain characters such as numbers and punctuation marks and does not start with a backslash. The optional argument \prm{arguments} is an integer specifying the number of arguments taken by the macro. If \prm{optional} is given, it specifies a default value for the first argument of the macro, which automatically becomes an optional argument. If the macro is already defined, this command issues an error message. As with \cmd{newcommand}, the regular variant of this command uses the \cmd{long} prefix in the definition while the starred one does not. If a macro has been declared to be long, it may take arguments containing \cmd{par} tokens. \cmd{newbibmacro} and \cmd{renewbibmacro} are provided for convenience. Style authors are free to use \cmd{newcommand} or \cmd{def} instead. However, note that most shared definitions found in \path{biblatex.def} are defined with \cmd{newbibmacro}, hence they must be used and modified accordingly.
+Defines a macro to be executed via \cmd{usebibmacro} later. The syntax of this command is very similar to \cmd{newcommand} except that \prm{name} may contain characters such as numbers and punctuation marks and does not start with a backslash. The optional argument \prm{arguments} is an integer specifying the number of arguments taken by the macro. If \prm{optional} is given, it specifies a default value for the first argument of the macro, which automatically becomes an optional argument. In contrast to \cmd{newcommand}, \cmd{newbibmacro} issues a warning message if the macro is already defined, and automatically falls back to \cmd{renewbibmacro}. As with \cmd{newcommand}, the regular variant of this command uses the \cmd{long} prefix in the definition while the starred one does not. If a macro has been declared to be long, it may take arguments containing \cmd{par} tokens. \cmd{newbibmacro} and \cmd{renewbibmacro} are provided for convenience. Style authors are free to use \cmd{newcommand} or \cmd{def} instead. However, note that most shared definitions found in \path{biblatex.def} are defined with \cmd{newbibmacro}, hence they must be used and modified accordingly.
\cmditem{renewbibmacro}{name}[arguments][optional]{definition}
\cmditem*{renewbibmacro*}{name}[arguments][optional]{definition}
-Similar to \cmd{newbibmacro} but redefines \prm{name}. This command issues an error message if the macro is undefined.
+Similar to \cmd{newbibmacro} but redefines \prm{name}. In contrast to \cmd{renewcommand}, \cmd{renewbibmacro} issues a warning message if the macro is undefined, and automatically falls back to \cmd{newbibmacro}.
\cmditem{providebibmacro}{name}[arguments][optional]{definition}
\cmditem*{providebibmacro*}{name}[arguments][optional]{definition}
@@ -5531,12 +5544,12 @@ These commands activate or deactivate all citation trackers locally (this will a
\end{ltxsyntax}
-\subsection{Punctuation and spacing}
+\subsection{Punctuation and Spacing}
\label{aut:pct}
The \sty{biblatex} package provides elaborate facilities designed to manage and track punctuation and spacing in the bibliography and in citations. These facilities work on two levels. The high"=level commands discussed in \secref{aut:pct:new} deal with punctuation and whitespace inserted by the bibliography style between the individual segments of a bibliography entry. The commands in \secref{aut:pct:chk, aut:pct:pct, aut:pct:spc} work at a lower level. They use \tex's space factor and modified space factor codes to track punctuation in a robust and efficient way. This way it is possible to detect trailing punctuation marks within fields, not only those explicitly inserted between fields. The same technique is also used for automatic capitalization of bibliography strings, see \cmd{DeclareCapitalPunctuation} in \secref{aut:pct:cfg} as well as \secref{aut:str} for details. Note that these facilities are only made available locally in citations and bibliographies. They will not affect any other part of a document.
-\subsubsection{Block and unit punctuation}
+\subsubsection{Block and Unit Punctuation}
\label{aut:pct:new}
The major segments of a bibliography entry are <blocks> and <units>. A block is the larger segment of the two, a unit is shorter or at most equal in length. For example, the values of fields such as \bibfield{title} or \bibfield{note} usually form a unit which is separated from subsequent data by a period or a comma. A block may comprise several fields which are treated as separate units, for example \bibfield{publisher}, \bibfield{location}, and \bibfield{year}. The segmentation of an entry into blocks and units is at the discretion of the bibliography style. An entry is segmented by inserting \cmd{newblock} and \cmd{newunit} commands at suitable places and \cmd{finentry} at the very end (see \secref{aut:bbx:drv} for an example). See also \secref{aut:cav:pct} for some practical hints.
@@ -5562,7 +5575,7 @@ The \cmd{setunit} command is similar to \cmd{newunit} except that it uses \prm{p
\cmditem{setpunctfont}{command}
-This command, which is intended for use in field formatting directives, provides an alternative way of dealing with unit punctuation after a field printed in a different font (for example, a title printed in italics). The standard \latex way of dealing with this is adding a small amount of space, the so-called italic correction. This command allows adapting the punctuation to the font of the preceeding field. The \prm{command} should be a text font command which takes one argument, such as \cmd{emph} or \cmd{textbf}. This command will only affect punctuation marks inserted by one of the commands from \secref{aut:pct:pct}. The font adaption is applied to the next punctuation mark only and will be reset automatically thereafter. If you want to reset it manually before it takes effect, issue \cmd{resetpunctfont}. If the \opt{punctfont} package option is disabled, this command does nothing. Note that the \cmd{mkbibemph} wrapper from \secref{aut:fmt:ich} incorporates this feature by default.
+This command, which is intended for use in field formatting directives, provides an alternative way of dealing with unit punctuation after a field printed in a different font (for example, a title printed in italics). The standard \latex way of dealing with this is adding a small amount of space, the so-called italic correction. This command allows adapting the punctuation to the font of the preceeding field. The \prm{command} should be a text font command which takes one argument, such as \cmd{emph} or \cmd{textbf}. This command will only affect punctuation marks inserted by one of the commands from \secref{aut:pct:pct}. The font adaption is applied to the next punctuation mark only and will be reset automatically thereafter. If you want to reset it manually before it takes effect, issue \cmd{resetpunctfont}. If the \opt{punctfont} package option is disabled, this command does nothing. Note that the \cmd{mkbibemph} and \cmd{mkbibbold} wrappers from \secref{aut:fmt:ich} incorporate this feature by default.
\csitem{resetpunctfont}
@@ -5570,7 +5583,7 @@ This command resets the unit punctuation font defined with \cmd{setpunctfont} be
\end{ltxsyntax}
-\subsubsection{Punctuation tests}
+\subsubsection{Punctuation Tests}
\label{aut:pct:chk}
The following commands may be used to test for preceding punctuation marks at any point in citations and the bibliography.
@@ -5591,7 +5604,7 @@ Executes \prm{true} if preceded by the punctuation mark \prm{character}, and \pr
\end{ltxsyntax}
-\subsubsection{Adding punctuation}
+\subsubsection{Adding Punctuation}
\label{aut:pct:pct}
The following commands are designed to prevent double punctuation marks. Bibliography and citation styles should always use these commands instead of literal punctuation marks. All \cmd{add...} commands in this section automatically remove preceding whitespace with \cmd{unspace} (see \secref{aut:pct:spc}). Note that the behavior of all \cmd{add...} commands discussed below is the package default, which is restored whenever \sty{biblatex} switches languages. This behavior may be adjusted with \cmd{DeclarePunctuationPairs} from \secref{aut:pct:cfg}.
@@ -5635,7 +5648,7 @@ Adds an internal marker which will cause the next punctuation command to print n
\end{ltxsyntax}
-\subsubsection{Adding whitespace}
+\subsubsection{Adding Whitespace}
\label{aut:pct:spc}
The following commands are designed to prevent spurious whitespace. Bibliography and citation styles should always use these commands instead of literal whitespace. In contrast to the commands in \secref{aut:pct:chk, aut:pct:pct}, they are not restricted to citations and the bibliography but available globally.
@@ -5698,7 +5711,7 @@ Adds a breakable slash. This command differs from the \cmd{slash} command in the
Note that the commands in this section implicitly execute \cmd{unspace} to remove spurious whitespace, hence they may be used to override each other. For example, you may use \cmd{addnbspace} to transform a previously inserted interword space into a non"=breakable one and \cmd{addspace} to turn a non"=breakable space into a breakable one.
-\subsubsection{Configuring punctuation and capitalization}
+\subsubsection{Configuring Punctuation and Capitalization}
\label{aut:pct:cfg}
The following commands configure various features related to punctuation and automatic capitalization.
@@ -5767,7 +5780,7 @@ Undoes the settings applied by \cmd{uspunctuation}, restoring standard punctuati
\end{ltxsyntax}
-\subsubsection{Correcting punctuation tracking}
+\subsubsection{Correcting Punctuation Tracking}
\label{aut:pct:ctr}
The facilities for punctuation tracking and automatic capitalization are very reliable under normal circumstances, but there are always marginal cases which may require manual intervention. Typical cases are bibliography strings printed as the first word in a footnote (which is usually treated as the beginning of a paragaph as far as capitalization is concerned, but \tex is not in vertical mode at this point) or punctuation after periods which are not really end"=of"=sentence periods (for example, after an ellipsis like «[\dots\unkern]» a command such as \cmd{addperiod} would do nothing since parentheses and brackets are transparent to the punctuation tracker). In such cases, use the following commands in bibliography and citation styles to mark the beginning or middle of a sentence if and where required:
@@ -5788,7 +5801,7 @@ The starred variant of \cmd{midsentence} differs from the regular one in that a
\end{ltxsyntax}
-\subsection{Bibliography strings}
+\subsection{Bibliography Strings}
\label{aut:str}
Bibliography strings are key terms such as <edition> or <volume> which are automatically translated by \sty{biblatex}'s localization modules. See \secref{aut:lng} for an overview and \secref{aut:lng:key} for a list of all strings supported by default. The commands in this section are used to print the localized term.
@@ -5797,32 +5810,74 @@ Bibliography strings are key terms such as <edition> or <volume> which are autom
\cmditem{bibstring}[wrapper]{key}
-Prints the bibliography string \prm{key}, where \prm{key} is an identifier in lowercase letters (see \secref{aut:lng:key}). The term will be capitalized as required, see \secref{aut:pct:cfg} for details. If the \prm{wrapper} argument is given, the string is passed to \prm{wrapper} as an argument. This is intended for font commands such as \cmd{emph}.
+Prints the bibliography string \prm{key}, where \prm{key} is an identifier in lowercase letters (see \secref{aut:lng:key}). The string will be capitalized as required, see \secref{aut:pct:cfg} for details.
+Depending on the \opt{abbreviate} package option from \secref{use:opt:pre}, \cmd{bibstring} prints the short or the long version of the string. If bibliography strings are nested, \ie if \cmd{bibstring} is used in another string, it will behave like \cmd{bibxstring}.
+If the \prm{wrapper} argument is given, the string is passed to the \prm{wrapper} for formatting. This is intended for font commands such as \cmd{emph}.
+
+\cmditem{biblstring}[wrapper]{key}
+
+Similar to \cmd{bibstring} but always prints the long string, ignoring the \opt{abbreviate} option.
+
+\cmditem{bibsstring}[wrapper]{key}
+
+Similar to \cmd{bibstring} but always prints the short string, ignoring the \opt{abbreviate} option.
\cmditem{bibcpstring}[wrapper]{key}
-This command is similar to \cmd{bibstring}, but the term is always capitalized.
+Similar to \cmd{bibstring} but the term is always capitalized.
+
+\cmditem{bibcplstring}[wrapper]{key}
+
+Similar to \cmd{biblstring} but the term is always capitalized.
+
+\cmditem{bibcpsstring}[wrapper]{key}
+
+Similar to \cmd{bibsstring} but the term is always capitalized.
\cmditem{bibucstring}[wrapper]{key}
-This command is similar to \cmd{bibstring}, but the whole term is uppercased.
+Similar to \cmd{bibstring} but the whole term is uppercased.
+
+\cmditem{bibuclstring}[wrapper]{key}
+
+Similar to \cmd{biblstring} but the whole term is uppercased.
+
+\cmditem{bibucsstring}[wrapper]{key}
+
+Similar to \cmd{bibsstring} but the whole term is uppercased.
\cmditem{biblcstring}[wrapper]{key}
-This command is similar to \cmd{bibstring}, but the whole term is lowercased.
+Similar to \cmd{bibstring} but the whole term is lowercased.
+
+\cmditem{biblclstring}[wrapper]{key}
+
+Similar to \cmd{biblstring} but the whole term is lowercased.
+
+\cmditem{biblcsstring}[wrapper]{key}
+
+Similar to \cmd{bibsstring} but the whole term is lowercased.
\cmditem{bibxstring}{key}
-A simplified but expandable version of \cmd{bibstring}. Note that this variant does not capitalize automatically, nor does it hook into the punctuation tracker. It is intended for special cases in which an expanded bibliography string is required in a test, but is not printed.
+A simplified but expandable version of \cmd{bibstring}. Note that this variant does not capitalize automatically, nor does it hook into the punctuation tracker. It is intended for special cases in which strings are nested or an expanded bibliography string is required in a test.
+
+\cmditem{bibxlstring}[wrapper]{key}
+
+Similar to \cmd{bibxstring} but always uses the long string, ignoring the \opt{abbreviate} option.
+
+\cmditem{bibxsstring}[wrapper]{key}
+
+Similar to \cmd{bibxstring} but always uses the short string, ignoring the \opt{abbreviate} option.
\end{ltxsyntax}
-\subsection{Localization modules}
+\subsection{Localization Modules}
\label{aut:lng}
A localization module provides translations for key terms such as <edition> or <volume> as well as definitions for language specific features such as the date format and ordinals. These definitions are provided in files with the suffix \file{lbx}. The base name of the file must be a language name known to the \sty{babel} package. The \file{lbx} files may also be used to map \sty{babel}'s language names to the backend modules of the \sty{biblatex} package. All localization modules are loaded on demand in the document body. Note that the contents of the file are processed in a group and that the category code of the character \texttt{@} is temporarily set to <letter>.
-\subsubsection{Localization commands}
+\subsubsection{Localization Commands}
\label{aut:lng:cmd}
The user"=level versions of the localization commands were already introduced in \secref{use:lng}. When used in \file{lbx} files, however, the syntax of localization commands is different from the user syntax in the preamble and the configuration file. When used in localization files, there is no need to specify the \prm{language} because the mapping of strings to a language is already provided by the name of the \file{lbx} file.
@@ -5884,6 +5939,20 @@ This command is only available in \file{lbx} files. It copies the bibliography e
This command corresponds to \cmd{DefineHyphenationExceptions} from \secref{use:lng}. The difference is that it is only available in \file{lbx} files and that the \prm{language} argument is omitted. The hyphenation exceptions will affect the language of the \file{lbx} file currently being processed.
+\cmditem{DeclareRedundantLanguages}{language, language, ...}{babel, babel, ...}
+
+This command provides the language mappings required by the \opt{clearlang} option from \secref{use:opt:pre}.
+The \prm{language} is the string given in the \bibfield{language} field (without the optional \texttt{lang} prefix); \prm{babel} is \sty{babel}'s language identifier, as given in the optional argument of \cmd{usepackage} when loading \sty{babel}. This command may be used in \file{lbx} files or in the document preamble. Here are some examples:
+
+\begin{lstlisting}[style=latex]{}
+\DeclareRedundantLanguages{french}{french}
+\DeclareRedundantLanguages{german}{german,ngerman,austrian,naustrian}
+\DeclareRedundantLanguages{english,american}{english,american,british,
+ canadian,australian,newzealand,USenglish,UKenglish}
+\end{lstlisting}
+%
+Note that this feature needs to be enabled globally with the \opt{clearlang} option from \secref{use:opt:pre}. If it is disabled, all mappings will be ignored. If the \prm{babel} parameter is blank, \sty{biblatex} will clear the mappings for the corresponding \prm{language}, \ie the feature will be disabled for this \prm{language} only.
+
\cmditem{DeclareLanguageMapping}{language}{file}
This command maps a \sty{babel} language identifier to an \file{lbx} file. The \prm{language} must be a language name known to the \sty{babel} package, \ie one of the identifiers listed in \tabref{bib:fld:tab1}. The \prm{file} argument is the name of an alternative \file{lbx} file without the \texttt{.lbx} suffix. Declaring the same mapping more than once is possible. Subsequent declarations will simply overwrite any previous ones. This command may only be used in the preamble. See \secref{aut:cav:lng} for further details.
@@ -5894,7 +5963,7 @@ This command, which may be used in the preamble (including \file{cbx} and \file{
\end{ltxsyntax}
-\subsubsection{Localization keys}
+\subsubsection{Localization Keys}
\label{aut:lng:key}
The localization keys in this section are defined by default and covered by the localization files which come with \sty{biblatex}. Note that these strings are only available in citations, the bibliography, and the list of shorthands. All expressions should be capitalized as they usually are when used in the middle of a sentence. \sty{biblatex} will capitalize them automatically at the beginning of a sentence. The only exceptions to these rules are the three strings intended for use in headings.
@@ -5910,7 +5979,7 @@ The following strings are special because they are intended for use in headings
\item[shorthands] The term <list of shorthands> or <list of abbreviations>, also available as \cmd{losname}.
\end{keymarglist}
-\paragraph{Roles, expressed as functions}
+\paragraph{Roles, Expressed as Functions}
\label{aut:lng:key:efn}
The following keys refer to roles which are expressed as a function (<editor>, <translator>) rather than as an action (<edited by>, <translated by>).
@@ -5936,7 +6005,7 @@ The following keys refer to roles which are expressed as a function (<editor>, <
\item[annotators] The plural form of \texttt{annotators}.
\end{keymarglist}
-\paragraph{Concatenated editor roles, expressed as functions}
+\paragraph{Concatenated Editor Roles, Expressed as Functions}
\label{aut:lng:key:cef}
The following keys are similar in function to \texttt{editor}, \texttt{translator}, etc. They are used to indicate additional roles of the editor, \eg <editor and translator>, <editor and foreword>.
@@ -6015,7 +6084,7 @@ Keys for \bibfield{editor}\slash \bibfield{annotator}\slash \bibfield{commentato
\item[editorstranaf] The plural form of \texttt{editortranaf}.
\end{keymarglist}
-\paragraph{Concatenated translator roles, expressed as functions}
+\paragraph{Concatenated Translator Roles, Expressed as Functions}
\label{aut:lng:key:ctf}
The following keys are similar in function to \texttt{translator}. They are used to indicate additional roles of the translator, \eg <translator and commentator>, <translator and introduction>.
@@ -6055,7 +6124,7 @@ Keys for \bibfield{translator}\slash \bibfield{annotator}\slash \prm{role} combi
\item[translatorsanaf] The plural form of \texttt{translatoranaf}.
\end{keymarglist}
-\paragraph{Roles, expressed as actions}
+\paragraph{Roles, Expressed as Actions}
\label{aut:lng:key:eac}
The following keys refer to roles which are expressed as an action (<edited by>, <translated by>) rather than as a function (<editor>, <translator>).
@@ -6073,7 +6142,7 @@ The following keys refer to roles which are expressed as an action (<edited by>,
\item[byannotator] The expression <annotated by \prm{name}>.
\end{keymarglist}
-\paragraph{Concatenated editor roles, expressed as actions}
+\paragraph{Concatenated Editor Roles, Expressed as Actions}
\label{aut:lng:key:cea}
The following keys are similar in function to \texttt{byeditor}, \texttt{bytranslator}, etc. They are used to indicate additional roles of the editor, \eg <edited and translated by>, <edited and furnished with an introduction by>, <edited, with a foreword, by>.
@@ -6129,7 +6198,7 @@ Keys for \bibfield{editor}\slash \bibfield{translator}\slash \bibfield{annotator
\item[byeditortranaf] Used if \bibfield{editor}\slash \bibfield{annotator}\slash \bibfield{commentator}\slash \bibfield{aftword} are identical.
\end{keymarglist}
-\paragraph{Concatenated translator roles, expressed as actions}
+\paragraph{Concatenated Translator Roles, Expressed as Actions}
\label{aut:lng:key:cta}
The following keys are similar in function to \texttt{bytranslator}. They are used to indicate additional roles of the translator, \eg <translated and commented by>, <translated and furnished with an introduction by>, <translated, with a foreword, by>.
@@ -6158,7 +6227,7 @@ Keys for \bibfield{translator}\slash \bibfield{annotator}\slash \prm{role} combi
\item[bytranslatoranaf] Used if \bibfield{translator}\slash \bibfield{annotator}\slash \bibfield{aftword} are identical.
\end{keymarglist}
-\paragraph{Roles, expressed as objects}
+\paragraph{Roles, Expressed as Objects}
\label{aut:lng:key:rob}
Roles which are related to supplementary material may also be expressed as objects (<with a commentary by>) rather than as functions (<commentator>) or as actions (<commented by>).
@@ -6171,7 +6240,7 @@ Roles which are related to supplementary material may also be expressed as objec
\item[withafterword] The expression <with an afterword by \prm{name}>.
\end{keymarglist}
-\paragraph{Supplementary material}
+\paragraph{Supplementary Material}
\label{aut:lng:key:mat}
\begin{keymarglist}
@@ -6182,7 +6251,7 @@ Roles which are related to supplementary material may also be expressed as objec
\item[afterword] The term <afterword>.
\end{keymarglist}
-\paragraph{Publication details}
+\paragraph{Publication Details}
\label{aut:lng:key:pdt}
\begin{keymarglist}
@@ -6204,7 +6273,7 @@ Roles which are related to supplementary material may also be expressed as objec
\item[reprintas] The expression <reprinted as \prm{title}>.
\end{keymarglist}
-\paragraph{Publication state}
+\paragraph{Publication State}
\label{aut:lng:key:pst}
\begin{keymarglist}
@@ -6304,7 +6373,7 @@ Other expressions frequently used in citations:
\item[thiscite] The expression used in some verbose citation styles to differentiate between the page range of the cited item (typically an article in a journal, collection, or conference proceedings) and the page number the citation refers to. For example: \enquote{Author, Title, in: Book, pp. 45--61, \texttt{thiscite} p. 52.}
\end{keymarglist}
-\paragraph{Month names}
+\paragraph{Month Names}
\label{aut:lng:key:mon}
\begin{keymarglist}
@@ -6322,7 +6391,7 @@ Other expressions frequently used in citations:
\item[december] The name <December>.
\end{keymarglist}
-\paragraph{Language names}
+\paragraph{Language Names}
\label{aut:lng:key:lng}
\begin{keymarglist}
@@ -6361,7 +6430,7 @@ The following strings are intended for use in phrases like <translated from [the
\item[fromswedish] The expression <from [the] Swedish>.
\end{keymarglist}
-\paragraph{Country names}
+\paragraph{Country Names}
\label{aut:lng:key:cnt}
Country names are localized by using the string \texttt{country} plus the \acr{ISO}-3166 country code as the key. The short version of the translation should be the \acr{ISO}-3166 country code. Note that only a small number of country names is defined by default, mainly to illustrate this scheme. These keys are used in the \bibfield{location} list of \bibtype{patent} entries but they may be useful for other purposes as well.
@@ -6375,7 +6444,7 @@ Country names are localized by using the string \texttt{country} plus the \acr{I
\item[countryus] The name <United States of America>, abbreviated as \texttt{US}.
\end{keymarglist}
-\paragraph{Patents and patent requests}
+\paragraph{Patents and Patent Requests}
\label{aut:lng:key:pat}
Strings related to patents are localized by using the term \texttt{patent} plus the \acr{ISO}-3166 country code as the key. Note that only a small number of patent keys is defined by default, mainly to illustrate this scheme. These keys are used in the \bibfield{type} field of \bibtype{patent} entries.
@@ -6400,12 +6469,12 @@ Patent requests are handled in a similar way, using the string \texttt{patreq} a
\item[patrequs] The expression <U.S. patent request>.
\end{keymarglist}
-\subsection{Formatting commands}
+\subsection{Formatting Commands}
\label{aut:fmt}
This section corresponds to \secref{use:fmt} in the user part of this manual. Bibliography and citation styles should incorporate the commands and facilities discussed in this section in order to provide a certain degree of high"=level configurability. Users should not be forced to write new styles if all they want to do is modify the spacing in the bibliography or the punctuation used in citations.
-\subsubsection{User-definable commands and hooks}
+\subsubsection{User-definable Commands and Hooks}
\label{aut:fmt:fmt}
This section corresponds to \secref{use:fmt:fmt} in the user part of the manual. The commands and hooks discussed here are meant to be redefined by users, but bibliography and citation styles may provide a default definition which is different from the package default. These commands are defined in \path{biblatex.def} to make it easier to look up the package defaults. Note that all commands starting with \cmd{mk\dots} take one mandatory argument.
@@ -6472,9 +6541,13 @@ Similar to \cmd{multinamedelim}, but intended for the \cmd{supercite} command on
Similar to \cmd{multicitedelim}, but intended for citation styles which <compress> multiple citations, \ie print the author only once if subsequent citations share the same author etc.
+\csitem{nametitledelim}
+
+The delimiter to be printed between the author\slash editor and the title. This command should be incorporated in the definition of all citation commands of author-title and some verbose citation styles.
+
\csitem{nameyeardelim}
-The delimiter to be printed between the author or editor and the year. This command should be incorporated in the definition of all citation commands of author-year citation styles.
+The delimiter to be printed between the author\slash editor and the year. This command should be incorporated in the definition of all citation commands of author-year citation styles.
\csitem{prenotedelim}
@@ -6502,7 +6575,7 @@ Similar to \cmd{mkbibnamelast}, but intended for the name affix.
\end{ltxsyntax}
-\subsubsection{Language-specific commands}
+\subsubsection{Language-specific Commands}
\label{aut:fmt:lng}
This section corresponds to \secref{use:fmt:lng} in the user part of the manual. The commands discussed here are usually handled by the localization modules, but may also be redefined by users on a per"=language basis. Note that all commands starting with \cmd{mk\dots} take one or more mandatory arguments.
@@ -6551,7 +6624,7 @@ Similar to \cmd{mkbibordinal}, but intended for use with the term <series>.
\end{ltxsyntax}
-\subsubsection{User-definable lengths and counters}
+\subsubsection{User-definable Lengths and Counters}
\label{aut:fmt:len}
This section corresponds to \secref{use:fmt:len} in the user part of the manual. The length registers and counters discussed here are meant to be altered by users. Bibliography and citation styles should incorporate them where applicable and may also provide a default setting which is different from the package default.
@@ -6588,7 +6661,7 @@ The penalty used by \cmd{addhighpenspace} and \cmd{addhpthinspace}, see \secref{
\end{ltxsyntax}
-\subsubsection{Auxiliary commands and hooks}
+\subsubsection{Auxiliary Commands and Hooks}
\label{aut:fmt:ich}
The auxiliary commands and facilities in this section serve a special purpose. Some of them are used by \sty{biblatex} to communicate with bibliography and citation styles in some way or other.
@@ -6599,6 +6672,10 @@ The auxiliary commands and facilities in this section serve a special purpose. S
A generic command which prints its argument in italics. This is a simple wrapper around the standard \cmd{emph} command. Apart from that, it uses \cmd{setpunctfont} from \secref{aut:pct:new} to adapt the font of the next punctuation mark following the text set in italics. If the \opt{punctfont} package option is disabled, this command behaves like \cmd{emph}.
+\cmditem{mkbibbold}{text}
+
+Similar in concept to \cmd{mkbibemph} but prints bold text. This is a simple wrapper around the standard \cmd{textbf} command which incorporates \cmd{setpunctfont}. If the \opt{punctfont} package option is disabled, this command behaves like \cmd{textbf}.
+
\cmditem{mkbibquote}{text}
A generic command which wraps its argument in quotation marks. If the \sty{csquotes} package is loaded, this command uses the language sensitive quotation marks provided by that package. \cmd{mkbibquote} also supports <American-style> punctuation, see \cmd{DeclareQuotePunctuation} in \secref{aut:pct:cfg} for details.
@@ -6697,7 +6774,7 @@ A special formatting directive for use with \cmd{printfield} and \cmd{printtext}
\end{ltxsyntax}
-\subsubsection{Auxiliary lengths, counters, and other facilities}
+\subsubsection{Auxiliary Lengths, Counters, and Other Features}
\label{aut:fmt:ilc}
The length registers and counters discussed here are used by \sty{biblatex} to pass information to bibliography and citation styles. Think of them as read"=only registers. Note that all counters are \latex counters. Use |\value{counter}| to read out the current value.
@@ -6799,7 +6876,7 @@ The name of the name list currently being processed by \cmd{printnames}. This in
\end{ltxsyntax}
-\subsubsection{General purpose hooks}
+\subsubsection{General Purpose Hooks}
\label{aut:fmt:hok}
\begin{ltxsyntax}
@@ -6842,12 +6919,12 @@ Appends the \prm{code} to an internal hook executed once for every entry as the
\end{ltxsyntax}
-\subsection{Hints and caveats}
+\subsection{Hints and Caveats}
\label{aut:cav}
This section provides some additional hints concerning the author interface of this package. It also addresses common problems and potential misconceptions.
-\subsubsection{Mixing programming interfaces}
+\subsubsection{Mixing Programming Interfaces}
\label{aut:cav:mif}
The \sty{biblatex} package provides two main programming interfaces for style authors. The \cmd{DeclareBibliographyDriver} command, which defines a handler for an entry type, is typically used in \file{bbx} files. \cmd{DeclareCiteCommand}, which defines a new citation command, is typically used in \file{cbx} files. However, in some cases it is convenient to mix these two interfaces. For example, the \cmd{fullcite} command prints a verbose citation similar to the full bibliography entry. It is essentially defined as follows:
@@ -6923,7 +7000,7 @@ When defining \cmd{bbx@xref}, the \prm{precode}, \prm{postcode}, and \prm{sepcod
}
\end{ltxexample}
-\subsubsection{Reference sets}
+\subsubsection{Reference Sets}
\label{aut:cav:set}
Reference sets have already been introduced in \secref{use:use:set}. This section discusses how to process reference sets in a bibliography style. Handling them is surprisingly simple. You will normally use the \cmd{entryset} command from \secref{aut:bib:dat} to loop over all set members (in the order in which they are listed in the \bibfield{entryset} field of the \bibtype{set} entry) and append \cmd{finentry} at the end. That's it. The formatting is handled by the drivers for the entry types of the individual set members:
@@ -6953,15 +7030,15 @@ The \bibfield{entrysetcount} field holds an integer indicating the position of a
%
Since this field is only defined when processing citations referring to a set member, there is no need to add any additional tests.
-\subsubsection{Citation/page trackers in floats and \acr{TOC}/\acr{LOT}/\acr{LOF}}
+\subsubsection{Citation/Page Trackers in Floats and \acr{TOC}/\acr{LOT}/\acr{LOF}}
\label{aut:cav:flt}
If a citation is given in a float (typically in the caption of a figure or table), scholarly back references like <ibidem> or back references based on the page tracker may get ambiguous because floats are objects which are (physically and logically) placed outside the flow of text, hence the logic of such back references applies poorly to them. To avoid any such ambiguities, the citation trackers are temporarily disabled in all floats. This is equivalent to setting \cmd{citetrackerfalse} locally and affects all of the following tests from \secref{aut:aux:tst}: \cmd{ifciteseen}, \cmd{ifentryseen}, \cmd{ifciteibid}, \cmd{ifciteidem}, \cmd{ifopcit}, and \cmd{ifloccit}. The page tracker is disabled as well. This is equivalent to setting \cmd{pagetrackerfalse} locally and affects the \cmd{ifsamepage} and \cmd{iffirstonpage} tests. The trackers are also disabled in the table of contents, the list of figures, and the list of tables for similar reasons.
-\subsubsection{Using the punctuation tracker (the right way)}
+\subsubsection{Using the Punctuation Tracker}
\label{aut:cav:pct}
-\paragraph{The basics}
+\paragraph{The Basics}
There is one fundamental principle style authors should keep in mind when designing a bibligraphy driver: block and unit punctuation is handled asynchronously. This is best explained by way of example. Consider the following code snippet:
@@ -7028,7 +7105,7 @@ This may all sound more complicated than it is. In practice, it means that it is
{. \printfield{note}}}%
\end{lstlisting}
-\paragraph{Common mistakes}
+\paragraph{Common Mistakes}
It is a fairly common misconception to think of the unit punctuation as something that is handled synchronously. This typically causes problems if the driver includes any literal text. Consider this erroneous code snippet which will generate misplaced unit punctuation:
@@ -7085,7 +7162,7 @@ We still need to handle cases in which there is no series information at all, so
%
One final hint: bibliography strings are not literal text as far as the punctuation tracker is concerned. Since \cmd{bibstring} and similar commands interface with the punctuation tracker, there is no need to wrap them in a \cmd{printtext} command.
-\paragraph{Advanced usage}
+\paragraph{Advanced Usage}
The punctuation tracker may also be used to handle more complex scenarios. For example, suppose that we want the fields \bibfield{location}, \bibfield{publisher}, and \bibfield{year} to be rendered in one of the following formats, depending on the available data:
@@ -7160,7 +7237,7 @@ This can be handled by the following code:
%
Since the punctuation after the location is special if there is no publisher, we need one \cmd{iflistundef} test to catch this case. Everything else is handled by the punctuation tracker.
-\subsubsection{Electronic publishing information}
+\subsubsection{Electronic Publishing Information}
\label{aut:cav:epr}
The standard styles feature dedicated support for arXiv references. Support for other resources is easily added. The standard styles handle the \bibfield{eprint} field as follows:
@@ -7180,7 +7257,7 @@ If an \bibfield{eprinttype} field is available, the above code tries to use the
%
In other words, adding support for additional resources is as easy as defining a field format named \texttt{eprint:\prm{resource}} where \prm{resource} is an identifier to be used in the \bibfield{eprinttype} field.
-\subsubsection{External abstracts and annotations}
+\subsubsection{External Abstracts and Annotations}
\label{aut:cav:prf}
External abstracts and annotations have been discussed in \secref{use:use:prf}. This section provides some more background for style authors. The standard styles use the following macros (from \path{biblatex.def}) to handle abstracts and annotations:
@@ -7201,7 +7278,7 @@ External abstracts and annotations have been discussed in \secref{use:use:prf}.
%
If the \bibfield{abstract}\slash \bibfield{annotation} field is undefined, the above code tries to load the abstracts\slash annotations from an external file. The \cmd{printfile} commands also incorporate file name prefixes which may be redefined by users. Note that you must enable \cmd{printfile} explicitly by setting the \opt{loadfiles} package option from \secref{use:opt:pre}. This feature is disabled by default for performance reasons.
-\subsubsection{Custom localization modules}
+\subsubsection{Custom Localization Modules}
\label{aut:cav:lng}
Style guides may include provisions as to how strings like <edition> should be abbreviated or they may mandate certain fixed expressions. For example, the \acr{mla} style guide requires authors to use the term <Works~Cited> rather than <Bibliography> or <References> in the heading of the bibliography. Localization commands such as \cmd{DefineBibliographyStrings} from \secref{use:lng} may indeed be used in \file{cbx} and \file{bbx} files to handle such cases. However, overloading style files with translations is rather inconvenient. This is where \cmd{DeclareLanguageMapping} from \secref{aut:lng:cmd} comes into play. This command maps an \file{lbx} file with alternative translations to a \sty{babel} language. For example, you could create a file named \path{french-humanities.lbx} which provides French translations adapted for use in the humanities and map it to the \sty{babel} language \texttt{french} in the preamble or in the configuration file:
@@ -7276,12 +7353,81 @@ In order to reduce the risk of name clashes, \latex packages typically prefix th
\end{marglist}
-\section{Revision history}
+\section{Revision History}
This revision history is a list of changes relevant to users of this package. Changes of a more technical nature which do not affect the user interface or the behavior of the package are not included in the list. If an entry in the revision history states that a feature has been \emph{improved} or \emph{extended}, this indicates a modification which either does not affect the syntax and behavior of the package or is syntactically backwards compatible (such as the addition of an optional argument to an existing command). Entries stating that a feature has been \emph{modified}, \emph{renamed}, or \emph{removed} demand attention. They indicate a modification which may require changes to existing styles or documents in some, hopefully rare, cases. The numbers on the right indicate the relevant section of this manual.
\begin{changelog}
+\begin{release}{0.9d}{2010-09-03}
+\item Added workaround for \sty{hyperref} space factor issue
+\item Added workaround for \sty{xkeyval}'s flawed class option inheritance
+\item Added workaround for \sty{fancyvrb}'s flawed brute-force \cmd{VerbatimFootnotes}
+\item Removed option \kvopt{date}{none}\see{use:opt:pre}
+\item Removed option \kvopt{urldate}{none}\see{use:opt:pre}
+\item Removed option \kvopt{origdate}{none}\see{use:opt:pre}
+\item Removed option \kvopt{eventdate}{none}\see{use:opt:pre}
+\item Removed option \kvopt{alldates}{none}\see{use:opt:pre}
+\item Added option \kvopt{date}{iso8601}\see{use:opt:pre}
+\item Added option \kvopt{urldate}{iso8601}\see{use:opt:pre}
+\item Added option \kvopt{origdate}{iso8601}\see{use:opt:pre}
+\item Added option \kvopt{eventdate}{iso8601}\see{use:opt:pre}
+\item Added option \kvopt{alldates}{iso8601}\see{use:opt:pre}
+\end{release}
+
+\begin{release}{0.9c}{2010-08-29}
+\item Added field \bibfield{eprintclass}\see{bib:fld:dat}
+\item Added field alias \bibfield{archiveprefix}\see{bib:fld:als}
+\item Added field alias \bibfield{primaryclass}\see{bib:fld:als}
+\item Updated documentation\see{use:use:epr}
+\item Tweaked package option \kvopt{babel}{other*}\see{use:opt:pre}
+\item Updated support for Brazilian (translations by Mateus Araújo)\see{use:opt:pre}
+\item Fixed some bugs
+\end{release}
+
+\begin{release}{0.9b}{2010-08-04}
+
+\item New dependency on \sty{logreq} package\see{int:pre:req}
+\item Improved separator masking in literal lists\see{bib:use:and}
+\item Added citation style \texttt{authortitle-ticomp}\see{use:xbx:cbx}
+\item Added option \opt{citepages} to all \texttt{verbose} citation styles\see{use:xbx:cbx}
+\item Added support for prefixes to all \texttt{numeric} citation styles\see{use:xbx:cbx}
+\item Added support for prefixes to all \texttt{numeric} bibliography styles\see{use:xbx:bbx}
+\item Renamed package option \opt{defernums} to \opt{defernumbers}\see{use:opt:pre}
+\item Added option \opt{sortcase}\see{use:opt:pre}
+\item Added option \opt{dateabbrev}\see{use:opt:pre}
+\item Added option \kvopt{date}{none}\see{use:opt:pre}
+\item Added option \kvopt{urldate}{none}\see{use:opt:pre}
+\item Added option \kvopt{origdate}{none}\see{use:opt:pre}
+\item Added option \kvopt{eventdate}{none}\see{use:opt:pre}
+\item Added option \kvopt{alldates}{none}\see{use:opt:pre}
+\item Added option \opt{clearlang}\see{use:opt:pre}
+\item Added option \opt{prefixnumbers} to \cmd{printbibliography}\see{use:bib:bib}
+\item Added option \opt{resetnumbers} to \cmd{printbibliography}\see{use:bib:bib}
+\item Added option \opt{omitnumbers} to \cmd{printbibliography}\see{use:bib:bib}
+\item Added special field \bibfield{prefixnumber}\see{aut:bbx:fld}
+\item Added \cmd{DeclareRedundantLanguages}\see{aut:lng:cmd}
+\item Added support for handles (\acr{HDL}s)\see{use:use:epr}
+\item Extended \cmd{defbibfilter}\see{use:bib:flt}
+\item Added \cmd{nametitledelim}\see{use:fmt:fmt}
+\item Improved \cmd{newbibmacro}\see{aut:aux:msc}
+\item Improved \cmd{renewbibmacro}\see{aut:aux:msc}
+\item Added \cmd{biblstring}\see{aut:str}
+\item Added \cmd{bibsstring}\see{aut:str}
+\item Added \cmd{bibcplstring}\see{aut:str}
+\item Added \cmd{bibcpsstring}\see{aut:str}
+\item Added \cmd{bibuclstring}\see{aut:str}
+\item Added \cmd{bibucsstring}\see{aut:str}
+\item Added \cmd{biblclstring}\see{aut:str}
+\item Added \cmd{biblcsstring}\see{aut:str}
+\item Added \cmd{bibxlstring}\see{aut:str}
+\item Added \cmd{bibxsstring}\see{aut:str}
+\item Added \cmd{mkbibbold}\see{aut:fmt:ich}
+\item Modified and extended log messages\see{bib:cav:ide}
+\item Fixed some bugs
+
+\end{release}
+
\begin{release}{0.9a}{2010-03-19}
\item Modified citation style \texttt{numeric}\see{use:xbx:cbx}