From e244e1c4b6d2aa14172a2a960118781b8aaa12a8 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Sat, 14 Jul 2012 23:27:39 +0000 Subject: biblatex 2.0 (8jul12) git-svn-id: svn://tug.org/texlive/trunk@27055 c570f23f-e606-0410-a88d-b1316a301751 --- Master/texmf-dist/doc/latex/biblatex/biblatex.tex | 2010 ++++++++++++++++++--- 1 file changed, 1768 insertions(+), 242 deletions(-) (limited to 'Master/texmf-dist/doc/latex/biblatex/biblatex.tex') diff --git a/Master/texmf-dist/doc/latex/biblatex/biblatex.tex b/Master/texmf-dist/doc/latex/biblatex/biblatex.tex index 7969dd0631d..6516124f689 100644 --- a/Master/texmf-dist/doc/latex/biblatex/biblatex.tex +++ b/Master/texmf-dist/doc/latex/biblatex/biblatex.tex @@ -1,4 +1,3 @@ -% $Id: biblatex.tex,v 1.7 2011/11/13 19:09:07 lehman stable $ \documentclass{ltxdockit}[2011/03/25] \usepackage{btxdockit} \usepackage[latin9]{inputenc} @@ -9,12 +8,29 @@ \usepackage{booktabs} \usepackage{shortvrb} \usepackage{pifont} +\usepackage{libertine} +\usepackage[scaled=0.8]{beramono} +\usepackage{microtype} +\lstset{basicstyle=\ttfamily,keepspaces=true} +\KOMAoptions{numbers=noenddot} +\addtokomafont{paragraph}{\spotcolor} +\addtokomafont{section}{\spotcolor} +\addtokomafont{subsection}{\spotcolor} +\addtokomafont{subsubsection}{\spotcolor} +\addtokomafont{descriptionlabel}{\spotcolor} +\pretocmd{\cmd}{\sloppy}{}{} +\pretocmd{\bibfield}{\sloppy}{}{} +\pretocmd{\bibtype}{\sloppy}{}{} +\makeatletter +\patchcmd{\paragraph} + {3.25ex \@plus1ex \@minus.2ex}{-3.25ex\@plus -1ex \@minus -.2ex}{}{} +\patchcmd{\paragraph}{-1em}{1.5ex \@plus .2ex}{}{} +\makeatother + \MakeAutoQuote{«}{»} \MakeAutoQuote*{<}{>} \MakeShortVerb{\|} -\rcsid{$Id: biblatex.tex,v 1.7 2011/11/13 19:09:07 lehman stable $} - \newcommand*{\biber}{Biber\xspace} \newcommand*{\biblatex}{Biblatex\xspace} \newcommand*{\biblatexhome}{http://sourceforge.net/projects/biblatex/} @@ -24,15 +40,15 @@ title={The \sty{biblatex} Package}, subtitle={Programmable Bibliographies and Citations}, url={\biblatexhome}, - author={Philipp Lehman}, - email={plehman@gmx.net}, - revision={\rcsrevision}, - date={\rcstoday}} + author={Philipp Lehman (with Audrey Boruvka, Philip Kime and Joseph Wright)}, + email={}, + revision={2.0}, + date={07/2012}} \hypersetup{% pdftitle={The \biblatex Package}, pdfsubject={Programmable Bibliographies and Citations}, - pdfauthor={Philipp Lehman}, + pdfauthor={Philipp Lehman, Philip Kime}, pdfkeywords={tex, latex, bibtex, bibliography, references, citation}} % tables @@ -122,16 +138,16 @@ For a quick start guide, browse \secref{int:abt, bib:typ, bib:fld, bib:use, use: \subsection[About]{About \sty{biblatex}} \label{int:abt} -This package provides advanced bibliographic facilities for use with \latex in conjunction with \bibtex. The package is a complete reimplementation of the bibliographic facilities provided by \latex. It redesigns the way in which \latex interacts with \bibtex at a fairly fundamental level. With \sty{biblatex}, \bibtex is only used to sort the bibliography and to generate labels. Instead of being implemented in \file{bst} files, the formatting of the bibliography is entirely controlled by \latex macros, hence the name \sty{biblatex}. Good working knowledge in \latex should be sufficient to design new bibliography and citation styles. There is no need to learn \bibtex's postfix stack language. This package also supports subdivided bibliographies, multiple bibliographies within one document, and separate lists of bibliographic shorthands. Bibliographies may be subdivided into parts and\slash or segmented by topics. Just like the bibliography styles, all citation commands may be freely defined. The package is completely localized and can interface with the \sty{babel} package. Please refer to \tabref{bib:fld:tab1} for a list of languages currently supported by this package. +This package provides advanced bibliographic facilities for use with \latex in conjunction with \bibtex. The package is a complete reimplementation of the bibliographic facilities provided by \latex. A custom backend \biber by default is used which processed the \bibtex format data files and them performs all sorting, label generation (and a great deal more). Legacy \bibtex is also supported as a backend, albeit with a reduced feature set. Biblatex does not use the backend to format the bibliography information as with traditional \bibtex: instead of being implemented in \bibtex style files, the 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. There is no need to learn \bibtex's postfix stack language. This package also supports subdivided bibliographies, multiple bibliographies within one document, and separate lists of bibliographic shorthands. Bibliographies may be subdivided into parts and\slash or segmented by topics. Just like the bibliography styles, all citation commands may be freely defined. With \biber as the backend, features such as customisable sorting, multiple bibliographies with different sorting, customisable labels, dynamic data modification are available. The package is completely localized and can interface with the \sty{babel} package. Please refer to \tabref{bib:fld:tab1} for a list of languages currently supported by this package. \subsection{License} -Copyright \textcopyright\ 2006--2011 Philipp Lehman. Permission is granted to copy, distribute and\slash or modify this software under the terms of the \lppl, version 1.3.\fnurl{http://www.ctan.org/tex-archive/macros/latex/base/lppl.txt} This package is author"=maintained. +Copyright \textcopyright\ 2006--2012 Philipp Lehman. Permission is granted to copy, distribute and\slash or modify this software under the terms of the \lppl, version 1.3.\fnurl{http://www.ctan.org/tex-archive/macros/latex/base/lppl.txt}. \subsection{Feedback} \label{int:feb} -Please use the \sty{biblatex} project page on SourceForge to report bugs and submit feature requests.\fnurl{http://sourceforge.net/projects/biblatex/} There are two trackers on this page: \texttt{Bugs} for bug reports and \texttt{Features} for feature requests.\fnurl{http://sourceforge.net/tracker2/?group_id=244752} Select a tracker, then click on to submit your report or request. I may consider implementing a new feature if the request is reasonable, seems to be relevant to a considerable number of users, and complies with the architecture and philosophy of \sty{biblatex}. Before making a feature request, please ensure that you have thoroughly studied this manual. If you do not want to report a bug or request a feature but are simply in need of assistance, you might want to consider posting your question on the \texttt{comp.text.tex} newsgroup. I can not provide end-user support by email or via the project page. +Please use the \sty{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} \subsection{Acknowledgments} @@ -149,7 +165,8 @@ Mateus Ara Andrea Marchitelli (Italian), José Carlos Santos (Portuguese), Oleg Domanov (Russian), -Pieter Belmans (Dutch). +Pieter Belmans (Dutch), +Baldur Kristinsson (Icelandic). \subsection{Prerequisites} \label{int:pre} @@ -166,11 +183,11 @@ The resources listed in this section are strictly required for \sty{biblatex} to \item[\etex] The \sty{biblatex} package requires \etex. \tex distributions have been shipping \etex binaries for quite some time, the popular distributions use them by default these days. The \sty{biblatex} package checks if it is running under \etex. Simply try compiling your documents as you usually do, the chances are that it just works. If you get an error message, try compiling the document with \bin{elatex} instead of \bin{latex} or \bin{pdfelatex} instead of \bin{pdflatex}, respectively. -\item[\bibtex] -By default, the \sty{biblatex} package uses \bibtex as a database backend. While a legacy \bibtex binary is sufficient to run \sty{biblatex}, using \bin{bibtex8} is recommended. If your \tex distribution does not ship with \bin{bibtex8}, you can get it from \acr{CTAN}.\fnurl{http://www.ctan.org/tex-archive/biblio/bibtex/8-bit/} +\item[\biber] +\biber is the default backend of \sty{biblatex}. You only need one backend, either \bibtex or \biber. \biber comes with TeXLive and is also available from SourceForge.\fnurl{http://biblatex-biber.sourceforge.net/} -\item[Biber] -Biber is the next"=generation backend of \sty{biblatex}. You only need one backend, either \bibtex or Biber. Biber is available from SourceForge.\fnurl{http://biblatex-biber.sourceforge.net/} +\item[\bibtex] +The \sty{biblatex} package can use legacy \bibtex as a data backend. While a legacy \bibtex binary is sufficient to run \sty{biblatex}, using \bin{bibtex8} is recommended. If your \tex distribution does not ship with \bin{bibtex8}, you can get it from \acr{CTAN}.\fnurl{http://www.ctan.org/tex-archive/biblio/bibtex/8-bit/} \item[etoolbox] This \latex package, which is loaded automatically, provides generic programming facilities required by \sty{biblatex}. It is available from \acr{CTAN}.\fnurl{http://www.ctan.org/tex-archive/macros/latex/contrib/etoolbox/} @@ -285,17 +302,19 @@ The \sty{ucs} package provides support for \utf encoded input. Either use \sty{i \section{Database Guide} \label{bib} -This part of the manual documents the \bibtex interface of this package. Note that you can not use \sty{biblatex} in conjunction with arbitrary \file{bst} files because the package depends on a special \bibtex interface. +It is important to distinguish between \bibtex the program and \bibtex the file format. \sty{biblatex} can be used with or without \bibtex the program since its default backend \biber uses fully supports the \bibtex file format (\file{bib}) and users should be able to move to \sty{biblatex} will little or no changes to their \bibtex data files when using \biber as a backend. If using \bibtex as the data backend, note that you cannot use arbitrary \file{bst} files because the package depends on a special \bibtex interface. When using \bibtex as a backend, \sty{biblatex} uses its own special \file{bst} file only. The entry guide below is backend agnostic unless otherwise stated. + +This section describes the default data model defined in the \file{blx-dm.def} file which is part of \path{biblatex}. The data model is defined using the macros documented in \secref{aut:ctm:dm}. It is possible to redefine the data model which both \sty{biblatex} and \biber use so that datasources can contain new entrytypes and fields (which of course will need style support). The data model specfication also allows for constraints to be defined so that data sources can be validated against the data model (using \biber's \path{--validate_datamodel} option). Users who want to customise the data model need to look at the \file{blx-dm.def} file and to read \secref{aut:ctm:dm}. \subsection{Entry Types} \label{bib:typ} -This section gives an overview of the entry types supported by \sty{biblatex} along with the fields supported by each type. +This section gives an overview of the entry types supported by the default \sty{biblatex} data model along with the fields supported by each type. \subsubsection{Regular Types} \label{bib:typ:blx} -The lists below indicate the fields supported by each entry type. Note that the mapping of fields to an entry type is ultimately at the discretion of the bibliography style. The lists below therefore serve two purposes. They indicate the fields supported by the standard styles which ship with this package and they also serve as a model for custom styles. Note that the fields are not strictly required in all cases, see \secref{bib:use:key} for details. The fields marked as are optional in a technical sense. Bibliographical formatting rules usually require more than just the fields. The standard styles will generally not perform any formal validity checks, but custom styles may do so. Generic fields like \bibfield{abstract} and \bibfield{annotation} or \bibfield{label} and \bibfield{shorthand} are not included in the lists below because they are independent of the entry type. The special fields discussed in \secref{bib:fld:spc}, which are also independent of the entry type, are not included in the lists either. +The lists below indicate the fields supported by each entry type. Note that the mapping of fields to an entry type is ultimately at the discretion of the bibliography style. The lists below therefore serve two purposes. They indicate the fields supported by the standard styles which ship with this package and they also serve as a model for custom styles. Note that the fields are not strictly required in all cases, see \secref{bib:use:key} for details. The fields marked as are optional in a technical sense. Bibliographical formatting rules usually require more than just the fields. The default data model defined a few constraints for the format of date fields, ISBNs and some special fields like \bibfield{gender} but the constraints are only used if validating against the data model with \biber's \path{--validate_datamodel} option. Generic fields like \bibfield{abstract} and \bibfield{annotation} or \bibfield{label} and \bibfield{shorthand} are not included in the lists below because they are independent of the entry type. The special fields discussed in \secref{bib:fld:spc}, which are also independent of the entry type, are not included in the lists either. See the default data model specification in the file \file{blx-dm.def} which comes with \sty{biblatex} for a complete specification. \begin{typelist} @@ -477,7 +496,7 @@ Custom types for special bibliography styles. Not used by the standard styles. \subsubsection{Type Aliases} \label{bib:typ:als} -The entry types listed in this section are provided for backwards compatibility with traditional \bibtex styles. These aliases are resolved by \bibtex as the data is exported. Bibliography styles will see the entry type the alias points to, not the alias name. All unknown entry types are generally exported as \bibtype{misc}. +The entry types listed in this section are provided for backwards compatibility with traditional \bibtex styles. These aliases are resolved by the backend as the data is processed. Bibliography styles will see the entry type the alias points to, not the alias name. All unknown entry types are generally exported as \bibtype{misc}. \begin{typelist} @@ -573,12 +592,12 @@ Audiovisual recordings, typically on \acr{DVD}, \acr{VHS} casette, or similar me \subsection{Entry Fields} \label{bib:fld} -This section gives an overview of the fields supported by \sty{biblatex}. See \secref{bib:fld:typ} for an introduction to the data types supported by this package and \secref{bib:fld:dat, bib:fld:spc} for the actual field listings. +This section gives an overview of the fields supported by the \sty{biblatex} default data model. See \secref{bib:fld:typ} for an introduction to the data types used by the data model specification and \secref{bib:fld:dat, bib:fld:spc} for the actual field listings. \subsubsection{Data Types} \label{bib:fld:typ} -In \file{bib} files all bibliographic data is specified in fields. Some of those fields, for example \bibfield{author} and \bibfield{editor}, may contain a list of items. This list structure is implemented by \bibtex via the keyword <|and|>, which is used to separate the individual items in the list. The \sty{biblatex} package implements three distinct data types to handle bibliographic data: name lists, literal lists, and fields. There are also several list and field subtypes. This section gives an overview of the data types supported by this package. See \secref{bib:fld:dat, bib:fld:spc} for information about the mapping of \bibtex's fields to \sty{biblatex}'s data types. +In datasources such as a \file{bib} file, all bibliographic data is specified in fields. Some of those fields, for example \bibfield{author} and \bibfield{editor}, may contain a list of items. This list structure is implemented by the \bibtex file format via the keyword <|and|>, which is used to separate the individual items in the list. The \sty{biblatex} package implements three distinct data types to handle bibliographic data: name lists, literal lists, and fields. There are also several list and field subtypes. This section gives an overview of the data types supported by this package. See \secref{bib:fld:dat, bib:fld:spc} for information about the mapping of the \bibtex file format fields to \sty{biblatex}'s data types. \begin{description} @@ -603,7 +622,7 @@ In \file{bib} files all bibliographic data is specified in fields. Some of those \item[Literal fields] are printed as is. Typical examples of literal fields are \bibfield{title} and \bibfield{note}. -\item[Range fields] are literal fields with one special feature: all dashes are normalized and replaced by the command \cmd{bibrangedash}. Any number of consecutive dashes will only yield a single range dash. A typical example of a range field is the \bibfield{pages} field. +\item[Range fields] are literal fields with one special feature: all dashes are normalized and replaced by the command \cmd{bibrangedash}. Any number of consecutive dashes will only yield a single range dash. A typical example of a range field is the \bibfield{pages} field. See also the \BiberOnlyMark\cmd{bibrangessep} command which can be used to customise the separator between multiple ranges. \item[Integer fields] hold unformatted integers which may be converted to ordinals or strings as they are printed. A typical example is the \bibfield{month} field. @@ -611,19 +630,21 @@ In \file{bib} files all bibliographic data is specified in fields. Some of those \item[Verbatim fields] are processed in verbatim mode and may contain special characters. Typical examples of verbatim fields are \bibfield{url} and \bibfield{doi}. -\item[Key fields] may hold printable data or localization keys. A test is performed to determine whether the value of the field is a known localization key (the localization keys defined by default are listed in \secref{aut:lng:key}). If so, the localized string is printed. If not, the value is printed as is. A typical example is the \bibfield{type} field. +\item[Comma"=separated value fields] A comma"=separated list of literal values. Examples are the \bibfield{keywords} and \bibfield{options} fields. + +\item[Pattern fields] A literal field which must match a particular pattern. An example is the \bibfield{gender} field from \secref{bib:fld:spc}. -\item[Special fields] are fields which require a special format not mentioned above. The field description will include details on the required format in this case. Typical examples are the fields \bibfield{hyphenation}, \bibfield{keywords}, and \bibfield{gender} from \secref{bib:fld:spc}. +\item[Key fields] May hold printable data or localization keys. A test is performed to determine whether the value of the field is a known localization key (the localization keys defined by default are listed in \secref{aut:lng:key}). If so, the localized string is printed. If not, the value is printed as is. A typical example is the \bibfield{type} field. + +\item[Code fields] Holds \tex code. \end{description} \end{description} -The data type of a field will usually not change, regardless of the type of entry it is used in. However, there are a few special cases. The field descriptions in \secref{bib:fld:dat} include the details or pointers to the relevant sections in this manual in such cases. For example, the \bibfield{location} field, which is a literal list by default, is treated as a key list when used in \bibtype{patent} entries. The \bibfield{series} field, which is a literal field by default, is handled in a special way when used in \bibtype{article} entries, see \secref{bib:use:ser} for details. - \subsubsection{Data Fields} \label{bib:fld:dat} -The fields listed in this section are the regular ones holding printable data. The name on the left is the name of the field, as used by both \bibtex and \sty{biblatex}. The \sty{biblatex} data type is given to the right of the name. See \secref{bib:fld:typ} for explanation of the various data types. +The fields listed in this section are the regular ones holding printable data in the default data model. The name on the left is the default data model name of the field as used by \sty{biblatex} and its backend. The \sty{biblatex} data type is given to the right of the name. See \secref{bib:fld:typ} for explanation of the various data types. \begin{fieldlist} @@ -731,6 +752,10 @@ Similar to \bibfield{editortype} but referring to the \bibfield{editorc} field. The electronic identifier of an \bibtype{article}. +\fielditem{entrysubtype}{literal} + +This field, which is not used by the standard styles, may be used to specify a subtype of an entry type. This may be useful for bibliography styles which support a finer"=grained set of entry types. + \fielditem{eprint}{verbatim} The electronic identifier of an online publication. This is roughly comparable to a \acr{doi} but specific to a certain archive, repository, service, or system. See \secref{use:use:epr} for details. Also see \bibfield{eprinttype} and \bibfield{eprintclass}. @@ -837,7 +862,7 @@ This field may be useful to record information such as a library name and a call \listitem{location}{literal} -The place(s) of publication, \ie the location of the \bibfield{publisher} or \bibfield{institution}, depending on the entry type. Traditional \bibtex uses the field name \bibfield{address}, which is supported as an alias. See also \secref{bib:fld:als, bib:use:and}. With \bibtype{patent} entries, this list indicates the scope of a patent and is treated as a key list. This list may also be useful for the custom types listed in \secref{bib:typ:ctm}. +The place(s) of publication, \ie the location of the \bibfield{publisher} or \bibfield{institution}, depending on the entry type. Traditional \bibtex uses the field name \bibfield{address}, which is supported as an alias. See also \secref{bib:fld:als, bib:use:and}. With \bibtype{patent} entries, this list indicates the scope of a patent. This list may also be useful for the custom types listed in \secref{bib:typ:ctm}. \fielditem{mainsubtitle}{literal} @@ -917,7 +942,7 @@ The publication state of the work, \eg\ . See \secref{aut:lng:key:pst} \fielditem{reprinttitle}{literal} -The title of a reprint of the work. Not used by the standard styles. +\BibTeXOnlyMark The title of a reprint of the work. Not used by the standard styles. \fielditem{series}{literal} @@ -1004,7 +1029,7 @@ The year of publication. See also \bibfield{date} and \secref{bib:use:dat}. \subsubsection{Special Fields} \label{bib:fld:spc} -The fields listed in this section do not hold printable data but serve a different purpose. They apply to all entry types. +The fields listed in this section do not hold printable data but serve a different purpose. They apply to all entry types in the default data model. \begin{fieldlist} @@ -1014,17 +1039,13 @@ This field holds an entry key for the cross"=referencing feature. Child entries \fielditem{entryset}{comma"=separated values} -This field is specific to entry sets. See \secref{use:use:set} for details. - -\fielditem{entrysubtype}{identifier} - -This field, which is not used by the standard styles, may be used to specify a subtype of an entry type. This may be useful for bibliography styles which support a finer"=grained set of entry types. +This field is specific to entry sets. See \secref{use:use:set} for details. This field is consumed by the backend processing and does not appear in the \path{.bbl}. \fielditem{execute}{code} A special field which holds arbitrary \tex code to be executed whenever the data of the respective entry is accessed. This may be useful to handle special cases. Conceptually, this field is comparable to the hooks \cmd{AtEveryBibitem}, \cmd{AtEveryLositem}, and \cmd{AtEveryCitekey} from \secref{aut:fmt:hok}, except that it is definable on a per"=entry basis in the \file{bib} file. Any code in this field is executed automatically immediately after these hooks. -\fielditem{gender}{\opt{sf}, \opt{sm}, \opt{sn}, \opt{pf}, \opt{pm}, \opt{pn}, \opt{pp}} +\fielditem{gender}{Pattern matching one of: \opt{sf}, \opt{sm}, \opt{sn}, \opt{pf}, \opt{pm}, \opt{pn}, \opt{pp}} The gender of the author or the gender of the editor, if there is no author. The following identifiers are supported: \opt{sf} (feminine singular, a single female name), \opt{sm} (masculine singular, a single male name), \opt{sn} (neuter singular, a single neuter name), \opt{pf} (feminine plural, a list of female names), \opt{pm} (masculine plural, a list of male names), \opt{pn} (neuter plural, a list of neuter names), \opt{pp} (plural, a mixed gender list of names). This information is only required by special bibliography and citation styles and only in certain languages. For example, a citation style may replace recurrent author names with a term such as . If the Latin word is used, as is custom in English and French, there is no need to specify the gender. In German publications, however, such key terms are usually given in German and in this case they are gender"=sensitive. @@ -1065,6 +1086,10 @@ Swedish & Sweden & \opt{swedish} \\ The language of the bibliography entry. The identifier must be a language name known to the \sty{babel} package. This information may be used to switch hyphenation patterns and localize strings in the bibliography. Note that the language names are case sensitive. The languages currently supported by this package are given in \tabref{bib:fld:tab1}. Note that \sty{babel} treats the identifier \opt{english} as an alias for \opt{british} or \opt{american}, depending on the babel version. The \sty{biblatex} package always treats it as an alias for \opt{american}. It is preferable to use the language identifiers \opt{american} and \opt{british} to avoid any possible confusion. Compare \bibfield{language} in \secref{bib:fld:dat}. +\fielditem{ids}{comma"=separated list of entrykeys\BiberOnlyMark} + +Citation key aliases for the main citation key. An entry may be cited by any of its aliases and \sty{biblatex} will treat the citation as if it had used the primary citation key. This is to aid users who change their citation keys but have legacy documents which use older keys for the same entry. This field is consumed by the backend processing and does not appear in the \path{.bbl}. + \fielditem{indexsorttitle}{literal} The title used when sorting the index. In contrast to \bibfield{indextitle}, this field is used for sorting only. The printed title in the index is the \bibfield{indextitle} or the \bibfield{title} field. This field may be useful if the title contains special characters or commands which interfere with the sorting of the index. Consider this example: @@ -1087,31 +1112,45 @@ A comma"=separated list of entry options in \keyval notation. This field is used \fielditem{presort}{string} -A special field used to modify the sorting order of the bibliography. This field is the first item the sorting routine considers when sorting the bibliography, hence it may be used to arrange the entries in groups. This may be useful when creating subdivided bibliographies with the bibliography filters. This field is only used internally during sorting. Please refer to \secref{use:srt} for further details. Also see \secref{aut:ctm:srt}. +A special field used to modify the sorting order of the bibliography. This field is the first item the sorting routine considers when sorting the bibliography, hence it may be used to arrange the entries in groups. This may be useful when creating subdivided bibliographies with the bibliography filters. Please refer to \secref{use:srt} for further details. Also see \secref{aut:ctm:srt}. This field is consumed by the backend processing and does not appear in the \path{.bbl}. + +\fielditem{related}{comma"=separated values} + +Citation keys of other entries which have a relationship to this entry. The relationship is specified by the \bibfield{relatedtype} field. Please refer to \secref{use:rel} for further details. + +\fielditem{relatedtype}{identifier\BiberOnlyMark} + +An identifier which specified the type of relationship for the keys listed in the \bibfield{related} field. The identifier is a localized bibliography string printed +before the data from the related entry list. It is also used to identify type-specific +formatting directives and bibliography macros for the related entries. Please refer to \secref{use:rel} for further details. + +\fielditem{relatedstring}{literal\BiberOnlyMark} + +A field used to override the bibliography string specified by \bibfield{relatedtype}. Please refer to \secref{use:rel} for further details. -\fielditem{sortkey}{literal} +\fielditem{sortkey}{literal\BiberOnlyMark} -A field used to modify the sorting order of the bibliography. Think of this field as the master sort key. If present, \sty{biblatex} uses this field during sorting and ignores everything else, except for the \bibfield{presort} field. This field is only used internally during sorting. Please refer to \secref{use:srt} for further details. +A field used to modify the sorting order of the bibliography. Think of this field as the master sort key. If present, \sty{biblatex} uses this field during sorting and ignores everything else, except for the \bibfield{presort} field. Please refer to \secref{use:srt} for further details. This field is consumed by the backend processing and does not appear in the \path{.bbl}. \listitem{sortname}{name} -A name or a list of names used to modify the sorting order of the bibliography. If present, this list is used instead of \bibfield{author} or \bibfield{editor} when sorting the bibliography. It is only used internally during sorting. Please refer to \secref{use:srt} for further details. +A name or a list of names used to modify the sorting order of the bibliography. If present, this list is used instead of \bibfield{author} or \bibfield{editor} when sorting the bibliography. Please refer to \secref{use:srt} for further details. This field is consumed by the backend processing and does not appear in the \path{.bbl}. \fielditem{sortshorthand}{literal\BiberOnlyMark} -Similar to \bibfield{sortkey} but used in the list of shorthands. If present, \sty{biblatex} uses this field instead of \bibfield{shorthand} when sorting the list of shorthands. This is useful if the \bibfield{shorthand} field holds shorthands with formatting commands such as \cmd{emph} or \cmd{textbf}. This field is only used internally during sorting. +Similar to \bibfield{sortkey} but used in the list of shorthands. If present, \sty{biblatex} uses this field instead of \bibfield{shorthand} when sorting the list of shorthands. This is useful if the \bibfield{shorthand} field holds shorthands with formatting commands such as \cmd{emph} or \cmd{textbf}. This field is consumed by the backend processing and does not appear in the \path{.bbl}. \fielditem{sorttitle}{literal} -A field used to modify the sorting order of the bibliography. If present, this field is used instead of the \bibfield{title} field when sorting the bibliography. It is only used internally during sorting. The \bibfield{sorttitle} field may come in handy if you have an entry with a title like «An Introduction to\dots» and want that alphabetized under rather than . In this case, you could put «Introduction to\dots» in the \bibfield{sorttitle} field. Please refer to \secref{use:srt} for further details. +A field used to modify the sorting order of the bibliography. If present, this field is used instead of the \bibfield{title} field when sorting the bibliography. The \bibfield{sorttitle} field may come in handy if you have an entry with a title like «An Introduction to\dots» and want that alphabetized under rather than . In this case, you could put «Introduction to\dots» in the \bibfield{sorttitle} field. Please refer to \secref{use:srt} for further details. This field is consumed by the backend processing and does not appear in the \path{.bbl}. \fielditem{sortyear}{literal} -A field used to modify the sorting order of the bibliography. If present, this field is used instead of the \bibfield{year} field when sorting the bibliography. It is only used internally during sorting. Please refer to \secref{use:srt} for further details. +A field used to modify the sorting order of the bibliography. If present, this field is used instead of the \bibfield{year} field when sorting the bibliography. Please refer to \secref{use:srt} for further details. This field is consumed by the backend processing and does not appear in the \path{.bbl}. -\fielditem{xdata}{comma-separated list of entry keys\BiberOnlyMark} +\fielditem{xdata}{comma-separated list of entrykeys\BiberOnlyMark} -This field inherits data from one or more \bibtype{xdata} entries. Conceptually, the \bibfield{xdata} field is related to \bibfield{crossref} and \bibfield{xref}: \bibfield{crossref} establishes a logical parent/child relation and inherits data; \bibfield{xref} establishes as logical parent/child relation without inheriting data; \bibfield{xdata} inherits data without establishing a relation. The value of the \bibfield{xdata} may be a single entry key or a comma"=separated list of keys. See \secref{use:use:xdat} for further details. +This field inherits data from one or more \bibtype{xdata} entries. Conceptually, the \bibfield{xdata} field is related to \bibfield{crossref} and \bibfield{xref}: \bibfield{crossref} establishes a logical parent/child relation and inherits data; \bibfield{xref} establishes as logical parent/child relation without inheriting data; \bibfield{xdata} inherits data without establishing a relation. The value of the \bibfield{xdata} may be a single entry key or a comma"=separated list of keys. See \secref{use:use:xdat} for further details. This field is consumed by the backend processing and does not appear in the \path{.bbl}. \fielditem{xref}{entry key} @@ -1225,7 +1264,7 @@ Note that traditional \bibtex styles support a \bibfield{key} field which is use \subsubsection{Corporate Authors and Editors} \label{bib:use:inc} -Corporate authors and editors are given in the \bibfield{author} or \bibfield{editor} field, respectively. Note that they must be wrapped in an extra pair of curly braces to prevent \bibtex from treating them as personal names which are to be dissected into their components. Use the \bibfield{shortauthor} field if you want to give an abbreviated form of the name or an acronym for use in citations. +Corporate authors and editors are given in the \bibfield{author} or \bibfield{editor} field, respectively. Note that they must be wrapped in an extra pair of curly braces to prevent data parsing from treating them as personal names which are to be dissected into their components. Use the \bibfield{shortauthor} field if you want to give an abbreviated form of the name or an acronym for use in citations. \begin{lstlisting}[style=bibtex]{} author = {<<{National Aeronautics and Space Administration}>>}, @@ -1496,7 +1535,7 @@ This section provides some additional hints concerning the data interface of thi \paragraph{The \bibfield{crossref} field (\bibtex)} \label{bib:cav:ref:btx} -The \bibfield{crossref} field is a convenient way to establish a parent\slash child relation between two associated entries. Unfortunately, \bibtex uses symmetric field mapping which reduces the usefulness of the \bibfield{crossref} field significantly. The are two issues with symmetric field mapping, as seen in the following example: +The \bibfield{crossref} field is a convenient way to establish a parent\slash child relation between two associated entries. Unfortunately, the \bibtex program uses symmetric field mapping which reduces the usefulness of the \bibfield{crossref} field significantly. The are two issues with symmetric field mapping, as seen in the following example: \begin{lstlisting}[style=bibtex]{} @Book{book, @@ -1520,10 +1559,10 @@ The \bibfield{crossref} field is a convenient way to establish a parent\slash ch % As \bibtex is not capable of mapping the \bibfield{title} field of the parent to the \bibfield{booktitle} field of the child, the title of the book needs to be given twice. The style then needs to ignore the \bibfield{booktitle} of the parent since it is only required to work around this fundamental limitation of \bibtex. The problem with the \bibfield{subtitle} field is the inverse of that. Since the \bibfield{subtitle} of the parent would become the \bibfield{subtitle}, rather than in the \bibfield{booksubtitle}, of the child, we need to add an empty \bibfield{subtitle} field to the child entry to prevent inheritance of this field. Of course we also need to duplicate the subtitle in the parent entry to ensure that it is available as \bibfield{booksubtitle} in the child entry. In short, using \bibtex's \bibfield{crossref} field tends to bloat database files and corrupt the data model. -\paragraph{The \bibfield{crossref} field (Biber)} +\paragraph{The \bibfield{crossref} field (\biber)} \label{bib:cav:ref:bbr} -With Biber, the limitations of \bibtex's \bibfield{crossref} field belong to the past. Biber features a highly customizable cross-referencing mechanism with flexible data inheritance rules. Duplicating certain fields in the parent entry or adding empty fields to the child entry is no longer required. Entries are specified in a natural way: +With \biber, the limitations of \bibtex's \bibfield{crossref} field belong to the past. \biber features a highly customizable cross-referencing mechanism with flexible data inheritance rules. Duplicating certain fields in the parent entry or adding empty fields to the child entry is no longer required. Entries are specified in a natural way: \begin{lstlisting}[style=bibtex]{} @Book{book, @@ -1555,7 +1594,7 @@ date = {1995}, pages = {5--25}, \end{lstlisting} % -See \apxref{apx:ref} for a list of mapping rules set up by default. Note that all of this is customizable. See \secref{aut:ctm:ref} on how to configure Biber's cross"=referencing mechanism. See also \secref{bib:fld:spc}. +See \apxref{apx:ref} for a list of mapping rules set up by default. Note that all of this is customizable. See \secref{aut:ctm:ref} on how to configure \biber's cross"=referencing mechanism. See also \secref{bib:fld:spc}. \paragraph{The \bibfield{xref} field} \label{bib:cav:ref:ref} @@ -1575,7 +1614,7 @@ Warning--I'm ignoring Jones1995's extra "volume" field --line 423 of file huge.bib \end{lstlisting} % -These warning messages could indeed indicate that the entry \texttt{Jones1995} is faulty because it includes two \bibfield{year} and two \bibfield{volume} fields. If that is not the case and the \file{bib} file is fairly large, this is most likely a capacity issue. What makes these warnings so confusing is that they are not tied to a specific entry. If you remove the allegedly faulty entry, a different one will trigger similar warnings. This is one reason why switching to \file{bibtex8} or Biber is advisable. +These warning messages could indeed indicate that the entry \texttt{Jones1995} is faulty because it includes two \bibfield{year} and two \bibfield{volume} fields. If that is not the case and the \file{bib} file is fairly large, this is most likely a capacity issue. What makes these warnings so confusing is that they are not tied to a specific entry. If you remove the allegedly faulty entry, a different one will trigger similar warnings. This is one reason why switching to \file{bibtex8} or \biber is advisable. \paragraph{\file{bibtex8}} \file{bibtex8} is a venerable tool as well and will also run out of memory with its default capacity. Switching from traditional \bibtex to \file{bibtex8} is still an improvement because the capacity of the latter may be increased at run"=time via command"=line switches and it also prints unambiguous error messages, for example: @@ -1625,8 +1664,8 @@ bibtex8 --wolfgang --mcites 30000 --mentints 30000 --mentstrs 40000 % When taking a closer look at \tabref{bib:cav:tab2}, you will notice that there are two parameters which can not be modified directly, |hash_prime| and |hash_size|. Increasing these values is only possible with the high"=level switches. That is why the above command includes the |--wolfgang| switch in addition to the low"=level switches. This situation is very unfortunate because the hash size effectively sets a cap on some other parameters. For example, |max_strings| can not be greater than |hash_size|. If you hit this cap, all you can do is recompile \file{bibtex8} with a larger capacity. Also note that the |wiz_fn_space| parameter is not related to the \file{bib} file but to the memory requirements of the \file{bst} file. \file{biblatex.bst} needs a value of about 6000. The value 10000 implicitly used by the |--wolfgang| switch is fine. -\paragraph{Biber} -Biber eliminates all of the above limitations. +\paragraph{\biber} +\biber eliminates all of the above limitations. \subsubsection{Sorting and Encoding Issues} \label{bib:cav:enc} @@ -1670,39 +1709,39 @@ sortname = {Ba<>mann, Paul}, % Not only \bibtex, \latex needs to know about the encoding as well. See \secref{bib:cav:enc:enc} on how to specify encodings. -\paragraph{Biber} -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 in the process of being added.\fnurl{http://cldr.unicode.org/} The bottom line is that Biber will deliver sorting results far superior to both \bibtex and \file{bibtex8} in many cases. If you are interested in the technical details, section 1.8 of Unicode Technical Standard \#10 will provide you with a very concise summary of why the inadequateness of traditional \bibtex and even \bin{bibtex8} is of a very general nature and not limited to the lack of \utf support.\fnurl{http://unicode.org/reports/tr10/#Common_Misperceptions} +\paragraph{\biber} +\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/} The bottom line is that \biber will deliver sorting results far superior to both \bibtex and \file{bibtex8} in many cases. If you are interested in the technical details, section 1.8 of Unicode Technical Standard \#10 will provide you with a very concise summary of why the inadequateness of traditional \bibtex and even \bin{bibtex8} is of a very general nature and not limited to the lack of \utf support.\fnurl{http://unicode.org/reports/tr10/#Common_Misperceptions} -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 <ß> mentioned as an example in \secref{bib:cav:enc:bt8} without any manual intervention. All you need to do to get localized sorting is specify the locale: +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 <ß> mentioned as an example in \secref{bib:cav:enc:bt8} without any manual intervention. All you need to do to get localized sorting is specify the locale: \begin{lstlisting}[style=latex]{} \usepackage[backend=biber,sortlocale=de]{biblatex} \end{lstlisting} % If the language of the document corresponds to the main locale of the operating system, \opt{sortlocale} is -omissible as Biber will detect the locale settings of the environment automatically. Note that this will also work with 8-bit encodings such as Latin\,9, \ie you can take advantage of Unicode-based sorting even though you are not using \utf input. See \secref{bib:cav:enc:enc} on how to specify input and data encodings properly. +omissible as \biber will detect the locale settings of the environment automatically. Note that this will also work with 8-bit encodings such as Latin\,9, \ie you can take advantage of Unicode-based sorting even though you are not using \utf input. See \secref{bib:cav:enc:enc} on how to specify input and data encodings properly. \paragraph{Specifying Encodings} \label{bib:cav:enc:enc} -When using a non-Ascii encoding in the \file{bib} file, it is important to understand what \sty{biblatex} can do for you and what may require manual intervention. The package takes care of the \latex side, \ie it ensures that the data imported from the \file{bbl} file is interpreted correctly, provided that the \opt{bibencoding} package option is set properly. Depending on the backend, the \bibtex side may demand attention, too. When using \bin{bibtex8}, you need to supply \bin{bibtex8} with a matching \file{csf} file as it needs to know about the encoding of the \file{bib} file to be able to alphabetize the entries correctly. Unfortunately, there is no way for \sty{biblatex} to pass this information to \bin{bibtex8} automatically. The only way is setting its |--csfile| option on the command line when running \bin{bibtex8}. When using Biber, all of this is handled automatically and no further steps, apart from setting the \opt{bibencoding} option in certain cases, are required. Here are a few typical usage scenarios along with the relevant lines from the document preamble: +When using a non-Ascii encoding in the \file{bib} file, it is important to understand what \sty{biblatex} can do for you and what may require manual intervention. The package takes care of the \latex side, \ie it ensures that the data imported from the \file{bbl} file is interpreted correctly, provided that the \opt{bibencoding} package option is set properly. Depending on the backend, the \bibtex side may demand attention, too. When using \bin{bibtex8}, you need to supply \bin{bibtex8} with a matching \file{csf} file as it needs to know about the encoding of the \file{bib} file to be able to alphabetize the entries correctly. Unfortunately, there is no way for \sty{biblatex} to pass this information to \bin{bibtex8} automatically. The only way is setting its |--csfile| option on the command line when running \bin{bibtex8}. When using \biber, all of this is handled automatically and no further steps, apart from setting the \opt{bibencoding} option in certain cases, are required. Here are a few typical usage scenarios along with the relevant lines from the document preamble: \begin{itemize} \setlength{\itemsep}{0pt} -\item Ascii notation in both the \file{tex} and the \file{bib} file with \pdftex or traditional \tex (this will work with \bibtex, \file{bibtex8}, and Biber): +\item Ascii notation in both the \file{tex} and the \file{bib} file with \pdftex or traditional \tex (this will work with \bibtex, \file{bibtex8}, and \biber): \begin{lstlisting}[style=latex]{} \usepackage{biblatex} \end{lstlisting} -\item Latin\,1 encoding (\acr{ISO}-8859-1) in the \file{tex} file, Ascii notation in the \file{bib} file with \pdftex or traditional \tex (\bibtex, \file{bibtex8}, Biber): +\item Latin\,1 encoding (\acr{ISO}-8859-1) in the \file{tex} file, Ascii notation in the \file{bib} file with \pdftex or traditional \tex (\bibtex, \file{bibtex8}, \biber): \begin{lstlisting}[style=latex]{} \usepackage[latin1]{inputenc} \usepackage[bibencoding=ascii]{biblatex} \end{lstlisting} -\item Latin\,9 encoding (\acr{ISO}-8859-15) in both the \file{tex} and the \file{bib} file with \pdftex or traditional \tex (\file{bibtex8}, Biber): +\item Latin\,9 encoding (\acr{ISO}-8859-15) in both the \file{tex} and the \file{bib} file with \pdftex or traditional \tex (\file{bibtex8}, \biber): \begin{lstlisting}[style=latex]{} \usepackage[latin9]{inputenc} @@ -1716,7 +1755,7 @@ Since \kvopt{bibencoding}{auto} is the default setting, the option is omissible. \usepackage{biblatex} \end{lstlisting} -\item \utf encoding in the \file{tex} file, Latin\,1 (\acr{ISO}-8859-1) in the \file{bib} file with \pdftex or traditional \tex (\file{bibtex8}, Biber): +\item \utf encoding in the \file{tex} file, Latin\,1 (\acr{ISO}-8859-1) in the \file{bib} file with \pdftex or traditional \tex (\file{bibtex8}, \biber): \begin{lstlisting}[style=latex]{} \usepackage[utf8]{inputenc} @@ -1729,7 +1768,7 @@ The same scenario with \xetex or \luatex in native \utf mode: \usepackage[bibencoding=latin1]{biblatex} \end{lstlisting} -\item Using \utf encoding in both the \file{tex} and the \file{bib} file is not possible with traditional \bibtex or \bin{bibtex8} since neither of them is capable of handling \utf. Unless you switch to Biber, you need to use an 8-bit encoding such as Latin\,1 (see above) or resort to Ascii notation in this case: +\item Using \utf encoding in both the \file{tex} and the \file{bib} file is not possible with traditional \bibtex or \bin{bibtex8} since neither of them is capable of handling \utf. Unless you switch to \biber, you need to use an 8-bit encoding such as Latin\,1 (see above) or resort to Ascii notation in this case: \begin{lstlisting}[style=latex]{} \usepackage[utf8]{inputenc} @@ -1744,7 +1783,7 @@ The same scenario with \xetex or \luatex in native \utf mode: \end{itemize} -Biber can handle Ascii notation, 8-bit encodings such as Latin\,1, and \utf. It is also capable of reencoding the \file{bib} data on the fly (replacing the limited macro-level reencoding feature of \sty{biblatex}). This will happen automatically if required, provided that you specify the encoding of the \file{bib} files properly. In addition to the scenarios discussed above, Biber can also handle the following cases: +\biber can handle Ascii notation, 8-bit encodings such as Latin\,1, and \utf. It is also capable of reencoding the \file{bib} data on the fly (replacing the limited macro-level reencoding feature of \sty{biblatex}). This will happen automatically if required, provided that you specify the encoding of the \file{bib} files properly. In addition to the scenarios discussed above, \biber can also handle the following cases: \begin{itemize} @@ -1777,7 +1816,7 @@ The same scenario with \xetex or \luatex in native \utf mode: \end{itemize} -Some workarounds may be required when using traditional \tex or \pdftex with \utf encoding because \sty{inputenc}'s \file{utf8} module does not cover all of Unicode. Roughly speaking, it only covers the Western European Unicode range. When loading \sty{inputenc} with the \file{utf8} option, \sty{biblatex} will normally instruct Biber to reencode the \file{bib} data to \utf. This may lead to \sty{inputenc} errors if some of the characters in the \file{bib} file are outside the limited Unicode range supported by \sty{inputenc}. +Some workarounds may be required when using traditional \tex or \pdftex with \utf encoding because \sty{inputenc}'s \file{utf8} module does not cover all of Unicode. Roughly speaking, it only covers the Western European Unicode range. When loading \sty{inputenc} with the \file{utf8} option, \sty{biblatex} will normally instruct \biber to reencode the \file{bib} data to \utf. This may lead to \sty{inputenc} errors if some of the characters in the \file{bib} file are outside the limited Unicode range supported by \sty{inputenc}. \begin{itemize} @@ -1788,7 +1827,7 @@ Some workarounds may be required when using traditional \tex or \pdftex with \ut \usepackage[safeinputenc]{biblatex} \end{lstlisting} % -If this option is enabled, \sty{biblatex} will ignore \sty{inputenc}'s \opt{utf8} option and use Ascii. Biber will then try to convert the \file{bib} data to Ascii notation. For example, it will convert \texttt{\k{S}} to |\k{S}|. This option is similar to setting \kvopt{texencoding}{ascii} but will only take effect in this specific scenario (\sty{inputenc}\slash \sty{inputenx} with \utf). This workaround takes advantage of the fact that both Unicode and the \utf transport encoding are backwards compatible with Ascii. +If this option is enabled, \sty{biblatex} will ignore \sty{inputenc}'s \opt{utf8} option and use Ascii. \biber will then try to convert the \file{bib} data to Ascii notation. For example, it will convert \texttt{\k{S}} to |\k{S}|. This option is similar to setting \kvopt{texencoding}{ascii} but will only take effect in this specific scenario (\sty{inputenc}\slash \sty{inputenx} with \utf). This workaround takes advantage of the fact that both Unicode and the \utf transport encoding are backwards compatible with Ascii. \end{itemize} @@ -1871,17 +1910,17 @@ Using any of the sorting schemes only makes sense in conjunction wi \boolitem[true]{sortcase} -Whether or not to sort the bibliography and the list of shorthands case"=sensitively. Note that case"=sensitive sorting is only supported by the \bin{bibtex8} and Biber backends. Sorting is always case"=insensitive with legacy \bibtex. See the \opt{backend} option for details. +Whether or not to sort the bibliography and the list of shorthands case"=sensitively. Note that case"=sensitive sorting is only supported by the \bin{bibtex8} and \biber backends. Sorting is always case"=insensitive with legacy \bibtex. See the \opt{backend} option for details. \boolitem[true]{sortupper}[\BiberOnly] -This option corresponds to Biber's |--sortupper| command-line option. It has no effect with any other backend. If enabled, the bibliography is sorted in order. Disabling this option means order. +This option corresponds to \biber's |--sortupper| command-line option. It has no effect with any other backend. If enabled, the bibliography is sorted in order. Disabling this option means order. \optitem{sortlocale}{\prm{locale}}[\BiberOnly] -This option corresponds to Biber's |--sortlocale| command-line option. It has no effect with any other backend. If set, it specifies the locale to be used for sorting. While \sty{biblatex} provides no default value for this option, Biber will inherit the locale settings from the environment if no locale has been specified explicitly. +This option corresponds to \biber's |--sortlocale| command-line option. It has no effect with any other backend. If set, it specifies the locale to be used for sorting. While \sty{biblatex} provides no default value for this option, \biber will inherit the locale settings from the environment if no locale has been specified explicitly. -\optitem[los]{sortlos}{\opt{bib}, \opt{los}} +\optitem[los]{sortlos}{\opt{bib}, \opt{los}}[\BibTeXOnly] The sorting order of the list of shorthands. The following choices are available: @@ -1890,9 +1929,15 @@ The sorting order of the list of shorthands. The following choices are available \item[los] Sort by shorthand. \end{valuelist} +The sorting order of shorthands with \biber is more flexible and is set with the \opt{sorting} option to the \cmd{printshorthands} command. + +\boolitem[true]{related} + +Whether or not to use information from related entries or not. See \secref{use:rel}. + \boolitem[false]{sortcites} -Whether or not to sort citations if multiple entry keys are passed to a citation command. If this option is enabled, citations are sorted according to the sorting order of the bibliography. This feature works with all citation styles. +Whether or not to sort citations if multiple entry keys are passed to a citation command. If this option is enabled, citations are sorted according to the global sorting order of the bibliography. This feature works with all citation styles. \intitem[3]{maxnames} @@ -2202,27 +2247,27 @@ Path selector for arXiv links. If hyperlink support is enabled, this option cont See \secref{use:use:epr} for details on support for arXiv and electronic publishing information. -\optitem[bibtex]{backend}{\opt{bibtex}, \opt{bibtex8}, \opt{bibtexu}, \opt{biber}} +\optitem[biber]{backend}{\opt{bibtex}, \opt{bibtex8}, \opt{bibtexu}, \opt{biber}} Specifies the database backend. The following backends are supported: \begin{valuelist} +\item[biber] \biber, the default backend of \sty{biblatex}, supports Ascii, 8-bit encodings, \utf, on-the-fly reencoding, locale"=specific sorting, and many other features. Locale"=specific sorting, case"=sensitive sorting, and upper\slash lowercase precedence are controlled by the options \opt{sortlocale}, \opt{sortcase}, and \opt{sortupper}, respectively. + \item[bibtex] Legacy \bibtex. Traditional \bibtex supports Ascii encoding only. Sorting is always case"=insensitive. \item[bibtex8] \bin{bibtex8}, the 8-bit implementation of \bibtex, supports Ascii and 8-bit encodings such as Latin~1. Depending on the \file{csf} file, case"=sensitive sorting may be supported. -\item[bibtexu] \bin{bibtexu} is a Unicode-enabled implementation of \bibtex which supports \utf. Note that \bin{bibtexu} is not actively supported by \sty{biblatex} and has not been tested as backend in any way. Biber is the recommended backend. - -\item[biber] Biber, the next"=generation backend of \sty{biblatex}, supports Ascii, 8-bit encodings, \utf, on-the-fly reencoding, locale"=specific sorting, and many other features. Locale"=specific sorting, case"=sensitive sorting, and upper\slash lowercase precedence are controlled by the options \opt{sortlocale}, \opt{sortcase}, and \opt{sortupper}, respectively. +\item[bibtexu] \bin{bibtexu} is a Unicode-enabled implementation of \bibtex which supports \utf. Note that \bin{bibtexu} is not actively supported by \sty{biblatex} and has not been tested as backend in any way. \biber is the recommended backend. \end{valuelist} -This option will typically be set permanently in the configuration file, see \secref{use:cfg} for details. Also see \secref{bib:cav:enc} for further instructions concerning the encoding of \file{bib} files. +See \secref{bib:cav:enc} for further instructions concerning the encoding of \file{bib} files. This option is only available at load-time as internally, the code chooses completely different paths depending on the backend. This means that you can't set the backend with, for example, \cmd{ExecuteBibliographyOptions} in the preamble. \optitem[auto]{texencoding}{\opt{auto}, \prm{encoding}} -Specifies the encoding of the \file{tex} file. This option affects the data transfered from the backend to \sty{biblatex}. When using Biber, this corresponds to Biber's |--bblencoding| option. The following choices are available: +Specifies the encoding of the \file{tex} file. This option affects the data transfered from the backend to \sty{biblatex}. When using \biber, this corresponds to \biber's |--bblencoding| option. The following choices are available: \begin{valuelist} @@ -2236,7 +2281,7 @@ Note that setting \kvopt{texencoding}{\prm{encoding}} will also affect the \opt{ \optitem[auto]{bibencoding}{\opt{auto}, \prm{encoding}} -Specifies the encoding of the \file{bib} files. When using Biber, this corresponds to Biber's |--bibencoding| option. The following choices are available: +Specifies the encoding of the \file{bib} files. When using \biber, this corresponds to \biber's |--bibencoding| option. The following choices are available: \begin{valuelist} @@ -2250,7 +2295,7 @@ By default, \sty{biblatex} assumes that the \file{tex} file and the \file{bib} f \boolitem[false]{safeinputenc}[\BiberOnly] -If this option is enabled, \sty{biblatex} will automatically force \kvopt{texencoding}{ascii} if the \sty{inputenc}\slash \sty{inputenx} package has been loaded and the input encoding is \utf, \ie it will ignore any macro-based \utf support and use Ascii only. Biber will then try to convert any non-Ascii data in the \file{bib} file to Ascii. For example, it will convert \texttt{\d{S}} to |\d{S}|. See \secref{bib:cav:enc:enc} for an explanation of why you may want to enable this option. +If this option is enabled, \sty{biblatex} will automatically force \kvopt{texencoding}{ascii} if the \sty{inputenc}\slash \sty{inputenx} package has been loaded and the input encoding is \utf, \ie it will ignore any macro-based \utf support and use Ascii only. \biber will then try to convert any non-Ascii data in the \file{bib} file to Ascii. For example, it will convert \texttt{\d{S}} to |\d{S}|. See \secref{bib:cav:enc:enc} for an explanation of why you may want to enable this option. \boolitem[true]{bibwarn} @@ -2258,7 +2303,7 @@ By default, \sty{biblatex} will report warnings issued by the backend concerning \intitem[2]{mincrossrefs} -Sets the minimum number of cross references to \prm{integer} when requesting a \bibtex run.\footnote{If an entry which is cross-referenced by other entries in the \file{bib} file hits this threshold, it is included in the bibliography even if it has not been cited explicitly. This is a standard feature of \bibtex and not specific to \sty{biblatex}. See the description of the \bibfield{crossref} field in \secref{bib:fld:spc} for further information.} Note that this package option merely affects the format of certain requests written to the transcript file. It will not have any effect if the editor or compiler script launching \bibtex does not include dedicated \sty{biblatex} support or if \bibtex is manually launched from the command"=line.\footnote{As of this writing, no \latex editors or compiler scripts with dedicated \sty{biblatex} support are known, but this will hopefully change in the future.} See \secref{bib:cav:ide} for details. This option also affects the handling of the \bibfield{xref} field. See the field description in \secref{bib:fld:spc} as well as \secref{bib:cav:ref} for details. +Sets the minimum number of cross references to \prm{integer} when requesting a backend run.\footnote{If an entry which is cross-referenced by other entries in the \file{bib} file hits this threshold, it is included in the bibliography even if it has not been cited explicitly. This is a standard feature of the \bibtex (also \biber) and not specific to \sty{biblatex}. See the description of the \bibfield{crossref} field in \secref{bib:fld:spc} for further information.} Note that when using the \bibtex backend, this package option merely affects the format of certain requests written to the transcript file. It will not have any effect if the editor or compiler script launching \bibtex does not include dedicated \sty{biblatex} support or if \bibtex is manually launched from the command"=line.\footnote{As of this writing, no \latex editors or compiler scripts with dedicated \sty{biblatex} support are known, but this will hopefully change in the future.} See \secref{bib:cav:ide} for details. This option also affects the handling of the \bibfield{xref} field. See the field description in \secref{bib:fld:spc} as well as \secref{bib:cav:ref} for details. \end{optionlist} @@ -2399,14 +2444,18 @@ The maximum permitted nesting level of parentheses and brackets. If parentheses When enabled, all first and middle names will be rendered as initials. The option will affect the \cmd{iffirstinits} test from \secref{aut:aux:tst}. +\boolitem[false]{sortfirstinits} + +When enabled, sorting names will only use their initials. \BiberOnlyMark This is separate from \opt{firstinits} in case users want to show only inits but sort on full names, for example. + \boolitem[false]{terseinits} -This option controls the format of initials generated by \sty{biblatex}. If enabled, initals are rendered using a terse format without dots and spaces. For example, the initials of Donald Ervin Knuth would be rendered as by default, and as if this option is enabled. \BiberOnlyMark With Biber, the option works by redefining some macros which control the format of initials. See \secref{use:cav:nam} for details. +This option controls the format of initials generated by \sty{biblatex}. If enabled, initals are rendered using a terse format without dots and spaces. For example, the initials of Donald Ervin Knuth would be rendered as by default, and as if this option is enabled. \BiberOnlyMark With \biber, the option works by redefining some macros which control the format of initials. See \secref{use:cav:nam} for details. \boolitem[false]{labelalpha} Whether or not to provide the special fields \bibfield{labelalpha} and \bibfield{extraalpha}, see \secref{aut:bbx:fld} for details. -\BiberOnlyMark With Biber, this option is also settable on a per-type basis. See also \opt{maxalphanames} and \opt{minalphanames}. +\BiberOnlyMark With \biber, this option is also settable on a per-type basis. See also \opt{maxalphanames} and \opt{minalphanames}. Table \ref{use:opt:tab2} summarises the various \opt{extra*} disambiguation counters and what they track. \intitem[3]{maxalphanames}[\BiberOnly] @@ -2421,15 +2470,23 @@ Similar to the \opt{minnames} option but customizes the format of the \bibfield{ Whether or not to provide the special field \bibfield{labelnumber}, see \secref{aut:bbx:fld} for details. This option is also settable on a per-type basis. +\boolitem[false]{labeltitle}[\BiberOnly] + +Whether or not to provide the special field \bibfield{extratitle}, see \secref{aut:bbx:fld} for details. Note that the special field \bibfield{labeltitle} is always provided and this option controls rather whether \bibfield{labeltitle} is used to generate \bibfield{extratitle} information. This option is also settable on a per-type basis. Table \ref{use:opt:tab2} summarises the various \opt{extra*} disambiguation counters and what they track. + +\boolitem[false]{labeltitleyear}[\BiberOnly] + +Whether or not to provide the special field \bibfield{extratitleyear}, see \secref{aut:bbx:fld} for details. Note that the special field \bibfield{labeltitle} is always provided and this option controls rather whether \bibfield{labeltitle} is used to generate \bibfield{extratitleyear} information. This option is also settable on a per-type basis. Table \ref{use:opt:tab2} summarises the various \opt{extra*} disambiguation counters and what they track. + \boolitem[false]{labelyear} -Whether or not to provide the special fields \bibfield{labelyear} and \bibfield{extrayear}, see \secref{aut:bbx:fld} for details. -\BiberOnlyMark With Biber, this option is also settable on a per-type basis. +Whether or not to provide the special fields \bibfield{labelyear} and \bibfield{extrayear}, see \secref{aut:bbx:fld} for details. +\BiberOnlyMark With \biber, this option is also settable on a per-type basis. Table \ref{use:opt:tab2} summarises the various \opt{extra*} disambiguation counters and what they track. \boolitem[false]{singletitle} Whether or not to provide the data required by the \cmd{ifsingletitle} test, see \secref{aut:aux:tst} for details. -\BiberOnlyMark With Biber, this option is also settable on a per-type basis. +\BiberOnlyMark With \biber, this option is also settable on a per-type basis. \optitem[false]{uniquename}{\opt{true}, \opt{false}, \opt{init}, \opt{full}, \opt{allinit}, \opt{allfull}, \opt{mininit}, \opt{minfull}}[\BiberOnly] @@ -2463,6 +2520,26 @@ Note that the \opt{uniquelist} option will also affect the \cmd{ifsingletitle} t \end{optionlist} +\begin{table} +\ttfamily +\tablesetup +\begin{tabularx}{\textwidth}{@{}p{100pt}@{}p{100pt}@{}p{100pt}@{}p{100pt}@{}} +\toprule +\multicolumn{1}{@{}H}{Option} & +\multicolumn{1}{@{}H}{Enabled field} & +\multicolumn{1}{@{}H}{Enabled counter} & +\multicolumn{1}{@{}H}{Counter tracks} \\ +\cmidrule(r){1-1}\cmidrule(r){2-2}\cmidrule(r){3-3}\cmidrule{4-4} +labelalpha & labelalpha & extraalpha & label\\ +labelyear & labelyear & extrayear & labelname+labelyear\\ +labeltitle & --- & extratitle & labelname+labeltitle\\ +labeltitleyear & --- & extratitleyear & labeltitle+labelyear\\ +\bottomrule +\end{tabularx} +\caption{Disambiguation counters} +\label{use:opt:tab2} +\end{table} + \subsubsection{Entry Options} \label{use:opt:bib} @@ -2478,17 +2555,17 @@ The following options are settable on a per"=entry basis in the \bibfield{option \boolitem[true]{useauthor} Whether the \bibfield{author} is used in labels and considered during sorting. This may be useful if an entry includes an \bibfield{author} field but is usually not cited by author for some reason. Setting \kvopt{useauthor}{false} does not mean that the \bibfield{author} is ignored completely. It means that the \bibfield{author} is not used in labels and ignored during sorting. The entry will then be alphabetized by \bibfield{editor} or \bibfield{title}. With the standard styles, the \bibfield{author} is printed after the title in this case. See also \secref{use:srt}. -\BiberOnlyMark With Biber, this option is also settable on a per-type basis. +\BiberOnlyMark With \biber, this option is also settable on a per-type basis. \boolitem[true]{useeditor} Whether the \bibfield{editor} replaces a missing \bibfield{author} in labels and during sorting. This may be useful if an entry includes an \bibfield{editor} field but is usually not cited by editor. Setting \kvopt{useeditor}{false} does not mean that the \bibfield{editor} is ignored completely. It means that the \bibfield{editor} does not replace a missing \bibfield{author} in labels and during sorting. The entry will then be alphabetized by \bibfield{title}. With the standard styles, the \bibfield{editor} is printed after the title in this case. See also \secref{use:srt}. -\BiberOnlyMark With Biber, this option is also settable on a per-type basis. +\BiberOnlyMark With \biber, this option is also settable on a per-type basis. \boolitem[false]{usetranslator} Whether the \bibfield{translator} replaces a missing \bibfield{author}\slash \bibfield{editor} in labels and during sorting. Setting \kvopt{usetranslator}{true} does not mean that the \bibfield{translator} overrides the \bibfield{author}\slash \bibfield{editor}. It means that the \bibfield{translator} is considered as a fallback if the \bibfield{author}\slash \bibfield{editor} is missing or if \opt{useauthor} and \opt{useeditor} are set to \texttt{false}. In other words, in order to cite a book by translator rather than by author, you need to set the following options: -\BiberOnlyMark With Biber, this option is also settable on a per-type basis. +\BiberOnlyMark With \biber, this option is also settable on a per-type basis. \begin{lstlisting}[style=bibtex]{} @Book{..., @@ -2503,7 +2580,7 @@ With the standard styles, the \bibfield{translator} is printed after the title b \boolitem[false]{useprefix} Whether the name prefix (von, van, of, da, de, della, etc.) is considered when printing the last name in citations. This also affects the sorting and formatting of the bibliography as well as the generation of certain types of labels. If this option is enabled, \sty{biblatex} always precedes the last name with the prefix. For example, Ludwig van Beethoven would be cited as «Beethoven» and alphabetized as «Beethoven, Ludwig van» by default. If this option is enabled, he is cited as «van Beethoven» and alphabetized as «Van Beethoven, Ludwig» instead. -\BiberOnlyMark With Biber, this option is also settable on a per-type basis. +\BiberOnlyMark With \biber, this option is also settable on a per-type basis. \optitem{indexing}{\opt{true}, \opt{false}, \opt{cite}, \opt{bib}} @@ -2521,22 +2598,22 @@ The following options are only settable on a per"=entry basis in the \bibfield{o \boolitem[false]{skipbib} If this option is enabled, the entry is excluded from the bibliography but it may still be cited. -\BiberOnlyMark With Biber, this option is also settable on a per-type basis. +\BiberOnlyMark With \biber, this option is also settable on a per-type basis. \boolitem[false]{skiplos} If this option is enabled, the entry is excluded from the list of shorthands. It is still included in the bibliography and it may also be cited by shorthand. -\BiberOnlyMark With Biber, this option is also settable on a per-type basis. +\BiberOnlyMark With \biber, this option is also settable on a per-type basis. \boolitem[false]{skiplab} If this option is enabled, \sty{biblatex} will not assign any labels to the entry. It is not required for normal operation. Use it with care. If enabled, \sty{biblatex} can not guarantee unique citations for the respective entry and citations styles which require labels may fail to create valid citations for the entry. -\BiberOnlyMark With Biber, this option is also settable on a per-type basis. +\BiberOnlyMark With \biber, this option is also settable on a per-type basis. \boolitem[false]{dataonly} Setting this option is equivalent to \opt{skipbib}, \opt{skiplos}, and \opt{skiplab}. It is not required for normal operation. Use it with care. -\BiberOnlyMark With Biber, this option is also settable on a per-type basis. +\BiberOnlyMark With \biber, this option is also settable on a per-type basis. \end{optionlist} @@ -2710,6 +2787,77 @@ This style prints all bibliographic data in tabular format. It is intended for d \end{marglist} +\subsection{Related Entries} +\label{use:rel} + +Almost all bibliography styles require authors to specify certain types of relationship between entries such as «Reprint of», «Reprinted in» etc. It is impossible to provide data fields to cover all of these relationships and so \sty{biblatex} provides a general mechanism for this using the entry fields \bibfield{related}, \bibfield{relatedtype} and \bibfield{relatedstring}. A related entry does not need to be cited and does not appear in the bibliography itself (unless of course it is also cited itseld independently). The \bibfield{relatedtype} field should specify a localization string which will be printed before the information from the related entries is printed, for example «Orig. Pub. as». The \bibfield{relatedstring} field can be used to override the string determined via \bibfield{relatedtype}. Some examples: + +\begin{lstlisting}[style=bibtex]{} +@Book{key1, + ... + related = {key2}, + relatedtype = {reprintof}, + ... +} + +@Book{key2, + ... +} +\end{lstlisting} +% +Here we specify that entry \texttt{key1} is a reprint of entry \texttt{key2}. In the bibliography driver for \texttt{Book} entries, when \cmd{usebibmacro\{related\}} is called for entry \texttt{key1}: + +\begin{itemize} +\item If the localization string «\texttt{reprintof}» is defined, it is printed, then +\item If the \texttt{related:reprintof} macro is defined, it is used to format the information contained in entry \texttt{key2}, otherwise the \texttt{related:default} macro is used +\item If the \texttt{related:reprintof} format is defined, it is used to format both the localization string and data. If this format is not defined, then the \texttt{related} format is used instead. +\end{itemize} +% +It is also supported to have cascading and/or circular relations: + +\begin{lstlisting}[style=bibtex]{} +@Book{key1, + ... + related = {key2}, + relatedtype = {reprintof}, + ... +} + +@Book{key2, + ... + related = {key3}, + relatedtype = {translationof}, + ... +} + +@Book{key3, + ... + related = {key2}, + relatedtype = {translatedas}, + ... +} +\end{lstlisting} +% +Multiple relations to the same entry are also possible: +\begin{lstlisting}[style=bibtex]{} +@MVBook{key1, + ... + related = {key2,key3}, + relatedtype = {multivolume}, + ... +} + +@Book{key2, + ... +} + +@Book{key3, + ... +} +\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}. + \subsection{Sorting Options} \label{use:srt} @@ -2719,7 +2867,7 @@ The first item considered in the sorting process is always the \bibfield{presort The chronological sorting schemes presented in \apxref{apx:srt:chr} also make use of the \bibfield{presort} and \bibfield{sortkey} fields, if defined. The next item considered is the \bibfield{sortyear} or the \bibfield{year} field, depending on availability. The \opt{ynt} scheme extracts the first four Arabic figures from the field. If both fields are undefined, the string \texttt{9999} is used as a fallback value. This means that all entries without a year will be moved to the end of the list. The \opt{ydnt} scheme is similar in concept but sorts the year in descending order. As with the \opt{ynt} scheme, the string \texttt{9999} is used as a fallback value. The remaining items are similar to the alphabetic sorting schemes discussed above. Note that the \opt{ydnt} sorting scheme will only sort the date in descending order. All other items are sorted in ascending order as usual. -Using special fields such as \bibfield{sortkey}, \bibfield{sortname}, or \bibfield{sorttitle} is usually not required. The \sty{biblatex} package is quite capable of working out the desired sorting order by using the data found in the regular fields of an entry. You will only need them if you want to manually modify the sorting order of the bibliography or if any data required for sorting is missing. Please refer to the field descriptions in \secref{bib:fld:spc} for details on possible uses of the special fields. Also note that using \file{bibtex8} or Biber instead of legacy \file{bibtex} is strongly recommended. +Using special fields such as \bibfield{sortkey}, \bibfield{sortname}, or \bibfield{sorttitle} is usually not required. The \sty{biblatex} package is quite capable of working out the desired sorting order by using the data found in the regular fields of an entry. You will only need them if you want to manually modify the sorting order of the bibliography or if any data required for sorting is missing. Please refer to the field descriptions in \secref{bib:fld:spc} for details on possible uses of the special fields. Also note that using \biber instead of legacy \bibtex is strongly recommended. \subsection{Bibliography Commands} \label{use:bib} @@ -2750,7 +2898,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} 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} @@ -2766,9 +2914,9 @@ The data type (format) of the resource. The following formats are currently supp \item[ris]\BiberOnlyMark Research Information Systems (\acr{RIS}) format.\fnurl{http://en.wikipedia.org/wiki/RIS_(file_format)} Note that an \texttt{ID} tag is required in all \acr{RIS} records. The \texttt{ID} value corresponds to the entry key. Support for this format is experimental. -\item[zoterordfxml]\BiberOnlyMark Zotero \acr{RDF}/\acr{XML} format. Support for this format is experimental. Refer to the Biber manual for details. +\item[zoterordfxml]\BiberOnlyMark Zotero \acr{RDF}/\acr{XML} format. Support for this format is experimental. Refer to the \biber manual for details. -\item[endnotexml]\BiberOnlyMark EndNote \acr{XML} format. Support for this format is experimental. Refer to the Biber manual for details. +\item[endnotexml]\BiberOnlyMark EndNote \acr{XML} format. Support for this format is experimental. Refer to the \biber manual for details. \end{valuelist} @@ -2817,13 +2965,17 @@ The prenote is an arbitrary piece of text to be printed after the heading but be The postnote is an arbitrary piece of text to be printed after the list of references. This option selects the postnote \prm{name}, as defined with \cmd{defbibnote}. By default, no postnote 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. -\intitem[0]{section} +\intitem[current section]{section} -Print only entries cited in reference section \prm{integer}. The reference sections are numbered starting at~1. All citations given outside a \env{refsection} environment are assigned to section~0. See \secref{use:bib:sec} for details and \secref{use:use:mlt} for usage examples. When giving a chain of multiple filters, the \texttt{section} filter must always be given first. +Print only entries cited in reference section \prm{integer}. The reference sections are numbered starting at~1. All citations given outside a \env{refsection} environment are assigned to section~0. See \secref{use:bib:sec} for details and \secref{use:use:mlt} for usage examples. \intitem[0]{segment} -Print only entries cited in reference segment \prm{integer}. The reference segments are numbered starting at~1. All citations given outside a \env{refsegment} environment are assigned to segment~0. See \secref{use:bib:seg} for details and \secref{use:use:mlt} for usage examples. +Print only entries cited in reference segment \prm{integer}. The reference segments are numbered starting at~1. All citations given outside a \env{refsegment} environment are assigned to segment~0. See \secref{use:bib:seg} for details and \secref{use:use:mlt} for usage examples. Remember that segments within a section are numbered local to the section so the segment you request will be the nth segment in the requested (or currently active enclosing) section. + +\valitem{sorting}{name}[\BiberOnly] + +Sort the bibliography according to a built-in or user specified sorting scheme defined with \cmd{DeclareSortingScheme}. If omitted, the global sorting scheme specified with package \opt{sorting} option is used. This option facilitates multiple bibliography lists within a refsection, each of which can be sorted differently. \valitem{type}{entrytype} @@ -2883,15 +3035,15 @@ This option applies to numerical citation\slash bibliography styles only and req \cmditem{bibbysection}[key=value, \dots] -This command automatically loops over all reference sections. This is equivalent to giving one \cmd{printbibliography} command for every section but has the additional benefit of automatically skipping sections without references. Note that \cmd{bibbysection} starts looking for references in section \texttt{1}. It will ignore references given outside of \env{refsection} environments since they are assigned to section~0. See \secref{use:use:mlt} for usage examples. The options are a subset of those supported by \cmd{printbibliography}. Valid options are \opt{env}, \opt{heading}, \opt{prenote}, \opt{postnote}. +This command automatically loops over all reference sections. This is equivalent to giving one \cmd{printbibliography} command for every section but has the additional benefit of automatically skipping sections without references. Note that \cmd{bibbysection} starts looking for references in section \texttt{1}. It will ignore references given outside of \env{refsection} environments since they are assigned to section~0. See \secref{use:use:mlt} for usage examples. The options are a subset of those supported by \cmd{printbibliography}. Valid options are \opt{env}, \opt{heading}, \opt{prenote}, \opt{postnote}. The global sorting scheme specified with package \opt{sorting} option is used for all sections. \cmditem{bibbysegment}[key=value, \dots] -This command automatically loops over all reference segments. This is equivalent to giving one \cmd{printbibliography} command for every segment but has the additional benefit of automatically skipping segments without references. Note that \cmd{bibbysegment} starts looking for references in segment \texttt{1}. It will ignore references given outside of \env{refsegment} environments since they are assigned to segment~0. See \secref{use:use:mlt} for usage examples. The options are a subset of those supported by \cmd{printbibliography}. Valid options are \opt{env}, \opt{heading}, \opt{prenote}, \opt{postnote}. +This command automatically loops over all reference segments. This is equivalent to giving one \cmd{printbibliography} command for every segment in the current \env{refsection} but has the additional benefit of automatically skipping segments without references. Note that \cmd{bibbysegment} starts looking for references in segment \texttt{1}. It will ignore references given outside of \env{refsegment} environments since they are assigned to segment~0. See \secref{use:use:mlt} for usage examples. The options are a subset of those supported by \cmd{printbibliography}. Valid options are \opt{env}, \opt{heading}, \opt{prenote}, \opt{postnote}. The global sorting scheme specified with package \opt{sorting} option is used for all segments. \cmditem{bibbycategory}[key=value, \dots] -This command loops over all bibliography categories. This is equivalent to giving one \cmd{printbibliography} command for every category but has the additional benefit of automatically skipping empty categories. The categories are processed in the order in which they were declared. See \secref{use:use:mlt} for usage examples. The options are a subset of those supported by \cmd{printbibliography}. Valid options are \opt{env}, \opt{prenote}, \opt{postnote}, \opt{section}. Note that \opt{heading} is not available with this command. The name of the current category is automatically used as the heading name. This is equivalent to passing \texttt{heading=\prm{category}} to \cmd{printbibliography} and implies that there must be a matching heading definition for every category. +This command loops over all bibliography categories. This is equivalent to giving one \cmd{printbibliography} command for every category but has the additional benefit of automatically skipping empty categories. The categories are processed in the order in which they were declared. See \secref{use:use:mlt} for usage examples. The options are a subset of those supported by \cmd{printbibliography}. Valid options are \opt{env}, \opt{prenote}, \opt{postnote}, \opt{section}. Note that \opt{heading} is not available with this command. The name of the current category is automatically used as the heading name. This is equivalent to passing \texttt{heading=\prm{category}} to \cmd{printbibliography} and implies that there must be a matching heading definition for every category. The global sorting scheme specified with package \opt{sorting} option is used for all categories. \cmditem{printbibheading}[key=value, \dots] @@ -2910,6 +3062,8 @@ If any entry includes a \bibfield{shorthand} field, \sty{biblatex} automatically This command prints the list of shorthands. It takes one optional argument, which is a list of options given in \keyval notation. Valid options are all options supported by \cmd{printbibliography} (\secref{use:bib:bib}) except \opt{prefixnumbers}, \opt{resetnumbers}, and \opt{omitnumbers}. If there are any \env{refsection} environments in the document, the list of shorthands will be local to these environments; see \secref{use:bib:sec} for details. By default, this command uses the heading \texttt{shorthands}. See \secref{use:bib:hdg} for details. +The \opt{sorting} option differs from \cmd{printbibliography} in that if omitted, the default is to sort by shorthand. + \end{ltxsyntax} \subsubsection{Bibliography Sections} @@ -2938,7 +3092,7 @@ The \env{refsegment} environment is used in the document body to mark a referenc \envitem{refsegment} -The difference between a \env{refsection} and a \env{refsegment} environment is that the former creates labels which are local to the environment whereas the latter provides a target for the \opt{segment} filter of \cmd{printbibliography} without affecting the labels. They will be unique across the entire document. \env{refsegment} environments may not be nested, but you may use them in conjunction with \env{refsection} to subdivide a reference section into segments. In this case, the segments are local to the enclosing \env{refsection} environment. Use the \env{refsegment} option of \cmd{printbibliography} to select a segment when printing the bibliography. The reference segments are numbered starting at~\texttt{1} and the number of the current segment will be written to the transcript file. All citations given outside a \env{refsegment} environment are assigned to segment~0. In contrast to the \env{refsection} environment, the current segment is not selected automatically if \cmd{printbibliography} is used within a \env{refsegment} environment. +The difference between a \env{refsection} and a \env{refsegment} environment is that the former creates labels which are local to the environment whereas the latter provides a target for the \opt{segment} filter of \cmd{printbibliography} without affecting the labels. They will be unique across the entire document. \env{refsegment} environments may not be nested, but you may use them in conjunction with \env{refsection} to subdivide a reference section into segments. In this case, the segments are local to the enclosing \env{refsection} environment. Use the \env{refsegment} option of \cmd{printbibliography} to select a segment when printing the bibliography. Within a section, the reference segments are numbered starting at~\texttt{1} and the number of the current segment will be written to the transcript file. All citations given outside a \env{refsegment} environment are assigned to segment~0. In contrast to the \env{refsection} environment, the current segment is not selected automatically if \cmd{printbibliography} is used within a \env{refsegment} environment. \csitem{newrefsegment} @@ -3145,7 +3299,7 @@ In addition to the \bibtype{set} entry type, \sty{biblatex} also supports dynami \cmditem{defbibentryset}{key}{key1,key2,key3, \dots}|\BiberOnlyMark| -The \prm{key} is the entry key of the set, which is used like any other entry key when referring to the set. The \prm{key} must be unique and it must not conflict with any other entry key. The second argument is a comma"=separated list of the entry keys which make up the set. \cmd{defbibentryset} implies the equivalent of a \cmd{nocite} command, \ie all sets which are declared are also added to the bibliography. When declaring the same set more than once, only the first invocation of \cmd{defbibentryset} will define the set. Subsequent definitions of the same \prm{key} are ignored and work like \cmd{nocite}\prm{key}. Dynamic entry sets defined in the document body are local to the enclosing \env{refsection} environment, if any. Otherwise, they are assigned to reference section~0. Those defined in the preamble are assigned to reference section~0. Note that dynamic entry sets require Biber. They will not work with any other backend. See \secref{use:use:set} for further details. +The \prm{key} is the entry key of the set, which is used like any other entry key when referring to the set. The \prm{key} must be unique and it must not conflict with any other entry key. The second argument is a comma"=separated list of the entry keys which make up the set. \cmd{defbibentryset} implies the equivalent of a \cmd{nocite} command, \ie all sets which are declared are also added to the bibliography. When declaring the same set more than once, only the first invocation of \cmd{defbibentryset} will define the set. Subsequent definitions of the same \prm{key} are ignored and work like \cmd{nocite}\prm{key}. Dynamic entry sets defined in the document body are local to the enclosing \env{refsection} environment, if any. Otherwise, they are assigned to reference section~0. Those defined in the preamble are assigned to reference section~0. Note that dynamic entry sets require \biber. They will not work with any other backend. See \secref{use:use:set} for further details. \end{ltxsyntax} @@ -3325,12 +3479,14 @@ These commands print the authors. Strictly speaking, it prints the \bibfield{lab This command prints the title. It will use the abridged title in the \bibfield{shorttitle} field, if available. Otherwise it falls back to the full title found in the \bibfield{title} field. The starred variant always prints the full title. \cmditem{citeyear}[prenote][postnote]{key} +\cmditem*{citeyear*}[prenote][postnote]{key} -This command prints the year (\bibfield{year} field or year component of \bibfield{date}). +This command prints the year (\bibfield{year} field or year component of \bibfield{date}). The starred variant includes the \bibfield{extrayear} information, if any. \cmditem{citedate}[prenote][postnote]{key} +\cmditem*{citedate*}[prenote][postnote]{key} -This command prints the full date (\bibfield{date} or \bibfield{year}). +This command prints the full date (\bibfield{date} or \bibfield{year}). The starred variant includes the \bibfield{extrayear} information, if any. \cmditem{citeurl}[prenote][postnote]{key} @@ -3839,6 +3995,28 @@ Similar to \cmd{mkbibnamelast}, but intended for the name prefix. Similar to \cmd{mkbibnamelast}, but intended for the name affix. +\csitem{relatedpunct} + +The separator between the \bibfield{relatedtype} bibliography localization string and the data from the first related entry. Here is an example with \cmd{relatedpunct} set to a dash: + +\begin{lstlisting}[style=latex]{} +A. Smith. Title. 2000, (Orig. pub. as<<->>Origtitle) +\end{lstlisting} + +\csitem{relateddelim} + +The separator between the data of multiple related entries. The default definition is an optional dot plus linebreak. Here is an example where volumes A-E are related entries of the 5 volume main work: + +\begin{lstlisting}[style=latex]{} +Donald E. Knuth. Computers & Typesetting. 5 vols. Reading, Mass.: Addison- +Wesley, 1984-1986. +Vol. A: The TEXbook. 1984. +Vol. B: TEX: The Program. 1986. +Vol. C: The METAFONTbook. By. 1986. +Vol. D: METAFONT: The Program. 1986. +Vol. E: Computer Modern Typefaces. 1986. +\end{lstlisting} + \end{ltxsyntax} \subsubsection{Language-specific Commands} @@ -3852,6 +4030,10 @@ The commands in this section are language specific. When redefining them, you ne The language specific dash to be used for ranges of numbers. +\csitem{bibrangessep}\BiberOnlyMark + +The language specific separator to be used between multiple ranges. + \csitem{bibdatedash} The language specific dash to be used for date ranges. @@ -4063,7 +4245,7 @@ Similar to \cmd{forceE} but enforces . \subsubsection{Greek} \label{use:loc:grk} -The Greek localization module requires \utf support. It will not work with any other encoding. Generally speaking, the \sty{biblatex} package is compatible with the \sty{inputenc} package and with \xelatex. The \sty{ucs} package will not work. Since \sty{inputenc}'s standard \file{utf8} module is missing glyph mappings for Greek, this leaves Greek users with \xelatex. Note that you may need to load additional packages which set up Greek fonts. As a rule of thumb, a setup which works for regular Greek documents should also work with \sty{biblatex}. However, there is one fundamental limitation. As of this writing, \sty{biblatex} has no support for switching scripts. Greek titles in the bibliography should work fine, provided that you use Biber as a backend, but English and other titles in the bibliography may be rendered in Greek letters. If you need multi-script bibliographies, using \xelatex is the only sensible choice. +The Greek localization module requires \utf support. It will not work with any other encoding. Generally speaking, the \sty{biblatex} package is compatible with the \sty{inputenc} package and with \xelatex. The \sty{ucs} package will not work. Since \sty{inputenc}'s standard \file{utf8} module is missing glyph mappings for Greek, this leaves Greek users with \xelatex. Note that you may need to load additional packages which set up Greek fonts. As a rule of thumb, a setup which works for regular Greek documents should also work with \sty{biblatex}. However, there is one fundamental limitation. As of this writing, \sty{biblatex} has no support for switching scripts. Greek titles in the bibliography should work fine, provided that you use \biber as a backend, but English and other titles in the bibliography may be rendered in Greek letters. If you need multi-script bibliographies, using \xelatex is the only sensible choice. \subsubsection{Russian} \label{use:loc:rus} @@ -4093,21 +4275,39 @@ Using the \sty{biblatex} package is slightly different from using traditional \b % With traditional \bibtex, the \cmd{bibliography} command serves two purposes. It marks the location of the bibliography and it also specifies the \file{bib} file(s). The file extension is omitted. With \sty{biblatex}, resources are specified in the preamble with \cmd{addbibresource} using the full name with \file{.bib} suffix. The bibliography is printed using the \cmd{printbibliography} command which may be used multiple times (see \secref{use:bib} for details). The document body may contain any number of citation commands (\secref{use:cit}). Processing this example file requires that a certain procedure be followed. Suppose our example file is called \path{example.tex} and our bibliographic data is in \path{bibfile.bib}. The procedure, then, is as follows: +\paragraph{\biber} + \begin{enumerate} -\item Run \bin{latex} on \path{example.tex}. If the file contains any citations, \sty{biblatex} will request the respective data from \bibtex by writing commands to the auxiliary file \path{example.aux}. +\item Run \bin{latex} on \path{example.tex}. If the file contains any citations, \sty{biblatex} will request the respective data from \biber by writing commands to the auxiliary file \path{example.bcf}. +\item Run \bin{biber} on \path{example.bcf}. \biber will retrieve the data from \path{bibfile.bib} and write it to the auxiliary file \path{example.bbl} in a format which can be processed by \sty{biblatex}. +\item Run \bin{latex} on \path{example.tex}. \sty{biblatex} will read the data from \path{example.bbl} and print all citations as well as the bibliography. -\item Run \bin{bibtex} on \path{example.aux}. \bibtex will retrieve the data from \path{bibfile.bib} and write it to the auxiliary file \path{example.bbl} in a format which can be processed by \sty{biblatex}. +\end{enumerate} + +\paragraph{\bibtex} + +\begin{enumerate} +\item Run \bin{latex} on \path{example.tex}. If the file contains any citations, \sty{biblatex} will request the respective data from \bibtex by writing commands to the auxiliary file \path{example.aux}. +\item Run \bin{bibtex} on \path{example.aux}. \bibtex will retrieve the data from \path{bibfile.bib} and write it to the auxiliary file \path{example.bbl} in a format which can be processed by \sty{biblatex}. \item Run \bin{latex} on \path{example.tex}. \sty{biblatex} will read the data from \path{example.bbl} and print all citations as well as the bibliography. \end{enumerate} -Whenever a reference to a work which has not been cited before is added, this procedure must be repeated. This is also the case if the last reference to a work which has been cited before is removed because some citation labels may change in this case. In contrast to traditional \bibtex, there is normally no need to run \bin{latex} twice after running \bin{bibtex} as far as the handling of bibliographic data is concerned.\footnote{That is, unless the \opt{defernumbers} package option is enabled. This option requires two \latex runs after the data has been exported to the \file{bbl} file by \bibtex.} Note that this only applies to the most basic case. Using the \bibfield{xref} field or the \bibfield{entryset} field may require an additional \latex/\bibtex/\latex cycle. Some other facilities provided by \sty{biblatex} may also require an additional \bin{latex} run to get certain references and the page tracking right. In this case, the usual warning messages such as «There were undefined references» and «Label(s) may have changed. Rerun to get cross-references right» will be printed. When using Biber as a backend, the workflow is essentially the same. +Whenever a reference to a work which has not been cited before is added, this procedure must be repeated. This is also the case if the last reference to a work which has been cited before is removed because some citation labels may change in this case. In contrast to traditional \bibtex, there is normally no need to run \bin{latex} twice after running the backend as far as the handling of bibliographic data is concerned.\footnote{That is, unless the \opt{defernumbers} package option is enabled. This option requires two \latex runs after the data has been exported to the \file{bbl} file by \bibtex.} + +\BibTeXOnlyMark Note that when using \bibtex as the backend this only applies to the most basic case. Using the \bibfield{xref} field or the \bibfield{entryset} field may require an additional \latex/\bibtex/\latex cycle. Some other facilities provided by \sty{biblatex} may also require an additional \bin{latex} run to get certain references and the page tracking right. In this case, the usual warning messages such as «There were undefined references» and «Label(s) may have changed. Rerun to get cross-references right» will be printed. \subsubsection{Auxiliary Files} \label{use:use:aux} +\paragraph{\biber} + +The \sty{biblatex} package uses one auxilliary \file{bcf} file only. Even if there are citation commands in a file included via \cmd{include}, you only need to run \biber on the main \file{bcf} file. All information \biber needs is in the \file{bcf} file, including information about all refsections if using mutiple \env{refsection} environments (see \secref{use:use:mlt}). + +\paragraph{\bibtex} + By default, the \sty{biblatex} package uses the main \file{aux} file only. Even if there are citation commands in a file included via \cmd{include}, which has its own \file{aux} file, you only need to run \bibtex on the main \file{aux} file. If you are using \env{refsection} environments in a document (see \secref{use:use:mlt}) \sty{biblatex} will create one additional \file{aux} file for every \env{refsection} environment. In this case, you also need to run \bin{bibtex} on each additional \file{aux} file. The name of the additional \file{aux} files is the base name of the main input file with the string \file{-blx} and a running number appended at the end. The \sty{biblatex} package issues a warning listing the files which require an additional \bibtex run. With the basic example presented in \secref{use:use:int}, it would issue the following warning: \begin{lstlisting}[style=plain] @@ -4126,14 +4326,16 @@ Package biblatex Warning: Please (re)run BibTeX on the file(s): (biblatex) and rerun LaTeX afterwards. \end{lstlisting} % -Apart from these \file{aux} files, \sty{biblatex} uses an additional \file{bib} file with the same suffix to pass certain control parameters to \bibtex. In the example above, this file would be named \path{example-blx.bib}. In the event of a file name conflict, you can change the suffix by redefining the macro \cmd{blxauxsuffix} in the document preamble. When using Biber, \sty{biblatex} writes a control file named \path{example.bcf} and ignores \cmd{blxauxsuffix}. There is also no auxiliary \file{bib} file in this case. +Apart from these \file{aux} files, \sty{biblatex} uses an additional \file{bib} file with the same suffix to pass certain control parameters to \bibtex. In the example above, this file would be named \path{example-blx.bib}. In the event of a file name conflict, you can change the suffix by redefining the macro \cmd{blxauxsuffix} in the document preamble. When using \biber, \sty{biblatex} writes a control file named \path{example.bcf} and ignores \cmd{blxauxsuffix}. There is also no auxiliary \file{bib} file in this case. Note that \sty{biblatex} will not overwrite any files it did not create. All auxiliary files created automatically by this package start with a special signature line. Before overwriting a file (excluding the main \file{aux} file, which is managed by \latex), \sty{biblatex} inspects the first line of the file to make sure that there is no file name conflict. If the file in question is missing the signature line, \sty{biblatex} will immediately issue an error message and abort before opening the output stream. In this case you should delete any spurious files accidentally left in the working directory. If the error persists, there may be a file name conflict with a file found in one of the \tex installation trees. Since the installation trees usually do not contain any \file{aux} files and the string \file{-blx} is fairly exotic in the name of a \file{bib} file, this is rather unlikely but theoretically possible. If you find out that this is indeed the case, you should redefine \cmd{blxauxsuffix} permanently in the \sty{biblatex} configuration file, \path{biblatex.cfg.} \subsubsection{Multiple Bibliographies} \label{use:use:mlt} -In a collection of articles by different authors, such as a conference proceedings volume for example, it is very common to have one bibliography for each article rather than a global one for the entire book. In the example below, each article would be presented as a separate \cmd{chapter} with its own bibliography. Note that \sty{biblatex} creates one additional \file{aux} file for every \env{refsection} environment. These files have to be processed by \bibtex as well, see \secref{use:use:aux} for details. +In a collection of articles by different authors, such as a conference proceedings volume for example, it is very common to have one bibliography for each article rather than a global one for the entire book. In the example below, each article would be presented as a separate \cmd{chapter} with its own bibliography. + +\BibTeXOnlyMark Note that with the \bibtex backend, \sty{biblatex} creates one additional \file{aux} file for every \env{refsection} environment. These files have to be processed by \bibtex as well, see \secref{use:use:aux} for details. \begin{ltxexample} \documentclass{...} @@ -4191,7 +4393,7 @@ Since giving one \cmd{printbibliography} command for each part of a subdivided b <<\bibbysection[heading=subbibliography]>> \end{lstlisting} % -When using a format with one cumulative bibliography subdivided by chapter (or any other document division) it may be more appropriate to use \env{refsegment} rather than \env{refsection} environments. The difference is that the \env{refsection} environment generates labels local to the environment while \env{refsegment} does not affect the generation of labels, hence they will be unique across the entire document. Note that \env{refsegment} environments do not require additional \file{aux} files. The next example could also be given in \secref{use:use:div} because, visually, it creates one global bibliography subdivided into multiple segments. +When using a format with one cumulative bibliography subdivided by chapter (or any other document division) it may be more appropriate to use \env{refsegment} rather than \env{refsection} environments. The difference is that the \env{refsection} environment generates labels local to the environment while \env{refsegment} does not affect the generation of labels, hence they will be unique across the entire document. Note that when using \bibtex as the backend, \env{refsegment} environments do not require additional \file{aux} files. The next example could also be given in \secref{use:use:div} because, visually, it creates one global bibliography subdivided into multiple segments. \begin{ltxexample} \documentclass{...} @@ -4221,7 +4423,7 @@ The use of \env{refsegment} is similar to \env{refsection} and there is also a c <<\bibbysegment[heading=subbibliography]>> \end{lstlisting} % -This is equivalent to giving one \cmd{printbibliography} command for every segment. +This is equivalent to giving one \cmd{printbibliography} command for every segment in the current \env{refsection}. \subsubsection{Subdivided Bibliographies} \label{use:use:div} @@ -4343,7 +4545,7 @@ An entry set is a group of entries which are cited as a single reference and lis \paragraph{Static entry sets} -\BiberOnlyMark Static entry sets are defined in the \file{bib} file like any other entry. When using Biber as the backend, defining an entry set is as simple as adding an entry of type \bibtype{set}. The entry has an \bibfield{entryset} field defining the members of the set as a comma"=separated list of entry keys: +\BiberOnlyMark Static entry sets are defined in the \file{bib} file like any other entry. When using \biber as the backend, defining an entry set is as simple as adding an entry of type \bibtype{set}. The entry has an \bibfield{entryset} field defining the members of the set as a comma"=separated list of entry keys: \begin{lstlisting}[style=bibtex]{} <<@Set>>{<>, @@ -4353,7 +4555,7 @@ An entry set is a group of entries which are cited as a single reference and lis % Entries may be part of a set in one document\slash refsection and stand-alone references in another one, depending on the presence of the \bibtype{set} entry. If the \bibtype{set} entry is cited, the set members are grouped automatically. If not, they will work like any regular entry. -When using \bibtex, which has no native support for entry sets, setting up entry sets involves more work. \bibtex requires \bibfield{entryset} and \bibfield{crossref} fields to be used in a special way. The members of the set are given in the \bibfield{entryset} field of the \bibtype{set} entry. The \bibtype{set} entry also requires a \bibfield{crossref} field which points to the first key in the \bibfield{entryset} field. In addition to that, all members of the set require \bibfield{entryset} fields which are reverse pointers to the entry key of the \bibtype{set} head entry: +When using \bibtex as the backend, which has no native support for entry sets, setting up entry sets involves more work. \bibtex requires \bibfield{entryset} and \bibfield{crossref} fields to be used in a special way. The members of the set are given in the \bibfield{entryset} field of the \bibtype{set} entry. The \bibtype{set} entry also requires a \bibfield{crossref} field which points to the first key in the \bibfield{entryset} field. In addition to that, all members of the set require \bibfield{entryset} fields which are reverse pointers to the entry key of the \bibtype{set} head entry: \begin{lstlisting}[style=bibtex]{} @Set{set1, @@ -4390,7 +4592,7 @@ Dynamic entry sets are set up and work much like static ones. The main differenc \defbibentryset{set1}{key1,key2,key3} \end{lstlisting} % -Dynamic entry sets in the document body are local to the enclosing \env{refsection} environment, if any. Otherwise, they are assigned to reference section~0. Those defined in the preamble are assigned to reference section~0. Note that dynamic entry sets require Biber. They will not work with any other backend. +Dynamic entry sets in the document body are local to the enclosing \env{refsection} environment, if any. Otherwise, they are assigned to reference section~0. Those defined in the preamble are assigned to reference section~0. Note that dynamic entry sets require \biber. They will not work with any other backend. \subsubsection[Data Containers]{Data Containers\BiberOnlyMark} \label{use:use:xdat} @@ -4638,7 +4840,7 @@ The \prm{postnote} argument is handled as a field and the formatting of this fie \subsubsection{Name Parts and Name Spacing} \label{use:cav:nam} -The \sty{biblatex} package gives users and style authors very fine"=grained control of name spacing and the line"=breaking behavior of names, especially when they are using Biber as the backend. The commands discussed in the following are documented in \secref{use:fmt:fmt,aut:fmt:fmt}. This section is meant to give an overview of how they are put together. A note on terminology: a name \emph{part} is a basic part of the name, for example the first or the last name. Each part of a name may be a single name or it may be composed of multiple names. For example, the name part \enquote*{first name} may be composed of a first and a middle name. The latter are referred to as name \emph{elements} in this section. Let's consider a simple name first: \enquote{John Edward Doe}. This name is composed of the following parts: +The \sty{biblatex} package gives users and style authors very fine"=grained control of name spacing and the line"=breaking behavior of names, especially when they are using \biber as the backend. The commands discussed in the following are documented in \secref{use:fmt:fmt,aut:fmt:fmt}. This section is meant to give an overview of how they are put together. A note on terminology: a name \emph{part} is a basic part of the name, for example the first or the last name. Each part of a name may be a single name or it may be composed of multiple names. For example, the name part \enquote*{first name} may be composed of a first and a middle name. The latter are referred to as name \emph{elements} in this section. Let's consider a simple name first: \enquote{John Edward Doe}. This name is composed of the following parts: \begin{nameparts} First & John Edward \\ @@ -4733,7 +4935,7 @@ This part of the manual documents the author interface of the \sty{biblatex} pac \subsection{Overview} \label{aut:int} -Before we get to the commands and facilities provided by \sty{biblatex}, we will have a look at some of its fundamental concepts. The \sty{biblatex} package interacts with \bibtex in a way that is somewhat different from the traditional way of doing things. Most notably, the \file{bbl} file is used differently and there is only one \file{bst} file which implements a structured data interface rather than exporting printable data. With \latex's standard bibliographic facilities, a document includes any number of citation commands in the document body plus \cmd{bibliographystyle} and \cmd{bibliography}, usually towards the end of the document. The location of the former is arbitrary, the latter marks the spot where the list of references is to be printed: +Before we get to the commands and facilities provided by \sty{biblatex}, we will have a look at some of its fundamental concepts. The \sty{biblatex} package uses auxilliary files in a specia way. Most notably, the \file{bbl} file is used differently and when using \bibtex as the backend, there is only one \file{bst} file which implements a structured data interface rather than exporting printable data. With \latex's standard bibliographic facilities, a document includes any number of citation commands in the document body plus \cmd{bibliographystyle} and \cmd{bibliography}, usually towards the end of the document. The location of the former is arbitrary, the latter marks the spot where the list of references is to be printed: \begin{ltxexample} \documentclass{...} @@ -4824,11 +5026,11 @@ In order to streamline the whole procedure, \sty{biblatex} essentially employs t \begin{enumerate} -\item Run \bin{latex}: The first step is similar to the traditional procedure described above: \cmd{bibstyle} and \cmd{bibdata} commands are written to the \file{aux} file, along with \cmd{citation} commands for all citations. We then wait for \bibtex to supply the required data. Since \sty{biblatex} uses a special \file{bst} file which implements its data interface on the \bibtex end, the \cmd{bibstyle} command is always |\bibstyle{biblatex}|. +\item Run \bin{latex}: The first step is similar to the traditional procedure described above: \cmd{bibstyle} and \cmd{bibdata} commands are written to the \file{aux} file (\bibtex backend) or \file{bcf} file (\biber backend), along with \cmd{citation} commands for all citations. We then wait for the backend to supply the required data. With \bibtex as a backend, since \sty{biblatex} uses a special \file{bst} file which implements its data interface on the \bibtex end, the \cmd{bibstyle} command is always |\bibstyle{biblatex}|. -\item Run \bin{bibtex}: \bibtex supplies those entries from the \file{bib} file which were requested by the \cmd{citation} commands in the \file{aux} file. However, it does not write a printable bibliography to the \file{bbl} file, but rather a structured representation of the bibliographic data. Just like an \file{aux} file, this \file{bbl} file does not print anything when read in. It merely puts data in memory. +\item Run \bin{biber} or \bin{bibtex}: The backend supplies those entries from the \file{bib} file which were requested by the \cmd{citation} commands in the auxilliary file. However, it does not write a printable bibliography to the \file{bbl} file, but rather a structured representation of the bibliographic data. Just like an \file{aux} file, this \file{bbl} file does not print anything when read in. It merely puts data in memory. -\item Run \bin{latex}: Starting with the second run, the \file{bbl} file is processed right at the beginning of the document body, just like an \file{aux} file. From this point on, all bibliographic data is available in memory so that all citations can be printed right away.\footnote{If the \opt{defernumbers} package option is enabled \sty{biblatex} uses an alogrithm similar to the traditional procedure to generate numeric lables. In this case, the numbers are assigned as the bibliography is printed and then cycled through the \file{aux} file. It will take an additional \latex run for them to be picked up in citations.} The citation commands have access to the complete bibliographic data, not only to a predefined label. The bibliography is generated from memory using the same data and may be filtered or split as required. +\item Run \bin{latex}: Starting with the second run, the \file{bbl} file is processed right at the beginning of the document body, just like an \file{aux} file. From this point on, all bibliographic data is available in memory so that all citations can be printed right away.\footnote{If the \opt{defernumbers} package option is enabled \sty{biblatex} uses an alogrithm similar to the traditional procedure to generate numeric lables. In this case, the numbers are assigned as the bibliography is printed and then cycled through the backend auzilliary file. It will take an additional \latex run for them to be picked up in citations.} The citation commands have access to the complete bibliographic data, not only to a predefined label. The bibliography is generated from memory using the same data and may be filtered or split as required. \end{enumerate} @@ -4844,14 +5046,19 @@ Let's consider the sample entry given above once more: } \end{lstlisting} % -With \sty{biblatex}, this entry is essentially exported in the following format: +With \sty{biblatex} and the \biber backend, this entry is essentially exported in the following format: \begin{lstlisting}[style=latex]{} \entry{companion}{book}{} - \name{author}{3}{% - {{Goossens}{G.}{Michel}{M.}{}{}{}{}}% - {{Mittelbach}{M.}{Frank}{F.}{}{}{}{}}% - {{Samarin}{S.}{Alexander}{A.}{}{}{}{}}% + \labelname{author}{3}{}{% + {{uniquename=0,hash=...}{Goossens}{G.}{Michel}{M.}{}{}{}{}}% + {{uniquename=0,hash=...}{Mittelbach}{M.}{Frank}{F.}{}{}{}{}}% + {{uniquename=0,hash=...}{Samarin}{S.}{Alexander}{A.}{}{}{}{}}% + } + \name{author}{3}{}{% + {{uniquename=0,hash=...}{Goossens}{G.}{Michel}{M.}{}{}{}{}}% + {{uniquename=0,hash=...}{Mittelbach}{M.}{Frank}{F.}{}{}{}{}}% + {{uniquename=0,hash=...}{Samarin}{S.}{Alexander}{A.}{}{}{}{}}% } \list{publisher}{1}{% {Addison-Wesley}% @@ -4988,7 +5195,7 @@ The list of shorthands is handled in a similar way. \cmd{printshorthands} uses t \subsubsection{Bibliography Drivers} \label{aut:bbx:drv} -Before we go over the commands which form the data interface of the \sty{biblatex} package, it may be instructive to have a look at the structure of a bibliography driver. Note that the example given below is greatly simplified, but still functional. For the sake of readability, we omit several fields which may be part of a \bibtype{book} entry and also simplify the handling of those which are considered. The main point is to give you an idea of how a driver is structured. For information about the mapping of \bibtex's fields to \sty{biblatex}'s data types, see \secref{bib:fld}. +Before we go over the commands which form the data interface of the \sty{biblatex} package, it may be instructive to have a look at the structure of a bibliography driver. Note that the example given below is greatly simplified, but still functional. For the sake of readability, we omit several fields which may be part of a \bibtype{book} entry and also simplify the handling of those which are considered. The main point is to give you an idea of how a driver is structured. For information about the mapping of the \bibtex file format fields to \sty{biblatex}'s data types, see \secref{bib:fld}. \begin{lstlisting}[style=latex]{} \DeclareBibliographyDriver{book}{% @@ -5048,7 +5255,7 @@ The following lists and fields are used by \sty{biblatex} to pass data to biblio \fielditem{entrykey}{string} -The entry key of an item in the \file{bib} file. This is the string used by \sty{biblatex} and \bibtex to identify an entry in the \file{bib} file. +The entry key of an item in the \file{bib} file. This is the string used by \sty{biblatex} and the backend to identify an entry in the \file{bib} file. \fielditem{childentrykey}{string} @@ -5095,16 +5302,16 @@ This field holds the initial letter of the string used during sorting. This is u \fielditem{labelalpha}{literal} -A label similar to the labels generated by the \path{alpha.bst} style of traditional \bibtex. This label consists of initials drawn from the \bibfield{labelname} list plus the last two digits of the publication year. The \bibfield{label} field may be used to override its non"=numeric portion. If the \bibfield{label} field is defined, \sty{biblatex} will use its value and append the last two digits of the publication year when generating \bibfield{labelalpha}. The \bibfield{shorthand} field may be used to override the entire label. If defined, \bibfield{labelalpha} is the \bibfield{shorthand} rather than an automatically generated label. A complete label consists of the fields \bibfield{labelalpha} plus \bibfield{extraalpha}. Note that the \bibfield{labelalpha} and \bibfield{extraalpha} fields need to be requested with the package option \opt{labelalpha} (\secref{use:opt:pre:int}). See also \bibfield{extraalpha} as well as \cmd{labelalphaothers} in \secref{use:fmt:fmt}. +When using \bibtex as the backend, a label similar to the labels generated by the \path{alpha.bst} style of traditional \bibtex. This default label consists of initials drawn from the \bibfield{labelname} list plus the last two digits of the publication year. The \bibfield{label} field may be used to override its non"=numeric portion. If the \bibfield{label} field is defined, \sty{biblatex} will use its value and append the last two digits of the publication year when generating \bibfield{labelalpha}. The \bibfield{shorthand} field may be used to override the entire label. If defined, \bibfield{labelalpha} is the \bibfield{shorthand} rather than an automatically generated label. \BiberOnlyMark With \biber, users can specify a template used to construct the alphabetic label (see \secref{aut:ctm:lab}) and the default template mirrors the format mentioned for bibtex above. A complete label consists of the fields \bibfield{labelalpha} plus \bibfield{extraalpha}. Note that the \bibfield{labelalpha} and \bibfield{extraalpha} fields need to be requested with the package option \opt{labelalpha} (\secref{use:opt:pre:int}). See also \bibfield{extraalpha} as well as \cmd{labelalphaothers} in \secref{use:fmt:fmt}. \fielditem{extraalpha}{integer} -The citation scheme usually requires a letter to be appended to the label if the bibliography contains two or more works by the same author which were all published in the same year. In this case, the \bibfield{extraalpha} field holds an integer which may be converted to a letter with \cmd{mknumalph} or formatted in some other way. This field is similar to the role of \bibfield{extrayear} in the author"=year scheme. A complete label consists of the fields \bibfield{labelalpha} plus \bibfield{extraalpha}. Note that the \bibfield{labelalpha} and \bibfield{extraalpha} fields need to be requested with the package option \opt{labelalpha}, see \secref{use:opt:pre:int} for details. See also \bibfield{labelalpha} as well as \cmd{labelalphaothers} in \secref{use:fmt:fmt}. +The citation scheme usually requires a letter to be appended to the label if the bibliography contains two or more works by the same author which were all published in the same year. In this case, the \bibfield{extraalpha} field holds an integer which may be converted to a letter with \cmd{mknumalph} or formatted in some other way. This field is similar to the role of \bibfield{extrayear} in the author"=year scheme. A complete label consists of the fields \bibfield{labelalpha} plus \bibfield{extraalpha}. Note that the \bibfield{labelalpha} and \bibfield{extraalpha} fields need to be requested with the package option \opt{labelalpha}, see \secref{use:opt:pre:int} for details. See also \bibfield{labelalpha} as well as \cmd{labelalphaothers} in \secref{use:fmt:fmt}. Table \ref{use:opt:tab2} summarises the various \opt{extra*} disambiguation counters and what they track. \listitem{labelname}{name} The name to be printed in citations. This list is a copy of either the \bibfield{shortauthor}, the \bibfield{author}, the \bibfield{shorteditor}, the \bibfield{editor}, or the \bibfield{translator} list, which are normally checked for in this order. If no authors and editors are available, this list is undefined. Note that this list is also responsive to the \opt{useauthor}, \opt{useeditor}, and \opt{usetranslator} options, see \secref{use:opt:bib}. Citation styles should use this list when printing the name in a citation. This list is provided for convenience only and does not carry any additional meaning. -\BiberOnlyMark With Biber, this field may be customized. See \secref{aut:ctm:fld} for details. +\BiberOnlyMark With \biber, this field may be customized. See \secref{aut:ctm:fld} for details. \fielditem{labelnumber}{literal} @@ -5116,16 +5323,24 @@ If the \opt{prefixnumbers} option of \cmd{printbibliography} has been set in ord \fielditem{labeltitle}{literal} -The title to be printed in citations. If a short title is available, \bibfield{labeltitle} is a copy of the \bibfield{shorttitle} field, otherwise \sty{biblatex} falls back to the \bibfield{title} field. Citation styles printing short titles may simply make use of this field instead of checking whether a \bibfield{shorttitle} field is available every time they print a title. This field is provided for convenience only and does not carry any additional meaning. +The printable title of a work. In some circumstances, a style might need to choose a title from a list of a possible title fields. For example, citation styles printing short titles may want to print the \bibfield{shorttitle} field if it exists but otherwise print the \bibfield{title} field. \BiberOnlyMark The list of fields to be considered when constructing \bibfield{labeltitle} may be customized. See \secref{aut:ctm:fld} for details. Note that the \bibfield{extratitle} field needs to be requested with the package option \opt{labeltitle}, see \secref{use:opt:pre:int} for details. See also \bibfield{extratitle}. Note also that the \bibfield{extratitleyear} field needs to be requested with the package option \opt{labeltitleyear}. See also \bibfield{extratitleyear}. + +\fielditem{extratitle}{integer} + +It is sometimes useful, for example in author"=title citation schemes, to be able to disambiguate works with the same title. For works by the same \bibfield{labelname} with the same \bibfield{labeltitle}, the \bibfield{extratitle} field holds an integer which may be converted to a letter with \cmd{mknumalph} or formatted in some other way (or it can be merely used as a flag to say that some other field such as a date should be used in conjunction with the \bibfield{labeltitle} field). This field is undefined if there is only one work with the same \bibfield{labeltitle} by the same \bibfield{labelname} in the bibliography. Note that the \bibfield{extratitle} field needs to be requested with the package option \opt{labeltitle}, see \secref{use:opt:pre:int} for details. See also \bibfield{labeltitle}. Table \ref{use:opt:tab2} summarises the various \opt{extra*} disambiguation counters and what they track. + +\fielditem{extratitleyear}{integer} + +It is sometimes useful, for example in author"=title citation schemes, to be able to disambiguate works with the same title in the same year but with no author. For works with the same \bibfield{labeltitle} and with the same \bibfield{labelyear}, the \bibfield{extratitleyear} field holds an integer which may be converted to a letter with \cmd{mknumalph} or formatted in some other way (or it can be merely used as a flag to say that some other field such as a publisher should be used in conjunction with the \bibfield{labelyear} field). This field is undefined if there is only one work with the same \bibfield{labeltitle} and \bibfield{labelyear} in the bibliography. Note that the \bibfield{extratitleyear} field needs to be requested with the package option \opt{labeltitleyear}, see \secref{use:opt:pre:int} for details. See also \bibfield{labeltitleyear}. Table \ref{use:opt:tab2} summarises the various \opt{extra*} disambiguation counters and what they track. \fielditem{labelyear}{literal} The publication year, as specified in the \bibfield{date} or the \bibfield{year} field, for use in author-year labels. A complete author-year label consists of the fields \bibfield{labelyear} plus \bibfield{extrayear}. Note that the \bibfield{labelyear} and \bibfield{extrayear} fields need to be requested with the package option \opt{labelyear}, see \secref{use:opt:pre:int} for details. See also \bibfield{extrayear}. -\BiberOnlyMark With Biber, this field may be customized. See \secref{aut:ctm:fld} for details. +\BiberOnlyMark With \biber, this field may be customized. See \secref{aut:ctm:fld} for details. \fielditem{extrayear}{integer} -The author"=year citation scheme usually requires a letter to be appended to the year if the bibliography contains two or more works by the same author which were all published in the same year. In this case, the \bibfield{extrayear} field holds an integer which may be converted to a letter with \cmd{mknumalph} or formatted in some other way. This field is undefined if there is only one work by the author in the bibliography or if all works by the author have different publication years. A complete author-year label consists of the fields \bibfield{labelyear} plus \bibfield{extrayear}. Note that the \bibfield{labelyear} and \bibfield{extrayear} fields need to be requested with the package option \opt{labelyear}, see \secref{use:opt:pre:int} for details. See also \bibfield{labelyear}. +The author"=year citation scheme usually requires a letter to be appended to the year if the bibliography contains two or more works by the same author which were all published in the same year. In this case, the \bibfield{extrayear} field holds an integer which may be converted to a letter with \cmd{mknumalph} or formatted in some other way. This field is undefined if there is only one work by the author in the bibliography or if all works by the author have different publication years. A complete author-year label consists of the fields \bibfield{labelyear} plus \bibfield{extrayear}. Note that the \bibfield{labelyear} and \bibfield{extrayear} fields need to be requested with the package option \opt{labelyear}, see \secref{use:opt:pre:int} for details. See also \bibfield{labelyear}. Table \ref{use:opt:tab2} summarises the various \opt{extra*} disambiguation counters and what they track. \end{fieldlist} @@ -5503,10 +5718,10 @@ Defines the name list format \prm{format}. This formatting directive is arbitrar \item[\#2] The last names, given as initials. \item[\#3] The first names. This argument also includes all middle names. \item[\#4] The first names, given as initials. -\item[\#5] The name prefixes, for example von, van, of, da, de, del, della, etc. Note that name prefixes are referred to as the of the name in the \bibtex documentation. +\item[\#5] The name prefixes, for example von, van, of, da, de, del, della, etc. Note that name prefixes are referred to as the of the name in the \bibtex file format documentation. \item[\#6] The name prefixes, given as initials. \item[\#7] The name affixes, for example , , , , etc. -Note that name affixes are referred to as the of the name in the \bibtex documentation. +Note that name affixes are referred to as the of the name in the \bibtex file format documentation. \item[\#8] The name affixes, given as initials. \end{argumentlist} % @@ -5556,162 +5771,1067 @@ Declares \prm{alias} to be an alias for the name list format \prm{format}. If an \subsection{Customization} \label{aut:ctm} -\subsubsection{Sorting} -\label{aut:ctm:srt} +\subsubsection{Related Entries} +\label{aut:ctm:rel} +The related entries feature comprises the following components: +\begin{itemize} +\item Special fields in an entry to set up and describe relationships +\item Optionally, localization strings to prefix the related data +\item Macros to extract and print the related data +\item Formats to format the localization string and related data +\end{itemize} +% +The special fields are \bibfield{related}, \bibfield{relatedtype} and \bibfield{relatedstring}: +\begin{keymarglist} +\item[related] A comma"=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[relatedtype] The type of relationship. This serves three purposes. If the value of this field resolves to a localization string identifier, then the resulting localized 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 localized 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 localization string identifier, the localization key value specified is printed before data from the related entries. If the field does not specify a localization 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). +\end{keymarglist} -In addition to the predefined sorting schemes discussed in \secref{use:srt}, it is possible to define new ones or modify the default definitions. The sorting process may be customized further by excluding certain fields from sorting on a per-type basis and by automatically populating the \bibfield{presort} field on a per-type basis. Note that custom sorting schemes require Biber. They will not work with any other backend. +The related entry feature is enabled by default by the package option \opt{related} from \secref{use:opt:pre:gen}. The related information entry data from the related entries is included via a \cmd{usebibmacro\{related\}} call. Standard styles call this macro towards the end of each driver. Style authors should ensure the existence of (or take note of existing) localization strings which are useful as values for the \bibfield{relatedtype} field, such as \texttt{translationof} or perhaps \texttt{translatedas}. They can then define macros and/or formats with the name \texttt{related:\prm{relatedtype}} which will be used to format the data. The file \path{biblatex.def} contains macros and formats for some common relation types which can be used as templates. In particular, the \cmd{entrydata*} command is essential in such macros in order to make the data of the related entries available. Examples of entries using this feature can be found in the \sty{biblatex} distribution examples file \path{biblatex-examples.bib}. There are some specific formatting macros for this feature which control delimiters and separators in related entry information, see \secref{aut:fmt:fmt}. -\begin{ltxsyntax} +\subsubsection{Dynamic Modification of Data} +\label{aut:ctm:map} -\cmditem{DeclareSortingScheme}{name}{specification}|\BiberOnlyMark| +Bibliographic data sources which are automatically generated or which you have no control over can be a problem if you need to edit them in some way. For this reason, \biber has ability to modify data as it is read so that you can apply modifications to the source data stream without actually changing it. The modification can be defined in \biber's config file (see \biber docs), or via \sty{biblatex} macros in which case you can apply the modification only for specific documents. -Defines the sorting scheme \prm{name}. The \prm{name} is the identifier passed to the \opt{sorting} option (\secref{use:opt:pre:gen}) when selecting the sorting scheme. The \prm{specification} is an undelimited list of \cmd{sort} directives which specify the elements to be considered in the sorting process. Spaces, tabs, and line endings may be used freely to visually arrange the \prm{specification}. Blank lines are not permissible. This command may only be used in the preamble. +\begin{ltxsyntax} -\cmditem{sort}{elements} +\cmditem{DeclareSourcemap}{specification}|\BiberOnlyMark| -Specifies the elements considered in the sorting process. The \prm{elements} are an undelimited list of \cmd{name}, \cmd{list}, \cmd{field}, \cmd{literal}, and \cmd{citeorder} commands which are evalutated in the order in which they are given. If an element is defined, it is added to the sort key and the sorting routine skips to the next \cmd{sort} directive. If it is undefined, the next element is evaluated. Since literal strings are always defined, any \cmd{literal} commands should be the sole or the last element in a \cmd{sort} directive. The \cmd{sort} command supports the following optional arguments: +Defines source data modification (mapping) rules which can be used to perform any combination of the following tasks: -\begin{optionlist*} +\begin{itemize} +\item Map data source entrytypes to different entrytypes +\item Map datasource fields to different fields +\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 +\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 + entrytype +\end{itemize} -\choitem[ascending]{direction}{ascending, descending} +The \prm{specification} is an undelimited list of \cmd{maps} directives which specify containers for mappings rules applying to a particular data source type (\ref{use:bib:res}). Spaces, tabs, and line endings may be used freely to visually arrange the \prm{specification}. Blank lines are not permissible. This command may only be used in the preamble. -The sort direction, which may be either \texttt{ascending} or \texttt{descending}. The default is ascending order. +\cmditem{maps}{elements} -\boolitem[false]{final} +Contains an ordered set of \cmd{map} elements each of which is a logically related set of mapping steps to apply to the data source. -This option marks a \cmd{sort} directive as the final one in the \prm{specification}. If one of the \prm{elements} is available, the remainder of the \prm{specification} will be ignored. The short form \opt{final} is equivalent to \kvopt{final}{true}. +\begin{optionlist*} -\boolitem{sortcase} +\choitem{datatype}{bibtex, biblatexml, ris, zoterordfxml, endnotexml} -Whether or not to sort case"=sensitively. The default setting depends on the global \opt{sortcase} option. +Data source type which the contained \cmd{map} directives apply to (\ref{use:bib:res}). -\boolitem{sortupper} +\boolitem[false]{overwrite} -Whether or not to sort in (\texttt{true}) or order (\texttt{false}). The default setting depends on the global \opt{sortupper} option. +Specify whether a mapping rule is allowed to overwrite already existing data in an entry. If this option is not specified, the default is \texttt{false}. The short form \opt{overwrite} is equivalent to \kvopt{overwrite}{true}. \end{optionlist*} -\cmditem{name}{name list} +\cmditem{map}{restrictions,steps} -The \cmd{name} element adds a \prm{name list} to the sorting specification. If the \prm{name list} is undefined, the element is skipped. +A container for an ordered set of map \cmd{step}s, optionally restricted to particular entrytypes or data sources. This is a grouping element to allow a set of mapping steps to apply only to specific entrytypes or data sources. Mapping steps must always be contained within a \cmd{map} element. -\cmditem{list}{literal list} +\begin{optionlist*} -The \cmd{list} element adds a \prm{literal list} to the sorting specification. If the \prm{literal list} is undefined, the element is skipped. +\boolitem{overwrite} -\cmditem{field}[key=value, \dots]{field} +As the same option on the parent \cmd{maps} element. This option allows an override on a per-map group basis. If this option is not specified, the default is the parent \cmd{maps} element option value. The short form \opt{overwrite} is equivalent to \kvopt{overwrite}{true}. -The \cmd{field} element adds a \prm{field} to the sorting specification. If the \prm{field} is undefined, the element is skipped. The \cmd{field} command supports the following optional arguments: +\end{optionlist*} -\begin{optionlist*} +\cmditem{perdatasource}{datasource} -\choitem[left]{padside}{left, right} +Restricts all \cmd{step}s in this \cmd{map} element to entries from the named \prm{datasource}. The \prm{datasource} name should be exactly as given in a \cmd{addresource} macro defining a data source for the document. Multiple \cmd{perdatasource} restrictions are allowed within a \cmd{map} element. -Pads a field on the \texttt{left} or \texttt{right} side using \opt{padchar} so that its width is \opt{padwidth}. If no padding option is set, no padding is done at all. If any padding option is specified, then padding is performed and the missing options are assigned built-in default values. If padding and substring matching are both specified, the substring match is performed first. Padding is particularly useful with numeric fields. For example, the command +\cmditem{pertype}{entrytype} -\begin{lstlisting}[style=latex]{} -\field[padside=left,padwidth=2,padchar=0]{volume} -\end{lstlisting} -% -will pad the \bibfield{volume} field with leading zeros to a width of two characters. This way, volumes are sorted by numeric value (\texttt{01\slash 02\slash 11\slash 12}) rather than in alphabetic order (\texttt{1\slash 11\slash 12\slash 2}). +Restricts all \cmd{step}s in this \cmd{map} element to entries of the named \prm{entrytype}. Multiple \cmd{pertype} restrictions are allowed within a \cmd{map} element. -\intitem[4]{padwidth} +\cmditem{step} -The target width in characters. +A mapping step. Each step is applied sequentially to every relevant entry where means those entries which correspond to the data source type, entrytype and data source name restrictions mentioned above. Each step is applied to the entry as it appears after the application of all previous steps. The mapping performed by the step is determined by the following options: -\valitem[0]{padchar}{character} +\begin{optionlist*} -The character to be used when padding the field. +\valitem{typesource}{entrytype} +\valitem{typetarget}{entrytype} +\valitem{fieldsource}{entryfield} +\valitem{fieldtarget}{entryfield} +\valitem{match}{regexp} +\valitem{replace}{regexp} +\valitem{fieldset}{entryfield} +\valitem{fieldvalue}{string} +\boolitem[false]{final} +\boolitem[false]{null} +\boolitem[false]{origfield} +\boolitem[false]{origfieldval} +\boolitem[false]{origentrytype} +% +For all boolean \cmd{step} options, the short form \opt{option} is equivalent to \kvopt{option}{true}. The following rules for a mapping step apply: -\choitem[left]{strside}{left, right} +\renewcommand{\labelitemii}{$\circ$} -Performs a substring match on the \texttt{left} or \texttt{right} side of the field. The number of characters to match is specified by the corresponding \texttt{strwidth} option. If no substring option is set, no substring matching is performed at all. If any substring option is specified, then substring matching is performed and the missing options are assigned built-in default values. If padding and substring matching are both specified, the substring match is performed first. +\begin{itemize} +\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. +\item Change the \texttt{fieldsource} \prm{entryfield} to + \texttt{fieldtarget}, if defined. If + \texttt{final} is \texttt{true} then if there is no \texttt{fieldsource} \prm{entryfield} in the entry, processing of the parent \cmd{map} immediately terminates. +\item If \texttt{match} is defined but + \texttt{replace} is not, only apply the step if the \texttt{fieldsource} \prm{entryfield} matches the + \texttt{match} regular expression\footnote{Regular expressions are full Perl 5.14 regular expressions. This means you may need to deal with special characters, see examples.} +\item Perform a regular expression match and replace on the value of the \texttt{fieldsource} \prm{entryfield} if \texttt{match} and \texttt{replace} are defined. +\item If \texttt{fieldset} is defined, then one and only one of the following other options is then mandatory: + \begin{itemize} + \item\ \texttt{fieldvalue} --- The \texttt{fieldset} \prm{entryfield} is set to the \texttt{fieldvalue} \prm{string} + \item\ \texttt{null} --- The \texttt{fieldset} \prm{entryfield} is ignored, as if it did not exist in the datasource + \item\ \texttt{origentrytype} --- The \texttt{fieldset} \prm{entryfield} is set to the most recently mentioned \texttt{typesource} \prm{entrytype} name + \item\ \texttt{origfield} --- The \texttt{fieldset} \prm{entryfield} is set to the most recently mentioned \texttt{fieldsource} \prm{entryfield} name + \item\ \texttt{origfieldval} --- The \texttt{fieldset} \prm{entryfield} is set to the most recently mentioned \texttt{fieldsource} value + \end{itemize} +\end{itemize} -\intitem[4]{strwidth} +\end{optionlist*} -The number of characters to match. +\end{ltxsyntax} -\end{optionlist*} +\begin{ltxsyntax} -\cmditem{literal}{string} +\cmditem{DeclareDefaultSourcemap}[datatype=driver]{specification}|\BiberOnlyMark| -The \cmd{literal} element adds a literal \prm{string} to the sorting specification. This is useful as a fallback if some fields are not available. +This command sets the driver default source mappings for the specified \prm{driver}. Such mappings are conceptually separate from user mappings defined with \cmd{DeclareSourcemap} and consist of mappings which are part of the driver setup. Users should not normally need to change these. User mappings defined with \cmd{DeclareSourcemap} are applied before the driver defaults. These defaults are described in Appendix \ref{apx:maps}. The \prm{specification} is identical to that for \cmd{DeclareSourcemap} but without the \cmd{maps} elements: the \prm{specification} is just a list of \cmd{map} elements since each \cmd{DeclareDefaultSourcemap} only applies to one datatype driver. See the default definitions in Appendix \ref{apx:maps} for examples. -\csitem{citeorder} +\end{ltxsyntax} -The \cmd{citeorder} element has a special meaning. It indicates that the entries should be kept in the order in which they were cited. It is usually the only element in the \prm{specification}: +Here are some data source mapping examples: \begin{lstlisting}[style=latex]{} -\DeclareSortingScheme{none}{ - \sort{\citeorder} +\DeclareSourcemap{ + \maps[datatype=bibtex]{ + \map{ + \perdatasource{<>} + \perdatasource{<>} + \step[fieldset=<>, fieldvalue={<>}] + } + } } \end{lstlisting} - -\end{ltxsyntax} - -Here are some examples. In the first example, we define a simple name\slash title\slash year scheme. The name element may be either the \bibfield{author}, the \bibfield{editor}, or the \bibfield{translator}. Given this specification, the sorting routine will use the first element which is available and continue with the \bibfield{title}. Note that the options \opt{useauthor}, \opt{useeditor}, and \opt{usetranslator} are considered automatically in the sorting process: - +% +This would add a \bibfield{keywords} field with value +to all entries which are found in either the +\texttt{examples1.bib} or \texttt{examples2.bib} files. +% \begin{lstlisting}[style=latex]{} -\DeclareSortingScheme{sample}{ - \sort{ - \name{<>} - \name{<>} - \name{<>} +\DeclareSourcemap{ + \maps[datatype=bibtex]{ + \map{ + \step[fieldsource=<>] + \step[fieldset=<<note>>, origfieldval] + } } - \sort{ - \field{<<title>>} +} +\end{lstlisting} +% +Copy the \bibfield{title} field to the \bibfield{note} field unless the +\bibfield{note} field already exists. +% +\begin{lstlisting}[style=latex]{} +\DeclareSourcemap{ + \maps[datatype=bibtex]{ + \map{ + \step[typesource=<<chat>>, typetarget=<<customa>>, final] + \step[fieldset=<<type>>, origentrytype] + } } - \sort{ - \field{<<year>>} +} +\end{lstlisting} +% +Any \bibfield{chat} entrytypes would become \bibfield{customa} entrytypes and +would automatically have a \bibfield{type} field set to +<chat> unless the \bibfield{type} field already exists in the entry (because +\texttt{overwrite} is false by default). This mapping applies only to entries of type +\bibtype{chat} since the first step has \texttt{final} set and so if the +\texttt{typesource} does not match the entry entrytype, processing of this +\cmd{map} immediately terminates. +% +\begin{lstlisting}[style=latex]{} +\DeclareSourcemap{ + \maps[datatype=bibtex]{ + \map{ + \perdatasource{<<examples.bib>>} + \pertype{<<article>>} + \pertype{<<book>>} + \step[fieldset=<<abstract>>, null] + \step[fieldset=<<note>>, fieldvalue={<<Auto-created this field>>}] + } } } \end{lstlisting} % -In the next example, we define the same scheme in a more elaborate way, considering special fields such as \bibfield{presort}, \bibfield{sortkey}, \bibfield{sortname}, etc. Since the \bibfield{sortkey} field specifies the master sort key, it needs to override all other elements except for \bibfield{presort}. This is indicated by the \opt{final} option. If the \bibfield{sortkey} field is available, processing will stop at this point. If not, the sorting routine continues with the next \cmd{sort} directive. This setup corresponds to the default definition of the \texttt{nty} scheme: - +Any entries of entrytype \bibtype{article} or \bibtype{book} from the +\texttt{examples.bib} datasource would have their \bibfield{abstract} +fields removed and a \bibfield{note} field added with value <Auto-created this field>. +% \begin{lstlisting}[style=latex]{} -\DeclareSortingScheme{nty}{ - \sort{ - \field{<<presort>>} +\DeclareSourcemap{ + \maps[datatype=bibtex]{ + \map{ + \step[fieldset=<<abstract>>, null] + \step[fieldsource=<<conductor>>, fieldtarget=<<namea>>] + \step[fieldsource=<<gps>>, fieldtarget=<<usera>>] + } } - \sort[<<final>>]{ - \field{<<sortkey>>} +} +\end{lstlisting} +% +This removes \bibfield{abstract} fields from any entry, changes +\bibfield{conductor} fields to \bibfield{namea} fields and changes \bibfield{gps} +fields to \bibfield{usera} fields. +% +\begin{lstlisting}[style=latex]{} +\DeclareSourcemap{ + \maps[datatype=bibtex]{ + \map{ + \step[fieldsource=<<pubmedid>>, fieldtarget=<<eprint>>, final] + \step[fieldset=<<eprinttype>>, origfield] + \step[fieldset=<<userd>>, fieldvalue={<<Some string of things>>}] + } } - \sort{ - \name{<<sortname>>} - \name{author} - \name{editor} - \name{translator} - \field{sorttitle} - \field{title} +} +\end{lstlisting} +% +Applies only to entries with \bibfield{pubmed} fields and maps +\bibfield{pubmedid} fields to \bibfield{eprint} fields, sets the \bibfield{eprinttype} +field to <pubmedid> and also sets the \bibfield{userd} field to the string +<Some string of things>. +% +\begin{lstlisting}[style=latex]{} +\DeclareSourcemap{ + \maps[datatype=bibtex]{ + \map{ + \step[fieldsource=<<series>>, + match=\regexp{<<\A\d*(.+)>>}, + replace=\regexp{<<\L$1}>>] + } } - \sort{ - \field{<<sorttitle>>} - \field{title} +} +\end{lstlisting} +%$<- to stop emacs highlighting breaking +Here, the contents of the \bibfield{series} field have leading numbers stripped and the remainder of the contents lowercased. Since regular expressions usually contain all sort of special characters, it is best to enclose them in the provided \cmd{regexp} macro as shown---this will pass the expression through to \biber correctly. +% +\begin{lstlisting}[style=latex]{} +\DeclareSourcemap{ + \maps[datatype=bibtex]{ + \map{ + \step[fieldsource=<<maintitle>>, + match=\regexp{<<Collected\s+Works.+Freud>>}, + final] + \step[fieldset=<<keywords>>, fieldvalue=<<freud>>] + } } - \sort{ - \field{<<sortyear>>} - \field{year} +} +\end{lstlisting} +%$<- to stop emacs highlighting breaking +Here, if for an entry, the \bibfield{maintitle} field matches a particular regular expression, we set a special keyword so we can, for example, make a references section just for certain items. +% +\begin{lstlisting}[style=latex]{} +\DeclareSourcemap{ + \maps[datatype=bibtex]{ + \map{ + \step[fieldsource=<<lista>>, match=\regexp{<<regexp>>}, final] + \step[fieldset=<<lista>>, null] + } } } \end{lstlisting} +% +If an entry has a \bibfield{lista} field which matches regular expression <regexp>, then it is removed. +% +\begin{lstlisting}[style=latex]{} +\DeclareSourcemap{ + \maps[datatype=bibtex]{ + \map{ + \step[fieldsource=<<author>>, + match={<<Smith, Bill>>}, + replace={<<Smith, William>>}] + \step[fieldsource=<<author>>, + match={<<Jones, Baz>>}, + replace={<<Jones, Barry>>}] + } + } +} +\end{lstlisting} +% +Here, we use multiple match/replace for the same field to regularise some inconstant name variants. Bear in mind that \cmd{step} processing within a \opt{map} element is sequential and so the changes from a previous \cmd{step}s are already committed. Note that we don't need the \cmd{regexp} macro to protect the regular expressions in this example as they contain no characters which need special escaping. Please note that due to the difficulty of protecting regular expressions in \LaTeX, there should be no literal spaces in the argument to \cmd{regexp}. Please use escape code equivalents if spaces are needed. For example, this example, if using \cmd{regexp}, should be: +% +\begin{lstlisting}[style=latex]{} +\DeclareSourcemap{ + \maps[datatype=bibtex]{ + \map{ + \step[fieldsource=<<author>>, + match=\regexp{<<Smith,\s+Bill>>}, + replace=\regexp{<<Smith,\x20William>>}] + \step[fieldsource=<<author>>, + match=\regexp{<<Jones,\s+Baz>>}, + replace=\regexp{<<Jones,\x20Barry>>}] + } + } +} +\end{lstlisting} +% +Here, we have used the hexadecimal escape sequence <|\x20|> in place of literal spaces in the replacement strings. +% +\begin{lstlisting}[style=latex]{} +\DeclareSourcemap{ + \maps[datatype=bibtex]{ + \map[overwrite]{ + \step[fieldsource=<<author>>, match={<<Doe,>>}, final] + \step[fieldset=<<shortauthor>>, origfieldval] + \step[fieldset=<<sortname>>, origfieldval] + \step[fieldsource=<<shortauthor>>, + match=\regexp{<<Doe,\s*(?:\.|ohn)(?:[-]*)(?:P\.|Paul)*>>}, + replace={<<Doe, John Paul>>}] + \step[fieldsource=<<sortname>>, + match=\regexp{<<Doe,\s*(?:\.|ohn)(?:[-]*)(?:P\.|Paul)*>>}, + replace={<<Doe, John Paul>>}] + } + } +} +\end{lstlisting} +% +Only applies to entries with an \bibfield{author} field matching <Doe,>. First the \bibfield{author} field is copied to both the \bibfield{shortauthor} and \bibfield{sortname} fields, overwriting them if they already exist. Then, these two new fields are modified to canonicalise a particular name, which presumably has some variants in the data source. -\begin{ltxsyntax} - -\cmditem{DeclareSortExclusion}{entrytype, \dots}{field, \dots}|\BiberOnlyMark| +\subsubsection{Data Model Specification} +\label{aut:ctm:dm} -Specifies fields to be excluded from sorting on a per-type basis. The \prm{entrytype} argument and the \prm{field} argument may be a comma"=separated list of values. A blank \prm{field} argument will clear all exclusions for this \prm{entrytype}. This command may only be used in the preamble. +The data model which \sty{biblatex} uses consists of four main elements: + +\begin{itemize} +\item Specification of valid Entrytypes +\item Specification of valid Fields along with their type, datatype and any special flags +\item Specification of which Fields are valid in which Entrytypes +\item Specification of constraints which can be used to validate data against the data model +\end{itemize} + +The default data model is defined in the core \sty{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 \sty{biblatex} and also by the backends. The data model for the \bibtex backend is hard-coded and cannot be changed. Changing the data model is only supported for the \biber 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}). + +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: + +\begin{itemize} +\item Whether all entrytypes are valid entrytypes +\item Whether all fields are valid fields for their entrytype +\item Whether the fields obey various constraints on their format which you specify +\end{itemize} +% +Redefining the data model can be done in several places. Style authors can create a \file{.dbx} file which contains the data model macros required and this will be loaded automatically when using the \sty{biblatex} package \opt{style} option by looking for a file named afer the style with a \file{.dbx} (just like the \file{.cbx} and \file{.bbx} files for a style). Alternatively, the name of the data model file can be different from the style name by specifying the name (without \file{.dbx} extension) to the package \opt{datamodel} option. After loading the style data model file, \sty{biblatex} then loads, if present, a users \file{biblatex-dm.cfg} which should be put somewhere \sty{biblatex} can find it, just like the main configuration file \sty{biblatex.cfg}. To summarise, the data model is determined by adding to the data model from each of these locations, in order:\\ + +\noindent\file{blx-dm.def}$\rightarrow$\\ +\hspace*{1em}\file{<datamodel option>.dbx} $\rightarrow$\\ +\hspace*{2em}\file{<style option>.dbx} $\rightarrow$\\ +\hspace*{3em}\file{biblatex-dm.cfg}\\ + +\noindent The data model is defined using the following macros: + +\begin{ltxsyntax} + +\cmditem{DeclareDatamodelEntrytypes}{entrytypes}|\BiberOnlyMark| + +Declares the comma"=separated list of \prm{entrytypes} to be valid entrytypes in the data model. This command may only be used in a data model configuration file. + +\cmditem{DeclareDatamodelFields}[options]{fields}|\BiberOnlyMark| + +Declares the comma"=separated list of \prm{fields} to be valid fields in the data model with associated comma"=separated \prm{options}. This command may only be used in a data model configuration file. Valid \prm{options} are: + +\begin{optionlist*} + +\valitem{type}{field type} + +Set the type of the field as described in \secref{bib:fld:typ}. Is typically <field> or <list>. + +\valitem{datatype}{field datatype} + +Set the datatype of the field as described in \secref{bib:fld:typ}. For example, <name> or <literal>. + +\boolitem[false]{nullok} + +The field is allowed to be defined but empty. + +\boolitem[false]{skipout} + +The field is not output to the \file{.bbl} and is therefore not present during \sty{biblatex} style processing. + +\end{optionlist*} + +\cmditem{DeclareDatamodelEntryfields}[entrytypes]{fields}|\BiberOnlyMark| + +Declares that the comma"=separated list of \prm{fields} is valid for the comma"=separated list of \prm{entrytypes}. If \prm{entrytypes} is not given, the fields are valid for all entrytypes. This command may only be used in a data model configuration file. + +\cmditem{DeclareDatamodelConstraints}[entrytypes]{specification}|\BiberOnlyMark| + +If a comma"=separated list of \prm{entrytypes} is given, the constraints apply only to those entrytypes. The \prm{specification} is an undelimited list of \cmd{constraint} directives which specify a constraint. Spaces, tabs, and line endings may be used freely to visually arrange the \prm{specification}. Blank lines are not permissible. This command may only be used in a data model configuration file. + +\cmditem{constraint}[type=constrainttype]{elements} + +Specifies a constraint of type \prm{constrainttype}. Valid constraint types are: + +\begin{optionlist*} + +\choitem{type}{data, mandatory, conditional} + +Constraints of type <data> put restrictions on the value of a field. Constraints of type <mandatory> specify which fields or combinations of fields an entrytype should have. Constraints of type <conditional> allow more sophisticated conditional and quantified field constraints. + +\choitem{datatype}{integer, isbn, issn, ismn, date, pattern} + +For constraints of type \prm{data}, constrain field values to be the given datatype. + +\valitem{rangemin}{num} + +For constraints of \prm{type} <data> and \prm{datatype} <integer>, constrain field values to be at least \prm{num}. + +\valitem{rangemax}{num} + +For constraints of \prm{type} <data> and \prm{datatype} <integer>, constrain field values to be at most \prm{num}. + +\valitem{pattern}{patt} + +For constraints of \prm{type} <data> and \prm{datatype} <pattern>, constrain field values to match regular expression pattern \prm{patt}. It is best to wrap any regular expression in the macro \cmd{regexp}, see \secref{aut:ctm:map}. + +\end{optionlist*} + +A \cmd{constraint} macro may contain any of the following: + +\cmditem{constraintfieldsor}{fields} + +For constraints of \prm{type} <mandatory>, specifies that an entry must contain a boolean OR of the \cmd{constraintfield}s. + +\cmditem{constraintfieldsxor}{fields} + +For constraints of \prm{type} <mandatory>, specifies that an entry must contain a boolean XOR of the \cmd{constraintfield}s. + +\cmditem{antecedent}[quantifier=quantspec]{fields} + +For constraints of \prm{type} <conditional>, specifies a quantified set of \cmd{constraintfield}s which must be satisfied before the \cmd{consequent} of the constraint is checked. \prm{quantspec} should have one of the following values: + +\begin{optionlist*} + +\choitem{quantifier}{all, one, none} + +Specifies how many of the \cmd{constrainfield}'s inside the \cmd{antecedent} have to be present to satisfy the antecedent of the conditional constraint. + +\end{optionlist*} + +\cmditem{consequent}[quantifier=quantspec]{fields} + +For constraints of \prm{type} <conditional>, specifies a quantified set of \cmd{constraintfield}s which must be satisfied if the preceding \cmd{antecedent} of the constraint was satisfied. \prm{quantspec} should have one of the following values: + +\begin{optionlist*} + +\choitem{quantifier}{all, one, none} + +Specifies how many of the \cmd{constrainfield}'s inside the \cmd{consequent} have to be present to satisfy the consequent of the conditional constraint. + +\end{optionlist*} + +\cmditem{constraintfield}{field} + +For constraints of \prm{type} <data>, the constraint applies to this \prm{field}. For constraints of \prm{type} <mandatory>, the entry must contain this \prm{field}. + +The data model declaration macros may be used multiple times as they append to the previous definitions. In order to replace, change or remove existing definitions (such as the default model which is loaded with \sty{biblatex}), you should reset (clear) the current definition and then set what you want using the following macros. Typically, these macros will be the first things in any \file{biblatex-dm.cfg} file: + +\cmditem{ResetDatamodelEntrytypes} + +Clear all data model entrytype information. + +\cmditem{ResetDatamodelFields} + +Clear all data model field information. + +\cmditem{ResetDatamodelEntryfields} + +Clear all data model fields for entrytypes information. + +\cmditem{ResetDatamodelConstraints} + +Clear all data model fields Constraints information. + +\end{ltxsyntax} + +Here is an example of a simple data model. Refer to the core \sty{biblatex} file \file{blx-dm.def} for the default data model specification. + +\begin{lstlisting}[style=latex]{} +\ResetDatamodelEntrytypes +\ResetDatamodelFields +\ResetDatamodelEntryfields +\ResetDatamodelConstraints + +\DeclareDatamodelEntrytypes{<<entrytype1, entrytype2>>} + +\DeclareDatamodelFields[type=field, datatype=literal]{<<field1,field2,field3,field4>>} + +\DeclareDatamodelEntryfields{<<field1>>} +\DeclareDatamodelEntryfields[entrytype1]{<<field2,field3>>} +\DeclareDatamodelEntryfields[entrytype2]{<<field2,field3,field4>>} + +\DeclareDatamodelConstraints[<<entrytype1>>]{ + \constraint[type=data, datatype=integer, rangemin=3, rangemax=10]{ + \constraintfield{<<field1>>} + } + \constraint[type=mandatory]{ + \constraintfield{<<field1>>} + \constraintfieldsxor{ + \constraintfield{<<field2>>} + \constraintfield{<<field3>>} + } + } +} +\DeclareDatamodelConstraints{ + \constraint[type=conditional]{ + \antecedent[quantifier=none]{ + \constraintfield{<<field2>>} + } + \consequent[quantifier=all]{ + \constraintfield{<<field3>>} + \constraintfield{<<field4>>} + } + } +} +\end{lstlisting} +% +This model specifies: + +\begin{itemize} +\item Clear the default data model completely +\item Two valid entry types \bibtype{entrytype1} and \bibtype{entrytype2} +\item Four valid literal field fields +\item \bibfield{field1} is valid for all entrytypes +\item \bibfield{field2} and \bibfield{field3} are valid for \bibfield{entrytype1} +\item \bibfield{field2}, \bibfield{field3} and \bibfield{field4} are valid for \bibtype{entrytype2} +\item For \bibtype{entrytype1}: + \begin{itemize} + \item \bibfield{field1} must be an integer between 3 and 10 + \item \bibfield{field1} must be present + \item One and only one of \bibfield{field2} or \bibfield{field3} must be present + \end{itemize} +\item For any entrytype, if \bibfield{field2} is not present, \bibfield{field3} and \bibfield{field4} must be present +\end{itemize} + +\subsubsection{Labels} +\label{aut:ctm:lab} + +Alphabetic styles use a label to identify bibliography entries. This label is constructed from components of the entry using a template which describes how to build the label. The template can be customised on a global or per-type basis. Label customisation requires \biber and will not work with any other backend. + +\begin{ltxsyntax} + +\cmditem{DeclareLabelalphaTemplate}[entrytype, \dots]{specification}|\BiberOnlyMark| + +Defines the alphabetic label template for the given entrytypes. If no entrytypes are specified in the first argument, then the global label template is defined. The \prm{specification} is an undelimited list of \cmd{labelelement} directives which specify the elements used to build the label. Spaces, tabs, and line endings may be used freely to visually arrange the \prm{specification}. Blank lines are not permissible. This command may only be used in the preamble. + +\cmditem{labelelement}{elements} + +Specifies the elements used to build the label. The \prm{elements} are an undelimited list of \cmd{field} or \cmd{literal} commands which are evaluated in the order in which they are given. The first \cmd{field} or \cmd{literal} which expands to a non-empty string is used as the \cmd{labelelement} expansion and the next \cmd{labelelement}, if any, is then processed. + +\cmditem{field}[options]{field} + +If \prm{field} is non-empty, use it as the current label \cmd{labelelement}, subject to the options below. Useful values for \prm{field} are typically the name list type fields, date fields, and title fields. You may also use the `citekey' pseudo-field to specify the citation key as part of the label. Name list fields are treated specially and the options which take substrings of the \prm{field} to use in the \cmd{labelelement} are applied to the lastname of every name in a name list (see below). + +\begin{optionlist*} + +\boolitem[false]{final} + +This option marks a \cmd{field} directive as the final one in the \prm{specification}. If the \prm{field} is non-empty, then this field is used for the label and the remainder of the \prm{specification} will be ignored. The short form \opt{final} is equivalent to \kvopt{final}{true}. + +\boolitem[false]{lowercase} + +Forces the label part derived from the field to lowercase. By default, the case is taken from the field source and not modified. + +\intitem[1]{strwidth} + +The number of characters of the \prm{field} to use. For name list fields, if \kvopt{useprefix}{true}, the first character of the name prefix is prepended to the substring. + +\choitem[left]{strside}{left, right} + +The side of the string from which to take the \texttt{strwidth} number of characters. + +\boolitem[false]{uppercase} + +Forces the label part derived from the field to uppercase. By default, the case is taken from the field source and not modified. + +\boolitem[false]{varwidth} + +Use a variable width, left-side substring of characters from the \prm{field} (each lastname in name list fields). The length of the string is determined by the minimum length needed to disambiguate the substring from all other \prm{field} elements in the same position in the label. For name list fields, this means that each name substring is disambigated from all other name substrings which occur in the sme position in the name list (see examples below). This option overrides \texttt{strwidth} if both are used. The short form \opt{varwidth} is equivalent to \kvopt{varwidth}{true}. For name list fields, if \kvopt{useprefix}{true}, the first character of the name prefix is prepended to the substring. + +\boolitem[false]{varwidthnorm} + +As \texttt{varwidth} but will force the disambiguated substrings for the \prm{field} to be the same length as the longest disambiguated substring. This can be used to regularise the format of the labels if desired. This option overrides \texttt{strwidth} if both are used. The short form \opt{varwidthnorm} is equivalent to \kvopt{varwidthnorm}{true}. + +\boolitem[false]{varwidthlist} + +Alternative method of automatic label disambiguation where the field as a whole is disambiguated from all other fields in the same label position. For non-name list fields, this is equivalent to \texttt{varwidth}. For name list fields, names in a name list are not disambiguated from other names in the same position in their name lists but instead the entire name list is disambiguated as a whole from other name lists (see examples below). This option overrides \texttt{strwidth} if both are used. The short form \opt{varwidthlist} is equivalent to \kvopt{varwidthlist}{true}. For name list fields, if \kvopt{useprefix}{true}, the first character of the name prefix is prepended to the substring. + +\intitem{strwidthmax} + +When using \texttt{varwidth}, this option sets a limit (in number of characters) on the length of variable width substrings. This option can be used to regularise the label. + +\intitem[1]{strfixedcount} + +When using \texttt{varwidthnorm}, there must be at least \texttt{strfixedcount} disambiguated substrings with the same, maximal length to trigger the forcing of all disambiguated substrings to this same maximal length. + +\boolitem[false]{compound} + +For static (non-varwidth) disambiguation, treat lastname name components separated by whitespace or hyphens (compound last names) as separate names for label generation. This means that when forming a label out of, for example the surname <Ballam Forsyth> with a 1 character, left-side substring, this name would give <BF> with \kvopt{compound}{true} and <B> with \kvopt{compound}{false}. The short form \opt{compound} is equivalent to \kvopt{compound}{true}. + +\intitem{ifnames} + +Only use this \cmd{field} specification if it is a name list field with \texttt{ifnames} names in it. This allows a \cmd{labelelement} to be conditionalised on name length (see below). + +\intitem{names} + +By default, for name list fields, the number of names considered when building the label obeys the \cnt{maxalphanames}\slash \cnt{minalphanames} truncation. This option can be used to override this with an explicit upper limit of how many names to consider. This is useful if you have some very long name lists which might result in a very long label. + +\end{optionlist*} + +\cmditem{literal}{characters} + +Insert the literal \prm{characters} into the label at this point. + +\end{ltxsyntax} + +Note that the template for labels can be defined per-type and you should be aware of this when using the automatically disambiguated label functionality. Disambiguation is not per-type as this might lead to ambiguity due to different label formats for different types being isolated from each others disambiguation process. Normally, you will want to use very different label formats for different types to make the type obvious by the label. + +Here are some examples. The default global \sty{biblatex} alphabetic label template is defined below. Firstly, \bibfield{shorthand} has \kvopt{final}{true} and so if there is a \bibfield{shorthand} field, it is used as the label and nothing more of the template is considered. Next, the \bibfield{label} field is used as the first label element if it exists. Otherwise, if there is only one name (\kvopt{ifnames}{1}) in the \bibfield{labelname} list, then three characters from the left side of the lastname in the \bibfield{labelname} are used as the first label element. If the \bibfield{labelname} has more than one name in it, one character from the left side of each lastname is used as the first label element. The second label element consists of 2 characters from the right side of the \bibfield{year} field. + +\begin{lstlisting}[style=latex]{} +\DeclareLabelalphaTemplate{ + \labelelement{ + \field[final]{<<shorthand>>} + \field{<<label>>} + \field[strwidth=3,strside=left,ifnames=1]{<<labelname>>} + \field[strwidth=1,strside=left]{<<labelname>>} + } + \labelelement{ + \field[strwidth=2,strside=right]{<<year>>} + } +} +\end{lstlisting} +% +To get an idea of how the label automatic disambiguation works, consider the following author lists: + +\begin{lstlisting}{} +Agassi, Chang, Laver (2000) +Agassi, Connors, Lendl (2001) +Agassi, Courier, Laver (2002) +Borg, Connors, Edberg (2003) +Borg, Connors, Emerson (2004) +\end{lstlisting} +% +Assuming a template declaration such as: + +\begin{lstlisting}[style=latex]{} +\DeclareLabelalphaTemplate{ + \labelelement{ + \field[varwidth]{<<labelname>>} + } +} +\end{lstlisting} +% +Then the labels would be: + +\begin{lstlisting}{} +Agassi, Chang, Laver [AChLa] +Agassi, Connors, Lendl [AConLe] +Agassi, Courier, Laver [ACouLa] +Borg, Connors, Edberg [BConEd] +Borg, Connors, Emerson [BConEm] +\end{lstlisting} +% +With normalised variable width labels defined: + +\begin{lstlisting}[style=latex]{} +\DeclareLabelalphaTemplate{ + \labelelement{ + \field[varwidthnorm]{<<labelname>>} + } +} +\end{lstlisting} +% +You would get the following as the substrings of names in each position are extended to the length of the longest substring in that same position: + +\begin{lstlisting}{} +Agassi, Chang, Laver [AChaLa] +Agassi, Connors, Lendl [AConLe] +Agassi, Courier, Laver [ACouLa] +Borg, Connors, Edberg [BConEd] +Borg, Connors, Emerson [BConEm] +\end{lstlisting} +% +With a restriction to two characters for the name components of the label element defined like this: + +\begin{lstlisting}[style=latex]{} +\DeclareLabelalphaTemplate{ + \labelelement{ + \field[varwidthnorm,strwidthmax=2]{<<labelname>>} + } +} +\end{lstlisting} +% +This would be the result (note that the individual lastname label parts are no longer unambiguous): + +\begin{lstlisting}{} +Agassi, Chang, Laver [AChLa] +Agassi, Connors, Lendl [ACoLe] +Agassi, Courier, Laver [ACoLa] +Borg, Connors, Edberg [BCoEd] +Borg, Connors, Emerson [BCoEm] +\end{lstlisting} +% +Alternatively, you could choose to disambiguate the name lists as a whole with: + +\begin{lstlisting}[style=latex]{} +\DeclareLabelalphaTemplate{ + \labelelement{ + \field[varwidthlist]{<<labelname>>} + } +} +\end{lstlisting} +% +Which would result in: + +\begin{lstlisting}{} +Agassi, Chang, Laver [AChL] +Agassi, Connors, Lendl [ACoL] +Agassi, Courier, Laver [ACL] +Borg, Connors, Edberg [BCEd] +Borg, Connors, Emerson [BCE] +\end{lstlisting} +% +Perhaps you only want to consider at most two names for label generation but disambiguate at the whole name list level: +\begin{lstlisting}[style=latex]{} +\DeclareLabelalphaTemplate{ + \labelelement{ + \field[varwidthlist,names=2]{<<labelname>>} + } +} +\end{lstlisting} +% +Which would result in: +\begin{lstlisting}{} +Agassi, Chang, Laver [ACh+] +Agassi, Connors, Lendl [ACo+] +Agassi, Courier, Laver [AC+] +Borg, Connors, Edberg [BC+a] +Borg, Connors, Emerson [BC+b] +\end{lstlisting} +% +In this last example, you can see \cmd{labelalphaothers} has been appended to show that there are more names. The last two labels now require disambiguating with \cmd{extraalpha} as there is no way of disambiguating this label name list with only two names. + +Finally, here is an example using multiple label elements: + +\begin{lstlisting}[style=latex]{} +\DeclareLabelalphaTemplate{ + \labelelement{ + \field[varwidthlist]{<<labelname>>} + } + \labelelement{ + \literal{-} + } + \labelelement{ + \field[strwidth=3,strside=right]{<<labelyear>>} + } +} +\end{lstlisting} +% +Which would result in: +\begin{lstlisting}{} +Agassi, Chang, Laver [AChL-000] +Agassi, Connors, Lendl [AConL-001] +Agassi, Courier, Laver [ACouL-002] +Borg, Connors, Edberg [BCEd-003] +Borg, Connors, Emerson [BCEm-004] +\end{lstlisting} + +\subsubsection{Sorting} +\label{aut:ctm:srt} + +In addition to the predefined sorting schemes discussed in \secref{use:srt}, it is possible to define new ones or modify the default definitions. The sorting process may be customized further by excluding certain fields from sorting on a per-type basis and by automatically populating the \bibfield{presort} field on a per-type basis. Note that custom sorting schemes require \biber. They will not work with any other backend. + +\begin{ltxsyntax} + +\cmditem{DeclareSortingScheme}{name}{specification}|\BiberOnlyMark| + +Defines the sorting scheme \prm{name}. The \prm{name} is the identifier passed to the \opt{sorting} option (\secref{use:opt:pre:gen}) when selecting the sorting scheme. The \prm{specification} is an undelimited list of \cmd{sort} directives which specify the elements to be considered in the sorting process. Spaces, tabs, and line endings may be used freely to visually arrange the \prm{specification}. Blank lines are not permissible. This command may only be used in the preamble. + +\cmditem{sort}{elements} + +Specifies the elements considered in the sorting process. The \prm{elements} are an undelimited list of \cmd{name}, \cmd{list}, \cmd{field}, \cmd{literal}, and \cmd{citeorder} commands which are evaluated in the order in which they are given. If an element is defined, it is added to the sort key and the sorting routine skips to the next \cmd{sort} directive. If it is undefined, the next element is evaluated. Since literal strings are always defined, any \cmd{literal} commands should be the sole or the last element in a \cmd{sort} directive. The \cmd{sort} command supports the following optional arguments: + +\begin{optionlist*} + +\choitem[ascending]{direction}{ascending, descending} + +The sort direction, which may be either \texttt{ascending} or \texttt{descending}. The default is ascending order. + +\boolitem[false]{final} + +This option marks a \cmd{sort} directive as the final one in the \prm{specification}. If one of the \prm{elements} is available, the remainder of the \prm{specification} will be ignored. The short form \opt{final} is equivalent to \kvopt{final}{true}. + +\boolitem{sortcase} + +Whether or not to sort case"=sensitively. The default setting depends on the global \opt{sortcase} option. + +\boolitem{sortupper} + +Whether or not to sort in <uppercase before lowercase> (\texttt{true}) or <lowercase before uppercase> order (\texttt{false}). The default setting depends on the global \opt{sortupper} option. + +\end{optionlist*} + +\cmditem{field}[key=value, \dots]{field} + +The \cmd{field} element adds a \prm{field} to the sorting specification. If the \prm{field} is undefined, the element is skipped. The \cmd{field} command supports the following optional arguments: + +\begin{optionlist*} + +\choitem[left]{padside}{left, right} + +Pads a field on the \texttt{left} or \texttt{right} side using \opt{padchar} so that its width is \opt{padwidth}. If no padding option is set, no padding is done at all. If any padding option is specified, then padding is performed and the missing options are assigned built-in default values. If padding and substring matching are both specified, the substring match is performed first. Padding is particularly useful with numeric fields. For example, the command + +\begin{lstlisting}[style=latex]{} +\field[padside=left,padwidth=2,padchar=0]{<<volume>>} +\end{lstlisting} +% +will pad the \bibfield{volume} field with leading zeros to a width of two characters. This way, volumes are sorted by numeric value (\texttt{01\slash 02\slash 11\slash 12}) rather than in alphabetic order (\texttt{1\slash 11\slash 12\slash 2}). + +\intitem[4]{padwidth} + +The target width in characters. + +\valitem[0]{padchar}{character} + +The character to be used when padding the field. + +\choitem[left]{strside}{left, right} + +Performs a substring match on the \texttt{left} or \texttt{right} side of the field. The number of characters to match is specified by the corresponding \texttt{strwidth} option. If no substring option is set, no substring matching is performed at all. If any substring option is specified, then substring matching is performed and the missing options are assigned built-in default values. If padding and substring matching are both specified, the substring match is performed first. + +\intitem[4]{strwidth} + +The number of characters to match. + +\end{optionlist*} + +\cmditem{literal}{string} + +The \cmd{literal} element adds a literal \prm{string} to the sorting specification. This is useful as a fallback if some fields are not available. + +\csitem{citeorder} + +The \cmd{citeorder} element has a special meaning. It requests a sort based on the lexical order of the actual citations. For entries cited within the same citation command like: + +\begin{lstlisting}[style=latex]{} +\cite{one,two} +\end{lstlisting} +% +there is a distinction between the lexical order and the semantic order. Here «one» and «two» have the same semantic order but a unique lexical order. The semantic order only matters if you specify further sorting to disambiguate entries with the same semantic order. For example, this is the definition of the \opt{none} sorting scheme): + +\begin{lstlisting}[style=latex]{} +\DeclareSortingScheme{none}{ + \sort{\citeorder} +} +\end{lstlisting} +% +This sorts the bibliography purely lexically by the order of the keys in the citation commands. In the example above, it sorts «one» before «two». However, suppose that you consider «one» and «two» to have the same order (semantic order) since they are cited at the same time and want to further sort these by year. Suppose «two» has an earlier \bibfield{year} than «one»: + +\begin{lstlisting}[style=latex]{} +\DeclareSortingScheme{noneyear}{ + \sort{\citeorder} + \sort{<<year>>} +} +\end{lstlisting} +% +This sorts «two» before «one», even though lexically, «one» would sort before «two». This is possible because the semantic order can be disambiguated by the further sorting on year. With the standard \opt{none} sorting scheme, the lexical order and semantic order are identical because there is nothing further to disambiguate them. This means that you can use \cmd{citeorder} just like any other sorting specification element, choosing how to further sort entries cited at the same time (in the same citation command). + +\end{ltxsyntax} + +Here are some examples of sorting schemes. In the first example, we define a simple name\slash title\slash year scheme. The name element may be either the \bibfield{author}, the \bibfield{editor}, or the \bibfield{translator}. Given this specification, the sorting routine will use the first element which is available and continue with the \bibfield{title}. Note that the options \opt{useauthor}, \opt{useeditor}, and \opt{usetranslator} are considered automatically in the sorting process: + +\begin{lstlisting}[style=latex]{} +\DeclareSortingScheme{sample}{ + \sort{ + \field{<<author>>} + \field{<<editor>>} + \field{<<translator>>} + } + \sort{ + \field{<<title>>} + } + \sort{ + \field{<<year>>} + } +} +\end{lstlisting} +% +In the next example, we define the same scheme in a more elaborate way, considering special fields such as \bibfield{presort}, \bibfield{sortkey}, \bibfield{sortname}, etc. Since the \bibfield{sortkey} field specifies the master sort key, it needs to override all other elements except for \bibfield{presort}. This is indicated by the \opt{final} option. If the \bibfield{sortkey} field is available, processing will stop at this point. If not, the sorting routine continues with the next \cmd{sort} directive. This setup corresponds to the default definition of the \texttt{nty} scheme: + +\begin{lstlisting}[style=latex]{} +\DeclareSortingScheme{nty}{ + \sort{ + \field{<<presort>>} + } + \sort[final]{ + \field{<<sortkey>>} + } + \sort{ + \field{<<sortname>>} + \field{<<author>>} + \field{<<editor>>} + \field{<<translator>>} + \field{<<sorttitle>>} + \field{<<title>>} + } + \sort{ + \field{<<sorttitle>>} + \field{<<title>>} + } + \sort{ + \field{<<sortyear>>} + \field{<<year>>} + } +} +\end{lstlisting} + +\begin{ltxsyntax} + +\cmditem{DeclareSortExclusion}{entrytype, \dots}{field, \dots}|\BiberOnlyMark| + +Specifies fields to be excluded from sorting on a per-type basis. The \prm{entrytype} argument and the \prm{field} argument may be a comma"=separated list of values. A blank \prm{field} argument will clear all exclusions for this \prm{entrytype}. This command may only be used in the preamble. \cmditem{DeclarePresort}[entrytype, \dots]{string}|\BiberOnlyMark| -Specifies are string to be used to automatically populate the \bibfield{presort} field of entries without a \bibfield{presort} field. The \bibfield{presort} may be defined globally or on a per-type basis. If the optional \prm{entrytype} argument is given, the \prm{string} applies to the respective entry type. If not, it serves as the global default value. Specifying an \prm{entrytype} in conjunction with a blank \prm{string} will clear the type-specific setting. The \prm{entrytype} argument may be a comma"=separated list of values. This command may only be used in the preamble. +Specifies a string to be used to automatically populate the \bibfield{presort} field of entries without a \bibfield{presort} field. The \bibfield{presort} may be defined globally or on a per-type basis. If the optional \prm{entrytype} argument is given, the \prm{string} applies to the respective entry type. If not, it serves as the global default value. Specifying an \prm{entrytype} in conjunction with a blank \prm{string} will clear the type-specific setting. The \prm{entrytype} argument may be a comma"=separated list of values. This command may only be used in the preamble. \end{ltxsyntax} +\subsubsection{Controlling Name Initials Generation} +\label{aut:ctm:noinit} + +Generating initials for name parts from a given name involves some difficulties when you have names with prefixes, diacritics, hyphens etc. Often, you want to ignore things like prefixes when generating initials so that the initials for «al-Hasan» is just «H» instead of «a-H». This is tricky when you also have names like «Ho-Pun» where you want the initials to be «H-P», for example. + +\begin{ltxsyntax} + +\cmditem{DeclareNoinit}{specification}|\BiberOnlyMark| + +Defines regular expressions to strip from names before generating initials. The \prm{specification} is an undelimited list of \cmd{noinit} directives which specify the regular expressions to remove from the name. Spaces, tabs and line endings may be used freely to visually arrange the \prm{specification}. Blank lines are not permissible. This command may only be used in the preamble. + +\cmditem{noinit}{regexp} + +Any number of \cmd{noinit} commands can be given each of which specifies to remove the \prm{regexp} from the copy of the name which the initials generation system sees. Since regular expressions usually contain special characters, it is best to enclose them in the provided \cmd{regexp} macro as shown---this will pass the expression through to \biber correctly. + +\end{ltxsyntax} + +If there is no \cmd{DeclareNoinit} specification, \biber will default to: + +\begin{lstlisting}[style=latex]{} +\DeclareNoinit{ + % strip lowercase prefixes like 'al-' when generating initials from names + \noinit{\regexp{<<\b\p{Ll}{2}\p{Pd}>>}} + % strip diacritics when generating initials from names + \noinit{\regexp{<<[\x{2bf}\x{2018}]>>}} +} +\end{lstlisting} +% +This \biber default strips diacritics and lowercase prefixes from names before generating initials. + +\subsubsection{Fine Tuning Sorting} +\label{aut:ctm:nosort} + +It can be useful to fine tune sorting so that it ignores certain parts of particular fields. + +\begin{ltxsyntax} + +\cmditem{DeclareNosort}{specification}|\BiberOnlyMark| + +Defines regular expressions to strip from particular fields or types of fields when sorting. The \prm{specification} is an undelimited list of \cmd{nosort} directives which specify the regular expressions to remove from particular fields or type of field. Spaces, tabs and line endings may be used freely to visually arrange the \prm{specification}. Blank lines are not permissible. This command may only be used in the preamble. + +\cmditem{nosort}{field or field type}{regexp} + +Any number of \cmd{nosort} commands can be given each of which specifies to remove the \prm{regexp} from the \prm{field} or \prm{field type}. A \prm{field type} is simple a convenience grouping of semantically similar fields from which you might want to remove a regexp. Table \ref{aut:nosort} shows the available field types. Since regular expressions usually contain special characters, it is best to enclose them in the provided \cmd{regexp} macro as shown---this will pass the expression through to \biber correctly. + +\end{ltxsyntax} + +If there is no \cmd{DeclareNosort} specification, \biber will default to: + +\begin{lstlisting}[style=latex]{} +\DeclareNosort{ + % strip prefixes like 'al-' when sorting names + \nosort{type_names}{\regexp{<<\A\p{L}{2}\p{Pd}>>}} + % strip diacritics when sorting names + \nosort{type_names}{\regexp{<<[\x{2bf}\x{2018}]>>}} +} +\end{lstlisting} +% +This \biber default strips diacritics and prefixes from names when sorting. Suppose you wanted to ignore «The» at the beginning of a \bibfield{title} field when sorting: + +\begin{lstlisting}[style=latex]{} +\DeclareNosort{ + \nosort{<<title>>}{\regexp{<<\AThe\s+>>}} +} +\end{lstlisting} +% +Or if you wanted to ignore «The» at the beginning of any title field: + +\begin{lstlisting}[style=latex]{} +\DeclareNosort{ + \nosort{<<type_title>>}{\regexp{<<\AThe\s+>>}} +} +\end{lstlisting} + +\begin{table}[h] +\tablesetup +\begin{tabular}{@{}V{0.5\textwidth}@{}V{0.5\textwidth}@{}} +\toprule +\multicolumn{1}{@{}H}{Field Type} & +\multicolumn{1}{@{}H}{Fields} \\ +\cmidrule(r){1-1}\cmidrule{2-2} +|type_name| & |author| \\ + & |afterword| \\ + & |annotator| \\ + & |bookauthor| \\ + & |commentator| \\ + & |editor| \\ + & |editora| \\ + & |editorb| \\ + & |editorc| \\ + & |foreword| \\ + & |holder| \\ + & |introduction| \\ + & |namea| \\ + & |nameb| \\ + & |namec| \\ + & |shortauthor| \\ + & |shorteditor| \\ + & |translator| \\ +|type_title| & |booktitle| \\ + & |eventtitle| \\ + & |issuetitle| \\ + & |journaltitle| \\ + & |maintitle| \\ + & |origtitle| \\ + & |title| \\ +\bottomrule +\end{tabular} +\caption{Field types for \cmd{nosort}} +\label{aut:nosort} +\end{table} + \subsubsection{Special Fields} \label{aut:ctm:fld} -Some of the automatically generated fields from \secref{aut:bbx:fld:lab} may be customized. Note that this requires Biber. +Some of the automatically generated fields from \secref{aut:bbx:fld:lab} may be customized. Note that this requires \biber. \begin{ltxsyntax} @@ -5735,12 +6855,22 @@ Defines the date components to consider when generating the \bibfield{labelyear} % The \bibfield{labelyear} field may be customized globally or on a per-type basis. If the optional \prm{entrytype} argument is given, the specification applies to the respective entry type. If not, it is applied globally. The \prm{entrytype} argument may be a comma"=separated list of values. This command may only be used in the preamble. See also \secref{aut:bbx:fld:dat}. +\cmditem{DeclareLabeltitle}[entrytype, \dots]{specification}|\BiberOnlyMark| + +Defines the fields to consider when generating the \bibfield{labeltitle} field (see \secref{aut:bbx:fld:lab}). The \prm{specification} is a comma"=separated list of fields. The fields are checked in the order listed and the first field which is available will be used as \bibfield{labeltitle}. This is the default definition: + +\begin{lstlisting}[style=latex]{} +\DeclareLabeltitle{shorttitle,title} +\end{lstlisting} +% +The \bibfield{labeltitle} field may be customized globally or on a per-type basis. If the optional \prm{entrytype} argument is given, the specification applies to the respective entry type. If not, it is applied globally. The \prm{entrytype} argument may be a comma"=separated list of values. This command may only be used in the preamble. + \end{ltxsyntax} \subsubsection{Data Inheritance (\bibfield{crossref})} \label{aut:ctm:ref} -Biber features a highly customizable cross-referencing mechanism with flexible data inheritance rules. This sections deals with the configuration interface. See \apxref{apx:ref} for the default configuration. Note that customized data inheritance requires Biber. It will not work with any other backend. A note on terminology: the \emph{child} or \emph{target} is the entry with the \bibfield{crossref} field, the \emph{parent} or \emph{source} is the entry the \bibfield{crossref} field points to. The child inherits data from the parent. +\biber features a highly customizable cross-referencing mechanism with flexible data inheritance rules. This sections deals with the configuration interface. See \apxref{apx:ref} for the default configuration. Note that customized data inheritance requires \biber. It will not work with any other backend. A note on terminology: the \emph{child} or \emph{target} is the entry with the \bibfield{crossref} field, the \emph{parent} or \emph{source} is the entry the \bibfield{crossref} field points to. The child inherits data from the parent. \begin{ltxsyntax} @@ -5788,7 +6918,7 @@ This example shows how to configure the default inheritance behavior. The above \begin{lstlisting}[style=latex]{} \DefaultInheritance[ - <<\except>>{<<*>>}{<<online>>}{<<all=false>>} + \except{<<*>>}{<<online>>}{<<all=false>>} ]{all=true,override=false} \end{lstlisting} % @@ -5796,9 +6926,9 @@ This example is similar to the one above but adds one exception: entries of type \begin{lstlisting}[style=latex]{} \DeclareDataInheritance{<<collection>>}{<<incollection>>}{ - <<\inherit>>{<<title>>}{<<booktitle>>} - \inherit{subtitle}{booksubtitle} - \inherit{titleaddon}{booktitleaddon} + \inherit{<<title>>}{<<booktitle>>} + \inherit{<<subtitle>>}{<<booksubtitle>>} + \inherit{<<titleaddon>>}{<<booktitleaddon>>} } \end{lstlisting} % @@ -5815,7 +6945,7 @@ This rule is an example of one-to-many mapping: it maps the \bibfield{author} fi \begin{lstlisting}[style=latex]{} \DeclareDataInheritance{<<*>>}{<<inbook,incollection>>}{ - <<\noinherit>>{<<introduction>>} + \noinherit{<<introduction>>} } \end{lstlisting} % @@ -5824,7 +6954,7 @@ This rule prevents inheritance of the \bibfield{introduction} field. It applies \begin{lstlisting}[style=latex]{} \DeclareDataInheritance{<<*>>}{<<*>>}{ - \noinherit{abstract} + \noinherit{<<abstract>>} } \end{lstlisting} % @@ -5835,7 +6965,7 @@ This rule, which applies to all entries, regardless of the source and target ent \ResetDataInheritance \end{lstlisting} % -This example demonstrates how to emulate \bibtex's cross"=referencing mechanism. It enables inheritance by default, disables overwriting, and clears all other inheritance rules and mappings. +This example demonstrates how to emulate traditional \bibtex's cross"=referencing mechanism. It enables inheritance by default, disables overwriting, and clears all other inheritance rules and mappings. \subsection{Auxiliary Commands} \label{aut:aux} @@ -6022,7 +7152,7 @@ Expands to \prm{true} if the \opt{usetranslator} option is enabled (either globa \cmditem{ifsingletitle}{true}{false} -Expands to \prm{true} if there is only one work by the author\slash editor in the bibliography, and to \prm{false} otherwise. Note that this feature needs to be enabled explicitly with the package option \opt{singletitle}. +Expands to \prm{true} if there is only one work by the \opt{labelname} name in the bibliography, and to \prm{false} otherwise. If there is no \opt{labelname} name at all for the entry, then this expands to \prm{true} if there is only one work with the \opt{labeltitle} title in the bibliography and \prm{false} otherwise. If neither \opt{labelname} nor \opt{labeltitle} are 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{singletitle}. \cmditem{ifandothers}{list}{true}{false} @@ -6407,7 +7537,7 @@ The optional argument \bibfield{bookpagination} is omissible in this case. \cmditem{mkcomprange}[postpro]{text} \cmditem*{mkcomprange*}[postpro]{text} -This command, which is intended for use in field formatting directives, will parse its \prm{text} argument for page ranges and compress them. For example, «125--129» may be formatted as «125--9». You may configure the behavior of \cmd{mkcomprange} by adjusting the \latex counters \cnt{mincomprange}, \cnt{maxcomprange}, and \cnt{mincompwidth}, as illustrated in \tabref{aut:aux:tab1}. The default settings are \texttt{10}, \texttt{100000}, and \texttt{1}, respectively. This means that the command tries to compress as much as possible by default. Use \cmd{setcounter} to adjust the parameters. The scanner recognizes \cmd{bibrangedash} and hyphens as range dashes. It will normalize the dash by replacing any number of consecutive hyphens with \cmd{bibrangedash}. Lists of ranges delimited with commas and/or semicolons are also supported. If you want to hide a character from the list/range scanner for some reason, wrap the character or the entire string in curly braces. The optional \prm{postpro} argument specifies a macro to be used for post-processing the \prm{text}. This is important if you want to combine \cmd{mkcomprange} with other formatting macros which also need to parse their \prm{text} argument, such as \cmd{mkpageprefix}. Simply nesting these commands will not work as expected. Use the \prm{postpro} argument to set up the processing chain as follows: +This command, which is intended for use in field formatting directives, will parse its \prm{text} argument for page ranges and compress them. For example, «125--129» may be formatted as «125--9». You may configure the behavior of \cmd{mkcomprange} by adjusting the \latex counters \cnt{mincomprange}, \cnt{maxcomprange}, and \cnt{mincompwidth}, as illustrated in \tabref{aut:aux:tab1}. The default settings are \texttt{10}, \texttt{100000}, and \texttt{1}, respectively. This means that the command tries to compress as much as possible by default. Use \cmd{setcounter} to adjust the parameters. The scanner recognizes \cmd{bibrangedash} and hyphens as range dashes. It will normalize the dash by replacing any number of consecutive hyphens with \cmd{bibrangedash}. Lists of ranges delimited with \cmd{bibrangessep} (\biber\footnote{\biber will always convert commas/semicolon multi-range separators into \cmd{bibrangessep} so that it can be controlled in the style.}) or commas/semicolons (BibTeX) are also supported. If you want to hide a character from the list/range scanner for some reason, wrap the character or the entire string in curly braces. The optional \prm{postpro} argument specifies a macro to be used for post-processing the \prm{text}. This is important if you want to combine \cmd{mkcomprange} with other formatting macros which also need to parse their \prm{text} argument, such as \cmd{mkpageprefix}. Simply nesting these commands will not work as expected. Use the \prm{postpro} argument to set up the processing chain as follows: \begin{lstlisting}[style=latex]{} \DeclareFieldFormat{postnote}{\mkcomprange[<<{>>\mkpageprefix[pagination]<<}>>]{#1}} @@ -6430,7 +7560,7 @@ p. 5, pp. 123-9, pp. 423-39 \cmditem{mkfirstpage}[postpro]{text} \cmditem*{mkfirstpage*}[postpro]{text} -This command, which is intended for use in field formatting directives, will parse its \prm{text} argument for page ranges and print the start page of the range only. The scanner recognizes \cmd{bibrangedash} and hyphens as range dashes. Lists of ranges delimited with commas and/or semicolons are also supported. If you want to hide a character from the list/range scanner for some reason, wrap the character or the entire string in curly braces. The optional \prm{postpro} argument specifies a macro to be used for post-processing the \prm{text}. See \cmd{mkcomprange} on how to use this argument. The starred version of this command differs from the regular one in the way the \prm{postpro} argument is applied to a list of values. For example: +This command, which is intended for use in field formatting directives, will parse its \prm{text} argument for page ranges and print the start page of the range only. The scanner recognizes \cmd{bibrangedash} and hyphens as range dashes. Lists of ranges delimited with \cmd{bibrangessep} (\biber\footnote{\biber will always convert commas/semicolon multi-range separators into \cmd{bibrangessep} so that it can be controlled in the style.}) or commas/semicolons (BibTeX) are also supported. If you want to hide a character from the list/range scanner for some reason, wrap the character or the entire string in curly braces. The optional \prm{postpro} argument specifies a macro to be used for post-processing the \prm{text}. See \cmd{mkcomprange} on how to use this argument. The starred version of this command differs from the regular one in the way the \prm{postpro} argument is applied to a list of values. For example: \begin{lstlisting}[style=latex]{} \mkfirstpage[\mkpageprefix]{5, 123-129, 423-439} @@ -6510,7 +7640,7 @@ This command is similar to \cmd{PackageWarning} but prints the entry key of the \cmditem{RequireBiber}[severity] -This command is intended for use in \file{cbx}\slash\file{bbx} files and in the \texttt{@preamble} of \file{bib} files. It checks the selected backend and warns if it is not Biber. The optional \prm{severity} argument is an integer specifying the severity. The value 1 triggers an informational message stating that Biber is recommended; 2 triggers a warning stating that Biber is required and the style\slash\file{bib} file may not work properly; 3 triggers an error stating that Biber is strictly required and the style\slash\file{bib} file will not work at all with any other backend. If \cmd{RequireBiber} is used multiple times, the highest \prm{severity} takes precedence. \file{cbx}\slash\file{bbx} files on the one hand and the \texttt{@preamble} snippets of all \file{bib} files on the other are tracked seperately. If the optional \prm{severity} argument is omitted, the default severity is 2 (warning). +This command is intended for use in \file{cbx}\slash\file{bbx} files and in the \texttt{@preamble} of \file{bib} files. It checks the selected backend and warns if it is not \biber. The optional \prm{severity} argument is an integer specifying the severity. The value 1 triggers an informational message stating that \biber is recommended; 2 triggers a warning stating that \biber is required and the style\slash\file{bib} file may not work properly; 3 triggers an error stating that \biber is strictly required and the style\slash\file{bib} file will not work at all with any other backend. If \cmd{RequireBiber} is used multiple times, the highest \prm{severity} takes precedence. \file{cbx}\slash\file{bbx} files on the one hand and the \texttt{@preamble} snippets of all \file{bib} files on the other are tracked separately. If the optional \prm{severity} argument is omitted, the default severity is 2 (warning). \boolitem{pagetracker} @@ -6941,7 +8071,7 @@ This command maps a \sty{babel} language identifier to an \file{lbx} file. The \ \cmditem{NewBibliographyString}{key} -This command, which may be used in the preamble (including \file{cbx} and \file{bbx} files) as well as in \file{lbx} files, declares new localization strings, \ie it initializes a new \prm{key} to be used in the \prm{definitions} of \cmd{DefineBibliographyStrings}. The \prm{key} argument may also be a comma"=separated list of key names. The keys listed in \secref{aut:lng:key} are defined by default. +This command, which may be used in the preamble (including \file{cbx} and \file{bbx} files) as well as in \file{lbx} files, declares new localization strings, \ie it initializes a new \prm{key} to be used in the \prm{definitions} of \cmd{DefineBibliographyStrings} or \cmd{DeclareBibliographyStrings}. The \prm{key} argument may also be a comma"=separated list of key names. When used in an \file{lbx}, the \prm{key} is initialized only for the language specified by the name of the \file{lbx} file. The keys listed in \secref{aut:lng:key} are defined by default. \end{ltxsyntax} @@ -7121,6 +8251,7 @@ The following keys refer to roles which are expressed as an action (<edited by>, \item[bycontinuator] The expression <continued by \prm{name}>. \item[byredactor] The expression <redacted by \prm{name}>. \item[byreviser] The expression <revised by \prm{name}>. +\item[byreviewer] The expression <reviewed by \prm{name}>. \item[bycollaborator] An expression like <in collaboration with \prm{name}> or <in cooperation with \prm{name}>. \item[bytranslator] The expression <translated by \prm{name}> or <translated from \prm{language} by \prm{name}>. \item[bycommentator] The expression <commented by \prm{name}>. @@ -7242,6 +8373,7 @@ Roles which are related to supplementary material may also be expressed as objec \begin{keymarglist} \item[volume] The term <volume>, referring to a book. \item[volumes] The plural form of \texttt{volume}. +\item[involumes] The term <in>, as used in expressions like <in \prm{number of volumes} volumes>. \item[jourvol] The term <volume>, referring to a journal. \item[jourser] The term <series>, referring to a journal. \item[book] The term <book>, referring to a document division. @@ -7259,6 +8391,15 @@ Roles which are related to supplementary material may also be expressed as objec \item[reprint] The term <reprint>. \item[reprintof] The expression <reprint of \prm{title}>. \item[reprintas] The expression <reprinted as \prm{title}>. +\item[reprintfrom] The expression <reprinted from \prm{title}>. +\item[translationof] The expression <translation of \prm{title}>. +\item[translationas] The expression <translated as \prm{title}>. +\item[translationfrom] The expression <translated from [the] \prm{language}>. +\item[reviewof] The expression <review of \prm{title}>. +\item[origpubas] The expression <originally published as \prm{title}>. +\item[origpubin] The expression <originally published in \prm{year}>. +\item[astitle] The term <as>, as used in expressions like <published by \prm{publisher} as \prm{title}>. +\item[bypublisher] The term <by>, as used in expressions like <published by \prm{publisher}>. \end{keymarglist} \paragraph{Publication State} @@ -7297,6 +8438,7 @@ The following keys are typically used in the \bibfield{type} field of \bibtype{t \begin{keymarglist} \item[mathesis] An expression equivalent to the term <Master's thesis>. \item[phdthesis] The term <PhD thesis>, <PhD dissertation>, <doctoral thesis>, etc. +\item[candthesis] An expression equivalent to the term <Candidate thesis>. Used for <Candidate> degrees that have no clear equivalent to the Master's or doctoral level. \item[techreport] The term <technical report>. \item[resreport] The term <research report>. \item[software] The term <computer software>. @@ -7633,6 +8775,14 @@ Similar to \cmd{mkbibnamelast}, but intended for the name prefix. Similar to \cmd{mkbibnamelast}, but intended for the name affix. +\csitem{relatedpunct} + +The separator between the relatedtype bibliography localization string and the data from the first related entry. + +\csitem{relateddelim} + +The separator between the data of multiple related entries. The default definition is a linebreak. + \end{ltxsyntax} \subsubsection{Language-specific Commands} @@ -8690,10 +9840,356 @@ In order to minimize the risk of name clashes, \latex packages typically prefix \section*{Appendix} \addcontentsline{toc}{section}{Appendix} -\section{Default \bibfield{crossref} Setup} +\section{Default Driver Source Mappings} +\label{apx:maps} + +These are the driver default source mappings. For drivers other than \opt{bibtex} and \opt{ris}, they are highly experimental and subject to change (because the driver datatype itself is unstable or not well suited to bibliographic data). + +\subsection{\opt{bibtex}} +The \opt{bibtex} driver is of course the most comprehensive and mature of the \biblatex/\biber supported data formats. These source mapping defaults are how the aliases from sections \ref{bib:typ:als} and \ref{bib:fld:als} are implemented. + +\begin{lstlisting}[style=latex]{} +\DeclareDefaultSourcemap[datatype=bibtex]{ + \map{ + \step[typesource=conference, typetarget=inproceedings] + \step[typesource=electronic, typetarget=online] + \step[typesource=www, typetarget=online] + } + \map{ + \step[typesource=mastersthesis, typetarget=thesis, final] + \step[fieldset=type, fieldvalue=mathesis] + } + \map{ + \step[typesource=phdthesis, typetarget=thesis, final] + \step[fieldset=type, fieldvalue=phdthesis] + } + \map{ + \step[typesource=techreport, typetarget=report, final] + \step[fieldset=type, fieldvalue=techreport] + } + \map{ + \step[fieldsource=address, fieldtarget=location] + \step[fieldsource=school, fieldtarget=institution] + \step[fieldsource=annote, fieldtarget=annotation] + \step[fieldsource=archiveprefix, fieldtarget=eprinttype] + \step[fieldsource=journal, fieldtarget=journaltitle] + \step[fieldsource=primaryclass, fieldtarget=eprintclass] + \step[fieldsource=key, fieldtarget=sortkey] + \step[fieldsource=pdf, fieldtarget=file] + } +} +\end{lstlisting} + +\subsection{\opt{endnotexml}} + +The \opt{endnotexml} driver for \biber uses the following mappings. This format is quite messy and not well suited to robust typsetting of bibliographic data. It is presented largely as an example of \biber's modular datasource abilities and also of how to map foreign data models into the \biblatex data model. Mappings from such messy and relatively simple data models are inevitably fragile and are of limited use. + +\begin{lstlisting}[style=latex]{} +\DeclareDefaultSourcemap[datatype=endnotexml]{ + \map{ + \step[typesource={Aggregated Database}, typetarget=misc] + \step[typesource={Ancient Text}, typetarget=misc] + \step[typesource=Artwork, typetarget=artwork] + \step[typesource={Audiovisual Material}, typetarget=misc] + \step[typesource=Bill, typetarget=jurisdiction] + \step[typesource=Blog, typetarget=online] + \step[typesource=Book, typetarget=book] + \step[typesource={Book Section}, typetarget=inbook] + \step[typesource=Case, typetarget=jurisdiction] + \step[typesource=Catalog, typetarget=misc] + \step[typesource={Chart or Table}, typetarget=misc] + \step[typesource={Classical Work}, typetarget=misc] + \step[typesource={Computer Program}, typetarget=software] + \step[typesource={Conference Paper}, typetarget=inproceedings] + \step[typesource={Conference Proceedings}, typetarget=proceedings] + \step[typesource=Dictionary, typetarget=inreference] + \step[typesource={Edited Book}, typetarget=collection] + \step[typesource={Electronic Article}, typetarget=article] + \step[typesource={Electronic Book}, typetarget=book] + \step[typesource={Encyclopedia}, typetarget=reference] + \step[typesource=Equation, typetarget=misc] + \step[typesource=Figure, typetarget=misc] + \step[typesource={Film or Broadcast}, typetarget=movie] + \step[typesource={Government Document}, typetarget=report] + \step[typesource=Grant, typetarget=misc] + \step[typesource=Hearing, typetarget=jurisdiction] + \step[typesource={Journal Article}, typetarget=article] + \step[typesource={Legal Rule or Regulation}, typetarget=legislation] + \step[typesource={Magazine Article}, typetarget=article] + \step[typesource=Manuscript, typetarget=unpublished] + \step[typesource=Map, typetarget=misc] + \step[typesource={Newspaper Article}, typetarget=article] + \step[typesource={Online Database}, typetarget=online] + \step[typesource={Online Multimedia}, typetarget=online] + \step[typesource=Pamphlet, typetarget=booklet] + \step[typesource=Patent, typetarget=patent] + \step[typesource={Personal Communication}, typetarget=letter] + \step[typesource=Report, typetarget=report] + \step[typesource=Serial, typetarget=periodical] + \step[typesource=Standard, typetarget=standard] + \step[typesource=Statute, typetarget=legislation] + \step[typesource=Thesis, typetarget=thesis] + \step[typesource={Unpublished Work}, typetarget=unpublished] + \step[typesource={Web Page}, typetarget=online] + } + \map{ + \step[fieldsource={electronic-resource-num}, fieldtarget=eprint] + \step[fieldsource={alt-title}, fieldtarget=shorttitle] + \step[fieldsource={meeting-place}, fieldtarget=venue] + \step[fieldsource={pub-location}, fieldtarget=location] + \step[fieldsource={orig-pub}, fieldtarget=origpublisher] + \step[fieldsource={authors}, fieldtarget=author] + \step[fieldsource={secondary-authors}, fieldtarget=editor] + \step[fieldsource={tertiary-authors}, fieldtarget=commentator] + \step[fieldsource={subsidiary-authors}, fieldtarget=translator] + \step[fieldsource={year}, fieldtarget=date] + \step[fieldsource={pub-dates}, fieldtarget=date] + \step[fieldsource={num-vols}, fieldtarget=volumes] + \step[fieldsource={call-num}, fieldtarget=library] + \step[fieldsource={notes}, fieldtarget=note] + \step[fieldsource={secondary-title}, fieldtarget=subtitle] + \step[fieldsource={work-type}, fieldtarget=type] + } + \map{ + \pertype{Edited Book} + \step[fieldsource=contributors/authors, fieldtarget=contributors/editor] + } + \map{ + \pertype{Electronic Article} + \pertype{Journal Article} + \pertype{Magazine Article} + \pertype{Newspaper Article} + \step[fieldsource=isbn, fieldtarget=issn] + } + \map{ + \pertype{Patent} + \pertype{Report} + \pertype{Government Document} + \pertype{Legal Rule or Regulation} + \step[fieldsource=isbn, fieldtarget=number] + } + \map{ + \pertype{Blog} + \pertype{Online Database} + \pertype{Online Multimedia} + \pertype{Web Page} + \step[fieldsource={titles/secondary-title}, fieldtarget={titles/title}] + } + \map{ + \pertype{Book Section} + \step[fieldsource={titles/secondary-title}, fieldtarget={titles/booktitle}] + } + \map{ + \pertype{Book} + \pertype{Electronic Book} + \pertype{Manuscript} + \pertype{Unpublished Work} + \step[fieldsource={titles/secondary-title}, fieldtarget={titles/series}] + } + \map{ + \pertype{Conference Paper} + \pertype{Conference Proceedings} + \step[fieldsource={titles/secondary-title}, fieldtarget={titles/eventtitle}] + } + \map{ + \pertype{Electronic Article} + \pertype{Journal Article} + \pertype{Magazine Article} + \pertype{Newspaper Article} + \step[fieldsource={titles/secondary-title}, fieldtarget={titles/journaltitle}] + } + \map{ + \pertype{Book Section} + \step[fieldsource={titles/tertiary-title}, fieldtarget={titles/booktitle}] + } + \map{ + \pertype{Conference Proceedings} + \pertype{periodical} + \step[fieldsource={titles/tertiary-title}, fieldtarget={titles/series}] + } +} +\end{lstlisting} + +\subsection{\opt{ris}} + +The \opt{ris} driver reflects the fact that \opt{ris} itself is a very simple and stable format. It is in fact so simple, it's hardly of any use for most \biblatex users. Again, here more as a proof of concept example. + +\begin{lstlisting}[style=latex]{} +\DeclareDefaultSourcemap[datatype=ris]{ + \map{ + \step[typesource=ART, typetarget=artwork] + \step[typesource=BILL, typetarget=jurisdiction] + \step[typesource=BOOK, typetarget=book] + \step[typesource=CHAP, typetarget=inbook] + \step[typesource=COMP, typetarget=software] + \step[typesource=CONF, typetarget=proceedings] + \step[typesource=GEN, typetarget=misc] + \step[typesource=JFULL, typetarget=article] + \step[typesource=JOUR, typetarget=article] + \step[typesource=MGZN, typetarget=misc] + \step[typesource=MPCT, typetarget=movie] + \step[typesource=NEWS, typetarget=misc] + \step[typesource=PAMP, typetarget=misc] + \step[typesource=PAT, typetarget=patent] + \step[typesource=PCOMM, typetarget=misc] + \step[typesource=RPRT, typetarget=report] + \step[typesource=SER, typetarget=misc] + \step[typesource=SLIDE, typetarget=misc] + \step[typesource=SOUND, typetarget=audio] + \step[typesource=STAT, typetarget=legal] + \step[typesource=THES, typetarget=thesis] + \step[typesource=UNBILL, typetarget=jurisdiction] + \step[typesource=UNPB, typetarget=unpublished] + } + \map{ + \step[fieldsource=Y1, fieldtarget=date] + \step[fieldsource=PY, fieldtarget=date] + \step[fieldsource=Y2, fieldtarget=eventdate] + \step[fieldsource=A1, fieldtarget=author] + \step[fieldsource=AU, fieldtarget=author] + \step[fieldsource=A2, fieldtarget=editor] + \step[fieldsource=A3, fieldtarget=editor] + \step[fieldsource=ED, fieldtarget=editor] + \step[fieldsource=SPEP, fieldtarget=pages] + \step[fieldsource=N1, fieldtarget=note] + \step[fieldsource=N2, fieldtarget=abstract] + \step[fieldsource=AB, fieldtarget=abstract] + \step[fieldsource=JO, fieldtarget=journaltitle] + \step[fieldsource=JF, fieldtarget=journaltitle] + \step[fieldsource=JA, fieldtarget=shortjournal] + \step[fieldsource=VL, fieldtarget=volume] + \step[fieldsource=IS, fieldtarget=issue] + \step[fieldsource=CP, fieldtarget=issue] + \step[fieldsource=CY, fieldtarget=location] + \step[fieldsource=SN, fieldtarget=isbn] + \step[fieldsource=PB, fieldtarget=publisher] + \step[fieldsource=KW, fieldtarget=keywords] + \step[fieldsource=TI, fieldtarget=title] + \step[fieldsource=U1, fieldtarget=usera] + \step[fieldsource=U2, fieldtarget=userb] + \step[fieldsource=U3, fieldtarget=userc] + \step[fieldsource=U4, fieldtarget=userd] + \step[fieldsource=U5, fieldtarget=usere] + \step[fieldsource=UR, fieldtarget=url] + \step[fieldsource=L1, fieldtarget=file] + } +} +\end{lstlisting} + +\subsection{\opt{zoterordfxml}} + +The \opt{zoterordfxml} driver reads the Zotero\footnote{\url{www.zotero.org}} XML representation of its RDF format. From the \biblatex point of view, it suffers from a lack of the notion of a citation key and so is of limited use. The format may include a citation key in the future at which point the \biber driver and these default mappings will be updated. As with \opt{endnotexml}, the format is somewhat messy with, in particular, a very limited way of dealing with related entries which makes the driver setup rather ugly. As can be seen below, it is possible to map into a field prefixed with «BIBERCUSTOM» which is not a real field in the data model but can be detected in the \biber driver itself and used to process a source field which does not map naturally to any \biblatex data model field as it needs special treatment. This is messy but is due largely due to messy source data models. + +\begin{lstlisting}[style=latex]{} +\DeclareDefaultSourcemap[datatype=zoterordfxml]{ + \map{ + \step[typesource=conferencePaper, typetarget=inproceedings] + \step[typesource=bookSection, typetarget=inbook] + \step[typesource=journalArticle, typetarget=article] + \step[typesource=magazineArticle, typetarget=article] + \step[typesource=newspaperArticle, typetarget=article] + \step[typesource=encyclopediaArticle, typetarget=inreference] + \step[typesource=manuscript, typetarget=unpublished] + \step[typesource=document, typetarget=misc] + \step[typesource=dictionaryEntry, typetarget=inreference] + \step[typesource=interview, typetarget=misc] + \step[typesource=film, typetarget=movie] + \step[typesource=webpage, typetarget=online] + \step[typesource=note, typetarget=misc] + \step[typesource=attachment, typetarget=misc] + \step[typesource=bill, typetarget=legislation] + \step[typesource=case, typetarget=jurisdiction] + \step[typesource=hearing, typetarget=jurisdiction] + \step[typesource=statute, typetarget=legislation] + \step[typesource=email, typetarget=letter] + \step[typesource=map, typetarget=image] + \step[typesource=blogPost, typetarget=online] + \step[typesource=instantMessage, typetarget=letter] + \step[typesource=forumPost, typetarget=online] + \step[typesource=audioRecording, typetarget=audio] + \step[typesource=presentation, typetarget=inproceedings] + \step[typesource=videoRecording, typetarget=video] + \step[typesource=tvBroadcast, typetarget=misc] + \step[typesource=radioBroadcast, typetarget=misc] + \step[typesource=podcast, typetarget=online] + \step[typesource=computerProgram, typetarget=software] + } + \map{ + \step[fieldsource=bib:contributors, fieldtarget=author] + \step[fieldsource=bib:authors, fieldtarget=author] + \step[fieldsource=z:interviewers, fieldtarget=author] + \step[fieldsource=z:directors, fieldtarget=author] + \step[fieldsource=z:scriptwriters, fieldtarget=author] + \step[fieldsource=z:bookAuthor, fieldtarget=author] + \step[fieldsource=z:inventors, fieldtarget=author] + \step[fieldsource=z:recipients, fieldtarget=author] + \step[fieldsource=z:counsels, fieldtarget=author] + \step[fieldsource=z:artists, fieldtarget=author] + \step[fieldsource=z:podcasters, fieldtarget=author] + \step[fieldsource=z:presenters, fieldtarget=author] + \step[fieldsource=z:commenters, fieldtarget=author] + \step[fieldsource=z:programers, fieldtarget=author] + \step[fieldsource=z:composers, fieldtarget=author] + \step[fieldsource=z:producers, fieldtarget=author] + \step[fieldsource=z:performers, fieldtarget=author] + \step[fieldsource=bib:editors, fieldtarget=editor] + \step[fieldsource=z:translators, fieldtarget=translator] + \step[fieldsource=z:seriesEditors, fieldtarget=editor] + \step[fieldsource=dc:date, fieldtarget=date] + \step[fieldsource=bib:pages, fieldtarget=pages] + \step[fieldsource=dc:title, fieldtarget=title] + \step[fieldsource=z:proceedingsTitle, fieldtarget=title] + \step[fieldsource=z:encyclopediaTitle, fieldtarget=title] + \step[fieldsource=z:dictionaryTitle, fieldtarget=title] + \step[fieldsource=z:websiteTitle, fieldtarget=title] + \step[fieldsource=z:forumTitle, fieldtarget=title] + \step[fieldsource=z:blogTitle, fieldtarget=title] + \step[fieldsource=z:nameOfAct, fieldtarget=title] + \step[fieldsource=z:caseName, fieldtarget=title] + \step[fieldsource=z:meetingName, fieldtarget=eventtitle] + \step[fieldsource=prism:volume, fieldtarget=volume] + \step[fieldsource=numberOfVolumes, fieldtarget=volumes] + \step[fieldsource=z:numPages, fieldtarget=pagetotal] + \step[fieldsource=prism:edition, fieldtarget=edition] + \step[fieldsource=dc:description, fieldtarget=note] + \step[fieldsource=dc:alternative, fieldtarget=shortjournal] + \step[fieldsource=dcterms:abstract, fieldtarget=abstract] + \step[fieldsource=dc:type, fieldtarget=type] + \step[fieldsource=z:shortTitle, fieldtarget=shorttitle] + \step[fieldsource=z:bookTitle, fieldtarget=booktitle] + \step[fieldsource=prism:number, fieldtarget=number] + \step[fieldsource=z:patentNumber, fieldtarget=number] + \step[fieldsource=z:codeNumber, fieldtarget=number] + \step[fieldsource=z:reportNumber, fieldtarget=number] + \step[fieldsource=z:billNumber, fieldtarget=number] + \step[fieldsource=z:documentNumber, fieldtarget=number] + \step[fieldsource=z:publicLawNumber, fieldtarget=number] + \step[fieldsource=z:applicationNumber, fieldtarget=number] + \step[fieldsource=z:episodeNumber, fieldtarget=number] + \step[fieldsource=dc:coverage, fieldtarget=location] + \step[fieldsource=z:university, fieldtarget=institution] + \step[fieldsource=z:language, fieldtarget=language] + \step[fieldsource=z:version, fieldtarget=version] + \step[fieldsource=z:libraryCatalog, fieldtarget=library] + \step[fieldsource=dcterms:isPartOf, fieldtarget=BIBERCUSTOMpartof] + \step[fieldsource=dc:identifier, fieldtarget=BIBERCUSTOMidentifier] + \step[fieldsource=dc:publisher, fieldtarget=BIBERCUSTOMpublisher] + \step[fieldsource=dc:presentedAt, fieldtarget=BIBERCUSTOMpresentedat] + \step[fieldsource=dc:subject, fieldtarget=BIBERCUSTOMsubject] + \step[fieldsource={dcterms:BIBERCUSTOMpartof/bib:Journal}, + fieldtarget={dcterms:BIBERCUSTOMpartof/periodical}] + \step[fieldsource={dcterms:BIBERCUSTOMpartof/bib:Book}, + fieldtarget={dcterms:BIBERCUSTOMpartof/book}] + \step[fieldsource={dcterms:BIBERCUSTOMpartof/bib:ConferenceProceedings}, + fieldtarget={dcterms:BIBERCUSTOMpartof/proceedings}] + } +} +\end{lstlisting} + +\section{Default Inheritance Setup} \label{apx:ref} -The following table shows the Biber cross-referencing rules defined by default. +The following table shows the \biber cross-referencing rules defined by default. Please refer to \secref{bib:cav:ref, aut:ctm:ref} for explanation. \begingroup @@ -8725,8 +10221,8 @@ Please refer to \secref{bib:cav:ref, aut:ctm:ref} for explanation. options\par presort\par related\par - relatedstring\par relatedtype\par + relatedstring\par shorthand\par shorthandintro\par sortkey & @@ -8930,7 +10426,7 @@ arxiv &\+&\+&\_&\_\\ autocite &\+&\+&\_&\_\\ autopunct &\+&\+&\_&\_\\ babel &\+&\+&\_&\_\\ -backend &\+&\+&\_&\_\\ +backend &\+&\_&\_&\_\\ backref &\+&\+&\_&\_\\ backrefsetstyle &\+&\+&\_&\_\\ backrefstyle &\+&\+&\_&\_\\ @@ -8943,6 +10439,7 @@ citereset &\+&\+&\_&\_\\ citestyle &\+&\_&\_&\_\\ citetracker &\+&\+&\_&\_\\ clearlang &\+&\+&\_&\_\\ +datamodel &\+&\_&\_&\_\\ dataonly &\_&\_&\+&\+\\ date &\+&\+&\_&\_\\ dateabbrev &\+&\+&\_&\_\\ @@ -8959,6 +10456,8 @@ indexing &\+&\+&\+&\+\\ isbn &\+&\+&\_&\_\\ % style labelalpha &\+&\+&\+&\_\\ labelnumber &\+&\+&\+&\_\\ +labeltitle &\+&\+&\+&\_\\ +labeltitleyear &\+&\+&\+&\_\\ labelyear &\+&\+&\+&\_\\ language &\+&\+&\_&\_\\ loadfiles &\+&\+&\_&\_\\ @@ -8993,6 +10492,7 @@ skiplab &\_&\_&\+&\+\\ skiplos &\_&\_&\+&\+\\ sortcase &\+&\+&\_&\_\\ sortcites &\+&\+&\_&\_\\ +sortfirstinits &\+&\+&\_&\_\\ sorting &\+&\+&\_&\_\\ sortlocale &\+&\+&\_&\_\\ sortlos &\+&\+&\_&\_\\ @@ -9018,6 +10518,27 @@ This revision history is a list of changes relevant to users of this package. Ch \begin{changelog} +\begin{release}{2.0}{2012-07-01} +\item Misc bug fixes +\item Generalised \opt{singletitle} test a little\see{aut:aux:tst}\BiberOnlyMark +\item Added new special field \bibfield{extratitleyear}\see{aut:bbx:fld}\BiberOnlyMark +\item Customisable data model\see{aut:ctm:dm}\BiberOnlyMark +\item Added \cmd{DeclareDefaultSourcemap}\see{aut:ctm:map}\BiberOnlyMark +\item Added \opt{labeltitle} option\see{use:opt:pre:int}\BiberOnlyMark +\item Added new special field \bibfield{extratitle}\see{aut:bbx:fld}\BiberOnlyMark +\item Made special field \bibfield{labeltitle} customisable\see{aut:bbx:fld}\BiberOnlyMark +\item Removed field \bibfield{reprinttitle}\see{use:rel}\BiberOnlyMark +\item Added related entry feature\see{use:rel}\BiberOnlyMark +\item Added \cmd{DeclareNoinit}\see{aut:ctm:noinit}\BiberOnlyMark +\item Added \cmd{DeclareNosort}\see{aut:ctm:nosort}\BiberOnlyMark +\item Added \opt{sorting} option for \cmd{printbibliography} and \cmd{printshorthands}\see{use:bib:bib}\BiberOnlyMark +\item Added \texttt{ids} field for citekey aliasing\see{bib:fld}\BiberOnlyMark +\item Added \opt{sortfirstinits} option\see{use:opt:pre:int}\BiberOnlyMark +\item Added data stream modification feature\see{aut:ctm:map}\BiberOnlyMark +\item Added customisable labels feature\see{aut:ctm:lab}\BiberOnlyMark +\item Added \cmd{citeyear*} and \cmd{citedate*}\see{use:cit:txt} +\end{release} + \begin{release}{1.7}{2011-11-13} \item Added \texttt{xdata} containers\see{use:use:xdat}\BiberOnlyMark \item Added special entry type \bibfield{xdata}\see{bib:typ:blx}\BiberOnlyMark @@ -10387,3 +11908,8 @@ This revision history is a list of changes relevant to users of this package. Ch \end{changelog} \end{document} +%%% Local Variables: +%%% TeX-command-default: "PDFLaTeX" +%%% eval: (auto-fill-mode -1) +%%% eval: (visual-line-mode) +%%% End: -- cgit v1.2.3