summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/biblatex/doc/biblatex.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/biblatex/doc/biblatex.tex')
-rw-r--r--macros/latex/contrib/biblatex/doc/biblatex.tex727
1 files changed, 524 insertions, 203 deletions
diff --git a/macros/latex/contrib/biblatex/doc/biblatex.tex b/macros/latex/contrib/biblatex/doc/biblatex.tex
index 213fe87e71..e9111c5e89 100644
--- a/macros/latex/contrib/biblatex/doc/biblatex.tex
+++ b/macros/latex/contrib/biblatex/doc/biblatex.tex
@@ -55,8 +55,8 @@
\newcommand*{\biber}{\sty{biber}\xspace}
\newcommand*{\biblatex}{\sty{biblatex}\xspace}
\newcommand*{\biblatexml}{\sty{biblatexml}\xspace}
-\newcommand*{\biblatexhome}{http://sourceforge.net/projects/biblatex/}
-\newcommand*{\biblatexctan}{http://ctan.org/pkg/biblatex/}
+\newcommand*{\biblatexhome}{https://sourceforge.net/projects/biblatex/}
+\newcommand*{\biblatexctan}{https://ctan.org/pkg/biblatex/}
\titlepage{%
title={The \biblatex Package},
@@ -64,7 +64,7 @@
url={\biblatexhome},
author={Philip Kime, Moritz Wemheuer, Philipp Lehman},
email={},
- revision={3.14},
+ revision={3.15},
date={\today}}
\hypersetup{%
@@ -173,7 +173,7 @@
\section{Introduction}
\label{int}
-This document is a systematic reference manual for the \biblatex package. Look at the sample documents which come with \biblatex to get a first impression.\fnurl{\biblatexctan doc/examples}
+This document is a systematic reference manual for the \biblatex package. Look at the sample documents which come with \biblatex to get a first impression.\fnurl{https://ctan.org/tex-archive/macros/latex/contrib/biblatex/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]{About \biblatex}
@@ -183,12 +183,12 @@ This package provides advanced bibliographic facilities for use with \latex. The
\subsection{License}
-Copyright \textcopyright\ 2006--2012 Philipp Lehman, 2012--2017 Philip Kime, Audrey Boruvka, Joseph Wright, 2018-- Philip Kime and Moritz Wemheuer. Permission is granted to copy, distribute and\slash or modify this software under the terms of the \lppl, version~1.3.\fnurl{http://www.latex-project.org/lppl.txt}
+Copyright \textcopyright\ 2006--2012 Philipp Lehman, 2012--2017 Philip Kime, Audrey Boruvka, Joseph Wright, 2018-- Philip Kime and Moritz Wemheuer. Permission is granted to copy, distribute and\slash or modify this software under the terms of the \lppl, version~1.3.\fnurl{https://www.latex-project.org/lppl.txt}
\subsection{Feedback}
\label{int:feb}
-Please use the \biblatex project page on GitHub to report bugs and submit feature requests.\fnurl{http://github.com/plk/biblatex} Before making a feature request, please ensure that you have thoroughly studied this manual. If you do not want to report a bug or request a feature but are simply in need of assistance, you might want to consider posting your question on the \texttt{comp.text.tex} newsgroup or \tex-\latex Stack Exchange.\fnurl{http://tex.stackexchange.com/questions/tagged/biblatex}
+Please use the \biblatex project page on GitHub to report bugs and submit feature requests.\fnurl{https://github.com/plk/biblatex} Before making a feature request, please ensure that you have thoroughly studied this manual. If you do not want to report a bug or request a feature but are simply in need of assistance, you might want to consider posting your question on the \texttt{comp.text.tex} newsgroup or \tex-\latex Stack Exchange.\fnurl{https://tex.stackexchange.com/questions/tagged/biblatex}
\subsection{Acknowledgements}
@@ -216,14 +216,17 @@ Márton Marczell, Bence Ferdinandy (Hungarian);
Baldur Kristinsson (Icelandic);
Enrico Gregorio, Andrea Marchitelli (Italian);
Rihards Skuja (Latvian);
+Valdemaras Klumbys (Lithuanian);
Håkon Malmedal, Hans Fredrik Nordhaug (Norwegian);
Anastasia Kandulina, Yuriy Chernyshov (Polish);
José Carlos Santos (Portuguese);
Oleg Domanov (Russian);
+Andrej Radović (Serbian);
Martin Vrábel, Dávid Lupták (Slovak);
Tea Tušar, Bogdan Filipič (Slovene);
Ignacio Fernández Galván (Spanish);
Per Starbäck, Carl-Gustav Werner, Filip Åsblom (Swedish);
+Abdulkerim Gok (Turkish);
Sergiy M. Ponomarenko (Ukrainian).
\subsection{Prerequisites}
@@ -242,19 +245,21 @@ The resources listed in this section are strictly required for \biblatex to func
The \biblatex package requires \etex. \tex distributions have been providing \etex binaries for quite some time, the popular distributions use them by default these days. The \biblatex package checks if it is running under \etex. Simply try compiling your documents as you usually do, the chances are that it just works. If you get an error message, try compiling the document with \bin{elatex} instead of \bin{latex} or \bin{pdfelatex} instead of \bin{pdflatex}, respectively.
\item[\biber]
-\biber is the backend of \biblatex used to transfer data from source files to the \latex code. \biber comes with TeX Live and is also available from SourceForge.\fnurl{http://biblatex-biber.sourceforge.net/}. \biber uses the \texttt{btparse} C library for \bibtex format file parsing which aimed to be compatible with \bibtex's parsing rules but also aimed at correcting some of the common problems. For details, see the manual page for the Perl \texttt{Text::BibTeX} module\fnurl{http://search.cpan.org/~ambs/Text-BibTeX}.
+\biber is the backend of \biblatex used to transfer data from source files to the \latex code. \biber comes with TeX Live and is also available from SourceForge.\fnurl{https://biblatex-biber.sourceforge.net/}. \biber uses the \texttt{btparse} C library for \bibtex format file parsing which aimed to be compatible with \bibtex's parsing rules but also aimed at correcting some of the common problems. For details, see the manual page for the Perl \texttt{Text::BibTeX} module\fnurl{https://metacpan.org/release/Text-BibTeX}.
\item[etoolbox]
-This \latex package, which is loaded automatically, provides generic programming facilities required by \biblatex. It is available from \acr{CTAN}.\fnurl{http://ctan.org/pkg/etoolbox}
+This \latex package, which is loaded automatically, provides generic programming facilities required by \biblatex. It is available from \acr{CTAN}.\fnurl{https://ctan.org/pkg/etoolbox}
\item[kvoptions]
-This \latex package, which is also loaded automatically, is used for internal option handling. It is available with the \sty{oberdiek} package bundle from \acr{CTAN}.\fnurl{http://ctan.org/pkg/kvoptions}
+This \latex package, which is also loaded automatically, is used for internal option handling. It is available from \acr{CTAN}.\fnurl{https://ctan.org/pkg/kvoptions}
\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://ctan.org/pkg/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{https://ctan.org/pkg/logreq/}
\item[pdftexcmds]
-This \latex package, which is loaded automatically, implements \pdftex primitives for \luatex, it also offers a unified interface for these primitives across engines. It is available from \acr{CTAN}.\fnurl{http://ctan.org/pkg/pdftexcmds/}
+This \latex package, which is loaded automatically, implements \pdftex primitives for \luatex, it also offers a unified interface for these primitives across engines. It is available from \acr{CTAN}.\fnurl{https://ctan.org/pkg/pdftexcmds/}
+
+\biblatex uses \sty{pdftexcmds} to access the MD5 hash primitives, so version~0.27 (2018/01/30) or above is strongly recommended.
\end{marglist}
@@ -263,20 +268,31 @@ Apart from the above resources, \biblatex also requires the standard \latex pack
\subsubsection{Recommended Packages}
\label{int:pre:rec}
-The packages listed in this section are not required for \biblatex to function, but they provide recommended additional functions or enhance existing features. The package loading order usually does not matter.
+The packages listed in this section are not strictly required for \biblatex to function, but they provide recommended additional functions or enhance existing features.
\begin{marglist}
\item[babel/polyglossia]
The \sty{babel} and \sty{polyglossia} packages provides the core architecture for multilingual typesetting. If you are writing in a language other than American English, using one of these packages is strongly recommended. You should load \sty{babel} or \sty{polyglossia} before \biblatex and then \biblatex will detect \sty{babel} or \sty{polyglossia} automatically. (While \sty{babel} may be loaded after \biblatex if so desired, \sty{polyglossia} must always be loaded before \biblatex.)
-\biblatex has only limited support for \sty{polyglossia} versions prior to~v1.45. If \sty{polyglossia} is used, it should be updated to version~1.45 (2019/10/27) or above.
+\biblatex has only limited support for \sty{polyglossia} versions prior to~v1.45 (2019/10/27). Additional useful features for \biblatex were added in version~1.49. If \sty{polyglossia} is used, it should be updated to version~1.49 (2020/04/08) or above.
+
+The minimum supported \sty{babel} version is~v3.9r (2016/04/23).
\item[csquotes]
-If this package is available, \biblatex will use its language sensitive quotation facilities to enclose certain titles in quotation marks. If not, \biblatex uses quotes suitable for American English as a fallback. When writing in a language other than American English, loading \sty{csquotes} is strongly recommended.\fnurl{http://ctan.org/pkg/csquotes/}
+If this package is available, \biblatex will use its language sensitive quotation facilities to enclose certain titles in quotation marks. If not, \biblatex uses quotes suitable for American English as a fallback. When writing in a language other than American English, loading \sty{csquotes} is strongly recommended.\fnurl{https://ctan.org/pkg/csquotes/}
+
+\end{marglist}
+
+\subsubsection{Additional Useful Packages}
+\label{int:pre:add}
+
+The packages listed in this section are not required for \biblatex to function, but provide additional specialist functions or enhance existing features. These packages generally only need to be loaded if their functionality is explicitly desired. The package loading order usually does not matter.
+
+\begin{marglist}
\item[xpatch]
-The \sty{xpatch} package extends the patching commands of \sty{etoolbox} to \biblatex bibliography macros, drivers and formatting directives.\fnurl{http://ctan.org/pkg/xpatch/}
+The \sty{xpatch} package extends the patching commands of \sty{etoolbox} to \biblatex bibliography macros, drivers and formatting directives.\fnurl{https://ctan.org/pkg/xpatch/} Its commands are useful to apply surgical-precision changes to bibliography macros, drivers or formatting directives without having to restate the whole definition to change it. The \biblatex core does not need or use these patching commands and styles that make use of them should load the package themselves.
\end{marglist}
@@ -299,6 +315,8 @@ When using the \sty{memoir} class, the default bibliography headings are adapted
\item[\acr{KOMA}-Script]
When using any of the \sty{scrartcl}, \sty{scrbook}, or \sty{scrreprt} classes, the default bibliography headings are adapted such that they blend with the default layout of these classes. See \secref{use:cav:scr} for further usage hints.
+If available \biblatex makes use of some of the more recent of \acr{KOMA}-Script's \emph{do-hooks}. The relevant hooks are present from version~3.27 (2019/10/12) onwards, which is therefore the minimum version recommendation.
+
\end{marglist}
\subsubsection{Incompatible Packages}
@@ -354,7 +372,11 @@ The \sty{splitbib} package provides support for bibliographies subdivided by top
The \sty{titlesec} package redefines user-level document division commands such as \cmd{chapter} or \cmd{section}. This approach is not compatible with internal command changes applied by the \biblatex \opt{refsection}, \opt{refsegment} and \opt{citereset} option settings described in \secref{use:opt:pre:gen}.
\item[ucs]
-The \sty{ucs} package provides support for \utf encoded input. Either use \sty{inputenc}'s standard \file{utf8} module or a Unicode enabled engine such as \xetex or \luatex instead.
+The \sty{ucs} package provides support for \utf encoded input, but it does so in a way incompatible with \biblatex.
+
+If you get an error about \sty{ucs} being loaded, but you don't load it explicitly in your preamble, check that you don't load \sty{inputenc}'s \file{utf8x} module: \verb|\usepackage[utf8x]{inputenc}| will also load \sty{ucs}.
+
+Instead of \sty{ucs}/\file{utf8x} use a Unicode engine such as \xetex or \luatex if you want full Unicode support. If you use \pdftex or \tex, the Unicode characters predefined by the \latex format are usually enough for many use cases (this is true for \latex from April 2018 or later, in older versions load \sty{inputenc} with the \file{utf8} module) and missing characters can be defined using \cmd{DeclareUnicodeCharacter} or \sty{newunicodechar}'s \cmd{newunicodechar}.
\item[etextools]
The \sty{etextools} package provides enhancements to list macros defined by \sty{etoolbox} and a few other tools for command definitions.
@@ -376,12 +398,15 @@ during processing if it encounters information which comes from a
compatibility matrix for the recent versions.
\begin{table}
+\caption{\biber/\biblatex\ compatibility matrix}
+\label{tab:int:pre:bibercompat}
\tablesetup\centering
\begin{tabular}{cc}
\toprule
\sffamily\bfseries\spotcolor Biber version
& \sffamily\bfseries\spotcolor \biblatex\ version\\
\midrule
+2.14 & 3.14\\
2.13 & 3.13\\
2.12 & 3.12\\
2.11 & 3.11\\
@@ -418,8 +443,6 @@ compatibility matrix for the recent versions.
0.9 & 1.4x\\
\bottomrule
\end{tabular}
-\caption{\biber/\biblatex\ compatibility matrix}
-\label{tab:int:pre:bibercompat}
\end{table}
\section{Database Guide}
@@ -448,14 +471,14 @@ The <alias> relation referred to in this subsection is the <soft alias> defined
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, month, pages, version, note, issn, addendum, pubstate, doi, eprint, eprintclass, eprinttype, url, urldate}
+\optitem{translator, annotator, commentator, subtitle, titleaddon, editor, editora, editorb, editorc, journalsubtitle, journaltitleaddon, issuetitle, issuesubtitle, issuetitleaddon, language, origlanguage, series, volume, number, eid, issue, month, pages, version, note, issn, addendum, pubstate, doi, eprint, eprintclass, eprinttype, url, urldate}
\typeitem{book}
A single"=volume book with one or more authors where the authors share credit for the work as a whole. 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, eprintclass, 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, eid, chapter, pages, pagetotal, addendum, pubstate, doi, eprint, eprintclass, eprinttype, url, urldate}
\typeitem{mvbook}
@@ -469,7 +492,7 @@ A multi"=volume \bibtype{book}. For backwards compatibility, multi"=volume books
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, eprintclass, 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, eid, chapter, pages, addendum, pubstate, doi, eprint, eprintclass, eprinttype, url, urldate}
\typeitem{bookinbook}
@@ -484,14 +507,14 @@ 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, eprintclass, eprinttype, url, urldate}
+\optitem{subtitle, titleaddon, language, howpublished, type, note, location, eid, chapter, pages, pagetotal, addendum, pubstate, doi, eprint, eprintclass, eprinttype, url, urldate}
\typeitem{collection}
A single"=volume collection 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, eprintclass, 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, eid, chapter, pages, pagetotal, addendum, pubstate, doi, eprint, eprintclass, eprinttype, url, urldate}
\typeitem{mvcollection}
@@ -505,7 +528,7 @@ A multi"=volume \bibtype{collection}. For backwards compatibility, multi"=volume
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, title, booktitle, year/date}
-\optitem{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}
+\optitem{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, eid, chapter, pages, addendum, pubstate, doi, eprint, eprintclass, eprinttype, url, urldate}
\typeitem{suppcollection}
@@ -523,7 +546,7 @@ A data set or a similar collection of (mostly) raw data.
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, eprintclass, eprinttype, url, urldate}
+\optitem{subtitle, titleaddon, language, edition, type, series, number, version, note, organization, publisher, location, isbn, eid, chapter, pages, pagetotal, addendum, pubstate, doi, eprint, eprintclass, eprinttype, url, urldate}
\typeitem{misc}
@@ -551,7 +574,7 @@ A patent or patent request. The number or record token is given in the \bibfield
An complete 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, month, note, issn, addendum, pubstate, doi, eprint, eprintclass, eprinttype, url, urldate}
+\optitem{editora, editorb, editorc, subtitle, titleaddon, issuetitle, issuesubtitle, issuetitleaddon, language, series, volume, number, issue, month, note, issn, addendum, pubstate, doi, eprint, eprintclass, eprinttype, url, urldate}
\typeitem{suppperiodical}
@@ -562,7 +585,7 @@ Supplemental material in a \bibtype{periodical}. This type is similar to \bibtyp
A single"=volume conference proceedings. This type is very 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{title, year/date}
-\optitem{editor, subtitle, titleaddon, maintitle, mainsubtitle, maintitleaddon, eventtitle, eventtitleaddon, 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}
+\optitem{editor, subtitle, titleaddon, maintitle, mainsubtitle, maintitleaddon, eventtitle, eventtitleaddon, eventdate, venue, language, volume, part, volumes, series, number, note, organization, publisher, location, month, isbn, eid, chapter, pages, pagetotal, addendum, pubstate, doi, eprint, eprintclass, eprinttype, url, urldate}
\typeitem{mvproceedings}
@@ -576,7 +599,7 @@ A multi"=volume \bibtype{proceedings} entry. For backwards compatibility, multi"
An article in a conference proceedings. This type is similar to \bibtype{incollection}. It supports an optional \bibfield{organization} field.
\reqitem{author, title, booktitle, year/date}
-\optitem{editor, subtitle, titleaddon, maintitle, mainsubtitle, maintitleaddon, booksubtitle, booktitleaddon, eventtitle, eventtitleaddon, eventdate, venue, language, volume, part, volumes, series, number, note, organization, publisher, location, month, isbn, chapter, pages, addendum, pubstate, doi, eprint, eprintclass, eprinttype, url, urldate}
+\optitem{editor, subtitle, titleaddon, maintitle, mainsubtitle, maintitleaddon, booksubtitle, booktitleaddon, eventtitle, eventtitleaddon, eventdate, venue, language, volume, part, volumes, series, number, note, organization, publisher, location, month, isbn, eid, chapter, pages, addendum, pubstate, doi, eprint, eprintclass, eprinttype, url, urldate}
\typeitem{reference}
@@ -595,7 +618,7 @@ An article in a work of reference. This is a more specific variant of the generi
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, eprintclass, eprinttype, url, urldate}
+\optitem{subtitle, titleaddon, language, number, version, note, location, month, isrn, eid, chapter, pages, pagetotal, addendum, pubstate, doi, eprint, eprintclass, eprinttype, url, urldate}
\typeitem{set}
@@ -610,14 +633,14 @@ Computer software. The standard styles will treat this entry type as an alias fo
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, isbn, chapter, pages, pagetotal, addendum, pubstate, doi, eprint, eprintclass, eprinttype, url, urldate}
+\optitem{subtitle, titleaddon, language, note, location, month, isbn, eid, 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, type, eventtitle, eventtitleaddon, eventdate, venue, language, howpublished, note, location, isbn, month, addendum, pubstate, url, urldate}
+\optitem{subtitle, titleaddon, type, eventtitle, eventtitleaddon, eventdate, venue, language, howpublished, note, location, isbn, month, addendum, pubstate, doi, eprint, eprintclass, eprinttype, url, urldate}
\typeitem{xdata}
@@ -655,7 +678,7 @@ An alias for \bibtype{online}, provided for \sty{jurabib} compatibility.
\subsubsection{Non-standard Types}
\label{bib:typ:ctm}
-The types in this section are similar to the custom types \bibtype{custom[a--f]}, \ie the standard bibliography styles provide no bibliography drivers for these types. When using the standard styles, they will therefore generally be treated as \bibtype{misc} entries---exceptions to this rule are noted in the descriptions below. The types are known to the default data model and will be happily accepted by \biber.
+The types in this section are similar to the custom types \bibtype{custom[a--f]}, \ie the standard bibliography styles provide no bibliography drivers for these types. In the standard styles they will use the bibliography driver for \bibtype{misc} entries---exceptions to this rule are noted in the descriptions below. The types are known to the default data model and will be happily accepted by \biber.
\begin{typelist}
@@ -899,7 +922,7 @@ Similar to \bibfield{editortype} but referring to the \bibfield{editorc} field.
\fielditem{eid}{literal}
-The electronic identifier of an \bibtype{article}. This field may replace the \bibfield{pages} field for journals deviating from the classic pagination scheme of printed journals by only enumerating articles or papers and not pages.
+The electronic identifier of an \bibtype{article} or chapter-like section of a larger work. This field may replace the \bibfield{pages} field for journals deviating from the classic pagination scheme of printed journals by only enumerating articles or papers and not pages.
\fielditem{entrysubtype}{literal}
@@ -989,6 +1012,10 @@ The subtitle of a specific issue of a journal or other periodical.
The title of a specific issue of a journal or other periodical.
+\fielditem{issuetitleaddon}{literal}
+
+An annex to the \bibfield{issuetitle}, to be printed in a different font.
+
\fielditem{iswc}{literal}
The International Standard Work Code of a musical work. Not used by the standard bibliography styles.
@@ -1001,6 +1028,11 @@ The subtitle of a journal, a newspaper, or some other periodical.
The name of a journal, a newspaper, or some other periodical.
+\fielditem{journaltitleaddon}{literal}
+
+An annex to the \bibfield{journaltitle}, to be printed in a different font.
+
+
\fielditem{label}{literal}
A designation to be used by the citation style as a substitute for the regular label if any data required to generate the regular label is missing. For example, when an author"=year citation style is generating a citation for an entry which is missing the author or the year, it may fall back to \bibfield{label}. See \secref{bib:use:key} for details. Note that, in contrast to \bibfield{shorthand}, \bibfield{label} is only used as a fallback. See also \bibfield{shorthand}.
@@ -1210,6 +1242,8 @@ A special field which holds arbitrary \tex code to be executed whenever the data
The gender of the author or the gender of the editor, if there is no author. The following identifiers are supported: \opt{sf} (feminine singular, a single female name), \opt{sm} (masculine singular, a single male name), \opt{sn} (neuter singular, a single neuter name), \opt{pf} (feminine plural, a list of female names), \opt{pm} (masculine plural, a list of male names), \opt{pn} (neuter plural, a list of neuter names), \opt{pp} (plural, a mixed gender list of names). This information is only required by special bibliography and citation styles and only in certain languages. For example, a citation style may replace recurrent author names with a term such as <idem>. If the Latin word is used, as is custom in English and French, there is no need to specify the gender. In German publications, however, such key terms are usually given in German and in this case they are gender"=sensitive.
\begin{table}
+\caption{Supported Languages}
+\label{bib:fld:tab1}
\tablesetup
\begin{tabularx}{\textwidth}{@{}p{90pt}@{}p{160pt}@{}X@{}}
\toprule
@@ -1242,21 +1276,23 @@ Hungarian & Hungary & \opt{magyar}, \opt{hungarian} \\
Icelandic & Iceland & \opt{icelandic} \\
Italian & Italy & \opt{italian} \\
Latvian & Latvia & \opt{latvian} \\
+Lithuanian & Lithuania & \opt{lithuanian} \\
Norwegian (Bokmål) & Norway & \opt{norsk} \\
Norwegian (Nynorsk) & Norway & \opt{nynorsk} \\
Polish & Poland & \opt{polish} \\
Portuguese & Brazil & \opt{brazil} \\
& Portugal & \opt{portuguese}, \opt{portuges} \\
Russian & Russia & \opt{russian} \\
+Serbian (Latin) & Serbia & \opt{serbian} \\
+Serbian (Cyrillic) & Serbia & \opt{serbianc} \\
Slovak & Slovakia & \opt{slovak} \\
Slovene & Slovenia & \opt{slovene}, \opt{slovenian} \\
Spanish & Spain & \opt{spanish} \\
Swedish & Sweden & \opt{swedish} \\
+Turkish & Turkey & \opt{turkish} \\
Ukrainian & Ukraine & \opt{ukrainian} \\
\bottomrule
\end{tabularx}
-\caption{Supported Languages}
-\label{bib:fld:tab1}
\end{table}
\fielditem{langid}{identifier}
@@ -1675,6 +1711,8 @@ This entry will be printed as «\emph{Journal Name}. New ser. 9 (1998)». See \s
\label{bib:use:dat}
\begin{table}
+\caption{Date Specifications}
+\label{bib:use:tab1}
\tablesetup
\begin{tabularx}{\textwidth}{@{}>{\ttfamily}llX@{}}
\toprule
@@ -1698,8 +1736,6 @@ This entry will be printed as «\emph{Journal Name}. New ser. 9 (1998)». See \s
2004-04-05T14:34:00 & 05/04/2004 2:34 PM & 5th April 2004 14:34:00\\
\bottomrule
\end{tabularx}
-\caption{Date Specifications}
-\label{bib:use:tab1}
\end{table}
Date fields such as the default data model dates \bibfield{date}, \bibfield{origdate}, \bibfield{eventdate}, and \bibfield{urldate} adhere to \acr{ISO8601-2} Extended Format specification level 1. In addition to the \acr{ISO8601-2} empty date range markers, you may also specify an open ended/start date range by giving the range separator and omitting the end/start date (\eg \texttt{YYYY/}, \texttt{/YYYY}). See \tabref{bib:use:tab1} for some examples of valid date specifications and the formatted dates automatically generated by \biblatex. The formatted date is language specific and will be adapted automatically. If there is no \bibfield{date} field in an entry, \biblatex will also consider the fields \bibfield{year} and \bibfield{month} for backwards compatibility with traditional \bibtex but this is not encouraged as explicit \bibfield{year} and \bibfield{month} are not parsed for date meta-information markers or times and are used as-is. Style authors 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 and time 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.
@@ -1711,6 +1747,8 @@ Date field names \emph{must} end with the string <date>, as with the default dat
\acr{ISO8601-2} supports dates before common era (BCE/BC) by way of a negative date format and supports <approximate> (circa) and uncertain dates. Such date formats set internal markers which can be tested for so that appropriate localised markers (such as \opt{circa} or \opt{beforecommonera}) can be inserted. Also supported are <unspecified> dates (\acr{ISO8601-2} 4.3) which are automatically expanded into appropriate data ranges accompanied by a field \bibfield{$<$datetype$>$dateunspecified} which details the granularity of the unspecified data. Styles may use this information to format such dates appropriately but the standard styles do not do this. See \tabref{bib:use:tab3} on page~\pageref{bib:use:tab3} for the allowed \acr{ISO8601-2} <unspecified> formats, their range expansions and \bibfield{$<$datetype$>$dateunspecified} values (see \secref{aut:bbx:fld:gen}).
\begin{table}
+\caption{ISO8601-2 4.3 Unspecified Date Parsing}
+\label{bib:use:tab3}
\tablesetup
\begin{tabularx}{\textwidth}{@{}>{\ttfamily}llX@{}}
\toprule
@@ -1725,15 +1763,15 @@ Date field names \emph{must} end with the string <date>, as with the default dat
1999-XX-XX & 1999-01-01/1999-12-31 & dayinyear \\
\bottomrule
\end{tabularx}
-\caption{ISO8601-2 4.3 Unspecified Date Parsing}
-\label{bib:use:tab3}
\end{table}
-\tabref{bib:use:tab2} shows formats which use appropriate tests and formatting. See the date meta-information tests in \secref{aut:aux:tst} and the localisation strings in \secref{aut:lng:key:dt}. See also the \file{96-dates.tex} example file for complete examples of the tests and localisation strings use.
+\Tabref{bib:use:tab2} shows formats which use appropriate tests and formatting. See the date meta-information tests in \secref{aut:aux:tst} and the localisation strings in \secref{aut:lng:key:dt}. See also the \file{96-dates.tex} example file for complete examples of the tests and localisation strings use.
The output of <circa>, uncertainty and era information in standard styles (or custom styles not customising the internal \cmd{mkdaterange*} macros) is controlled by the package options \opt{datecirca}, \opt{dateuncertain}, \opt{dateera} and \opt{dateeraauto} (see \secref{use:opt:pre:gen}). See \tabref{bib:use:tab2} on page~\pageref{bib:use:tab2} for examples which assumes these options are all used.
\begin{table}
+\caption{Enhanced Date Specifications}
+\label{bib:use:tab2}
\tablesetup
\begin{tabularx}{\textwidth}{@{}>{\ttfamily}llX@{}}
\toprule
@@ -1758,8 +1796,6 @@ The output of <circa>, uncertainty and era information in standard styles (or cu
2004-24 & 2004 & also, \bibfield{season} is set to the localisation string <winter>\\
\bottomrule
\end{tabularx}
-\caption{Enhanced Date Specifications}
-\label{bib:use:tab2}
\end{table}
\subsubsection{Year, Month and Date}
@@ -1846,7 +1882,7 @@ In addition to the \bibfield{crossref} field, \biblatex supports a simplified cr
\subsubsection{Sorting and Encoding Issues}
\label{bib:cav:enc}
-\biber handles Ascii, 8-bit encodings such as Latin\,1, and \utf. It features true Unicode support and is capable of reencoding the \file{bib} data on the fly in a robust way. For sorting, \biber uses a Perl implementation of the Unicode Collation Algorithm (\acr{UCA}), as outlined in Unicode Technical Standard \#10.\fnurl{http://unicode.org/reports/tr10/} Collation tailoring based on the Unicode Common Locale Data Repository (\acr{CLDR}) is also supported.\fnurl{http://cldr.unicode.org/}
+\biber handles Ascii, 8-bit encodings such as Latin\,1, and \utf. It features true Unicode support and is capable of reencoding the \file{bib} data on the fly in a robust way. For sorting, \biber uses a Perl implementation of the Unicode Collation Algorithm (\acr{UCA}), as outlined in Unicode Technical Standard \#10.\fnurl{https://unicode.org/reports/tr10/} Collation tailoring based on the Unicode Common Locale Data Repository (\acr{CLDR}) is also supported.\fnurl{http://cldr.unicode.org/}
Supporting Unicode implies much more than handling \utf input. Unicode is a complex standard covering more than its most well-known parts, the Unicode character encoding and transport encodings such as \utf. It also standardizes aspects such as string collation, which is required for language-sensitive sorting. For example, by using the Unicode Collation Algorithm, \biber can handle the character <ß> without any manual intervention. All you need to do to get localised sorting is specify the locale:
@@ -2037,6 +2073,10 @@ Loads compatibility module which provides aliases for the citation commands of t
Loads a citation module which provides \sty{mcite}\slash\sty{mciteplus}-like citation commands. See \secref{use:cit:mct} for details.
+\optitem[auto]{casechanger}{\opt{auto}, \opt{latex2e}, \opt{expl3}}
+
+This option selects the implementation of \biblatex's case changing functions, most prominently \cmd{MakeSentenceCase*}. \opt{expl3} selects the new implementation based on the \latex3 module \sty{l3text}. \opt{latex2e} selects the original implementation, which has tricky brace protection behaviour and some shortcomings when dealing with non-ASCII characters. The default \opt{auto} selects the case changing code based on the available \sty{expl3} version (\opt{expl3} is selected if \sty{expl3} is at least version 2020-04-06).
+
\end{optionlist}
\subsubsection{Preamble Options}
@@ -2162,13 +2202,17 @@ 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}/\sty{polyglossia} and \biblatex provide for the respective language, and translate key terms such as <editor> and <volume>. The extra definitions include localisations of the date format, of ordinals, and similar things.
\item[other*]
-Enclose the entry in an \env{otherlanguage*} environment. Please note that \biblatex treats \env{otherlanguage*} like \env{otherlanguage} but other packages may make a distinction in this case.
+Enclose the entry in an \env{otherlanguage*} environment. Please note that \biblatex treats \env{otherlanguage*} like \env{otherlanguage} if \opt{langhook} is set to \opt{extras}.
\item[langname]
\sty{polyglossia} only. Enclose the entry in a \env{$<$languagename$>$} environment. The benefit of this option value for \sty{polyglossia} users is that it takes note of the \bibfield{langidopts} field so that you can add per-language options to an entry (like selecting a language variant). When using \sty{babel}, this option does the same as the \opt{other} option value.
\end{valuelist}
+\optitem[captions]{langhook}{\opt{captions}, \opt{extras}}
+
+This option controls whether bibliography strings and extras are written to \cmd{captions$<$language$>$} or \cmd{extras$<$language$>$}. The exact effect of this option depend on the language package (\sty{babel}/\sty{polyglossia}). Broadly speaking, the language switching environments provided by those packages (except \env{hyphenrules}) either switch language captions and extras or only language extras. Hence, if this option is set to \opt{extras}, all language switches will affect \biblatex, whereas with \opt{captions} only language switches that also switch other parts of the document language affect \biblatex.
+
\optitem[none]{block}{\opt{none}, \opt{space}, \opt{par}, \opt{nbpar}, \opt{ragged}}
This option controls the extra spacing between blocks, \ie larger segments of a bibliography entry. The possible choices are:
@@ -2253,6 +2297,11 @@ This option controls how back references to \bibtype{set} entries and their memb
\end{valuelist}
+\boolitem[true]{backreffloats}
+
+Whether to enable back references to citations in floats.
+
+
\optitem[false]{indexing}{\opt{true}, \opt{false}, \opt{cite}, \opt{bib}}
This option controls indexing in citations and in the bibliography. More precisely, it affects the \cmd{ifciteindex} and \cmd{ifbibindex} commands from \secref{aut:aux:tst}. The option is settable on a global, a per-type, or on a per-entry basis. The possible choices are:
@@ -2341,7 +2390,7 @@ January 21--30, 2010\par
2010-1-21/2010-1-30
\end{valuelist}
%
-Note that \opt{iso} format will enforce \kvopt{dateera}{astronomical}, \kvopt{datezeros}{true}, \kvopt{timezeros}{true}, \kvopt{seconds}{true}, \kvopt{$<$datetype$>$time}{24h} and \kvopt{julian}{false}. \opt{ymd} is an ETFT-like format but which can change the various options which the strict \opt{iso} option does not allow for.
+Note that \opt{iso} format will enforce \kvopt{dateera}{astronomical}, \kvopt{datezeros}{true}, \kvopt{timezeros}{true}, \kvopt{seconds}{true}, \kvopt{$<$datetype$>$time}{24h} and \kvopt{julian}{false}. \opt{ymd} is an EDTF-like format but which can change the various options which the strict \opt{iso} option does not allow for.
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 for months and days in all short formats may be controlled separately with the \opt{datezeros} package option. The leading zeros for hours, minutes and seconds in all short formats may be controlled separately with the \opt{timezeros} package option. If outputting times, the printing of seconds and timezones is controlled by the \opt{seconds} and \opt{timezones} options respectively.
@@ -2440,7 +2489,7 @@ Sets \opt{labeltime} and the \opt{$<$datetype$>$time} option for all times in th
\boolitem[false]{dateusetime}
-Specifies whether to print any time component of a date field after the date component. The separator between the date and time components is \cmd{bibdatetimesep} from \secref{use:fmt:lng}. This option does nothing if a compact date format is being used (see \secref{use:opt:pre:gen}) as this would be very confusing.
+Specifies whether to print any time component of a date field after the date component. The separator between the date and time components is \cmd{bibdatetimesep} from \secref{use:fmt:lng}.
\boolitem[false]{labeldateusetime}
@@ -2519,6 +2568,10 @@ Sets the minimum number of cross references to \prm{integer} when requesting a b
As \opt{mincrossrefs} but for \bibfield{xref} fields.
+\boolitem[true]{bibtexcaseprotection}
+
+This option only has an effect when the \sty{expl3} implementation of the case changing functions is selected. If the option is set to \opt{true}, \cmd{MakeSentenceCase*} supports brace protection of words from case change as in classical \bibtex. If the option is set to \opt{false}, pairs of braces no longer imply case protection, which can now be enforced by wrapping the relevant word in \cmd{NoCaseChange}---this makes for a less confusing, if more verbose, markup of case protection.
+
\end{optionlist}
\paragraph{Style-specific}
@@ -2562,6 +2615,20 @@ Suppose \texttt{key1} and \texttt{key2} are members of the set \texttt{set1}. Wi
\end{optionlist}
+\subparagraph{\texttt{numeric-comp}} The citation style \texttt{numeric-comp} supports the \opt{subentrycomp} option in global, per-type and per-entry scope.
+
+\begin{optionlist}
+
+\boolitem[true]{subentrycomp}
+
+This option determines whether or not citations to set members are compressed similar to non-set citations. The option only has an effect if \opt{subentry} is set to \texttt{true}.
+
+Suppose \texttt{key1}, \texttt{key2} and \texttt{key3} are members of the set \texttt{set1}. With \opt{subentrycomp} set to \texttt{true} the three entries will be compressed to <[1a--c]> in citations. With \opt{subentry} set to \texttt{false} the citation will show in the more verbose form <[1a, 1b, 1c]>.
+
+The option is intended mainly for backwards compatibility, because earlier versions of \biblatex did not compress set member citations.
+
+\end{optionlist}
+
\subparagraph{\texttt{authortitle}/\texttt{authoryear}} All bibliography styles of the \texttt{authoryear} and \texttt{authortitle} family as well as all bibliography styles of the \texttt{verbose} family---whose bibliography styles are based on \texttt{authortitle}---support the option \opt{dashed} in global scope.
\begin{optionlist}
@@ -2592,7 +2659,7 @@ This option controls whether and how the date specification in the entry is merg
More in-depth examples of this option can be found in the style examples.
\end{optionlist}
-\subparagraph{<ibid> styles} Citation styles with <ibid.> function, namely \texttt{authortitle-ibid}, \texttt{author\allowbreakhere title-icomp}, \texttt{author\allowbreakhere year-ibid}, \texttt{authoryear-icomp}, \texttt{ver\allowbreakhere bose-ibid}, \texttt{verbose-inote}, \texttt{verbose-trad1}, \texttt{verbose-trad2} and \texttt{verbose-trad3} provide the global \opt{ibidpage} option.
+\subparagraph{<ibid> styles} Citation styles with <ibid.>\ function, namely \texttt{authortitle-ibid}, \texttt{author\allowbreakhere title-icomp}, \texttt{author\allowbreakhere year-ibid}, \texttt{authoryear-icomp}, \texttt{ver\allowbreakhere bose-ibid}, \texttt{verbose-inote}, \texttt{verbose-trad1}, \texttt{verbose-trad2} and \texttt{verbose-trad3} provide the global \opt{ibidpage} option.
\begin{optionlist}
@@ -2656,7 +2723,7 @@ This option controls the page tracker which is required by the \cmd{ifsamepage}
\item[spread] Enable the tracker in spread mode. In this mode, tracking works on a per"=spread (double page) basis.
\end{valuelist}
-Note that this tracker is disabled in all floats, see \secref{aut:cav:flt}.
+Note that this tracker is disabled in all floats unless explicitly requested with \opt{trackfloats}, see \secref{aut:cav:flt}.
\optitem[false]{citecounter}{\opt{true}, \opt{false}, \opt{context}}
@@ -2680,7 +2747,7 @@ This option controls the citation tracker which is required by the \cmd{ifcitese
\item[constrict] This mode combines the features of \opt{context} and \opt{strict}.
\end{valuelist}
-Note that this tracker is disabled in all floats, see \secref{aut:cav:flt}.
+Note that this tracker is disabled in all floats unless explicitly requested with \opt{trackfloats}, see \secref{aut:cav:flt}.
This option is also settable on a per-type or per-entry basis.
\optitem[false]{ibidtracker}{\opt{true}, \opt{false}, \opt{context}, \opt{strict}, \opt{constrict}}
@@ -2695,7 +2762,7 @@ This option controls the <ibidem> tracker which is required by the \cmd{ifciteib
\item[constrict] This mode combines the features of \opt{context} and \opt{strict}. It also keeps track of footnote numbers and detects potentially ambiguous references in footnotes in a stricter way than the \opt{strict} option. In addition to the conditions imposed by the \opt{strict} option, a reference in a footnote will only be considered as unambiguous if the current citation and the previous citation are given in the same footnote or in immediately consecutive footnotes.
\end{valuelist}
-Note that this tracker is disabled in all floats, see \secref{aut:cav:flt}.
+Note that this tracker is disabled in all floats unless explicitly requested with \opt{trackfloats}, see \secref{aut:cav:flt}.
This option is also settable on a per-type or per-entry basis.
\optitem[false]{opcittracker}{\opt{true}, \opt{false}, \opt{context}, \opt{strict}, \opt{constrict}}
@@ -2710,7 +2777,7 @@ This option controls the <opcit> tracker which is required by the \cmd{ifopcit}
\item[constrict] This mode combines the features of \opt{context} and \opt{strict}. See the explanation of \kvopt{ibidtracker}{constrict} for details.
\end{valuelist}
-Note that this tracker is disabled in all floats, see \secref{aut:cav:flt}.
+Note that this tracker is disabled in all floats unless explicitly requested with \opt{trackfloats}, see \secref{aut:cav:flt}.
This option is also settable on a per-type or per-entry basis.
\optitem[false]{loccittracker}{\opt{true}, \opt{false}, \opt{context}, \opt{strict}, \opt{constrict}}
@@ -2725,7 +2792,7 @@ This option controls the <loccit> tracker which is required by the \cmd{ifloccit
\item[constrict] This mode combines the features of \opt{context} and \opt{strict}. See the explanation of \kvopt{ibidtracker}{constrict} for details. In addition to that, this mode also checks if the \prm{postnote} argument is numerical (based on \cmd{ifnumerals} from \secref{aut:aux:tst}).
\end{valuelist}
-Note that this tracker is disabled in all floats, see \secref{aut:cav:flt}.
+Note that this tracker is disabled in all floats unless explicitly requested with \opt{trackfloats}, see \secref{aut:cav:flt}.
This option is also settable on a per-type or per-entry basis.
\optitem[false]{idemtracker}{\opt{true}, \opt{false}, \opt{context}, \opt{strict}, \opt{constrict}}
@@ -2740,9 +2807,13 @@ This option controls the <idem> tracker which is required by the \cmd{ifciteidem
\item[constrict] This mode is similar to \opt{context} with one additional condition: a reference in a footnote will only be considered as unambiguous if the current citation and the previous citation are given in the same footnote or in immediately consecutive footnotes.
\end{valuelist}
-Note that this tracker is disabled in all floats, see \secref{aut:cav:flt}.
+Note that this tracker is disabled in all floats unless explicitly requested with \opt{trackfloats}, see \secref{aut:cav:flt}.
This option is also settable on a per-type or per-entry basis.
+\boolitem[false]{trackfloats}
+
+Whether to enable citation tracking in floats. Citation tracking in floats can be tricky, so this option should only be enabled if absolutely necessary and the output should be scrutinised carefully, see also \secref{aut:cav:flt}.
+
\boolitem[true]{parentracker}
This option controls the parenthesis tracker which keeps track of nested parentheses and brackets. This information is used by \cmd{parentext} and \cmd{brackettext} from \secref{use:cit:txt}, \cmd{mkbibparens} and \cmd{mkbibbrackets} from \secref{aut:fmt:ich} and \cmd{bibopenparen}, \cmd{bibcloseparen}, \cmd{bibopenbracket}, \cmd{bibclosebracket} (also \secref{aut:fmt:ich}).
@@ -2803,6 +2874,8 @@ Whether or not to provide the special fields \bibfield{labelyear}, \bibfield{lab
This option is also settable on a per-type and per-entry basis. Table \ref{use:opt:tab1} summarises the various \opt{extra*} disambiguation counters and what they track.
\begin{table}
+\caption{Work Uniqueness options}
+\label{use:opt:wu}
\footnotesize
\ttfamily
\tablesetup
@@ -2818,8 +2891,6 @@ uniquebaretitle & \cmd{ifuniquebaretitle} & labeltitle {\rmfamily when} labelnam
uniquework & \cmd{ifuniquework} & labelname+labeltitle\\
\bottomrule
\end{tabularx}
-\caption{Work Uniqueness options}
-\label{use:opt:wu}
\end{table}
\boolitem[false]{singletitle}
@@ -2892,27 +2963,22 @@ With \kvopt{maxnames}{3}, \kvopt{minnames}{1}, \kvopt{nohashothers}{false}, the
\begin{lstlisting}{}
Jones 1972
- Jones et al 1972
+ Jones et al. 1972
Smith 2000
- Smith et al 2000
+ Smith et al. 2000
\end{lstlisting}
%
Whereas with \kvopt{maxnames}{3}, \kvopt{minnames}{1}, \kvopt{nohashothers}{true}, the result would be:
\begin{lstlisting}{}
Jones 1972a
- Jones et al 1972b
+ Jones et al. 1972b
Smith 2000a
- Smith et al 2000b
+ Smith et al. 2000b
\end{lstlisting}
-If desired, this could be further simplified with:
-
-\begin{ltxexample}
- \DefineBibliographyStrings{english}{andothers={}}
-\end{ltxexample}
-%
-To obtain:
+If desired, this could be further simplified by removing the <et al.\@>
+to obtain:
\begin{lstlisting}{}
Jones 1972a
@@ -2940,6 +3006,8 @@ This option is also settable on a per-type, per-entry and per-namelist basis.
\end{optionlist}
\begin{table}
+\caption{Disambiguation counters}
+\label{use:opt:tab1}
\footnotesize
\ttfamily
\tablesetup
@@ -2972,8 +3040,6 @@ labeltitleyear & {\rmfamily ---} & extratitleyear & labeltitle+labelyear\\
{\rmfamily ---} & {\rmfamily ---} & extraname & labelname\\
\bottomrule
\end{tabularx}
-\caption{Disambiguation counters}
-\label{use:opt:tab1}
\end{table}
\subsubsection{Entry Options}
@@ -3121,7 +3187,7 @@ The citation styles which come with this package implement several common citati
This style implements a numeric citation scheme similar to the standard bibliographic facilities of \latex. It should be employed in conjunction with a numeric bibliography style which prints the corresponding labels in the bibliography. It is intended for in-text citations. The style will set the following package options at load time: \kvopt{autocite}{inline}, \kvopt{labelnumber}{true}. This style also provides an additional preamble option called \opt{subentry} which affects the handling of entry sets. If this option is disabled, citations referring to a member of a set will point to the entire set. If it is enabled, the style supports citations like «[5c]» which point to a subentry in a set (the third one in this example). See the style example for details.
\item[numeric-comp]\seestyleexample{31-style-numeric-comp-biber}
-A compact variant of the \texttt{numeric} style which prints a list of more than two consecutive numbers as a range. This style is similar to the \sty{cite} package and the \opt{sort\&compress} option of the \sty{natbib} package in numerical mode. For example, instead of «[8, 3, 1, 7, 2]» this style would print «[1--3, 7, 8]». It is intended for in-text citations. The style will set the following package options at load time: \kvopt{autocite}{inline}, \kvopt{sortcites}{true}, \kvopt{labelnumber}{true}. It also provides the \opt{subentry} option.
+A compact variant of the \texttt{numeric} style which prints a list of more than two consecutive numbers as a range. This style is similar to the \sty{cite} package and the \opt{sort\&compress} option of the \sty{natbib} package in numerical mode. For example, instead of «[8, 3, 1, 7, 2]» this style would print «[1--3, 7, 8]». It is intended for in-text citations. The style will set the following package options at load time: \kvopt{autocite}{inline}, \kvopt{sortcites}{true}, \kvopt{labelnumber}{true}. It also provides the \opt{subentry} and \opt{subentrycomp} options.
\item[numeric-verb]\seestyleexample{32-style-numeric-verb-biber}
A verbose variant of the \texttt{numeric} style. The difference affects the handling of a list of citations and is only apparent when multiple entry keys are passed to a single citation command. For example, instead of «[2, 5, 6]» this style would print «[2]; [5]; [6]». It is intended for in-text citations. The style will set the following package options at load time: \kvopt{autocite}{inline}, \kvopt{labelnumber}{true}. It also provides the \opt{subentry} option.
@@ -3311,7 +3377,7 @@ Multiple relations to the same entry are also possible:
}
\end{lstlisting}
%
-Note the the order of the keys in lists of multiple related entries is important. The data from multiple related entries is printed in the order of the keys listed in this field. See \secref{aut:ctm:rel} for a more details on the mechanisms behind this feature. You can turn this feature off using the package option \opt{related} from \secref{use:opt:pre:gen}.
+Note the order of the keys in lists of multiple related entries is important. The data from multiple related entries is printed in the order of the keys listed in this field. See \secref{aut:ctm:rel} for a more details on the mechanisms behind this feature. You can turn this feature off using the package option \opt{related} from \secref{use:opt:pre:gen}.
You can use the \bibfield{relatedoptions} to set options on the related entry data clone. This is useful if you need to override the \opt{dataonly} option which is set by default on all related entry clones. For example, if you will expose some of the names in the related clone in your document, you may want to have them disambiguated from names in other entries but normally this won't happen as related clones have the per"=entry \opt{dataonly} option set and this in turn sets \kvopt{uniquename}{false} and \kvopt{uniquelist}{false}. In such a case, you can set \bibfield{relatedoptions} to just \opt{skiplab, skipbib, skipbiblist}.
@@ -3546,9 +3612,9 @@ Adds a \prm{resource}, such as a \file{.bib} file, to the default resource list.
\begin{ltxexample}
\addbibresource{bibfile1.bib}
\addbibresource{bibfile2.bib}
-\addbibresource{bibfiles/bibfile*.bib}
-\addbibresource{bibfile-num?.bib}
-\addbibresource{bibfile{1,2,3}.bib}
+\addbibresource[glob]{bibfiles/bibfile*.bib}
+\addbibresource[glob]{bibfile-num?.bib}
+\addbibresource[glob]{bibfile{1,2,3}.bib}
\addbibresource[location=remote]{http://www.citeulike.org/bibtex/group/9517}
\addbibresource[location=remote,label=lan]{ftp://192.168.1.57/~user/file.bib}
\end{ltxexample}
@@ -3567,7 +3633,7 @@ Assigns a label to a resource. The \prm{identifier} may be used in place of the
\valitem[local]{location}{location}
-The location of the resource. The \prm{location} may be either \texttt{local} for local resources or \texttt{remote} for \acr{URL}s. Remote resources require \biber. The protocols \acr{HTTP} and \acr{FTP} are supported. The remote \acr{URL} must be a fully qualified path to a \file{bib} file or a \acr{URL} which returns a \file{bib} file.
+The location of the resource. The \prm{location} may be either \texttt{local} for local resources or \texttt{remote} for \acr{URL}s. Remote resources require \biber. The protocols \acr{HTTP/HTTPS} and \acr{FTP} are supported. The remote \acr{URL} must be a fully qualified path to a \file{bib} file or a \acr{URL} which returns a \file{bib} file.
\valitem[file]{type}{type}
@@ -3585,6 +3651,13 @@ The data type (format) of the resource. The following formats are currently supp
\end{valuelist}
+\boolitem{glob}
+
+Whether \biber should glob (expand according to pattern) the datasource name. There is
+a global setting for this in \biber (false by default and settable to true
+using the \opt{--glob-datasources} option). This option allows overriding
+the \biber default on a per-resource basis.
+
\end{optionlist*}
\cmditem{addglobalbib}[options]{resource}
@@ -3622,6 +3695,10 @@ The bibliography and the list of shorthands typically have a chapter or section
This option overrides the default title provided by the heading selected with the \opt{heading} option, if supported by the heading definition. See \secref{use:bib:hdg} for details.
+\optitem[\normalfont\emph{global setting} (\opt{none})]{block}{\opt{none}, \opt{space}, \opt{par}, \opt{nbpar}, \opt{ragged}}
+
+This option overrides the global \opt{block} option (see \secref{use:opt:pre:gen}, the meaning of the settings is explained there as well).
+
\valitem{prenote}{name}
The prenote is an arbitrary piece of text to be printed after the heading but before the list of references. This option selects the prenote \prm{name}, as defined with \cmd{defbibnote}. By default, no prenote is printed. The note is printed in the standard text font. It is not affected by \cmd{bibsetup} and \cmd{bibfont} but it may contain its own font declarations. See \secref{use:bib:nts} for details.
@@ -3710,7 +3787,7 @@ This command loops over all bibliography categories. This is equivalent to givin
This command prints a bibliography heading defined with \cmd{defbibheading}. It takes one optional argument, which is a list of options given in \keyval notation. The options are a small subset of those supported by \cmd{printbibliography}. Valid options are \opt{heading} and \opt{title}. By default, this command uses the heading \texttt{bibliography}. See \secref{use:bib:hdg} for details. Also see \secref{use:use:mlt,use:use:div} for usage examples.
-\cmditem{DeclarePrintbibliographyDefaults}[key=value, \dots]
+\cmditem{DeclarePrintbibliographyDefaults}{key=value, \dots}
This command can be used to globally set defaults for some options to \cmd{printbibliography}, the \cmd{bibby...} bibliography commands and \cmd{printbibheading}.
The supported keys are
@@ -3816,15 +3893,17 @@ Naturally all defaults can be overridden by options to \cmd{printbiblist} and de
Bibliography lists are often used to print lists of various kinds of shorthands and this can result in duplicate entries if more than one bibliography entry has the same shorthand. For example, several journal articles in the same journal would result in duplicate entries in a list of journal shorthands. You can use the fact that such lists automatically pick up a \cmd{bibcheck} with the same name as the list to define a check to remove duplicates. If you are defining a list to print all of the journal shorthands using the \bibfield{shortjournal} field, you could define a \cmd{bibcheck} like this:
-\begin{ltxexample}
+\begin{ltxexample}[basicstyle=\displayverbfont\footnotesize]
\defbibcheck{shortjournal}{%
\iffieldundef{shortjournal}
{\skipentry}
{\iffieldundef{journaltitle}
{\skipentry}
- {\ifcsdef{\strfield{shortjournal}=\strfield{journaltitle}}
+ {\ifcsdef{sjcheck@\therefsection
+ -\strfield{shortjournal}=\strfield{journaltitle}}
{\skipentry}
- {\savefieldcs{journaltitle}{\strfield{shortjournal}=\strfield{journaltitle}}}}}}
+ {\savefieldcs{journaltitle}{sjcheck@\therefsection
+ -\strfield{shortjournal}=\strfield{journaltitle}}}}}}
\end{ltxexample}
\subsubsection{Bibliography Sections}
@@ -4250,7 +4329,7 @@ At the beginning of the document, there is always a global context containing gl
\cmditem{assignrefcontextentries*}[key=value, \dots]{*}
\end{ltxsyntax}
-These commands automate putting citations into refcontexts when the default behaviour is not sufficient. The \prm{key=value} options are as for \cmd{DeclareRefcontext}. The default behaviour is that the data for a citation is drawn from the refcontext of the most recently processed bibliography in which it was printed\footnote{This does not always mean what one might think. In a document containing multiple bibliographies, the last bibliography will be the context for any citations \emph{before} the first bibliography because all bibliographies are processed when the \file{.bbl}is read.}. For citations that are used in some way but not printed in a bibliography or bibliography list, they default to drawing their data from the global refcontext established at the beginning of the document. To override this behaviour, instead of manually wrapping citation commands in \env{refcontext} environments, which might be error-prone and tedious, you can register a comma"=separated list of \prm{keywords}, \prm{categories} or \prm{entrykeys} which, respectively, make the entries with any of the specified keywords, entries in any of the specified categories (see \secref{use:use:div}) or entries with any of the specified citation keys draw their data from a particular refcontext specified by the \prm{refcontext key/values} which are parsed as the per the corresponding \env{refcontext} options. Such refcontext auto-assignments are specific to the current refsection. You may specify the same citation key in any of these commands but be aware that assignment is done in the order \prm{keywords}, \prm{categories}, \prm{entrykeys} with the later specifications overriding the earlier. \cmd{assignrefcontextentries} accepts a single asterisk instead of a list of entrykeys which allows the assignment of all keys in a refsection to a refcontext with having to explicitly list them. An example:
+These commands automate putting citations into refcontexts when the default behaviour is not sufficient. The \prm{key=value} options are as for \cmd{DeclareRefcontext}. The default behaviour is that the data for a citation is drawn from the refcontext of the most recently processed bibliography in which it was printed\footnote{This does not always mean what one might think. In a document containing multiple bibliographies, the last bibliography will be the context for any citations \emph{before} the first bibliography because all bibliographies are processed when the \file{.bbl} is read.}. For citations that are used in some way but not printed in a bibliography or bibliography list, they default to drawing their data from the global refcontext established at the beginning of the document. To override this behaviour, instead of manually wrapping citation commands in \env{refcontext} environments, which might be error-prone and tedious, you can register a comma"=separated list of \prm{keywords}, \prm{categories} or \prm{entrykeys} which, respectively, make the entries with any of the specified keywords, entries in any of the specified categories (see \secref{use:use:div}) or entries with any of the specified citation keys draw their data from a particular refcontext specified by the \prm{refcontext key/values} which are parsed as the per the corresponding \env{refcontext} options. Such refcontext auto-assignments are specific to the current refsection. You may specify the same citation key in any of these commands but be aware that assignment is done in the order \prm{keywords}, \prm{categories}, \prm{entrykeys} with the later specifications overriding the earlier. \cmd{assignrefcontextentries} accepts a single asterisk instead of a list of entrykeys which allows the assignment of all keys in a refsection to a refcontext with having to explicitly list them. An example:
\begin{ltxexample}[style=latex]
\assignrefcontextentries[labelprefix=A]{key2}
@@ -4701,6 +4780,8 @@ will execute:
Note that the \texttt{mcite} module is not a compatibility module. It provides commands which are very similar but not identical in syntax and function to \sty{mcite}'s commands. When migrating from \sty{mcite}\slash\sty{mciteplus} to \biblatex, legacy files must be updated. With \sty{mcite}, the first member of the citation group is also the identifier of the group as a whole. Borrowing an example from the \sty{mcite} manual, this group:
\begin{table}
+\caption{\sty{mcite}-like commands}
+\label{use:cit:mct:tab1}
\tablesetup
\begin{tabular}{@{}V{0.5\textwidth}@{}V{0.5\textwidth}@{}}
\toprule
@@ -4716,10 +4797,10 @@ Note that the \texttt{mcite} module is not a compatibility module. It provides c
|\textcite| & |\mtextcite| \\
|\Textcite| & |\Mtextcite| \\
|\supercite| & |\msupercite| \\
+|\autocite| & |\mautocite| \\
+|\Autocite| & |\Mautocite| \\
\bottomrule
\end{tabular}
-\caption{\sty{mcite}-like commands}
-\label{use:cit:mct:tab1}
\end{table}
\begin{ltxexample}
@@ -4735,6 +4816,9 @@ consists of three entries and the entry key of the first one also serves as iden
Once defined, an entry set is handled like any regular entry in a \file{bib} file. When using one of the \texttt{numeric} styles which come with \biblatex and activating its \opt{subentry} option, it is even possible to refer to set members. See \tabref{use:cit:mct:tab2} for some examples. Restating the original definition of the set is redundant, but permissible. In contrast to \sty{mciteplus}, however, restating a part of the original definition is invalid. Use the entry key of the set instead.
\begin{table}
+\caption[\sty{mcite}-like syntax]
+{\sty{mcite}-like syntax (sample output with \kvopt{style}{numeric} and \opt{subentry} option)}
+\label{use:cit:mct:tab2}
\tablesetup
\begin{tabular}{@{}V{0.6\textwidth}@{}V{0.1\textwidth}@{}p{0.3\textwidth}@{}}
\toprule
@@ -4750,9 +4834,6 @@ Once defined, an entry set is handled like any regular entry in a \file{bib} fil
|\cite{weinberg}| & [1c] & Regular |\cite| works as well \\
\bottomrule
\end{tabular}
-\caption[\sty{mcite}-like syntax]
-{\sty{mcite}-like syntax (sample output with \kvopt{style}{numeric} and \opt{subentry} option)}
-\label{use:cit:mct:tab2}
\end{table}
\subsection{Localization Commands}
@@ -4909,7 +4990,11 @@ This command should be used with \cmd{bibnamedelimd} as a reversed-name separato
The dash to be used as a replacement for recurrent authors or editors in the bibliography. The default is an <em> or an <en> dash, depending on the indentation of the list of references.
\csitem{labelnamepunct}\DeprecatedMark
-A separator to be printed after the name used for alphabetizing in the bibliography (\bibfield{author} or \bibfield{editor}, if the \bibfield{author} field is undefined) instead of \cmd{newunitpunct}. The default is \cmd{newunitpunct}, \ie it is not handled differently from regular unit punctuation but permits convenient reconfiguration. This punctuation command is deprecated and has been superseded by the context-sensitive \cmd{nametitledelim} (see \secref{use:fmt:csd}). For backwards compatibility reasons, however, \cmd{nametitledelim} still defaults to \cmd{labelnamepunct} in the \texttt{bib} and \texttt{biblist} contexts. Style authors may want to consider replacing \cmd{labelnampunct} with \texttt{\textbackslash printdelim\{nametitledelim\}} and users may want to prefer modifying the context-sensitive \texttt{nametitledelim} with \cmd{DeclareDelimFormat} over redefining \cmd{labelnamepunct}.
+A separator to be printed after the name used for alphabetizing in the bibliography (\bibfield{author} or \bibfield{editor}, if the \bibfield{author} field is undefined) instead of \cmd{newunitpunct}. The default is \cmd{newunitpunct}, \ie it is not handled differently from regular unit punctuation but permits convenient reconfiguration. This punctuation command is deprecated and has been superseded by the context-sensitive \cmd{nametitledelim} (see \secref{use:fmt:csd}). For backwards compatibility reasons, however, \cmd{nametitledelim} still defaults to \cmd{labelnamepunct} in the \texttt{bib} and \texttt{biblist} contexts. Style authors may want to consider replacing \cmd{labelnampunct} with \texttt{\textbackslash printdelim\{nametitledelim\}} and users may want to prefer modifying the context-sensitive \texttt{nametitledelim} in the \texttt{bib} context with \cmd{DeclareDelimFormat} over redefining \cmd{labelnamepunct}, e.g.
+\begin{ltxexample}
+\DeclareDelimFormat[bib]{nametitledelim}{%
+ \addcolon\space}
+\end{ltxexample}
\csitem{subtitlepunct}
The separator printed between the fields \bibfield{title} and \bibfield{subtitle}, \bibfield{booktitle} and \bibfield{booksubtitle}, as well as \bibfield{maintitle} and \bibfield{mainsubtitle}. With the default styles, this separator replaces \cmd{newunitpunct} at this location. The default definition is \cmd{newunitpunct}, \ie it is not handled differently from regular unit punctuation.
@@ -4923,6 +5008,9 @@ The separator printed before the \bibfield{pages} field. The default is a comma
\csitem{bibpagerefpunct}
The separator printed before the \bibfield{pageref} field. The default is an interword space.
+\csitem{bibeidpunct}
+The separator printed before the \bibfield{eid} field (similar to \cmd{bibpagespunct}). The default is a comma plus an interword space.
+
\csitem{multinamedelim}\CSdelimMark
The delimiter printed between multiple items in a name list like \bibfield{author} or \bibfield{editor} if there are more than two names in the list. The default is a comma plus an interword space. See \cmd{finalnamedelim} for an example.\footnote{Note that \cmd{multinamedelim} is not used at all if there are only two names in the list. In this case, the default styles use the \cmd{finalnamedelim}.}
@@ -4960,9 +5048,27 @@ The delimiter printed before the localisation string <\texttt{andmore}> if a lit
\csitem{multicitedelim}
The delimiter printed between citations if multiple entry keys are passed to a single citation command. The default is a semicolon plus an interword space.
+\csitem{multiciterangedelim}
+The delimiter printed between two citations if they are compressed to a range. The default is \cmd{bibrangedash}.
+
+\csitem{multicitesubentrydelim}
+The delimiter printed between subentry citations of the same set. This delimiter is only used in citation styles that reduce citations of the same set to a more compact form (\opt{subentry} of \texttt{numeric-comp}). The default is a comma.
+
+\csitem{multicitesubentryrangedelim}
+The delimiter printed between two citations of the same set if they are compressed to a range. The default is \cmd{multiciterangedelim}.
+
\csitem{supercitedelim}
Similar to \cmd{multicitedelim}, but used by the \cmd{supercite} command only. The default is a comma.
+\csitem{superciterangedelim}
+Analogue of \cmd{multiciterangedelim} for \cmd{supercite}. The default is \cmd{bibrangedash}.
+
+\csitem{supercitesubentrydelim}
+Analogue of \cmd{multicitesubentrydelim} for \cmd{supercite}. The default is \cmd{supercitedelim}.
+
+\csitem{supercitesubentryrangedelim}
+Analogue of \cmd{multicitesubentryrangedelim} for \cmd{supercite}. The default is \cmd{superciterangedelim}.
+
\csitem{compcitedelim}
Similar to \cmd{multicitedelim}, but used by certain citation styles when <compressing> multiple citations. The default definition is a comma plus an interword space.
@@ -5043,13 +5149,13 @@ For backwards compatibility with the legacy \bibtex name parts, the following ar
\mkbibnameaffix
\end{ltxexample}
-\csitem{mkbibcompletenamefamily}{text}
+\cmditem{mkbibcompletenamefamily}{text}
This command, which takes one argument, is used to format the complete name in \texttt{family} format order.
-\csitem{mkbibcompletenamefamilygiven}{text}
+\cmditem{mkbibcompletenamefamilygiven}{text}
This command, which takes one argument, is used to format the complete name in \texttt{family-given} format order.
-\csitem{mkbibcompletenamegivenfamily}{text}
+\cmditem{mkbibcompletenamegivenfamily}{text}
This command, which takes one argument, is used to format the complete name in \texttt{given-family} format order.
\cmditem{mkbibcompletename}{text}
@@ -5079,7 +5185,7 @@ Prints \acr{ISO8601-2} format date circa information when the global option \opt
\csitem{enddatecircaprintiso}
Prints \acr{ISO8601-2} format date circa information when the global option \opt{datecirca} is enabled and the \cmd{ifenddatecirca} test is true. Prints \cmd{textasciitilde}.
-\csitem{dateeraprint}{yearfield}
+\cmditem{dateeraprint}{yearfield}
Prints date era information when the global option \opt{dateera} is set to <secular> or <christian>. By default, prints the \opt{dateeradelim} delimiter and the appropriate localised era term (\secref{aut:lng:key:dt}). If the \opt{dateeraauto} option is set, then the passed \prm{yearfield} (which is the name of a year field such as <year>, <origyear>, <endeventyear> etc.) is tested to see if its value is earlier than the \opt{dateeraauto} threshold and if so, then the BCE/CE localisation will be output too. The default setting for \opt{dateeraauto} is 0 and so only BCE/BC localisation strings are candidates for output. Detects whether the start or end year era information is to be printed by looking at the \prm{yearfield} name passed to it.
\csitem{dateeraprintpre}
@@ -5124,26 +5230,31 @@ The delimiters described in \secref{use:fmt:fmt} are globally defined. That is,
\cmditem{DeclareDelimFormat}[context, \dots]{name, \dots}{code}
\cmditem*{DeclareDelimFormat}*[context, \dots]{name, \dots}{code}
-Declares the delimiter macros in the comma"=separated list \prm{names} with the replacement test \prm{code}. If the optional comma"=separated list of \prm{contexts} is given, declare the \prm{names} only for those contexts. \prm{names} defined without any \prm{contexts} behave just like the global delimiter definitions which \cmd{newcommand} gives---just a plain macro with a replacement which can be used as \cmd{name}. However, you can also call delimiter macros defined in this way by using \cmd{printdelim}, which is context-aware. The starred version clears all \prm{context} specific declarations for all \prm{names} first.
+Declares the delimiter macros in the comma"=separated list \prm{names} with the replacement text \prm{code}. If the optional comma"=separated list of \prm{contexts} is given, declare the \prm{names} only for those contexts. \prm{names} defined without any \prm{contexts} behave just like the global delimiter definitions which \cmd{newcommand} gives---just a plain macro with a replacement which can be used as \cmd{name}. However, you can also call delimiter macros defined in this way by using \cmd{printdelim}, which is context-aware. The starred version clears all \prm{context} specific declarations for all \prm{names} first.
+
+\cmditem{DeclareDelimAlias}[alias context, \dots]{alias}[delim context]{delim}
-\cmditem{DeclareDelimAlias}{alias}{delim}
-\cmditem*{DeclareDelimAlias}*[alias context, \dots]{alias}[delim context]{delim}
+Declares \prm{alias} to be an alias for the delimiter \prm{delim}. If the optional \prm{alias context, \dots} nor \prm{delim context} are given, the assigment is performed for all existing contexts of the target \prm{delim} separately, so that \prm{alias} becomes an exact copy of \prm{delim} in all contexts. If only the second optional argument \prm{delim context} is given, all existing contexts of \prm{alias} will be cleared and the global/empty context becomes an alias of \prm{delim} in the context \prm{delim context}. The first optional argument \prm{alias context, \dots} may hold a list of contexts for which the alias is assigned. In that case the second optional argument \prm{delim context} specifies the context of the target delimiter. This argument may not be a list, it can only hold one context. If it is missing, the \prm{alias context} is assumed (if \prm{alias context} is a list, the assignment is performed separately for each list item), if it is empty the global context is used.
-Declares \prm{alias} to be an alias for the delimiter \prm{delim}. The assigment is performed for all existing contexts of the target \prm{delim}.
-The starred version assigns the alias for specific contexts only. The first optional argument \prm{alias context} holds a list of contexts for which the assignment is going to be performed. If it is empty or missing the global/empty context is assumed. The second optional argument \prm{delim context} specifies the context of the target delimiter. This argument may not be a list, it can only hold one context. If it is missing the \prm{alias context} is assumed (if \prm{alias context} is a list, the assignment is performed separately for each list item), if it is empty the global context is used.
\begin{ltxexample}[style=latex]
-\DeclareDelimAlias*[bib,biblist]{finalnamedelim}[]{multinamedelim}
+\DeclareDelimAlias[bib,biblist]{finalnamedelim}[]{multinamedelim}
\end{ltxexample}
%
Defines the \opt{bib} and \opt{biblist} contexts of \cmd{finalnamedelim} as aliases of \cmd{multinamedelim} in global context.
On the other hand
\begin{ltxexample}[style=latex]
-\DeclareDelimAlias*[bib,biblist]{finalnamedelim}{multinamedelim}
+\DeclareDelimAlias[bib,biblist]{finalnamedelim}{multinamedelim}
\end{ltxexample}
%
defines \cmd{finalnamedelim} in the context \opt{bib} to be an alias of \cmd{multinamedelim} in the \opt{bib} context and defines \cmd{finalnamedelim} in \opt{biblist} context to be an alias of \cmd{multinamedelim} in \opt{biblist}.
+\cmditem*{DeclareDelimAlias}*[alias context, \dots]{alias}[delim context]{delim}\DeprecatedMark
+
+The starred version of \cmd{DeclareDelimAlias} is deprecated in favour of using unstarred \cmd{DeclareDelimAlias} with optional arguments.
+
+It assigns the delimiter alias for specific contexts only. The first optional argument \prm{alias context} holds a list of contexts for which the assignment is going to be performed. If it is empty or missing the global/empty context is assumed. The second optional argument \prm{delim context} specifies the context of the target delimiter. This argument may not be a list, it can only hold one context. If it is missing the \prm{alias context} is assumed (if \prm{alias context} is a list, the assignment is performed separately for each list item), if it is empty the global context is used.
+
\cmditem{printdelim}[context]{name}
Prints a delimiter with name \prm{name}, locally establishing a optional \prm{context} first. Without the optional \prm{context}, \cmd{printdelim} uses the currently active delimiter context.
@@ -5479,11 +5590,6 @@ This will yield <Œuvres> or <œuvres>.
The facilities discussed in this section are specific to certain localisation modules.
-\subsubsection{Bulgarian}
-\label{use:loc:bul}
-
-Like the Greek localisation module, the Bulgarian module also requires \utf support. It will not work with any other encoding.
-
\subsubsection{American}
\label{use:loc:us}
@@ -5499,6 +5605,36 @@ By default, the <American punctuation> feature is enabled by the \texttt{america
It is highly advisable to always specify \texttt{american}, \texttt{british}, \texttt{australian}, etc. rather than \texttt{english} when loading the \sty{babel}/\sty{polyglossia} packages to avoid any possible confusion. Older versions of the \sty{babel} package used to treat \opt{english} as an alias for \opt{british}; more recent ones treat it as an alias for \opt{american}. The \biblatex package essentially treats \texttt{english} as an alias for \opt{american}, except for the above feature which is only enabled if \texttt{american} is requested explicitly.
+\subsubsection{Bulgarian}
+\label{use:loc:bul}
+
+Like the Greek localisation module, the Bulgarian module also requires \utf support. It will not work with any other encoding.
+
+\subsubsection{Greek}
+\label{use:loc:grk}
+
+The Greek localisation module requires \utf support. It will not work with any other encoding. Generally speaking, the \biblatex package is compatible with the \sty{inputenc} package and with the Unicode engines \lualatex and \xelatex. The \sty{ucs} package will not work. 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 \biblatex. However, there is one fundamental limitation. As of this writing, \biblatex has no support for switching scripts. Greek titles in the bibliography should work fine, but English and other titles in the bibliography may be rendered in Greek letters. If you need multi-script bibliographies, using a Unicode engine is the only sensible choice.
+
+\subsubsection{Hungarian}
+\label{use:loc:hun}
+
+The Hungarian localisation module needs to redefine certain field formats to obtain the grammatically correct word order. This means that these field formats are overwritten whenever the Hungarian localisation is active, no matter whether they were defined in the preamble or by a custom style. So please be aware that using the Hungarian localisation module may cause the bibliography output to deviate from the format dictated by the loaded style and preamble definitions. Changes to this behaviour need to be made using \cmd{DefineBibliographyExtras}. In particular \cmd{mkpageprefix} is redefined to output the <page> or <pages> string as a suffix after the page number following Hungarian conventions, and all formats of fields involving pages, chapters and volumes were modified so that numbers are printed as ordinals. The Hungarian localisation module will print a warning to remind you of these changes whenever it is loaded in a document. The warning tells you how to silence it.
+
+\subsubsection{Latvian}
+\label{use:loc:lav}
+
+The Latvian localisation module, like the Hungarian language module, needs to redefine certain field formats to obtain the grammatically correct word order. This means that these field formats are overwritten whenever the Latvian localisation is active, no matter whether they were defined in the preamble or by a custom style. So please be aware that using the Latvian localisation module may cause the bibliography output to deviate from the format dictated by the loaded style and preamble definitions. Changes to this behaviour need to be made using \cmd{DefineBibliographyExtras}. In particular \cmd{mkpageprefix} is redefined to output the <page> or <pages> string as a suffix after the page number following Latvian conventions, and all formats of fields involving pages, chapters and volumes were modified so that numbers are printed as ordinals. The Latvian localisation module will print a warning to remind you of these changes whenever it is loaded in a document. The warning tells you how to silence it.
+
+\subsubsection{Lithuanian}
+\label{use:loc:lit}
+
+The Lithuanian localisation module needs \utf support and will only work with this encoding.
+
+\subsubsection{Russian}
+\label{use:loc:rus}
+
+Like the Greek and Lithuanian localisation module, the Russian module also requires \utf support. It will not work with any other encoding.
+
\subsubsection{Spanish}
\label{use:loc:esp}
@@ -5527,25 +5663,11 @@ Similar to \cmd{forceE} but enforces <y>.
\end{ltxsyntax}
-\subsubsection{Greek}
-\label{use:loc:grk}
-
-The Greek localisation module requires \utf support. It will not work with any other encoding. Generally speaking, the \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 \biblatex. However, there is one fundamental limitation. As of this writing, \biblatex has no support for switching scripts. Greek titles in the bibliography should work fine, 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.
+\subsubsection{Turkish}
+\label{use:loc:tur}
-\subsubsection{Russian}
-\label{use:loc:rus}
-
-Like the Greek localisation module, the Russian module also requires \utf support. It will not work with any other encoding.
+By default \sty{babel}'s Turkish localisation module makes <\texttt{=}> a <shorthand>, which breaks the \keyval parser uses by \biblatex. This problem can be resolved by telling \sty{babel} not to make <\texttt{=}> a shorthand (for example by loading \sty{babel} with the option \texttt{shorthands=:!}) or by loading a \keyval package that can deal with active characters (\sty{kvsetkeys} and \sty{xkeyval})\fnurl{https://tex.stackexchange.com/a/160428/35864}.
-\subsubsection{Hungarian}
-\label{use:loc:hun}
-
-The Hungarian localisation module needs to redefine certain field formats to obtain the grammatically correct word order. This means that these field formats are overwritten whenever the Hungarian localisation is active, no matter whether they were defined in the preamble or by a custom style. So please be aware that using the Hungarian localisation module may cause the bibliography output to deviate from the format dictated by the loaded style and preamble definitions. Changes to this behaviour need to be made using \cmd{DefineBibliographyExtras}. In particular \cmd{mkpageprefix} is redefined to output the <page> or <pages> string as a suffix after the page number following Hungarian conventions, and all formats of fields involving pages, chapters and volumes were modified so that numbers are printed as ordinals. The Hungarian localisation module will print a warning to remind you of these changes whenever it is loaded in a document. The warning tells you how to silence it.
-
-\subsubsection{Latvian}
-\label{use:loc:lav}
-
-The Latvian localisation module, like the Hungarian language module, needs to redefine certain field formats to obtain the grammatically correct word order. This means that these field formats are overwritten whenever the Latvian localisation is active, no matter whether they were defined in the preamble or by a custom style. So please be aware that using the Latvian localisation module may cause the bibliography output to deviate from the format dictated by the loaded style and preamble definitions. Changes to this behaviour need to be made using \cmd{DefineBibliographyExtras}. In particular \cmd{mkpageprefix} is redefined to output the <page> or <pages> string as a suffix after the page number following Latvian conventions, and all formats of fields involving pages, chapters and volumes were modified so that numbers are printed as ordinals. The Latvian localisation module will print a warning to remind you of these changes whenever it is loaded in a document. The warning tells you how to silence it.
\subsection{Usage Notes}
\label{use:use}
@@ -6023,17 +6145,19 @@ This section provides additional usage hints and addresses some common problems
\subsubsection{Usage with \acr{KOMA}-Script Classes}
\label{use:cav:scr}
-When using \biblatex in conjunction with one of the \sty{scrbook}, \sty{scrreprt}, or \sty{scrartcl} classes, the headings \texttt{bibliography} and \texttt{biblist} 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{printbiblist}. See \secref{use:bib:bib, use:bib:biblist, 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, \biblatex will also provide the following additional tests which may be useful in custom heading definitions:
+When used in conjunction with a recent version\footnote{At least \acr{KOMA}-Script 3.25 (2018/03/30).} one of the \sty{scrbook}, \sty{scrreprt}, or \sty{scrartcl} classes, \biblatex passes control over the (default) headings \texttt{bibliography} and \texttt{biblist} from \secref{use:bib:hdg} to the class. Hence, bibliography-heading-related class options can be used as usual. You can override the default headings by using the \opt{heading} option of \cmd{printbibliography}, \cmd{printbibheading} and \cmd{printbiblist}. See \secref{use:bib:bib, use:bib:biblist, use:bib:hdg} for details.
+
+\biblatex also tries to detect bibliography-related class options and settings itself.\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}.} This was required to be able to adapt the bibliography headings to the class settings in older versions of \acr{KOMA}-Script. If one of the above classes is detected, \biblatex will provide the following additional tests which may be useful in custom heading definitions. Since these tests rely on the error-prone external detection of \acr{KOMA}-Script settings and are no longer used with newer \acr{KOMA}-Script versions, these tests are deprecated and should no longer be used.
\begin{ltxsyntax}
-\cmditem{ifkomabibtotoc}{true}{false}
+\cmditem{ifkomabibtotoc}{true}{false}\DeprecatedMark
-Expands to \prm{true} if the class would add the bibliography to the table of contents, and to \prm{false} otherwise.
+Expands to \prm{true} if the class would add the bibliography to the table of contents, and to \prm{false} otherwise. This test is deprecated.
-\cmditem{ifkomabibtotocnumbered}{true}{false}
+\cmditem{ifkomabibtotocnumbered}{true}{false}\DeprecatedMark
-Expands to \prm{true} if the class would add the bibliography to the table of contents as a numbered section, and to \prm{false} otherwise. If this test yields \prm{true}, \cmd{ifkomabibtotoc} will always yield \prm{true} as well, but not vice versa.
+Expands to \prm{true} if the class would add the bibliography to the table of contents as a numbered section, and to \prm{false} otherwise. If this test yields \prm{true}, \cmd{ifkomabibtotoc} will always yield \prm{true} as well, but not vice versa. This test is deprecated.
\end{ltxsyntax}
@@ -6067,7 +6191,7 @@ If the \prm{postnote} argument to a citation command is a page number or page ra
\cite[vii--x; 5, 7]{key}
\end{ltxexample}
%
-In some other cases, however, the tests may get it wrong and you need to resort to the auxiliary commands \cmd{pno}, \cmd{ppno}, and \cmd{nopp} from \secref{use:cit:msc}. For example, suppose a work is cited by a special pagination scheme consisting of numbers and letters. In this scheme, the string <|27a|> would mean <page~27, part~a>. Since this string does not look like a number or a range to \biblatex, you need to force the prefix for a single number manually:
+In some other cases, however, the tests may get it wrong and you need to resort to the auxiliary commands \cmd{pnfmt}, \cmd{pno}, \cmd{ppno}, and \cmd{nopp} from \secref{use:cit:msc}. For example, suppose a work is cited by a special pagination scheme consisting of numbers and letters. In this scheme, the string <|27a|> would mean <page~27, part~a>. Since this string does not look like a number or a range to \biblatex, you need to force the prefix for a single number manually:
\begin{ltxexample}
\cite[\pno~27a]{key}
@@ -6088,6 +6212,12 @@ These commands may be used anywhere in the \prm{postnote} argument. They may als
\cite[see][\ppno~37--46, in particular \pno~40]{key}
\end{ltxexample}
%
+The command \cmd{pnfmt} can be used for \prm{postnote}s consisting of a page range and some additional text. \cmd{pnfmt} prints its argument in the format specified for the postnote and can be used to format the page range automatically without the need for \cmd{pno} and \cmd{ppno}.
+
+\begin{ltxexample}
+\cite[\pnfmt{37-46}, in particular \pnfmt{40}]{key}
+\end{ltxexample}
+%
There are also two auxiliary command for suffixes like <the following page(s)>. Instead of inserting such suffixes literally (which would require \cmd{ppno} to force a prefix):
\begin{ltxexample}
@@ -6102,7 +6232,7 @@ use the auxiliary commands \cmd{psq} and \cmd{psqq}. Note that there is no space
\cite[55\psqq]{key}
\end{ltxexample}
%
-Since the postnote is printed without any prefix if it includes any character which is not an Arabic or Roman numeral, you may also type the prefix manually:
+Since the postnote is printed without any prefix if it includes any character which is not an Arabic or Roman numeral, you may also type the prefix manually---though this is discouraged:
\begin{ltxexample}
\cite[p.~5]{key}
@@ -6184,11 +6314,33 @@ This is how they are employed:
\item K\delim{.-}{c}H\delim{.}{a} Mustermann
\end{namesample}
-\subsubsection{Bibliography Filters and Citation Labels}
+\subsubsection{Split Bibliographies 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{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.
+Compare the output of the following example with \texttt{defernumbers=true} and \texttt{defernumbers=false}.
+%
+\begin{ltxexample}
+\documentclass{article}
+\usepackage[defernumbers=true]{biblatex}
+
+\addbibresource{biblatex-examples.bib}
+
+\begin{document}
+Lorem \autocite{worman} ipsum \autocite{sigfridsson}
+dolor \autocite{nussbaum} sit \autocite{aksin}
+
+\printbibheading[title={Bibliography}]
+\printbibliography[heading=subbibliography,
+ type=book, title={Books}]
+\printbibliography[heading=subbibliography,
+ type=article, title={Articles}]
+\end{document}
+\end{ltxexample}
+
+There are pathological cases where neither \texttt{defernumbers=true} nor \texttt{defernumbers=false} produce fully desirable output. This may be the case when entries can end up in several of the split bibliographies---or if there is an additional global bibliography. But in most cases with non-overlapping split bibliographies \texttt{defernumbers=true} produces better results. \sty{biblatex} will therefore suggest setting \opt{defernumbers} to \opt{true} in a warning when a split bibliography setup is detected. That warning can be suppressed in case setting \opt{defernumbers} to \opt{true} is not desirable.
+
\subsubsection{Active Characters in Bibliography Headings}
\label{use:cav:act}
@@ -6649,7 +6801,7 @@ would result in the same information in the \file{.bbl} as:
}
\end{lstlisting}
%
-but would additionally have the field \bibfield{dateunspecified} set to <yearincentury> and \bibfield{origdateunspecified} set to <yearindecade>. This information could be used to render the \bibfield{date} as perhaps <20th century> and \bibfield{origdate} as <The 1990s>, information which cannot be derived from the date ranges alone. Since such auto-generated ranges have a know values, given the <unspecified> meta-information, it is relatively easy to use the range values to format special cases. While the standard styles not do this, examples are given in the file \file{96-dates.tex}.
+but would additionally have the field \bibfield{dateunspecified} set to <yearincentury> and \bibfield{origdateunspecified} set to <yearindecade>. This information could be used to render the \bibfield{date} as perhaps <20th century> and \bibfield{origdate} as <The 1990s>, information which cannot be derived from the date ranges alone. Since such auto-generated ranges have known values, given the <unspecified> meta-information, it is relatively easy to use the range values to format special cases. While the standard styles do not do this, examples are given in the file \file{96-dates.tex}.
\fielditem{entrykey}{string}
@@ -6877,10 +7029,15 @@ will tell you if the corresponding date is defined and an open"=ended range. Ope
\begingroup
\tablesetup
\begin{longtable}[l]{%
- @{}V{0.15\textwidth}%
- @{}V{0.4\textwidth}%
- @{}V{0.3\textwidth}%
- @{}V{0.2\textwidth}@{}}
+ @{}V{0.15\textwidth}%
+ @{}V{0.4\textwidth}%
+ @{}V{0.3\textwidth}%
+ @{}V{0.2\textwidth}@{}}
+\caption{Date Interface}
+\label{aut:bbx:fld:tab1}
+\endfirsthead
+\caption[]{Date Interface (cont'd)}
+\endhead
\toprule
\multicolumn{2}{@{}H}{\file{bib} File} &
\multicolumn{2}{H}{Data Interface} \\
@@ -7020,11 +7177,8 @@ eventdate & 1995-01-31/1995-02-05 & eventday & 31 \\
& & eventendtimezone & undefined \\
\bottomrule
%\end{tabularx}
-\caption{Date Interface}
-\label{aut:bbx:fld:tab1}
\end{longtable}
\endgroup
-
\begin{fieldlist}
\fielditem{hour}{datepart}
@@ -7362,7 +7516,7 @@ If an unknown \prm{position} identifier is used, it defaults to \opt{o}.
\item[l] The punctuation mark is moved to the left of the citation and thus appears before it.
\item[f] Like \opt{r} in footnotes and like \opt{l} otherwise.
\item[c] Pass the punctuation on to the internal implementation of the citation commands. It will then be executed within the \prm{wrapper} command if given.
-\item[o] Retain the default set-up of \opt{c} for citation defined commands without \prm{wrapper} command and \opt{l} for citation commands defined with a \prm{wrapper} command.
+\item[o] Retain the default setup of \opt{c} for citation defined commands without \prm{wrapper} command and \opt{l} for citation commands defined with a \prm{wrapper} command.
\item[d] Drop the explicit punctuation mark. It will only be available as the field \bibfield{postpunct}.
\end{valuelist}
%
@@ -7575,12 +7729,12 @@ This section introduces the commands used to define the formatting directives re
\cmditem{DeclareFieldFormat}[entrytype, \dots]{format}{code}
\cmditem*{DeclareFieldFormat}*{format}{code}
-Defines the field format \prm{format}. This formatting directive is arbitrary \prm{code} to be executed by \cmd{printfield}. The value of the field will be passed to the \prm{code} as its first and only argument. The name of the field currently being processed is available to the \prm{code} as \cmd{currentfield}. If an \prm{entrytype} is specified, the format is specific to that type. The \prm{entrytype} argument may be a comma"=separated list of values. The starred variant of this command is similar to the regular version, except that all type-specific formats are cleared. \emph{Do not put any whitespace between the arguments to this macro as the definitions are quite complex and you will get unexpected results}.
+Defines the field format \prm{format}. This formatting directive is arbitrary \prm{code} to be executed by \cmd{printfield}. The value of the field will be passed to the \prm{code} as its first and only argument. The name of the field currently being processed is available to the \prm{code} as \cmd{currentfield}. If an \prm{entrytype} is specified, the format is specific to that type. The \prm{entrytype} argument may be a comma"=separated list of values. The starred variant of this command is similar to the regular version, except that all type-specific formats are cleared.
\cmditem{DeclareListFormat}[entrytype, \dots]{format}{code}
\cmditem*{DeclareListFormat}*{format}{code}
-Defines the literal list format \prm{format}. This formatting directive is arbitrary \prm{code} to be executed for every item in a list processed by \cmd{printlist}. The current item will be passed to the \prm{code} as its first and only argument. The name of the literal list currently being processed is available to the \prm{code} as \cmd{currentlist}. If an \prm{entrytype} is specified, the format is specific to that type. The \prm{entrytype} argument may be a comma"=separated list of values. Note that the formatting directive also handles the punctuation to be inserted between the individual items in the list. You need to check whether you are in the middle of or at the end of the list, \ie whether \cnt{listcount} is smaller than or equal to \cnt{liststop}. The starred variant of this command is similar to the regular version, except that all type-specific formats are cleared. \emph{Do not put any whitespace between the arguments to this macro as the definitions are quite complex and you will get unexpected results}.
+Defines the literal list format \prm{format}. This formatting directive is arbitrary \prm{code} to be executed for every item in a list processed by \cmd{printlist}. The current item will be passed to the \prm{code} as its first and only argument. The name of the literal list currently being processed is available to the \prm{code} as \cmd{currentlist}. If an \prm{entrytype} is specified, the format is specific to that type. The \prm{entrytype} argument may be a comma"=separated list of values. Note that the formatting directive also handles the punctuation to be inserted between the individual items in the list. You need to check whether you are in the middle of or at the end of the list, \ie whether \cnt{listcount} is smaller than or equal to \cnt{liststop}. The starred variant of this command is similar to the regular version, except that all type-specific formats are cleared.
\cmditem{DeclareNameFormat}[entrytype, \dots]{format}{code}
@@ -7608,7 +7762,7 @@ The value of the datamodel <nameparts> constant (see \secref{aut:bbx:drv}) creat
\namepartgiveni
\end{ltxexample}
%
-If a certain part of a name is not available, the corresponding macro will be empty, hence you may use, for example, the \sty{etoolbox} tests like \cmd{ifdefvoid} to check for the individual parts of a name. The name of the name list currently being processed is available to the \prm{code} as \cmd{currentname}. Note that the formatting directive also handles the punctuation to be inserted between separate names and between the individual parts of a name. You need to check whether you are in the middle of or at the end of the list, \ie whether \cnt{listcount} is smaller than or equal to \cnt{liststop}. See also \secref{use:cav:nam}. The starred variant of this command is similar to the regular version, except that all type-specific formats are cleared. \emph{Do not put any whitespace between the arguments to this macro as the definitions are quite complex and you will get unexpected results}.
+If a certain part of a name is not available, the corresponding macro will be empty, hence you may use, for example, the \sty{etoolbox} tests like \cmd{ifdefvoid} to check for the individual parts of a name. The name of the name list currently being processed is available to the \prm{code} as \cmd{currentname}. Note that the formatting directive also handles the punctuation to be inserted between separate names and between the individual parts of a name. You need to check whether you are in the middle of or at the end of the list, \ie whether \cnt{listcount} is smaller than or equal to \cnt{liststop}. See also \secref{use:cav:nam}. The starred variant of this command is similar to the regular version, except that all type-specific formats are cleared.
\cmditem{DeclareListWrapperFormat}[entrytype, \dots]{format}{code}
\cmditem*{DeclareListWrapperFormat}*{format}{code}
@@ -7635,17 +7789,6 @@ Defines the literal list format \prm{format}. This formatting directive is arbit
Defines the name list format \prm{format}. This formatting directive is arbitrary \prm{code} to be executed for every name in a list processed by \cmd{indexnames}. The name of the name list currently being processed is available to the \prm{code} as \cmd{currentname}. If an \prm{entrytype} is specified, the format is specific to that type. The \prm{entrytype} argument may be a comma"=separated list of values. The parts of the name will be passed to the \prm{code} as separate arguments. This command is very similar to \cmd{DeclareNameFormat} except that the data handled by the \prm{code} is not intended to be printed but written to the index. Note that \cmd{indexnames} will execute the \prm{code} as is, \ie the \prm{code} must include \cmd{index} or a similar command. The starred variant of this command is similar to the regular version, except that all type-specific formats are cleared.
-\cmditem{DeclareIndexListWrapperFormat}[entrytype, \dots]{format}{code}
-\cmditem*{DeclareIndexListWrapperFormat}*{format}{code}
-
-Similar to \cmd{DeclareIndexListFormat} but for the list format used for indices.
-
-
-\cmditem{DeclareIndexNameWrapperFormat}[entrytype, \dots]{format}{code}
-\cmditem*{DeclareIndexNameWrapperFormat}*{format}{code}
-
-Similar to \cmd{DeclareIndexNameFormat} but for the name list format used for indices.
-
\cmditem{DeclareFieldAlias}[entry type]{alias}[format entry type]{format}
Declares \prm{alias} to be an alias for the field format \prm{format}. If an \prm{entrytype} is specified, the alias is specific to that type. The \prm{format entry type} is the entry type of the backend format. This is only required when declaring an alias for a type"=specific formatting directive.
@@ -7678,14 +7821,6 @@ Declares \prm{alias} to be an alias for the literal list format \prm{format}. If
Declares \prm{alias} to be an alias for the name list format \prm{format}. If an \prm{entrytype} is specified, the alias is specific to that type. The \prm{format entry type} is the entry type of the backend format. This is only required when declaring an alias for a type"=specific formatting directive.
-\cmditem{DeclareIndexListWrapperAlias}[entrytype, \dots]{format}{code}
-
-Similar to \cmd{DeclareIndexListFormat} but for the list format used for indices.
-
-\cmditem{DeclareIndexNameWrapperAlias}[entrytype, \dots]{format}{code}
-
-Similar to \cmd{DeclareIndexNameFormat} but for the name list format used for indices.
-
\cmditem{DeprecateFieldFormatWithReplacement}[entry type]{alias}[format entry type]{format}
Declares \prm{alias} to be an alias for the name list format \prm{format} and issue a deprecation warning. If an \prm{entrytype} is specified, the alias is specific to that type. The \prm{format entry type} is the entry type of the backend format. This is only required when declaring an alias for a type"=specific formatting directive.
@@ -7718,14 +7853,6 @@ Similar to \cmd{DeprecateFieldFormatWithReplacement} but for index list formats.
Similar to \cmd{DeprecateFieldFormatWithReplacement} but for index name formats.
-\cmditem{DeprecateIndexListWrapperFormatWithReplacement}[entry type]{alias}[format entry type]{format}
-
-Similar to \cmd{DeprecateFieldFormatWithReplacement} but for index list formats.
-
-\cmditem{DeprecateIndexNameWrapperFormatWithReplacement}[entry type]{alias}[format entry type]{format}
-
-Similar to \cmd{DeprecateFieldFormatWithReplacement} but for index name formats.
-
\end{ltxsyntax}
\subsection{Customization}
@@ -7743,7 +7870,7 @@ The related entries feature comprises the following components:
%
The special fields are \bibfield{related}, \bibfield{relatedtype}, \bibfield{relatedstring} and \bibfield{relatedoptions}:
\begin{keymarglist}
-\item[related] A separated list of keys of entries which are related to this entry in some way. Note the the order of the keys is important. The data from multiple related entries is printed in the order of the keys listed in this field.
+\item[related] A separated list of keys of entries which are related to this entry in some way. Note the order of the keys is important. The data from multiple related entries is printed in the order of the keys listed in this field.
\item[relatedtype] The type of relationship. This serves three purposes. If the value of this field resolves to a localisation string identifier, then the resulting localised string is printed before the data from the related entries. Secondly, if there is a macro called \texttt{related:\prm{relatedtype}}, this is used to format the data from the related entries. If no such macro exists, then the macro \texttt{related:default} is used. Lastly, if there is a format named \texttt{related:\prm{relatedtype}}, then it is used to format both the localised string and related entry data. If there is no related type specific format, the \texttt{related} format is used.
\item[relatedstring] If an entry contains this field, then if value of the field resolves to a localisation string identifier, the localisation key value specified is printed before data from the related entries. If the field does not specify a localisation key, its value is printed literally. If both \bibfield{relatedtype} and \bibfield{relatedstring} are present in an entry, \bibfield{relatedstring} is used for the pre-data string (but \bibfield{relatedtype} is still used to determine the macro and format to use when printing the data).
\item[relatedoptions] A list of per"=entry options to set on the related entry (actually on the clone of the related entry which is used as a data source---the actual related entry is not modified because it might be cited directly itself).
@@ -7834,7 +7961,7 @@ Defines source data modification (mapping) rules which can be used to perform an
\item Add new fields to an entry
\item Remove fields from an entry
\item Modify the contents of a field using standard Perl regular expression
- match and replace
+ match and replace\footnote{See for example \url{https://perldoc.perl.org/perlretut.html}, \url{https://perldoc.perl.org/perlrequick.html} and \url{https://perldoc.perl.org/perlre.html}. There are many more resources available about regular expessions in Perl.}
\item Restrict any of the above operations to entries coming from
particular datasources which you defined in \cmd{addresource} macros
\item Restrict any of the above operations to entries only of a certain
@@ -7932,6 +8059,7 @@ A mapping step. Each step is applied sequentially to every relevant entry where
\boolitem[false]{nocited}
\boolitem[false]{citedornocited}
\boolitem[false]{allnocited}
+\boolitem[false]{starnocited}
\boolitem[false]{entrynocite}
\boolitem[false]{entrynull}
\boolitem[false]{append}
@@ -7946,18 +8074,18 @@ For all boolean \cmd{step} options, the short form \opt{option} is equivalent to
\renewcommand{\labelitemii}{$\circ$}
-Note that the options \opt{cited}, \opt{nocited}, \opt{citedornocited} and
-\opt{allnocited} are unique in that they can make the results of a
-sourcemap differ depending on the refsection. This is because a datasource
-to which source mapping applies may be used in several refsections and
-source mappings are applied when fetching the data from the datasources for
-a refsection. Citation commands are local to a refsection and therefore may
-differ for the same entry from refsection to refsection. For example, the same
-entry may be \cmd{cite}d in one refsection but \cmd{nocite}d in another,
-resulting in different source map results and therefore data between the
-refsections. This can be avoided if desired, by limiting source maps to
-specific refsections only (see \opt{refsection} option to the \cmd{map}
-command above).
+Note that the options \opt{cited}, \opt{nocited}, \opt{citedornocited},
+\opt{allnocited} and \opt{starnocited} are unique in that they can make the
+results of a sourcemap differ depending on the refsection. This is because
+a datasource to which source mapping applies may be used in several
+refsections and source mappings are applied when fetching the data from the
+datasources for a refsection. Citation commands are local to a refsection
+and therefore may differ for the same entry from refsection to refsection.
+For example, the same entry may be \cmd{cite}d in one refsection but
+\cmd{nocite}d in another, resulting in different source map results and
+therefore data between the refsections. This can be avoided if desired, by
+limiting source maps to specific refsections only (see \opt{refsection}
+option to the \cmd{map} command above).
\begin{itemize}
\item If \texttt{entrynew} is set, a new entry is created with the entry key \texttt{entrynewkey} and the entry type given in the option \texttt{entrynewtype}. This
@@ -7990,6 +8118,9 @@ command above).
of an entry was specifically cited via \cmd{cite} or specifically nocited via \cmd{nocite}.
\item If \texttt{allnocited} is used then only apply the step if the entry key
of an entry was included via \cmd{nocite\{*\}}.
+\item If \texttt{starnocited} is used then only apply the step if the entry key
+ of an entry was included solely because of \cmd{nocite\{*\}}. This
+ implies that the entry was neither explicitly \cmd{cite}ed nor explicitly \cmd{nocite}ed.
\item Change the \texttt{typesource} \prm{entrytype} to the
\texttt{typetarget} \prm{entrytype}, if defined. If
\texttt{final} is \texttt{true} then if the \prm{entrytype} of the entry is not \texttt{typesource}, processing of the parent \cmd{map} immediately terminates.
@@ -8392,7 +8523,7 @@ The data model which \biblatex uses consists of four main elements:
The default data model is defined in the core \biblatex file \file{blx-dm.def} using the macros described in this section. The default data model is described in detail in \secref{bib}. The data model is used internally by \biblatex and also by the backend. In practice, changing the data model means that you can define the entrytypes and fields for your datasources and validate your data against the data model. Naturally, this is not much use unless your style supports any new entrytypes or fields and it raises issues of portability between styles (although this can be mitigated by using the dynamic data modification functionality described in \secref{aut:ctm:map}).
-Note that while the \biber/\bibtex input site is not case sensitive when it comes to entry types and field names, the \latex side is case sensitive and uses the exact capitalisation from the data model. At the moment custom data fields are only supported in lowercase.
+Note that while the \biber/\bibtex input site is not case sensitive when it comes to entry types and field names (Perl's Unicode case folding is used to normalise field names and entry types), the \latex side is case sensitive and uses the exact capitalisation from the data model.
Validation against the data model means that after mapping your data sources into the data model, \biber (using its \path{--validate_datamodel} option) can check:
@@ -9345,6 +9476,8 @@ An example of transliterating titles so that they sort correctly in Sanskrit. Th
\end{ltxsyntax}
\begin{table}
+\caption{Valid transliteration pairs}
+\label{tab:translit}
\tablesetup\centering
\begin{tabular}{lll}
\toprule
@@ -9357,8 +9490,6 @@ russian & ala-lc & ALA-LC romanisation for Russian\\
russian & bgn/pcgn-standard & BGN/PCGN:1947 (Standard Variant), Cyrillic to Latin, Russian\\
\bottomrule
\end{tabular}
-\caption{Valid transliteration pairs}
-\label{tab:translit}
\end{table}
\subsubsection[Bibliography List Filters]{Bibliography List Filters}
@@ -10020,10 +10151,18 @@ Expands to \prm{true} if the two dates \prm{datetype1} and \prm{datetype2} would
Expands to \prm{true} if the two dates \prm{datetype1} and \prm{datetype2} have the same year and era. Since the sign of the date is saved in the era field, years should be compared using this command to avoid confusion when the two years have opposite signs
+\cmditem{ifdatesequal}{datetype1}{datetype2}{true}{false}
+
+Expands to \prm{true} if the two dates \prm{datetype1} and \prm{datetype2} are the same. Here \prm{datetype2} may be the <end> bit of \prm{datetype1} (or vice versa).
+
+\cmditem{ifdaterangesequal}{datetype1}{datetype2}{true}{false}
+
+Expands to \prm{true} if the two date ranges---that is the start and the end date---\prm{datetype1} and \prm{datetype2} are the same.
+
\cmditem{ifcaselang}[language]{true}{false}
-Expands to \prm{true} if the the optional \prm{language} is one of those
+Expands to \prm{true} if the optional \prm{language} is one of those
declared by \cmd{DeclareCaseLangs} (see \secref{aut:aux:msc}) and to
\prm{false} otherwise. Without the optional argument, checks the current
value of \cmd{currentlang}.
@@ -10166,7 +10305,7 @@ Expands to \prm{true} if there is only one work by the \opt{labelname} name with
\cmditem{ifuniqueprimaryauthor}{true}{false}
-Expands to \prm{true} if there is only one work by the the primary (first) author name of \opt{labelname} and to \prm{false} otherwise. Only the base name parts of the author name are considered, as defined by \cmd{DeclareUniquenameTemplate} see \secref{aut:cav:amb}. If \opt{labelname} is not set for an entry, this will always expand to \prm{false}. Note that this feature needs to be enabled explicitly with the package option \opt{uniqueprimaryauthor}.
+Expands to \prm{true} if the primary (first) author name of \opt{labelname} is unique in the bibliography list and to \prm{false} otherwise. This effectively answers the question <is there more than one author with the same base name>. The base name parts are defined by \cmd{DeclareUniquenameTemplate} see \secref{aut:cav:amb}. This is required by some styles (e.g. APA) which mandates primary author disambiguation only and only if there are (different) primary authors with the same family name. If \opt{labelname} is not set for an entry, this will always expand to \prm{false}. Note that this feature needs to be enabled explicitly with the package option \opt{uniqueprimaryauthor}.
\cmditem{ifandothers}{list}{true}{false}
@@ -10274,11 +10413,11 @@ Executes \prm{true} if the \prm{string} is an Arabic or Roman numeral, and \prm{
\cmditem{ifnumerals}{string}{true}{false}
-Executes \prm{true} if the \prm{string} is a range or a list of Arabic or Roman numerals, and \prm{false} otherwise. This command is robust. In contrast to \cmd{ifnumeral}, it will also execute \prm{true} with arguments like «52--58», «14/15», «1,~3,~5», and so on. See also \cmd{DeclareNumChars}, \cmd{DeclareRangeChars}, \cmd{DeclareRangeCommands}, and \cmd{NumCheckSetup} in \secref{aut:aux:msc}.
+Executes \prm{true} if the \prm{string} is a range or a list of Arabic or Roman numerals, and \prm{false} otherwise. This command is robust. In contrast to \cmd{ifnumeral}, it will also execute \prm{true} with arguments like «52--58», «14/15», «1,~3,~5», and so on. See also \cmd{DeclareNumChars}, \cmd{DeclareRangeChars}, \cmd{DeclareRangeCommands}, \cmd{NumCheckSetup}, and \cmd{NumsCheckSetup} in \secref{aut:aux:msc}.
\cmditem{ifpages}{string}{true}{false}
-Similar to \cmd{ifnumerals}, but also considers \cmd{DeclarePageCommands} from \secref{aut:aux:msc}.
+Similar to \cmd{ifnumerals}, but also considers \cmd{DeclarePageCommands} and \cmd{PagesCheckSetup} from \secref{aut:aux:msc}.
\cmditem{iffieldint}{field}{true}{false}
@@ -10323,7 +10462,7 @@ Executes \prm{true} if \biblatex's punctuation tracker would capitalize a locali
\cmditem{ifcitation}{true}{false}
Expands to \prm{true} when located in a citation, and to \prm{false} otherwise. Note that this command is responsive to the outermost context in which it is used. For example, if a citation command defined with \cmd{DeclareCiteCommand} executes a driver defined with \cmd{DeclareBibliographyDriver}, any \cmd{ifcitation} tests in the driver code will yield \prm{true}. See \secref{aut:cav:mif} for a practical example.
-
+
\cmditem{ifvolcite}{true}{false}
Expands to \prm{true} when located in \cmd{volcite} or a related citation command (\secref{use:cit:spc}), and to \prm{false} otherwise.
@@ -10529,7 +10668,11 @@ Similar to \cmd{MakeUppercase} but only converts the first printable character i
\cmditem{MakeSentenceCase}{text}
\cmditem*{MakeSentenceCase*}{text}
-Converts its \prm{text} argument to sentence case, \ie the first word is capitalized and the remainder of the string is converted to lowercase. This command is robust. The starred variant differs from the regular version in that it considers the language of the entry, as specified in the \bibfield{langid} field. If the \bibfield{langid} field is defined and holds a language declared with \cmd{DeclareCaseLangs} (see below)\footnote{By default, converting to sentence case is enabled for the following language identifiers: \texttt{american}, \texttt{british}, \texttt{canadian}, \texttt{english}, \texttt{australian}, \texttt{newzealand} as well as the aliases \texttt{USenglish} and \texttt{UKenglish}. Use \cmd{DeclareCaseLangs} to extend or change this list.}, then the sentence case conversion is performed. If the \bibfield{langid} field is undefined, then the language list declared with \cmd{DeclareCaseLangs} is checked for the presence of the main document language derived from the \opt{language} option. If found, sentence case conversion is performed, if not, the \prm{text} is not altered in any way. It is recommended to use \cmd{MakeSentenceCase*} rather than the regular variant in formatting directives. Both variants support the traditional \bibtex convention for \file{bib} files that anything wrapped in a pair of curly braces is not modified when changing the case. For example:
+Converts its \prm{text} argument to sentence case, \ie the first word is capitalized and the remainder of the string is converted to lowercase. This command is robust. The starred variant differs from the regular version in that it considers the language of the entry, as specified in the \bibfield{langid} field. If the \bibfield{langid} field is defined and holds a language declared with \cmd{DeclareCaseLangs} (see below)\footnote{By default, converting to sentence case is enabled for the following language identifiers: \texttt{american}, \texttt{british}, \texttt{canadian}, \texttt{english}, \texttt{australian}, \texttt{newzealand} as well as the aliases \texttt{USenglish} and \texttt{UKenglish}. Use \cmd{DeclareCaseLangs} to extend or change this list.}, then the sentence case conversion is performed. If the \bibfield{langid} field is undefined, then the language list declared with \cmd{DeclareCaseLangs} is checked for the presence of the main document language derived from the \opt{language} option. If found, sentence case conversion is performed, if not, the \prm{text} is not altered in any way. It is recommended to use \cmd{MakeSentenceCase*} rather than the regular variant in formatting directives.
+
+Depending on the option \opt{casechanger} \cmd{MakeCaseChange} and \cmd{MakeCaseChange*} are either implemented using the \sty{expl3} module \sty{l3text} or original \LaTeXe code.
+
+Both variants support the traditional \bibtex convention for \file{bib} files that anything wrapped in a pair of curly braces is not modified when changing the case. For example:
\begin{ltxexample}
\MakeSentenceCase{an Introduction to LaTeX}
@@ -10554,14 +10697,18 @@ Macros in titles must also be protected with braces
\begin{lstlisting}[style=bibtex]{}
title = {The {\TeX book}},
\end{lstlisting}
+
%
-Unlike \bibtex's built-in case changing function \texttt{change.case\$} \biblatex's \cmd{MakeSentenceCase} is implemented in \latex, it may therefore behave differently in certain situations and is more fragile.
-Currently \cmd{MakeSentenceCase} behaves as follows.
+The behaviour of \cmd{MakeSentenceCase} differs slightly between the \opt{latex2e} and \opt{expl3} implementation. Generally speaking, the \opt{expl3} code is closer to the \bibtex behaviour of \texttt{change.case\$}. It is also better equipped to deal with non-ASCII input and macros than the \opt{latex2e} implementation. \cmd{MakeSentenceCase} behaves as follows.
\begin{itemize}\setlength{\labelsep}{1em}
- \item The first letter of its argument is capitalised with \cmd{MakeUppercase}. This is different from \bibtex's \texttt{change.case\$}, which does not touch the first letter of its argument. Note that a pair of braces that starts with a control sequence will be treated as one character for capitalisation purposes. This means that the entire argument of a command protected with a single pair of braces is capitalised.
- \item Expandable commands are expanded before the case change, which means that the case change applies to the replacement text. Unexpandable commands are not touched. \bibtex does not interpret macros and therefore passes commands through unchanged (this does not necessarily apply to the \emph{arguments} of those commands).
- \item Text wrapped in one or more pairs of braces is protected from case change unless it starts with a control sequence. This is the same behaviour as with \bibtex. Note that the braces could either be explicit groups or argument delimiters.
- \item Text in a single pair of braces that starts with a control sequence is not protected and will be subject to case changes. Note that this need not apply to braces that are argument delimiters, in fact the implementation of \cmd{MakeSentenceCase} may in some cases produce an error or otherwise undesirable output if the argument of a command starts with a control sequence. \bibtex's case change function does not differentiate between argument delimiters and brace groups and always subjects text at brace level~1 to case change if it starts with a control sequence.
+ \item The first letter of its argument is capitalised with \cmd{MakeUppercase}. This is different from \bibtex's \texttt{change.case\$}, which does not touch the first letter of its argument.
+
+ Note that with the \opt{latex2e} code a pair of braces that starts with a control sequence will be treated as a single character for capitalisation purposes. This means that the entire argument of a command protected with a single pair of braces is capitalised.
+ \item With the \opt{latex2e} code expandable commands are expanded before the case change, which means that the case change applies to the replacement text. Unexpandable commands are not touched.
+
+ \bibtex does not interpret macros and therefore passes commands through unchanged (this does not necessarily apply to the \emph{arguments} of those commands). The \opt{expl3} implementation also does not expand commands and only applies case change to the arguments.
+ \item Text wrapped in one or more pairs of braces is protected from case change \emph{unless} it starts with a control sequence. This is the same behaviour as with \bibtex. Note that the braces could either be explicit groups or argument delimiters.
+ \item Text in a single pair of braces that starts with a control sequence is not protected and will be subject to case changes. Note that this need not apply to braces that are argument delimiters, in fact the \opt{latex2e} implementation of \cmd{MakeSentenceCase} may in some cases produce an error or otherwise undesirable output if the argument of a command starts with a control sequence. \bibtex's case change function does not differentiate between argument delimiters and brace groups and always subjects text at brace level~1 to case change if it starts with a control sequence.
\end{itemize}
For most intents and purposes the following rules should give a sensible result.
@@ -10574,17 +10721,25 @@ For most intents and purposes the following rules should give a sensible result.
\end{itemize}
\item While it is possible to protect words from case change at the beginning of a field with a pair of braces, it is not possible to undo the case protection that a command automatically implies by wrapping it in braces in that position. In that case work-arounds are necessary.
\end{itemize}
-
-
+%
\begin{lstlisting}[style=bibtex]{}
-title = {The Story of {HMS} \emph{Erebus} in {\emph{Really}} Strong Wind},
+title = {The Story of {HMS} \emph{Erebus}
+ in {\emph{Really}} Strong Wind},
\end{lstlisting}
would be converted to sentence case by \cmd{MakeSentenceCase} as
\begin{quote}
The story of HMS \emph{Erebus} in {\emph{really}} strong wind
\end{quote}
-Due to its complex implementation this command can not accept arbitrary input, it only safely operates on raw text or field data. In the standard styles the \bibfield{title} and other \bibfield{title}-like field formats do not work together with \cmd{MakeSentenceCase} because of their argument structure, so the standard styles offer a dedicated \texttt{titlecase} field format to apply this command. To enable sentence casing in standard styles for languages that support it you would use:
+If the \sty{expl3} implementation of the case changing functions is selected, the \bibtex case protection behaviour can be exchanged for a slightly simpler version. When \opt{bibtexcaseprotection} set to \opt{false}, braces no longer automatically imply case protection. Instead words can be protected from case change with \cmd{NoCaseChange}. The examples from above would then read
+\begin{lstlisting}[style=bibtex]{}
+title = {An Introduction to \NoCaseChange{LaTeX}},
+title = {The Story of \NoCaseChange{HMS \emph{Erebus}}
+ in \emph{Really} Strong Wind},
+\end{lstlisting}
+Generally, this option should allow for a saner case protection input, because curly braces are no longer overloaded with different levels of meaning, but it is a big departure from the standard case protection input that has been with the \latex world for a long time.
+
+Due to its complex implementation \cmd{MakeSentenceCase} can not accept arbitrary input, it only safely operates on raw text or field data. In the standard styles the \bibfield{title} and other \bibfield{title}-like field formats do not work together with \cmd{MakeSentenceCase} because of their argument structure, so the standard styles offer a dedicated \texttt{titlecase} field format to apply this command. To enable sentence casing in standard styles for languages that support it you would use:
\begin{ltxexample}
\DeclareFieldFormat{titlecase}{<<\MakeSentenceCase*{#1}>>}
\end{ltxexample}
@@ -10617,6 +10772,8 @@ The optional argument \bibfield{bookpagination} is omissible in this case.
The pagination strings are taken from \texttt{$<$pagination$>$total} and \texttt{$<$pagination$>$totals}.
\begin{table}
+\caption{\cmd{mkcomprange} setup}
+\label{aut:aux:tab1}
\tablesetup\lnstyle
\begin{tabularx}{\textwidth}{@{}>{\ttfamily}X@{}p{0.25\textwidth}@{}p{0.25\textwidth}@{}p{0.25\textwidth}@{}}
\toprule
@@ -10648,8 +10805,6 @@ The pagination strings are taken from \texttt{$<$pagination$>$total} and \texttt
1111--1555 & 1111--555 & 1111--555 & 1111--555 \\
\bottomrule
\end{tabularx}
-\caption{\cmd{mkcomprange} setup}
-\label{aut:aux:tab1}
\end{table}
\cmditem{mkcomprange}[postpro][itempostpro]{text}
@@ -10782,6 +10937,35 @@ This command is similar to \cmd{DeclareRangeCommands}, except that it only affec
Use this command to temporarily redefine any commands which interfere with the tests performed by \cmd{ifnumeral}, \cmd{ifnumerals}, and \cmd{ifpages} from \secref{aut:aux:tst}. The setup will also affect \cmd{iffieldnum}, \cmd{iffieldnums}, \cmd{iffieldpages} as well as \cmd{mkpageprefix} and \cmd{mkpagetotal}. The \prm{code} will be executed in a group by these commands. Since the above mentioned commands will expand the string to be analyzed, it is possible to remove commands to be ignored by the tests by making them expand to an empty string. See also \secref{bib:use:pag, use:cav:pag} for further details.
+\cmditem{NumsCheckSetup}{code}
+
+Like \cmd{NumCheckSetup} but only applies to \cmd{ifnumerals} and \cmd{ifpages} from \secref{aut:aux:tst} and their derivative tests.
+
+\cmditem{PagesCheckSetup}{code}
+
+Like \cmd{NumCheckSetup} but only applies to \cmd{ifpages} from \secref{aut:aux:tst} and its derivative tests. The default setting is makes \cmd{pnfmt} transparent to the test:
+
+\begin{ltxexample}
+\PagesCheckSetup{\let\pnfmt\@firstofone}
+\end{ltxexample}
+
+\cmditem{DeclareBabelToExplLanguageMapping}{babel language}{expl language}
+
+This command is only available if the \sty{expl3} case changing code is used.
+
+Use \prm{expl language} as \prm{language} argument for the \sty{l3text} case changing functions when \sty{babel language} is active. This command is only required if \prm{babel language} should correspond to a language for which \sty{l3text} has special rules set up. The default invocations of this command are
+\begin{ltxexample}
+\DeclareBabelToExplLanguageMapping{dutch}{nl}
+\DeclareBabelToExplLanguageMapping{greek}{el}
+\DeclareBabelToExplLanguageMapping{turkish}{tr}
+\end{ltxexample}
+
+\cmditem{UndeclareBabelToExplLanguageMapping}{babel language}
+
+This command is only available if the \sty{expl3} case changing code is used.
+
+Removes the \sty{babel}-to-\sty{expl3} language mapping for \prm{babel language}. If the argument is an asterisk \texttt{*}, all language mappings are removed.
+
\cmditem{DeclareCaseLangs}{languages}
\cmditem*{DeclareCaseLangs*}{languages}
@@ -11091,7 +11275,7 @@ This command marks the middle of a sentence. A localisation string immediately a
\csitem*{midsentence*}
-The starred variant of \cmd{midsentence} differs from the regular one in that a preceding abbreviation dot is not hidden from the the punctuation tracker, \ie any code after \cmd{midsentence*} will see a preceding abbreviation dot. All other punctuation marks are hidden from the punctuation tracker and capitalization is suppressed.
+The starred variant of \cmd{midsentence} differs from the regular one in that a preceding abbreviation dot is not hidden from the punctuation tracker, \ie any code after \cmd{midsentence*} will see a preceding abbreviation dot. All other punctuation marks are hidden from the punctuation tracker and capitalization is suppressed.
\end{ltxsyntax}
@@ -11116,6 +11300,18 @@ Similar to \cmd{bibstring} but always prints the long string, ignoring the \opt{
Similar to \cmd{bibstring} but always prints the short string, ignoring the \opt{abbreviate} option.
+\cmditem{bibncpstring}[wrapper]{key}
+
+Similar to \cmd{bibstring} but the term is never capitalized.
+
+\cmditem{bibncplstring}[wrapper]{key}
+
+Similar to \cmd{biblstring} but the term is never capitalized.
+
+\cmditem{bibncpsstring}[wrapper]{key}
+
+Similar to \cmd{bibsstring} but the term is never capitalized.
+
\cmditem{bibcpstring}[wrapper]{key}
Similar to \cmd{bibstring} but the term is always capitalized.
@@ -11765,14 +11961,17 @@ Other expressions frequently used in citations:
\item[langjapanese] The language <Japanese>.
\item[langlatin] The language <Latin>.
\item[langlatvian] The language <Latvian>.
+\item[langlithuanian] The language <Lithuanian>.
\item[langnorwegian] The language <Norwegian>.
\item[langpolish] The language <Polish>.
\item[langportuguese] The language <Portuguese>.
\item[langrussian] The language <Russian>.
+\item[langserbian] The language <Serbian>.
\item[langslovak] The language <Slovak>.
\item[langslovene] The language <Slovene>.
\item[langspanish] The language <Spanish>.
\item[langswedish] The language <Swedish>.
+\item[langturkish] The language <Turkish>.
\item[langukrainian] The language <Ukrainian>.
\end{keymarglist}
%
@@ -11798,14 +11997,17 @@ The following strings are intended for use in phrases like <translated from [the
\item[fromjapanese] The expression <from [the] Japanese>.
\item[fromlatin] The expression <from [the] Latin>.
\item[fromlatvian] The expression <from [the] Latvian>.
+\item[fromlithuanian] The language <from [the] Lithuanian>.
\item[fromnorwegian] The expression <from [the] Norwegian>.
\item[frompolish] The expression <from [the] Polish>.
\item[fromportuguese] The expression <from [the] Portuguese>.
\item[fromrussian] The expression <from [the] Russian>.
+\item[fromserbian] The expression <from [the] Serbian>.
\item[fromslovak] The expression <from [the] Slovak>.
\item[fromslovene] The expression <from [the] Slovene>.
\item[fromspanish] The expression <from [the] Spanish>.
\item[fromswedish] The expression <from [the] Swedish>.
+\item[fromturkish] The expression <from [the] Turkish>.
\item[fromukrainian] The expression <from [the] Ukrainian>.
\end{keymarglist}
@@ -11984,6 +12186,9 @@ The separator to be printed before the \bibfield{pages} field. Use this separato
\csitem{bibpagerefpunct}
The separator to be printed before the \bibfield{pageref} field. Use this separator instead of \cmd{newunitpunct} at this location. The default is an interword space.
+\csitem{bibeidpunct}
+The separator printed before the \bibfield{eid} field (similar to \cmd{bibpagespunct}). The default is a comma plus an interword space.
+
\csitem{multinamedelim}\CSdelimMark
The delimiter to be printed between multiple items in a name list like \bibfield{author} or \bibfield{editor} if there are more than two names in the list. If there are only two names in the list, use the \cmd{finalnamedelim} instead. This command should be incorporated in all formatting directives for name lists. The default is a comma followed by an interword space.
@@ -12008,9 +12213,27 @@ The delimiter to be printed before the localisation string <\texttt{andmore}> if
\csitem{multicitedelim}
The delimiter printed between citations if multiple entry keys are passed to a single citation command. This command should be incorporated in the definition of all citation commands, for example in the \prm{sepcode} argument passed to \cmd{DeclareCiteCommand}. See \secref{aut:cbx:cbx} for details. The default is a semicolon plus an interword space.
+\csitem{multiciterangedelim}
+The delimiter printed between two citations if they are compressed to a range. The default is \cmd{bibrangedash}.
+
+\csitem{multicitesubentrydelim}
+The delimiter printed between subentry citations of the same set. This delimiter is only used in citation styles that reduce citations of the same set to a more compact form (\opt{subentry} of \texttt{numeric-comp}). The default is a comma.
+
+\csitem{multicitesubentryrangedelim}
+The delimiter printed between two citations of the same set if they are compressed to a range. The default is \cmd{multiciterangedelim}.
+
\csitem{supercitedelim}
Similar to \cmd{multinamedelim}, but intended for the \cmd{supercite} command only. The default is a comma.
+\csitem{superciterangedelim}
+Analogue of \cmd{multiciterangedelim} for \cmd{supercite}. The default is \cmd{bibrangedash}.
+
+\csitem{supercitesubentrydelim}
+Analogue of \cmd{multicitesubentrydelim} for \cmd{supercite}. The default is \cmd{supercitedelim}.
+
+\csitem{supercitesubentryrangedelim}
+Analogue of \cmd{multicitesubentryrangedelim} for \cmd{supercite}. The default is \cmd{superciterangedelim}.
+
\csitem{compcitedelim}
Similar to \cmd{multicitedelim}, but intended for citation styles that <compress> multiple citations, \ie print the author only once if subsequent citations share the same author etc. The default definition is a comma plus an interword space.
@@ -12664,6 +12887,7 @@ The default setting is:
\begin{ltxexample}
\AtUsedriver{%
+ \delimcontext{bib}%
\let\finentry\blx@finentry@usedrv
\let\newblock\relax
\let\abx@macro@bibindex\@empty
@@ -12753,8 +12977,74 @@ Executes the internal hook corresponding to \cmd{AtVolcite}.
Locally un-defines the internal hook specified by \cmd{AtNextCitekey}. This essentially defers the hook to the next entry key in the citation list, when executed in the \prm{precode} argument of \cmd{DeclareCiteCommand} (\secref{aut:cbx:cbx}).
+\cmditem{AtEveryEntrykey}{code}{success}{failure}
+
+Appends \prm{code} to an internal hook executed every time an entrykey is processed for a citation command or \cmd{nocite}. The \prm{code} is passed one argument (\lstinline{#1}), which contains the entrykey. If the code can be appended to the hook \prm{success} is executed, otherwise \prm{failure} is executed. Unlike \cmd{AtEveryCitekey} the entry data of the current entrykey is not available when \prm{code} is processed, indeed it is not even known whether or not there is any entry data at all.
+
+\end{ltxsyntax}
+
+\subsubsection{File hooks}
+\label{aut:fmt:hok:fil}
+\biblatex has rudimentary support for injecting arbitrary code before and after a file is loaded via file hooks. For files that are loaded using \biblatex's file interface---that includes all bibliography and citation styles---the following three hooks are available
+
+\begin{ltxsyntax}
+\cmditem{blx@filehook@preload@$<$filename with extension$>$}
+
+If \file{$<$filename with extension$>$} is found, this hook is exected before it is loaded.
+
+\cmditem{blx@filehook@postload@$<$filename with extension$>$}
+
+If \file{$<$filename with extension$>$} is found, this hook is exected after it is loaded.
+
+\cmditem{blx@filehook@failure@$<$filename with extension$>$}
+
+This hook is executed if \file{$<$filename with extension$>$} can not be found.
+\end{ltxsyntax}
+
+\biblatex generally only loads files once even if they were requested multiple times,
+so the hooks will only be executed once.
+Naturally, the file hooks need to be populated before the files are loaded, so the safest would be to populate them before \biblatex is loaded.
+It is advisable to only append code to avoid overwriting previous hook contents.
+Since the name of the file hook include the dot and the file extension they will usually have to be defined with a command like \cmd{csappto} from \sty{etoolbox}.
+
+The \file{.lbx} files are special and may have to be loaded several times in some situations.
+Their file hooks are
+
+\begin{ltxsyntax}
+\cmditem{blx@lbxfilehook@once@preload@$<$filename with extension$>$}
+
+If \file{$<$filename with extension$>$} is found, this hook is exected before it is loaded in a situation where the \file{.lbx} files are loaded only once.
+
+\cmditem{blx@lbxfilehook@once@postload@$<$filename with extension$>$}
+
+If \file{$<$filename with extension$>$} is found, this hook is exected after it is loaded in a situation where the \file{.lbx} files are loaded only once.
+
+\cmditem{blx@lbxfilehook@once@failure@$<$filename with extension$>$}
+
+This hook is executed if \file{$<$filename with extension$>$} can not be found in a situation where the \file{.lbx} files are loaded only once.
+
+\cmditem{blx@lbxfilehook@simple@preload@$<$filename with extension$>$}
+
+If \file{$<$filename with extension$>$} is found, this hook is exected before it is loaded in a situation where the \file{.lbx} files may be loaded multiple times.
+
+\cmditem{blx@lbxfilehook@simple@postload@$<$filename with extension$>$}
+
+If \file{$<$filename with extension$>$} is found, this hook is exected after it is loaded in a situation where the \file{.lbx} files may be loaded multiple times.
+
+\cmditem{blx@lbxfilehook@simple@failure@$<$filename with extension$>$}
+
+This hook is executed if \file{$<$filename with extension$>$} can not be found in a situation where the \file{.lbx} files may be loaded multiple times.
\end{ltxsyntax}
+The following code sets up \sty{beamer} to print the bibliography labels instead of its bibliography icons when \file{numeric.bbx} after is loaded
+\begin{ltxexample}
+\csappto{blx@filehook@postload@numeric.bbx}{%
+ \mode<presentation>{%
+ \setbeamertemplate{bibliography item}{%
+ \insertbiblabel}}}
+\end{ltxexample}
+
+
\subsection{Hints and Caveats}
\label{aut:cav}
@@ -12860,7 +13150,7 @@ Only use the \prm{namepart} in constructing the uniquename information if there
\boolitem[false]{base}
-The \prm{namepart} is part of the <base> which is the main piece of namepart(s) information which is being disambiguated by uniqueness information. For example, a family name which may be disambiguated by further given names. <base> \prm{namepart}s must occur before any non-<base> \prm{nameparts}.
+The \prm{namepart} is part of the <base> which is the main piece of namepart(s) information which is being disambiguated by uniqueness information. For example, a family name which may be disambiguated by further given names. <base> \prm{namepart}s must occur before any non-<base> \prm{nameparts}. There \emph{must} be at least one <base> \prm{namepart} and \biber will report an error if this is not the case.
\choitem{disambiguation}{none, init, initorfull, full}
@@ -13122,7 +13412,7 @@ In the last citation, \kvopt{uniquelist}{minyear} does not override \opt{maxname
\subsubsection{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 get ambiguous because floats are objects which are (physically and logically) placed outside the flow of text, hence the logic of such references applies poorly to them. To avoid any such ambiguities, the citation and page trackers are temporarily disabled in all floats. In addition to that, these trackers plus the back reference tracker (\opt{backref}) are temporarily disabled in the table of contents, the list of figures, and the list of tables.
+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 get ambiguous because floats are objects which are (physically and logically) placed outside the flow of text, hence the logic of such references applies poorly to them. To avoid any such ambiguities, the citation and page trackers are temporarily disabled in all floats unless explicitly requested with \opt{trackfloats}. In addition to that, these trackers plus the back reference tracker (\opt{backref}) are temporarily disabled in the table of contents, the list of figures, and the list of tables.
\subsubsection{Mixing Programming Interfaces}
\label{aut:cav:mif}
@@ -14022,8 +14312,10 @@ backrefsetstyle &\+&\+&\_&\_&\_&\_&\_\\
backrefstyle &\+&\+&\_&\_&\_&\_&\_\\
bibencoding &\+&\+&\_&\_&\_&\_&\_\\
bibstyle &\+&\_&\_&\_&\_&\_&\_\\
+bibtexcaseprotection &\+&\+&\_&\+&\+&\_&\_\\
bibwarn &\+&\+&\_&\_&\_&\_&\_\\
block &\+&\+&\_&\_&\_&\_&\_\\
+casechanger &\+&\_&\_&\_&\_&\_&\_\\
citecounter &\+&\+&\_&\_&\_&\_&\_\\
citereset &\+&\+&\_&\_&\_&\_&\_\\
citestyle &\+&\_&\_&\_&\_&\_&\_\\
@@ -14135,6 +14427,35 @@ use$<$name$>$ &\+&\+&\_&\+&\+&\_&\_\\
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. More technical details are to be found in the \file{CHANGES.md} file. The numbers on the right indicate the relevant section of this manual.
\begin{changelog}
+\begin{release}{3.15}{2020-08-16}
+\item Added \opt{starnocited} option to sourcemaps\see{aut:ctm:map}
+\item Added the \opt{glob} option to \cmd{addbibresource}\see{use:bib:res}
+\item Added \bibfield{eid} to more entry types\see{bib:typ:blx}
+\item Added \cmd{bibeidpunct}\see{use:fmt:fmt}
+\item Added \bibfield{issuetitleaddon} and \bibfield{journaltitleaddon}\see{bib:fld:dat}
+\item \texttt{numeric-comp} compresses \opt{subentry} set references now\see{use:opt:pre:bbx}
+\item Added \opt{subentrycomp} to \texttt{numeric-comp} style\see{use:opt:pre:bbx}
+\item Added \cmd{multiciterangedelim}, \cmd{multicitesubentrydelim},
+ \cmd{multicitesubentryrangedelim}, \cmd{superciterangedelim},
+ \cmd{supercitesubentrydelim}, \cmd{supercitesubentryrangedelim}%
+ \see{use:fmt:fmt}
+\item Implemented \opt{expl3} case changing functions\see{aut:aux:msc}
+\item Added \opt{casechanger} option\see{use:opt:ldt}
+\item Added \opt{bibtexcaseprotection} option\see{use:opt:pre:gen}
+\item Added \cmd{mautocite} and \cmd{Mautocite}\see{use:cit:mct}
+\item Added \opt{trackfloats} and \opt{backreffloats}\see{use:opt:pre:gen}
+\item Added \opt{block} option to \cmd{printbibliography} and friends\see{use:bib:bib}
+\item Added \cmd{NumsCheckSetup} and \cmd{PagesCheckSetup}\see{aut:aux:msc}
+\item Added \cmd{AtEveryEntrykey}\see{aut:fmt:hok}
+\item Added \cmd{ifdatesequal} and \cmd{ifdaterangesequal}\see{aut:aux:tst}
+\item Clarified \cmd{ifuniqueprimaryauthor} semantics\see{aut:aux:tst}
+\item Added \cmd{bibncpstring}, \cmd{bibncplstring} and \cmd{bibncpsstring}\see{aut:str}
+\item Added Lithuanian localisation (Valdemaras Klumbys)
+\item Added Serbian localisation (Andrej Radović)
+\item Added Turkish localisation (Abdulkerim Gok)
+\item Added file hooks\see{aut:fmt:hok:fil}
+\item Deprecated \cmd{ifkomabibtotoc} and \cmd{ifkomabibtotocnumbered}\see{use:cav:scr}
+\end{release}
\begin{release}{3.14}{2019-12-01}
\item Added new mapping verbs for citation sources\see{aut:ctm:map}
\item Added documentation for new \biber granular \bibtype{xdata} functionality\see{use:use:xdat}