-
Notifications
You must be signed in to change notification settings - Fork 8
/
biber-zh-cn.tex
3073 lines (2666 loc) · 141 KB
/
biber-zh-cn.tex
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
\documentclass{ltxdockit}
\usepackage{btxdockit}
\usepackage[british]{babel}
\usepackage[strict=true]{csquotes}%,autostyle=true
\usepackage{ifthen}
\usepackage{fontspec}
\usepackage{tikz}
\usepackage{graphicx}
\usepackage{booktabs}
\usepackage{fixfoot}
\usepackage{color}
\usepackage{listings}
\usepackage{metalogo}
\usepackage{colortbl}
\usepackage{ctex}
\usepackage[retainmissing]{MnSymbol}
\setmainfont[Ligatures=TeX]{CMU Serif}
\setsansfont[Ligatures=TeX]{CMU Sans Serif}
\setmonofont{CMU Typewriter Text}
\def\BibLaTeX{\textsc{Bib}\latex}
\def\BibTeX{\textsc{Bib}\kern-.08em \TeX}
\renewcommand{\labelitemii}{$\circ$}
\newcommand*{\biber}{Biber\xspace}
\newcommand*{\biblatex}{Biblatex\xspace}
\MakeAutoQuote{«}{»}
\gdef\biberversion{2.11} % BIBER VERSION
\gdef\biblatexversion{3.11} % BIBLATEX VERSION
% colour for tables
\definecolor{Gray}{gray}{0.85}
\newcolumntype{a}{>{\columncolor{Gray}}l}
% Set up tikz things
\usetikzlibrary{shapes.geometric}
\usetikzlibrary{arrows}
\usetikzlibrary{fit}
\usetikzlibrary{calc}
\tikzstyle{file} = [rectangle, black, very thick, draw=blue, fill=blue!20,
minimum width=6em, minimum height=3em, align=center]
\tikzstyle{funit} = [rectangle, rounded corners=1ex, black, very thick,
shape border rotate=-90, draw=green, fill=green!20,
minimum size=3em, align=center]
% colours for the .dot examples
\xdefinecolor{centry}{HTML}{A0D0FF}
\xdefinecolor{ncentry}{HTML}{DEEFFF}
\xdefinecolor{doentry}{HTML}{FDFFD9}
\xdefinecolor{section}{HTML}{FCE3FA}
\xdefinecolor{set}{HTML}{E3DADC}
\xdefinecolor{related}{HTML}{AD1741}
\xdefinecolor{clone}{HTML}{AD1741}
\xdefinecolor{crossref}{HTML}{7D7879}
\xdefinecolor{xref}{HTML}{7D7879}
\xdefinecolor{xdata}{HTML}{2CA314}
\DeclareFixedFootnote{\tpb}{Binary maintained by third party. See README in
binary download directory for this platform for support/contact
details. Usually, the binary maintainer is also the binary build
provider for \TeX Live.}
\titlepage{%
title={biber},
subtitle={A backend bibliography processor for biblatex},
url={http://biblatex-biber.sourceforge.net},
author={Philip Kime, François Charette},
email={Philip@kime.org.uk, firmicus@ankabut.net},
revision={biber \biberversion\ (biblatex \biblatexversion)},
date={\today}}
\hypersetup{%
pdftitle={biber},
pdfsubject={A backend bibliography processor for biblatex},
pdfauthor={Philip Kime},
pdfkeywords={biblatex, bibliography}}
% Control list spacing
\usepackage{enumitem}
\setdescription{noitemsep}
\setenumerate{noitemsep}
\setitemize{noitemsep}
\def\biberex#1{\hbox{\hspace{-4em}\texttt{\small \detokenize{#1}}}}
\begin{document}
\definecolor{grey}{rgb}{0.7,0.7,0.7}
\printtitlepage
\tableofcontents
\section{Important Changes}\label{special}
Please see the \verb+Changes+ file which accompanies \biber\ for the
details on changes in each version. This section is just for important
things like incompatible changes which users should be aware of.
\minisec{2.6}
When outputting \bibtex\ data in tool mode (\opt{--tool}), \biber now
follows a full internal processing chain involving the data model. In
previous versions, \bibtex output would just output the raw
\bibtex input data, only allowing for some re-formatting options and
therefore no tool mode conversions from other formats into \bibtex format
were possible. This change has some normalisation consequences:
\begin{itemize}
\item Dates are normalised into \bibfield{DATE} fields. Legacy
\bibfield{YEAR} fields are never output in \bibtex format data output.
\item Fields which are not defined in the data model described in the
default \file{biber-tool.conf} are ignored and are neither read nor
output. If custom fields are required, they should be defined in the data
model by using a custom tool mode config file (see below). If you would
like to have ignored fields reported on, use the
\opt{--validate-datamodel} option.
\end{itemize}
\minisec{1.9}
\biber no longer checks the environment for locales to use for sorting. This
was always rather against the spirit of \tex since it means that the same
document might look different when compiled by different people. However,
\biblatex now passes Babel/Polyglossia language identifiers (or real locale
identifiers if you prefer) in the \file{.bcf} and \biber can use these to
set the sorting locale globally or on a per-sortscheme basis. This is better
than using environment variables since Babel/Polyglossia are more \latex
relevant language environments anyway.
\minisec{1.8}
Various option name changes. Old names are retained for backwards
compatibility. See the output of the \opt{--help} option.
\minisec{1.0}
The \opt{--validate-structure} option is now called \opt{--validate-datamodel}
\minisec{0.9.9}
The output format option \opt{--graph} has been moved to a
new option \opt{--output-format}. The option \opt{--graph} should now be
specified as \opt{--output-format=dot} and the \linebreak\opt{--dot-include} option
should be used to specify the elements to include in the DOT output. For
example:
\begin{verbatim}
biber --graph=section,field <file>
\end{verbatim}
\noindent is now:
\begin{verbatim}
biber --output-format=dot --dot-include=section,field <file>
\end{verbatim}
\minisec{1.8}
\textcolor{red}{Several option names have changed}. Several options have
changed names to facilitate better semantic classification of options. The
previous names are supported as legacy aliases. See the \opt{--help}
output of the \biber command.
\minisec{0.9.8}
\textcolor{red}{The \opt{sourcemap} option syntax has changed}.The syntax
was too confusing. It is now simplified and more powerful. It is uses a
sequential processing model to apply mappings to an entry. See section
\ref{ref:map}.
\minisec{0.9.7}
\textcolor{red}{The user config file has a completely new format}.The
reason for this is that the older \verb+Config::General+ format
could not be extended to deal with more sophisticated features like
per-datasource restrictions. An XML format is much better and in
fact easier to understand. The old format of the \opt{map} option
(now called \opt{sourcemap}) was rather confusing because
of limitations in the old config file format. Please see section
\ref{ref:map} and convert your config files to the new format.
\minisec{0.9.6}
\textcolor{red}{Matching of citation keys and datasource entry keys is now
\emph{case-sensitive}}. This is to enforce consistency across the entire
Bib\latex\ and \biber\ processing chain. All of the usual referencing
mechanisms in \latex\ are case-sensitive and so is the matching in
Bib\latex\ of citations to entries in the \texttt{.bbl} file generated by
\biber. It is inconsistent and messy to enforce case-insensitivity in only
\biber's matching of citations keys to datasource entry keys. If \biber\
detects what looks like a case mismatch between citation keys, it will warn
you.
\noindent \textcolor{red}{Summary of warnings/errors is now a new format}.
When \biber\ finishes writing the \verb+.bbl+, it gives a summary
count of errors/warnings. It used to do this in the same format as
Bib\TeX, for compatibility. Now it uses a more consistent and easier
to parse format which matches all other \biber\ messages. Please note
if you need to support \biber\ in an external tool. I have updated the
notes on AUC\TeX\ support below to reflect this.
\section{Introduction}\label{int}
\subsection{About}
\biber\ is conceptually a \BibTeX\ replacement for
\biblatex. It is written in Perl with the aim of providing a
customised and sophisticated data preparation backend for \biblatex.
You do \emph{not} need to install Perl to use \biber---binaries
are provided for many operating systems via the main \TeX\
distributions (\TeX Live, Mac\TeX, MiK\TeX) and also via download from SourceForge.
Functionally, \biber\ offers a superset of \BibTeX's capabilities but is
tightly coupled with \biblatex\ and cannot be used as a stand-alone tool
with standard \verb+.bst+ styles. \biber's primary role is to support
\biblatex\ by performing the following tasks:
\begin{itemize}
\item Parsing data from datasources
\item Processing cross-references, entry sets, related entries
\item Generating data for name, name list and name/year disambiguation
\item Structural validation according to \biblatex\ data model
\item Sorting reference lists
\item Outputting data to a \verb+.bbl+ for \biblatex\ to consume
\end{itemize}
\biber\ also has the ability to output different formats than \file{.bbl}
and can, for example, output a new \bibtex\ file which contains only
cited entries from the datasources (using the \opt{--output-format=bibtex}
option). There is also a «<tool» mode which operates on datasources instead
of individual documents, allowing you to transform, convert, reformat and
generally change the contents of a datasource (see \ref{ref:tool}).
\subsection{Requirements}\label{ref:req}
\biber\ is distributed primarily as a stand-alone binary and is
included in \TeX Live, Mac\TeX\ and MiK\TeX. If you are using any of these
distributions, you do not need any additional software installed to use
\biber. You do \emph{not} need a Perl installation at all to use
the binary distribution of \biber\footnote{If you prefer, you can run
\biber\ as a normal Perl program and doing this \emph{does} require
you to have a Perl interpreter installed. See section \ref{binaries}.}.
\biber's git repository and bug/feature tracker is on
github\footnote{\url{https://github.com/plk/biber}}. \biber's documentation,
binary downloads and supporting files are on
SourceForge\footnote{\url{http://sourceforge.net/projects/biblatex-biber/}}
\biber\ is included into \TeX Live, the binaries coming from SourceForge.
\subsection{Compatibility Matrix}
\biber\ versions are closely coupled with \biblatex\ versions. You
need to have the right combination of the two. \biber\ will warn you
during processing if it encounters information which comes from a
\biblatex\ version which is incompatible. Table \ref{tab:compat} shows a
compatibility matrix for the recent versions.
\begin{table}
\begin{center}
\small
\begin{tabular}{lllll}
\toprule
\biber\ version & \biblatex\ version\\
\midrule
2.11 & 3.11\\
2.10 & 3.10\\
2.9 & 3.9\\
2.8 & 3.8\\
2.7 & 3.7\\
2.6 & 3.5, 3.6\\
2.5 & 3.4\\
2.4 & 3.3\\
2.3 & 3.2\\
2.2 & 3.1\\
2.1 & 3.0\\
2.0 & 3.0\\
1.9 & 2.9\\
1.8 & 2.8x\\
1.7 & 2.7\\
1.6 & 2.6\\
1.5 & 2.5\\
1.4 & 2.4\\
1.3 & 2.3\\
1.2 & 2.1, 2.2\\
1.1 & 2.1\\
1.0 & 2.0\\
0.9.9 & 1.7x\\
0.9.8 & 1.7x\\
0.9.7 & 1.7x\\
0.9.6 & 1.7x\\
0.9.5 & 1.6x\\
0.9.4 & 1.5x\\
0.9.3 & 1.5x\\
0.9.2 & 1.4x\\
0.9.1 & 1.4x\\
0.9 & 1.4x\\
\bottomrule
\end{tabular}
\end{center}
\caption{\biber/\biblatex\ compatibility matrix}
\label{tab:compat}
\end{table}
\subsection{License}
\biber\ is released under the free software Artistic License 2.0\footnote{\url{http://www.opensource.org/licenses/artistic-license-2.0.php}}
%\subsection{History}
\subsection{历史}
\BibTeX\ has been the default (only \ldots) integrated choice for
bibliography processing in \TeX\ for a long time. It has well known
limitations which stem from its data format, data model and lack of Unicode
support\footnote{In fact, there is now a Unicode version}. The
\verb+.bst+ language for writing bibliography styles is painful to learn
and use. It is not a general programming language and this makes it really
very hard to do sophisticated automated processing of bibliographies.
\biblatex\ was a major advance for \latex\ users as it moved much
of the bibliography processing into \latex\ macros. However,
\biblatex\ still used \BibTeX\ as a sorting engine for the
bibliography and also to generate various labels for
entries. \BibTeX's capabilities even for this reduced set of
tasks was still quite restricted due to the lack of Unicode support and
the more and more complex programming issues involved in label
preparation and file encoding.
%\biber\ was designed specifically for \biblatex\ in order to
%provide a powerful backend engine which could deal with any required
%tasks to do with \verb+.bbl+ preparation. Its main features are:
biber 是专门为biblatex设计的一种强大的后端引擎，它可以处理与.bbl文件准备相关的任意可能任务。它的主要功能有：
\begin{itemize}
\item %Deals with the full range of UTF-8
处理UTF-8全范围编码。
\item %Sorts in a completely customisable manner using, when available, CLDR collation tailoring
排序实现完全自定义，需要时还可使用 CLDR 排序调整。
\item %Allows for per-entrytype options
允许以条目为单位设置参数。
\item %Automatically encodes the \verb+.bbl+ into any supported encoding format\footnote{«Supported» here means encodings supported by the Perl \texttt{Encode} module}
能自动将.bbl文件转换为任意支持的编码格式。
\item %Processes all bibliography sections in one pass of the tool
能在一次处理过程中处理完所有的参考文献节。
\item %Output to GraphViz instead of \verb+.bbl+ in order to help visualise complex bibliographies with many crossrefs etc. (see section \ref{ref:vis})
使用GraphViz代替.bbl文件来帮助实现具有很多交叉引用的复杂参考文献的可视化。（见3.12节）
\item %Handles UTF-8 citekeys and filenames (given a suitable fully UTF-8 compliant \TeX\ engine)
能处理UTF-8编码的引用关键字和文件名（假设使用一个合适的完全兼容UTF-8的tex引擎）
\item %Creates entry sets dynamically and allows easily defined static entry sets, all processed in one pass
能在一次处理过程中动态创建条目集并允许简单定义静态条目集。
\item %«Syntactic» inheritance via new \bibtype{XDATA} entrytype and field. This can be thought of as a field-based generalisation of the \BibTeX\ \bibtype{STRING} functionality (which is also supported).
通过新的@XDATA条目和域实现`句法'继承。这可以看成是BIBTEX @STRING功能（也支持）的一种基于域的一般化方法。
\item %«Semantic» inheritance via a generalisation of the \BibTeX\ crossreference mechanism. This is highly customisable by the user---it is possible to choose which fields to inherit for which entrytypes and to inherit fields under different names etc. Nested crossreferences are also supported.
通过BIBTEX交叉引用机制一般化的`语义'继承。可以由用户深度定制————可以选择将某些条目的某些域继承不同的域中等。也支持嵌套的交叉引用。
\item %Handles complex auto-expansion and contraction of names and namelists (See section 4.11.4 of the \biblatex\ manual for an excellent explanation with examples, this is quite an impressive feature \ldots)
能处理姓名和姓名列表的自动缩减和扩展（一个详细解释的例子见biblatex 手册的4.11.4节，这是一种令人印象深刻的功能）。
\item %Extensible modular datasource architecture for ease of adding more datasource types
可扩展的模块化的数据源架构便于增加更多的数据源类型。
\item %Support for remote datasources
支持远程的数据源。
\item %User-definable mapping and suppression of fields and entrytypes in datasources. You can use this to, for example, ignore all \bibfield{ABSTRACT} fields completely. See section \ref{ref:map}
可对数据源中的条目类型和域做用户自定义的映射和禁用。比如，可以利用它来完全忽略所有的ABSTRACT域，见3.1.2节。
\item %Support for related entries, to enable generic treatment of things like «translated as», «reprinted as», «reprint of» etc.
支持关联条目以实现对类似«translated as», «reprinted as», «reprint of»
等的通用处理。
\item %Customisable labels
可定制的标签
\item %Multiple bibliography lists in the same section with different sorting and filtering
在同一节内实现具有不同排序和过滤的多个文献表。
\item %No more restriction to a static data model of specific fields and entrytypes
不在对特定条目和域的静态数据模型做限制。
\item %Structural validation of the data against the data model with a customisable validation model
数据的结构化验证和可定制验证模型的数据模型
\item %Tool mode for operations on datasources directly
对数据源直接操作的工具模式
\end{itemize}
%\noindent Figure \ref{fig:overview} shows the main functional units of
%processing in \biber. The most difficult tasks which \biber\
%performs are the processing of \biblatex's \opt{uniquename} and
%\opt{uniquelist} options\footnote{A rather tricky unbounded loop but with
% a guaranteed eventual stable exit state.}, the sorting of
%lists\footnote{This is multi-field ST sort with an embedded cache for
% performance.} and the initial data parse and remap into an
%internal data model. \biber\ is getting on for around 20,000 lines of
%mostly OO Perl and relies on certain splendid Perl modules
%such as \verb+Unicode::Collate+, \verb+Text::BibTeX+ and
%\verb+XML::LibXML+.
图1展示了biber处理过程主要功能环节。biber在执行过程中最困难的任务是处理biblatex的uniquename和uniquelist选项，列表的排序，数据的初步解析及重映射为内部数据模型。biber已经接近有20000行的面向对象的perl代码，并依赖于一些非常出色的perl模块比如Unicode::Collate,Text::BibTeX and XML::LibXML。
\begin{figure}[!htpb]
\centering\small
\begin{tikzpicture}
\node[file] (dsfiles) {datasources};
\node[file] (bcf) [right of=dsfiles,node distance=8em] {\texttt{.bcf} control file};
\node[funit] (decode) [below of=dsfiles,node distance=8em] {Decode to UTF-8} edge [<-,very thick] (dsfiles) edge [<-,very thick] (bcf);
\node[funit] (mapp) [below of=decode,node distance=6em] {remap/parse} edge [<-,very thick] (decode);
\node[file] (config) [left of=mapp,node distance=12em] {User \texttt{biber.conf} file} edge [->,very thick] (mapp);
\node[funit] (dyn) [below of=mapp,node distance=6em] {Instantiate dynamic sets and\\related entries} edge [<-,very thick] (mapp);
\node[funit] (xdata) [below of=dyn,node distance=6em] {Process XDATA} edge [<-,very thick] (dyn);
\node[funit] (crossrefs) [below of=xdata,node distance=6em] {Process cross-references and\\sets} edge [<-,very thick] (xdata);
\node[funit] (validate) [below of=crossrefs,node distance=6em] {Validate data model} edge [<-,very thick] (crossrefs);
\node[funit] (pre) [below of=validate,node distance=6em] {Resolve label* fields\\generate hashes\\enforce mincrossrefs} edge [<-,very thick] (validate);
\node[funit] (unique) [right of=decode,node distance=16em] {Generate uniqueness data};
\draw[->,very thick] (pre.east) -- ($ (pre.east) + (2em,0) $) -- ($ (unique.west) - (2em,0) $) -- (unique.west);
\node[funit] (visible) [below of=unique,node distance=6em] {Generate name visibility data} edge [<-,very thick] (unique);
\node[funit] (post) [below of=visible,node distance=6em] {Generate more hashes and\\labels} edge [<-,very thick] (visible);
\node[funit] (sort) [below of=post,node distance=6em] {Perform sorting} edge [<-,very thick] (post);
\node[funit] (output) [below of=sort,node distance=6em] {Construct output objects} edge [<-,very thick] (sort);
\node[funit] (encode) [below of=output,node distance=6em] {Encode to output encoding} edge [<-,very thick] (output);
\node[file] (bbl) [below of=encode,node distance=8em] {output file} edge [<-,very thick] (encode);
\end{tikzpicture}
\caption{Overview of \biber's main functional units}
\label{fig:overview}
\end{figure}
It may be useful to know something about the different routes a datasource
entry can take as it passes through \biber.
\begin{enumerate}
\item\label{list:cited} All cited entries which are subsequently found in a
datasource are instantiated in the internal \biber\ data model.
\item Some uncited entries on which cited entries depend are
instantiated in the internal \biber\ data model:
\begin{itemize}
\item Entries with entrytype \bibtype{XDATA} which are referenced from cited
entries.
\item Entries mentioned in the \bibfield{CROSSREF} or
\bibfield{XREF} field of a cited entry (unless they are also cited
themselves in which case they are already instantiated as per item
\ref{list:cited} above).
\item Clones of entries mentioned as a «related» entry of a cited
entry.
\item Members of sets, either explicit \bibtype{SET} entrytype entries or
dynamic sets.
\end{itemize}
\item Some uncited but instantiated entries are promoted to cited
status so that they make it into the output:
\begin{itemize}
\item Entries instantiated by being members of a set.
\item Entries instantiated by being mentioned as a \bibfield{CROSSREF} are
promoted to cited status if \bibfield{CROSSREF}'ed or \bibfield{XREF}'ed at
least \opt{mincrosref} times.
\item Clones of entries mentioned as a «related» entry of a cited entry.
\end{itemize}
\item Some of these auto-cited entries have the «dataonly» option set on
them so that \biblatex\ will only use them for data and will not output
them to the bibliography:
\begin{itemize}
\item Clones of entries mentioned as a «related» entry of a cited entry.
\end{itemize}
\end{enumerate}
\subsection{Performance}
\biber\ can't really be compared with \BibTeX\ in any meaningful
way performance-wise. \biber\ is written in Perl and does a
\emph{great} deal more than \BibTeX\ which is written in C. One of
\biber's test cases is a 2150 entry, 15,000 line \verb+.bib+ file
which references a 630 entry macros file with a resulting 160 or so page (A4)
formatted bibliography. This takes \biber\ just under 30 seconds to process on
a reasonable computer. This is perfectly acceptable, especially for a
batch program.
\subsection{Acknowledgements}
François Charette originally wrote a first modest version of \biber. Philip Kime joined in
the development in 2009 and is largely responsible for making it what it is today.
\section{Use}
Firstly, please note that \biber\ will \emph{not} attempt to sanitise
the content of \BibTeX\ datasources. That is, don't expect it to
auto-escape any \TeX\ special characters like «\verb+&+» or «\verb+%+» which
it finds in, for example, your \bibfield{TITLE} fields. It used to do this in
earlier versions in some cases but as of version 0.9, it doesn't because
it's fraught with problems and leads to inconsistent expectations and
behaviour between different datasource types. In your \BibTeX\ data
sources, please make sure your entries are legal \TeX\ code.
Running \opt{biber --help} will display all options and description of
each and is the primary source of usage information. \biber\
returns an exit code of 0 on success or 1 if there was an error.
Most \biber\ options can be specified in long or short format. When
mentioning options below, they are referred to as
«\opt{long form|short form}» when an option has both a long and short
form. As usual with such options, when the option requires an argument, the
long form is followed by an equals sign «\verb+=+» and then the argument,
the short form is followed by a space and then the argument. For example,
the \opt{--configfile|-g} option can be given in two ways:
\begin{verbatim}
biber --configfile=somefile.conf
biber -g somefile.conf
\end{verbatim}
With the \opt{backend=biber} option, \biblatex\ switches its backend
interface and passes all options and information relevant to \biber's
operation in a control file with extension \verb+.bcf+\footnote{\biblatex\ Control
File}. This is conceptually equivalent to the \verb+.aux+ file which
\latex\ uses to pass information to \BibTeX. The \verb+.bcf+ file is
XML and contains many options and settings which configure how \biber\
is to process the bibliography and generate the \verb+.bbl+ file.
The usual way to call \biber\ is simply with the \verb+.bcf+ file
as the only argument. \biblatex\ always writes the control file with
a \verb+.bcf+ extension. Specifying the «\verb+.bcf+» extension to
\biber\ is optional. Assuming a control file called
\verb+test.bcf+, the following two commands are equivalent:
\begin{verbatim}
biber test.bcf
biber test
\end{verbatim}
\noindent Figure \ref{fig:biber-mdf} is a graphical overview of the data flow for
data model information. See Figure \ref{fig:overview} for a more complete
overview of \biber's processing steps.
\begin{figure}[!htpb]
\centering\small
\begin{tikzpicture}
\node[file] (dsfile) {datasource};
\node[funit] (remap) [below of=dsfile, node distance=8em] {remap} edge [<-,dashed] (dsfile);
\node[file] (docremap) [left of=dsfile, node distance=15em] {document data model mapping\\from \texttt{.bcf}} edge [->,dashed] (remap);
\node[file] (defaultremap) [left of=remap, node distance=15em] {default data model mapping\\from \texttt{.bcf}} edge [->,dashed] (remap);
\node[file] (conf) [below of=remap, node distance=7em] {data model mapping\\from \biber\ config file} edge [->,dashed] (remap);
\node[funit] (parser) [right of=remap, node distance=8em] {parser} edge [<-,very thick] (remap);
\node[funit] (validation) [right of=parser, node distance=8em] {validation} edge [<-,very thick] (parser);
\node[file] (hard) [above of=validation, node distance=8em]
{\biblatex\ data\\model from \texttt{.bcf}} edge [->,dashed]
(parser) edge [->,dashed] (remap) edge [->,dashed] (validation);
\node[file] (bbl) [below of=validation, node distance=8em] {output file} edge [<-,very thick] (validation);
\end{tikzpicture}
\caption{Model data flow in \biber}
\label{fig:biber-mdf}
\end{figure}
\bigskip
\subsection{Options and config file}\label{conffile}
\biblatex\ options which \biber\ needs to know about are passed
via the \verb+.bcf+ file. See Table \ref{tab:bltxopts} for the \biblatex\
options which \biber\ uses and also for the scopes which are supported
for each option. \biber\ also has its own options which are set using
the following resource chain, given in decreasing precedence order:\\[2ex]
\begin{table}
\begin{center}
\small
\begin{tabular}{llll}
\toprule
\biblatex\ option & Global & Per-type & Per-entry\\
\midrule
alphaothers & $\checkmark$ & $\checkmark$ & \\
dataonly & & $\checkmark$ & $\checkmark$\\
inheritance & $\checkmark$ & & \\
labelalpha & $\checkmark$ & $\checkmark$ & \\
labelalphatemplate & $\checkmark$ & $\checkmark$ & \\
labeldate & $\checkmark$ & $\checkmark$ & \\
labeldatespec & $\checkmark$ & $\checkmark$ & \\
labelnamespec & $\checkmark$ & $\checkmark$ & \\
labelnumber & $\checkmark$ & $\checkmark$ & \\
labeltitle & $\checkmark$ & $\checkmark$ & \\
labeltitleyear & $\checkmark$ & $\checkmark$ & \\
maxalphanames & $\checkmark$ & $\checkmark$ & $\checkmark$\\
maxbibnames & $\checkmark$ & $\checkmark$ & $\checkmark$\\
maxcitenames & $\checkmark$ & $\checkmark$ & $\checkmark$\\
maxitems & $\checkmark$ & $\checkmark$ & $\checkmark$\\
minalphanames & $\checkmark$ & $\checkmark$ & $\checkmark$\\
minbibnames & $\checkmark$ & $\checkmark$ & $\checkmark$\\
mincitenames & $\checkmark$ & $\checkmark$ & $\checkmark$\\
minitems & $\checkmark$ & $\checkmark$ & $\checkmark$\\
presort & $\checkmark$ & $\checkmark$ & $\checkmark$\\
singletitle & $\checkmark$ & $\checkmark$ & \\
skipbib & & $\checkmark$ & $\checkmark$\\
skiplab & & $\checkmark$ & $\checkmark$\\
skiplos & & $\checkmark$ & $\checkmark$\\
sortalphaothers & $\checkmark$ & $\checkmark$ & \\
sortexclusion & & $\checkmark$ & \\
sortfirstinits & $\checkmark$ & & \\
sorting & $\checkmark$ & & \\
uniquelist & $\checkmark$ & $\checkmark$ & $\checkmark$\\
uniquename & $\checkmark$ & $\checkmark$ & $\checkmark$\\
useauthor & $\checkmark$ & $\checkmark$ & $\checkmark$\\
useeditor & $\checkmark$ & $\checkmark$ & $\checkmark$\\
useprefix & $\checkmark$ & $\checkmark$ & $\checkmark$\\
usetranslator & $\checkmark$ & $\checkmark$ & $\checkmark$\\
\bottomrule
\end{tabular}
\end{center}
\caption{\biblatex\ options which \biber\ uses}
\label{tab:bltxopts}
\end{table}
\noindent command line options $\rightarrow$\\
\hspace*{1em}\verb+biber.conf+ file $\rightarrow$\\
\hspace*{2em}\verb+.bcf+ file$\rightarrow$\\
\hspace*{3em}\biber\ hard-coded defaults\\[2ex]
\noindent Users do not need to care directly about the contents or format of the
\verb+.bcf+ file as this is generated from the options which they specify
via \biblatex. The config file is a place to set commonly used
command-line options and also to set options which cannot be set on the
command line.
The configuration file is by default called \verb+biber.conf+ but this can
be changed using the \opt{--configfile|-g} option. Unless
\opt{--configfile|-g} is used, the config file is
looked for in the following places, in decreasing order of preference:\\[2ex]
\noindent \verb+biber.conf+ in the current directory $\rightarrow$\\
\hspace*{1em}\verb+$HOME/.biber.conf+ $\rightarrow$\\
\hspace*{2em}\verb+$XDG_CONFIG_HOME/biber/biber.conf+ $\rightarrow$\\
\hspace*{3em}\verb+$HOME/Library/biber/biber.conf+ (Mac OSX only)\\
\hspace*{3em}\verb+$APPDATA/biber.conf+ (Windows only) $\rightarrow$\\
\hspace*{4em}the output of «\verb+kpsewhich biber.conf+» (if available on the
system)\\[2ex]
\noindent The config file is XML. Here Below is
an example config file which displays the \biber\ defaults:
\begin{lstlisting}[language=xml]
<?xml version="1.0" encoding="UTF-8"?>
<config>
<clrmacros>0</clrmacros>
<collate_options>
<option name="level" value="4"/>
<option name="variable" value="non-ignorable"/>
<option name="normalization" value="prenormalized"/>
</collate_options>
<debug>0</debug>
<decodecharsset>base</decodecharsset>
<dieondatamodel>0</dieondatamodel>
<graph>0</graph>
<input_encoding>UTF-8</input_encoding>
<listsep>and</listsep>
<mincrossrefs>0</mincrossrefs>
<namesep>and</namesep>
<nodieonerror>0</nodieonerror>
<noinit>
<!-- strip lowercase prefices like 'al-' when generating initials -->
<option value="\b\p{Ll}{2}\p{Pd}"/>
<!-- strip diacritics when generating initials -->
<option value="[\x{2bf}\x{2018}]"/>
</noinit>
<nolabel>
<!-- strip punctuation, symbols, separator and control characters -->
<option value="[\p{P}\p{S}\p{C}]+"/>
</nolabel>
<nolog>0</nolog>
<nostdmacros>0</nostdmacros>
<nosort>
<!-- strip prefices like 'El-' when sorting name fields -->
<option name="setnames" value="\A\p{L}{2}\p{Pd}"/>
<!-- strip some diacritics when sorting name fields -->
<option name="setnames" value="[\x{2bf}\x{2018}]"/>
</nosort>
<onlylog>0</onlylog>
<others_string>others</others_string>
<ouput_align>0</output_align>
<output_encoding>UTF-8</output_encoding>
<output_fieldcase>upper</output_fieldcase>
<output_format>bbl</output_format>
<output_indent>2</output_indent>
<output_resolve_xdata>0</output_resolve_xdata>
<output_resolve_crossrefs>0</output_resolve_crossrefs>
<output_resolve_sets>0</output_resolve_sets>
<output_safechars>0</output_safechars>
<output_safecharsset>base</output_safecharsset>
<quiet>0</quiet>
<sortcase>true</sortcase>
<sortupper>true</sortupper>
<tool>false</tool>
<trace>false</trace>
<validate_bltxml>0</validate_bltxml>
<validate_config>0</validate_config>
<validate_control>0</validate_control>
<validate_datamodel>0</validate_datamodel>
<wraplines>0</wraplines>
<xsvsep>\s*,\s*</xsvsep>
</config>
\end{lstlisting}
\noindent In practice, the most commonly used options will be set via
\biblatex\ macros in your document and automatically passed to \biber\
via the \verb+.bcf+ file. Certain options apply only to \biber\ and can
only be set in the config file, particularly the more complex
options. Most options are simple tags. Exceptions are the
\opt{nosort}, \opt{noinit} and \opt{collate-options} options which are slightly
more complex and can have sub-options as shown. A much more complex
option is the \opt{sourcemap} option which is not set by default and
which is described in section \ref{ref:map}.
\subsubsection{The \texttt{output-format} option}\label{ref:of}
\biber\ is able to output formats other than \file{.bbl} files for \biblatex\
to consume. It is also able to output other formats such as \file{DOT} for
visualisation of entry dependencies (see section \ref{ref:vis}), the
experimental \verb+biblatexml+ XML format, \bibtex\ \file{.bib} files and
an XML version of the \file{.bbl} format with extension \file{.bblxml}.
\file{.bib} output is possible in tool mode, when you are converting an
entire datasource file independently of any particular document (see
section \ref{ref:tool}). It is also useful when you want, instead of a
\file{.bbl}, a new \file{.bib} file containing only the cited entries from
a document so that you can, for example, send a minimally complete package
for typesetting to someone. To do this, you would, after the first \latex
run, call \biber like this:
\begin{verbatim}
biber --output-format=bibtex test.bcf
\end{verbatim}
\noindent This would result in a new \file{.bib} file called
\file{test\_biber.bib} containing all cited entries in \file{test.tex}, in
citation order, formatted according to the various \opt{ouput-*} options.
You could of course also perform more processing like source mapping
(see section \ref{ref:map}), reencoding (see section \ref{ref:enc}) etc. using more
command line options or a config file.
The \file{.bblxml} format for output is an XML version of the \file{.bbl}.
It cannot be read by \biblatex\ but contains the same information as in the
\file{.bbl} and may be useful if you want to transform a document
bibliography into some other format since XML is a well-supported
transformation format (using, for example, XSLT). By default, when choosing
\file{.bblxml} output with the option \opt{--output-format=bblxml}, a
RelaxNG XML schema is also generated (unless the \opt{--no-bblxml-schema}
is used). This schema is derived from the active datamodel in the document
(passed in the \file{.bcf} from \biblatex) and is placed in the same
directory as the \file{.bblxml} output file. The extension of the schema is
\file{.rng}. The option \opt{--validate-bblxml} may be used to validate the
\file{.bblxml} against the schema.
\subsubsection{The \texttt{sourcemap} option}\label{ref:map}
The datasource drivers implement a mapping from datasource
entrytypes and fields into the \biblatex\ data model. If you want to
override or augment the driver mappings you can use the
\opt{sourcemap} option which makes it possible to, for example, have a
datasource with non-standard entrytypes or fields and to have these
automatically mapped into other entrytypes/fields without modifying
your datasource. Essentially, this alters the source data stream
which \biber\ uses to build the internal \biblatex\ data model and is an
automatic way of editing the datasource as it is read by \biber.
Source mappings can be defined at different «levels» which are applied
in a defined order. See the \biblatex\ manual regarding these macros:\\[2ex]
\noindent \texttt{user}-level maps defined with \cmd{DeclareSourcemap}$\rightarrow$\\
\hspace*{1em}\texttt{user}-level maps defined in the \biber\ config file (described below)$\rightarrow$\\
\hspace*{2em}\texttt{style}-level maps defined with \cmd{DeclareStyleSourcemap}$\rightarrow$\\
\hspace*{3em}\texttt{driver}-level maps defined with \cmd{DeclareDriverSourcemap}\\[2ex]
The \opt{sourcemap} option can only be set in the config file
and not on the command line as it has a complex structure. This
option allows you to perform various datasource mapping
tasks which can be useful for pre-processing data which you do not
generate yourself:
\begin{itemize}
\item Map datasource 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 \verb+\addresource{}+ macros.
\item Restrict any of the above operations to entries only of a certain
entrytype.
\end{itemize}
\noindent There is in fact, more flexibility than the above suggests,
examples will show this below. The format of the \opt{sourcemap} option
section in the config file is described below, followed by examples which
will make things clearer. Items in \textcolor{red}{red} are not literal,
they are descriptive meta-values which are explained in the accompanying
text. Items in \textcolor{blue}{blue} are optional within their parent
section or element. The general structure is:
\lstset{showspaces=false}
\lstset{showstringspaces=false}
\begin{lstlisting}[language=xml,escapechar=+,mathescape=true]
<sourcemap>
<maps datatype="+\textcolor{red}{driver$_1$}+" map_overwrite="1|0">
<map$_1$ +\textcolor{blue}{map\_overwrite="1|0"}+> ... </map$_1$>
$\vdots$
<map$_n$ +\textcolor{blue}{map\_overwrite="1|0"}+> ... </map$_n$>
</maps>
$\vdots$
<maps datatype="+\textcolor{red}{driver$_n$}+" map_overwrite="1|0">
<map$_1$ +\textcolor{blue}{map\_overwrite="1|0"}+> ... </map$_1$>
$\vdots$
<map$_n$ +\textcolor{blue}{map\_overwrite="1|0"}+> ... </map$_n$>
</maps>
</sourcemap>
\end{lstlisting}
\noindent Here, \textcolor{red}{\texttt{driver$_1$}}\ldots
\textcolor{red}{\texttt{driver$_n$}} are the names of valid \biber\ data
source drivers (see section \ref{dsd}). One thing to note here is the
\opt{map\_overwrite} attribute. This boolean attribute determines whether,
for this driver mapping section, you may overwrite existing fields when
adding new fields or mapping them. This attribute can be overridden on a
per-map basis, see below. A warning will be issued either way saying
whether an existing field will or will not be overwritten. If omitted, it
defaults to «0».
The \opt{map} elements are processed in sequence and contain a number of
\opt{map\_step}s which are also processed in sequence. Each \opt{map\_step}
allows you to do a particular thing or combination of things:
\begin{itemize}
\item Change the entrytype of an entry
\item Change the name of a field
\item Add extra fields the entry
\item Change the contents of a field
\end{itemize}
\noindent These facilities are explained in more detail below, with
examples. A \opt{map} element looks like this:
\begin{lstlisting}[language=xml,escapechar=+,mathescape=true]
<map +\textcolor{blue}{map\_overwrite="0|1"} \textcolor{blue}{map\_foreach="\textcolor{red}{loopval}"}+>
+\textcolor{blue}{<per\_datasource>\textcolor{red}{datasource}</per\_datasource>}+
+\textcolor{blue}{<per\_type>\textcolor{red}{entrytype}</per\_type>}+
+\textcolor{blue}{<per\_nottype>\textcolor{red}{entrytype}</per\_nottype>}+
<map_step +\textcolor{blue}{map\_type\_source="\textcolor{red}{source-entrytype}"}+
+\textcolor{blue}{map\_field\_source="\textcolor{red}{source-field}"}+
+\textcolor{blue}{map\_notfield="\textcolor{red}{source-field}"}+
+\textcolor{blue}{map\_type\_target="\textcolor{red}{target-entrytype}"}+
+\textcolor{blue}{map\_field\_target="\textcolor{red}{target-field}"}+
+\textcolor{blue}{map\_match="\textcolor{red}{match-regexp}"}+
+\textcolor{blue}{map\_nomatch="\textcolor{red}{match-regexp}"}+
+\textcolor{blue}{map\_replace="\textcolor{red}{replace-regexp}"}+
+\textcolor{blue}{map\_field\_set="\textcolor{red}{set-field}"}+
+\textcolor{blue}{map\_field\_value="\textcolor{red}{set-value}"}+
+\textcolor{blue}{map\_entry\_new="\textcolor{red}{newentrykey}"}+
+\textcolor{blue}{map\_entry\_newtype="\textcolor{red}{newentrykeytype}"}+
+\textcolor{blue}{map\_entry\_entrytarget="\textcolor{red}{newentrykey}"}+
+\textcolor{blue}{map\_append="1"}+
+\textcolor{blue}{map\_null="1"}+
+\textcolor{blue}{map\_entry\_null="1"}+
+\textcolor{blue}{map\_entry\_clone="\textcolor{red}{clonekey}"}+
+\textcolor{blue}{map\_origfield="1"}+
+\textcolor{blue}{map\_origfieldval="1"}+
+\textcolor{blue}{map\_origentrytype="1"}+
+\textcolor{blue}{map\_final="1"}+/>
</map>
\end{lstlisting}%| <- sometimes emacs highlighting needs this
\begin{itemize}
\item If there are any \textcolor{red}{\texttt{datasource}}s named in
\textcolor{blue}{\texttt{per\_datasource}} elements, this mapping only applies to entries
coming from the named \textcolor{red}{\texttt{datasource}}s. There can be
multiple \textcolor{blue}{\texttt{per\_datasource}} elements each specifying one of the
datasource names given in a \biblatex\ \verb+\addbibresource+ macro.
\item If there are any \textcolor{red}{\texttt{entrytypes}}s named in
\textcolor{blue}{\texttt{per\_type}} elements, this mapping only applies to entries
of the named \textcolor{red}{\texttt{entrytypes}}s.
\item If there are any \textcolor{red}{\texttt{entrytypes}}s named in
\textcolor{blue}{\texttt{per\_nottype}} elements, this mapping only applies to entries
not of the named \textcolor{red}{\texttt{entrytypes}}s.
\item The \texttt{map\_overwrite} attribute can be used to override the
value for this attribute set on the parent \opt{maps} element. If
omitted, it defaults to the parent \opt{maps} attribute value.
\item The \texttt{map\_foreach} attribute loops over all \cmd{step}s in
this \cmd{map}, setting the special variable \verb+$MAPLOOP+ to each of
the comma-separated values contained in
\textcolor{red}{\texttt{loopval}}. \textcolor{red}{\texttt{loopval}} can
either be the name of a datafield set defined with \biblatex's
\cmd{DeclareDatafieldSet}, a datasource field which contains a
comma-separated values list or an explicit comma-separated values list
itself (and \textcolor{red}{\texttt{loopval}} is determined in that
order). This allows the user to repeat a group of \opt{map\_step}s for
each value of \textcolor{red}{\texttt{loopval}}. The special variable
\verb+$MAPUNIQ+ may also be used in the \opt{map\_step}s to generate a
random unique string. This can be useful when creating keys for new
entries. The special variable \verb+$MAPUNIQVAL+ may be used the
\opt{map\_step}s to refer to the value of the last random unique string
generated with \verb+$MAPUNIQ+.
\end{itemize}
\noindent Each \opt{map\_step} is looked at in turn and compared with the
datasource entry being processed. A \opt{map\_step} works like this:
\begin{itemize}
\item If \textcolor{blue}{\texttt{map\_entry\_new}} is set, a new entry is
created with the entry key \textcolor{red}{\texttt{newentrykey}} and the
entry type \textcolor{red}{\texttt{newentrykeytype}} given in the option
\textcolor{blue}{\texttt{map\_entry\_newtype}}. This entry is only
in-scope during the processing of the current entry and can be referenced
by \textcolor{red}{\texttt{newentrykey}} given as the value to
\textcolor{blue}{\texttt{map\_entrytarget}}. In
\textcolor{red}{\texttt{newentrykey}}, you may use standard Perl
regular expression backreferences to captures from a
previous \textcolor{blue}{\texttt{map\_match}} step.
\item When a \textcolor{blue}{\texttt{map\_field\_set}} step has
\textcolor{blue}{\texttt{map\_entrytarget}} set to the entrykey of an
entry created by \textcolor{blue}{\texttt{map\_entry\_new}}, the target
for the field set will be the \textcolor{blue}{\texttt{map\_entrytarget}}
entry rather than the entry being currently processed. This allows users
to create new entries and set fields in them.
\item If \textcolor{blue}{\texttt{map\_entry\_null}} is set,
processing of the \opt{map} immediately terminates and the current
entry is not created. It is as if it did not exist in the
datasource. Obviously, you should select the entries which you want
to apply this to using prior mapping steps.
\item If \textcolor{blue}{\texttt{map\_entry\_clone}} is set, a clone of
the entry is created with an entry key
\textcolor{red}{\texttt{clonekey}}. Obviously this may cause labelling
problems in author/year styles etc. and should be used with care. The
cloned entry is in-scope during the processing of the current entry and
can be modified by passing its key as the value to
\textcolor{blue}{\texttt{map\_entrytarget}}. In
\textcolor{red}{\texttt{clonekey}}, you may use standard Perl
regular expression backreferences to captures from a
previous \textcolor{blue}{\texttt{map\_match}} step.
\item Change the \textcolor{red}{\texttt{source-entrytype}} to
\textcolor{red}{\texttt{target-entrytype}}, if defined. If
\textcolor{blue}{\texttt{map\_final}} is set then if the entrytype of the
entry is not \textcolor{red}{\texttt{source-entrytype}}, processing of
this \opt{map} immediately terminates.
\item Change the \textcolor{red}{\texttt{source-field}} to
\textcolor{red}{\texttt{target-field}}, if defined. If
\textcolor{blue}{\texttt{map\_final}} is set, then if there is no
\textcolor{red}{\texttt{source-field}} field in the entry, processing of
this \opt{map} immediately terminates.
\item If \textcolor{blue}{\texttt{map\_notfield}} is used then only apply
the step if the \textcolor{red}{\texttt{source-field}} does not exist.
\item If \textcolor{blue}{\texttt{map\_match}} is defined but
\textcolor{blue}{\texttt{map\_replace}} is not, only apply the
step if the \textcolor{red}{\texttt{source-field}} matches
\textcolor{blue}{\texttt{map\_match}}. You can use parentheses as usual
to capture parts of the match and can then use these later when setting a \textcolor{blue}{\texttt{map\_field\_value}}.
\item \textcolor{blue}{\texttt{map\_notmatch}} is the same as
\textcolor{blue}{\texttt{map\_match}} but with the logic reversed.
\item Perform a Perl regular expression match and replace on the value of
\textcolor{red}{\texttt{source-field}} if
\textcolor{blue}{\texttt{map\_match}} and
\textcolor{blue}{\texttt{map\_replace}} are defined. You may use (and almost certainly
will want to use) parentheses for back-references in \textcolor{blue}{\texttt{map\_replace}}.
Do not quote the regular expressions in any special (i.e. non-Perly) way---it's not
necessary.
\item If \textcolor{blue}{\texttt{map\_field\_set}} is defined, then its
value is \textcolor{red}{\texttt{set-field}} which will be set to a value
specified by further attributes. If
\textcolor{blue}{\texttt{map\_overwrite}} is false for this step and the
field to set already exists then the map step is ignored. If
\textcolor{blue}{\texttt{map\_final}} is also set on this step, then
processing of the parent map stops at this point. If
\textcolor{blue}{\texttt{map\_append}} is set, then the value to set is
appended to the current value of \textcolor{red}{\texttt{set-field}}. The
value to set is specified by a mandatory one and only one of the
following attributes:
\begin{itemize}
\item \textcolor{blue}{\texttt{map\_field\_value}} --- The
\textcolor{red}{\texttt{set-field}} is set to
\textcolor{red}{\texttt{set-value}}
\item \textcolor{blue}{\texttt{map\_null}} --- The field is ignored, as
if it did not exist in the datasource
\item \textcolor{blue}{\texttt{map\_origentrytype}} --- The
\textcolor{red}{\texttt{set-field}} is set to the
most recently mentioned \textcolor{red}{\texttt{source-entrytype}} name.
\item \textcolor{blue}{\texttt{map\_origfield}} --- The
\textcolor{red}{\texttt{set-field}} is set to the most recently
mentioned \textcolor{red}{\texttt{source-field}} name
\item \textcolor{blue}{\texttt{map\_origfieldval}} --- The
\textcolor{red}{\texttt{set-field}} is set to the most recently
mentioned \textcolor{red}{\texttt{source-field}} value
\end{itemize}
\end{itemize}
\noindent With \bibtex\ datasources, you can specify the
pseudo-field «entrykey» for \textcolor{red}{\texttt{source-field}}
which is the citation key of the entry. Naturally, this «field» cannot
be changed (used as \textcolor{red}{\texttt{set-field}},
\textcolor{red}{\texttt{target-field}} or changed using
\textcolor{blue}{\texttt{map\_replace}}).
Note that for XML datasources like BibLaTeXML, the names of
fields and entrytypes are matched in a case sensitive manner. For all other
datasource types, entrytype and field name matching is
case insensitive.
\noindent Here are some examples: