new2-Introduction.tex

\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{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}
\label{int:abt}

This package provides advanced bibliographic facilities for use with \latex. The package is a complete reimplementation of the bibliographic facilities provided by \latex. The \biblatex\ package works with the \enquote{backend} (program) \biber, which is used to process \bibtex\ format data files and them performs all sorting, label generation (and a great deal more). Formatting of the bibliography is entirely controlled by \tex\ macros. Good working knowledge in \latex should be sufficient to design new bibliography and citation styles. This package also supports subdivided bibliographies, multiple bibliographies within one document, and separate lists of bibliographic information such as abbreviations of various fields. Bibliographies may be subdivided into parts and\slash or segmented by topics. Just like the bibliography styles, all citation commands may be freely defined. Features such as full Unicode support for bibliography data, customisable sorting, multiple bibliographies with different sorting, customisable labels and dynamic data modification are available. Please refer to \secref{int:pre:bibercompat} for information on \biber/\biblatex version compatibility. The package is completely localised and can interface with the \sty{babel} and \sty{polyglossia} packages. Please refer to \tabref{bib:fld:tab1} for a list of languages currently supported by this package.

\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{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{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}

The package was originally written by Philipp Lehman and much of his excellent
original code remains in the core. Philip Kime took over the package in
2012 with Moritz Wemheuer making regular and valuable contributions from 2017.
The main authors would like to acknowledge the valuable help of Audrey
Boruvka and Joseph Wright who helped with the transition of ownership in
2012 and following years.

The language modules of this package are made possible thanks to the following contributors:\\
Ander Zarketa-Astigarraga (Basque);
Augusto Ritter Stoffel, Mateus Araújo, Gustavo Barros (Brazilian);
Kaloyan Ganev (Bulgarian);
Sebastià Vila-Marta (Catalan);
Ivo Pletikosić (Croatian);
Michal Hoftich (Czech);
Christian Mondrup, Jonas Nyrup (Danish);
Johannes Wilm (Danish\slash Norwegian);
Alexander van Loon, Pieter Belmans, Hendrik Maryns (Dutch);
Kristian Kankainen, Benson Muite (Estonian);
Hannu Väisänen, Janne Kujanpää (Finnish);
Denis Bitouzé (French);
Apostolos Syropoulos, Prokopis (Greek);
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}
\label{int:pre}

This section gives an overview of all resources required by this package and discusses compatibility issues.

\subsubsection{Requirements}
\label{int:pre:req}

The resources listed in this section are strictly required for \biblatex to function. The package will not work if they are not available.

\begin{marglist}

\item[\etex]
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{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{https://ctan.org/pkg/etoolbox}

\item[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{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{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}

Apart from the above resources, \biblatex also requires the standard \latex packages \sty{keyval} and \sty{ifthen} as well as the \sty{url} package. These package are included in all common \tex distributions and will be loaded automatically.

\subsubsection{Recommended Packages}
\label{int:pre:rec}

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 (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{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{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}

\subsubsection{Compatible Classes and Packages}
\label{int:pre:cmp}

The \biblatex package provides dedicated compatibility code for the classes and packages listed in this section.

\begin{marglist}

\item[hyperref]
The \sty{hyperref} package transforms citations into hyperlinks. See the \opt{hyperref} and \opt{backref} package options in \secref{use:opt:pre:gen} for further details. When using the \sty{hyperref} package, it is preferable to load it after \biblatex.

\item[showkeys]
The \sty{showkeys} package prints the internal keys of, among other things, citations in the text and items in the bibliography. The package loading order does not matter.

\item[memoir]
When using the \sty{memoir} class, the default bibliography headings are adapted such that they blend well with the default layout of this class. See \secref{use:cav:mem} for further usage hints.

\item[\acr{KOMA}-Script]
When using any of the \sty{scrartcl}, \sty{scrbook}, or \sty{scrreprt} classes, the default bibliography headings are adapted such that they blend with the default layout of these classes. See \secref{use:cav:scr} for further usage hints.

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}
\label{int:pre:inc}

The packages listed in this section are not compatible with \biblatex. Since it reimplements the bibliographic facilities of \latex from the ground up, \biblatex naturally conflicts with all packages modifying the same facilities. This is not specific to \biblatex. Some of the packages listed below are also incompatible with each other for the same reason.

\begin{marglist}

\item[babelbib]
The \sty{babelbib} package provides support for multilingual bibliographies. This is a standard feature of \biblatex. Use the \bibfield{langid} field and the package option \opt{autolang} for similar functionality. Note that \biblatex automatically adjusts to the main document language if \sty{babel} or \sty{polyglossia} is loaded. You only need the above mentioned features if you want to switch languages on a per"=entry basis within the bibliography. See \secref{bib:fld:spc, use:opt:pre:gen} for details. Also see \secref{use:lng}.

\item[backref]
The \sty{backref} package creates back references in the bibliography. See the package options \opt{hyperref} and \opt{backref} in \secref{use:opt:pre:gen} for comparable functionality.

\item[bibtopic]
The \sty{bibtopic} package provides support for bibliographies subdivided by topic, type, or other criteria. For bibliographies subdivided by topic, see the category feature in \secref{use:bib:cat} and the corresponding filters in \secref{use:bib:bib}. Alternatively, you may use the \bibfield{keywords} field in conjunction with the \opt{keyword} and \opt{notkeyword} filters for comparable functionality, see \secref{bib:fld:spc, use:bib:bib} for details. For bibliographies subdivided by type, use the \opt{type} and \opt{nottype} filters. Also see \secref{use:use:div} for examples.

\item[bibunits]
The \sty{bibunits} package provides support for multiple partial (\eg per chapter) bibliographies. See \sty{chapterbib}.

\item[chapterbib]
The \sty{chapterbib} package provides support for multiple partial bibliographies. Use the \env{refsection} environment and the \opt{section} filter for comparable functionality. Alternatively, you might also want to use the \env{refsegment} environment and the \opt{segment} filter. See \secref{use:bib:sec, use:bib:seg, use:bib:bib} for details. Also see \secref{use:use:mlt} for examples.

\item[cite]
The \sty{cite} package automatically sorts numeric citations and can compress a list of consecutive numbers to a range. It also makes the punctuation used in citations configurable. For sorted and compressed numeric citations, see the \opt{sortcites} package option in \secref{use:opt:pre:gen} and the \texttt{numeric-comp} citation style in \secref{use:xbx:cbx}. For configurable punctuation, see \secref{use:fmt}.

\item[citeref]
Another package for creating back references in the bibliography. See \sty{backref}.

\item[inlinebib]
The \sty{inlinebib} package is designed for traditional citations given in footnotes. For comparable functionality, see the verbose citation styles in \secref{use:xbx:cbx}.

\item[jurabib]
Originally designed for citations in law studies and (mostly German) judicial documents, the \sty{jurabib} package also provides features aimed at users in the humanities. In terms of the features provided, there are some similarities between \sty{jurabib} and \biblatex but the approaches taken by both packages are quite different. Since both \sty{jurabib} and \biblatex are full"=featured packages, the list of similarities and differences is too long to be discussed here.

\item[mcite]
The \sty{mcite} package provides support for grouped citations, \ie multiple items can be cited as a single reference and listed as a single block in the bibliography. The citation groups are defined as the items are cited. This only works with unsorted bibliographies. The \biblatex package also supports grouped citations, which are called <entry sets> or <reference sets> in this manual. See \secref{use:use:set,use:bib:set,use:cit:mct} for details.

\item[mciteplus]
A significantly enhanced reimplementation of the \sty{mcite} package which supports grouping in sorted bibliographies. See \sty{mcite}.

\item[multibib]
The \sty{multibib} package provides support for bibliographies subdivided by topic or other criteria. See \sty{bibtopic}.

\item[natbib]
The \sty{natbib} package supports numeric and author"=year citation schemes, incorporating sorting and compression code found in the \sty{cite} package. It also provides additional citation commands and several configuration options. See the \texttt{numeric} and \texttt{author-year} citation styles and their variants in \secref{use:xbx:cbx}, the \opt{sortcites} package option in \secref{use:opt:pre:gen}, the citation commands in \secref{use:cit}, and the facilities discussed in \secref{use:bib:hdg, use:bib:nts, use:fmt} for comparable functionality. Also see \secref{use:cit:nat}.

\item[splitbib]
The \sty{splitbib} package provides support for bibliographies subdivided by topic. See \sty{bibtopic}.

\item[titlesec]
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, 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.
The package redefines list handling macros in a way incompatible with \biblatex.

If you must load the \sty{etextools} package at all costs, define the control sequence \cs{blx@noerroretextools} before you load \biblatex.
If \cs{blx@noerroretextools} is defined, no error will be issued if \sty{etextools} is loaded, the message is degraded to a warning instead.
In that case you need to make sure that all redefined macros used by \biblatex\ (currently only \cmd{forlistloop}) have their original \sty{etoolbox} definitions when \biblatex\ is loaded.

\end{marglist}

\subsubsection{Compatibility Matrix for \biber}
\label{int:pre:bibercompat}

\biber\ versions are closely coupled with \biblatex\ versions. You
need to have the right combination of the two. \biber\ will throw a fatal error
during processing if it encounters information which comes from a
\biblatex\ version which is incompatible. \Tabref{tab:int:pre:bibercompat} shows 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.15 & 3.15\\
2.14 & 3.14\\
2.13 & 3.13\\
2.12 & 3.12\\
2.11 & 3.11\\
2.10 & 3.10\\
2.9 & 3.9\\
2.8 & 3.8\\
2.7 & 3.7\\
2.6 & 3.5, 3.6\\
2.5 & 3.4\\
2.4 & 3.3\\
2.3 & 3.2\\
2.2 & 3.1\\
2.1 & 3.0\\
2.0 & 3.0\\
1.9 & 2.9\\
1.8 & 2.8\\
1.7 & 2.7\\
1.6 & 2.6\\
1.5 & 2.5\\
1.4 & 2.4\\
1.3 & 2.3\\
1.2 & 2.1, 2.2\\
1.1 & 2.1\\
1.0 & 2.0\\
0.9.9 & 1.7x\\
0.9.8 & 1.7x\\
0.9.7 & 1.7x\\
0.9.6 & 1.7x\\
0.9.5 & 1.6x\\
0.9.4 & 1.5x\\
0.9.3 & 1.5x\\
0.9.2 & 1.4x\\
0.9.1 & 1.4x\\
0.9 & 1.4x\\
\bottomrule
\end{tabular}
\end{table}