# What does the final option of biblatex's DeclareSourcemap do?

A BibTeX document

The following BibTeX code is saved in ~/TestBib.bib.

@book{shakespeare,
author = {William Shakespeare},
title = {Hamlet},
year = {1600},
langid = {english}
}
@book{homer,
author = {Homer},
year = {8th century BC},
langid = {greek}
}
@book{tolstoy,
author = {Leo Tolstoy},
title = {War and Peace},
year = {1869},
langid = {russian}
}


A simple LaTeX document with a bibliography

The following LaTeX code is saved in ~/Test.tex.

\documentclass{article}
\usepackage{biblatex}
\begin{document}
\cite{shakespeare}\cite{homer}\cite{tolstoy}
\printbibliography
\end{document}


The result of running

> cd ~
> lualatex Test
> biber Test
> lualatex Test

is

English first, Russian second

We shall now add a source map to order the bibliographic entries in such a way that the English entry is first, and the Russian entry is second.

\documentclass{article}
\usepackage{biblatex}
\DeclareSourcemap {
\maps {
\map {
\step [
fieldsource=langid,
match=english,
fieldset=presort,
fieldvalue=a
]
\step [
fieldsource=langid,
match=russian,
fieldset=presort,
fieldvalue=b
]
}
}
}
\begin{document}
\cite{shakespeare}\cite{homer}\cite{tolstoy}
\printbibliography
\end{document}


The output is as expected:

Adding final to the first step

If we now add the option final to the first step, as follows:

         \step [
fieldsource=langid,
match=english,
fieldset=presort,
fieldvalue=a,
final
]


The output is:

Note that the Russian entry is no longer second.

Question

Why does the addition of the final option change the order of the bibliographic entries?

What I expected this option to do is merely improve the efficiency of the processing: once the first step matches the English entry, the final option would cause the second step to be skipped, whereas without the final option, the second step would have russian tested against the entry even if it has already matched against english.

• If the second step is skipped then the sort order for the Russian entry would be the normal sort order, i.e., by author last name, and therefore third (Tolstoy after Homer), right? Nov 24 at 16:07
• @Marijn Right. If it is always skipped, or equivalently if it is physically deleted from the above code. Nov 24 at 16:16

The final keyword stops processing of the current \map after the \step where it is used if the 'precondition' of the current step is not met.

Step final terminates if
typeseource=<type>, current entry is not of type <type>
fieldsource=<field>, field <field> is not present
notfield=<field>, field <field> is present
fieldsource=<field>, match=<regexp>, field <field> does not match the regular expression <regexp>
fieldset=<field>, <field> is already present and overwrite is false

The final in

  \step[
fieldsource=langid,
match=english,
fieldset=presort,
fieldvalue=a,
final
]


triggers the fieldsource=<field>, match=<regexp>, case here, which means that the \map is aborted for entries whose langid field does not match english. This is the case for both homer and tolstoy. So both of those entry do not get their presort value set (which means the value falls back to mm).

• Thank you. This is very clear! Are you a developer of the biblatex package? If so, the table from your answer should be part of the manual. The manual is both unclear and misleading about the semantics of final. The following sentence from the manual suggests that final aborts the current map when the match succeeds, which is what led to my confusion: Nov 24 at 17:38
• "If fieldset is defined, then its value is 〈entryfield〉 which will be set to a value specified by further options. If overwrite is false for this step and the field to set already exists then the map step is ignored. If final is also true for this step, then processing of the parent map stops at this point." (p. 203 of the current version, 3.18b, July 12, 2022). Nov 24 at 17:38
• I have created a ticket in biblatex's bug-tracking list for improving the manual's explanation of final . Nov 25 at 8:03