summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/bibtex/biber/doc/biber.tex
blob: 1130e606879943b90263b28c0b48d9d25d43a281 (plain)
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
\documentclass{ltxdockit}
\usepackage[british]{babel}
\usepackage[strict=true,autostyle=true]{csquotes}
\usepackage{ifthen}
\usepackage{fontspec}
\usepackage{graphicx}
\usepackage{booktabs}
\setmainfont[Ligatures=TeX]{TeXGyrePagella}
\setsansfont[Ligatures=TeX]{Arial}
\setmonofont[Ligatures=TeX]{Courier New}

\MakeAutoQuote{«}{»}

\titlepage{%
  title={biber},
  subtitle={A backend bibliography processor for biblatex},
  url={http://biblatex-biber.sourceforge.net},
  author={François Charette, Philip Kime},
  email={firmicus@ankabut.net, Philip@kime.org.uk},
  revision={biber 0.8 (biblatex 1.2)},
  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}

\printtitlepage
\tableofcontents

\section{Introduction}
\label{int}

\subsection{About}

\verb+biber+ is conceptually a \verb+bibtex+ replacement for
\verb+biblatex+. It is written in Perl with the aim of providing a
customised and sophisticated data preparation backend for \verb+biblatex+.
Functionally, it offers a superset of \verb+bibtex+'s capabilities but is
tightly coupled with \verb+biblatex+ and cannot be used as a stand-alone tool
with standard \verb+.bst+ styles.

\subsection{Requirements}\label{ref:req}

\verb+biber+ is distributed in two ways. There is a Perl source
version which requires you to have a working Perl installation
(preferably version 5.12 but no less than 5.10) and the ability to
install the pre-requisite modules. Also provided are binaries for
major OSes built with the Perl \verb+PAR::Packer+ module and utilities.

Currently there are binaries available for:

\begin{itemize}
\item OSX Intel 64-bit
\item Windows
\item Linux 32-bit
\item Linux 64-bit
\end{itemize}

These should work on any fairly recent OS version. Both binaries and
Perl source are available on SourceForge\footnote{\url{http://sourceforge.net/projects/biblatex-biber/}}.

\subsection{License}

\verb+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}

\verb+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.

\verb+biblatex+ was a major advance for LaTeX users as it moved much
of the bibliography processing into LaTeX macros. However,
\verb+biblatex+ still used \verb+bibtex+ as a sorting engine for the
bibliography and also to generate various labels for
entries. \verb+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.

\verb+biber+ was designed specifically for \verb+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:

\begin{itemize}
\item Deals with the full range of UTF-8
\item Sorts in a completely customisable manner, using when available,
  CLDR collation tailorings
\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}
\item Processes all bibliography sections in one pass of the tool
\item Handles UTF-8 citekeys and filenames (given a suitable fully
  UTF-8 compliant TeX engine)
\item Creates entry sets dynamically and allow easily defined static entry sets,
  all processed in one pass
\item Flexible user-customisable crossreference field inheritance
  model
\item Support for related entries, to enable generic treatment of things
  like «translated as», «reprinted as», «reprint of» etc.\footnote{In BibLaTeX 1.2}
\item Handles very complex auto-expansion and contraction of names and
  namelists\footnote{In BibLaTeX 1.3}
\item Extensible modular data sources architecture for ease of adding
  more data source types.
\item Support for remote data sources
\end{itemize}

\subsection{Performance}

\verb+biber+ can't really be compared with \verb+bibtex+ in any meaningful
way performance-wise. \verb+biber+ is written in perl and does a
great deal more than \verb+bibtex+ which is written in C. One of
\verb+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 \verb+biber+ about 100 seconds on
average to process on a reasonable computer. This is perfectly acceptable,
especially for a batch program \ldots

\subsection{Acknowledgements}

François Charette originally wrote \verb+biber+. Philip Kime joined in
the development in 2009.

\section{Use}

Firstly, running \verb+biber --help+ will display all options and a brief
description of each. This is the most useful brief source of usage
information. \verb+biber+ returns an exit code of 0 on success or 1 if
there was an error.

Most \verb+biber+ options can be specified in long or short format. When
mentioning options below, they are referred to as
«\verb+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 \verb+--configfile|-g+ option can be given in two ways:

\begin{verbatim}
biber --configfile=somefile.conf
biber -g somefile.conf
\end{verbatim}

With the \verb+backend=biber+ option, \verb+biblatex+ switches its backend
interface and passes all options and information relevant to \verb+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 \verb+bibtex+. The \verb+.bcf+ file is
XML and contains many options and settings which configure how \verb+biber+
is to process the bibliography and generate the \verb+.bbl+ file.

The usual way to call \verb+biber+ is simply with the \verb+.bcf+ file
as the only argument. The «\verb+.bcf+» extension of the control file
is not optional. \verb+biblatex+ always outputs a control file with
the \verb+.bcf+ extension. Specifying the «\verb+.bcf+» extension to
\verb+biber+ \emph{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}

\subsection{Options and config file}
\verb+biber+ sets its options using the following resource 
chain which is given in decreasing precedence order:\\[2ex]

\noindent command line options $\rightarrow$\\
\hspace*{1em}\verb+.bcf+ file$\rightarrow$\\
\hspace*{2em}\verb+biber.conf+ file $\rightarrow$\\
\hspace*{3em}\verb+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
for \verb+biblatex+. To override the \verb+.bcf+ options, users
may use either a configuration file or the command line to set options.

The configuration file is by default called \verb+biber.conf+ but this can
be changed using the \verb+--configfile|-g+ option. Unless
\verb+--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 format is a very flexible one which allows users to specify
options in most common formats, even mixed in the same file. It's easier to
see an example. Here is a config file which displays the \verb+biber+
hard-coded defaults:

\begin{verbatim}
bblencoding         UTF-8
bibencoding         UTF-8
collate             1
<collate_options>
    level           3
</collate_options>
debug               0
fastsort            0
mincrossrefs        2
nolog               0
nostdmacros         0
<nosort>
  # ignore prefices like 'al-' when sorting name fields
  type_names      \A\p{L}{2}\p{Pd}
  # ignore diacritics when sorting author
  type_names      [\x{2bf}\x{2018}]
</nosort>
onlylog             0
quiet               0
sortcase            true
sortlocale          en_US.utf8
sortupper           true
trace               0
validate_control    0
validate_structure  0
wraplines           0
\end{verbatim}

\noindent You can see here that options with multiple key/value pairs of
their own like\linebreak[4] \verb+--collate_options|-c+ can be specified in
Apache config format. Please see the documentation
for the \verb+Config::General+ Perl
module\footnote{\url{http://search.cpan.org/search?query=Config::General&mode=all}}
if you really need details. In practise, if you use a config file at all
for \verb+biber+, it will contain very little as you will usually set all
options by setting options in \verb+biblatex+ which will pass them to
\verb+biber+ via the \verb+.bcf+ file.

The \verb+--collate_options|-c+ option takes a number of key/value pairs as
value. See section \ref{coll} for details.

\subsubsection{The nosort option}

The value of the \verb+nosort+ option can only be set in the config file
and not on the command line. This is because the values are Perl regular
expressions and would need special quoting to set on the command line. This
can get a bit tricky on some OSes (like Windows) so it's safer to set them
in the config file. In any case, it's unlikely you would want to set them
for particular \verb+biber+ runs; they would more likely be set as your
personal default and thus they would naturally be set in the config file
anyway. \verb+nosort+ allows you to ignore parts of a field for sorting.
This is done using \verb+perl+ regular expressions which specify what to
ignore in a field. You can specify as many patterns as you like for a
specific field. Also available are some field type aliases so you can, for
example, specify patterns for all name fields or all title fields. These
field types all begin with the string «\verb+type_+», see Table
\ref{tab:nst}.

\begin{table}
\begin{center}
\small
\begin{tabular}{lllll}
\toprule
Alias & Fields\\
\midrule
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}
\end{center}
\caption{nosort option field type aliases}
\label{tab:nst}
\end{table}

For example, this option can be used to ignore diacritic marks and prefices
in names which should not be considered when sorting. Given (the default):

\begin{verbatim}
<nosort>
  type_names      \A\p{L}{2}\p{Pd}
  type_names      [\x{2bf}\x{2018}]
</nosort>
\end{verbatim}

and the \verb+.bib+ entry:

\begin{verbatim}
author	   = {{al-Hasan}, ʿAlī},
\end{verbatim}

\noindent the prefix «al-» and the diacritic «ʿ» will not be considered
when sorting. See the \verb+perl+ regular expression manual page for
details of the regular expression syntax\footnote{\url{http://perldoc.perl.org/perlre.html}}.

If a \verb+nosort+ option is found for a specific field, it will override
any option for a type which also covers that field.

Here is another example. Suppose you wanted to ignore «The» at the
beginning of a \verb+TITLE+ field when sorting, you could add this to your
\verb+biber.conf+:

\begin{verbatim}
<nosort>
  title      \AThe\s+
</nosort>
\end{verbatim}

\noindent If you wanted to do this for all title fields listed in Table
\ref{tab:nst}, then you would do this:

\begin{verbatim}
<nosort>
  type_title      \AThe\s+
</nosort>
\end{verbatim}

\noindent \textbf{Note:} \verb+nosort+ can be specified for most fields but
not for things like dates and special fields as that wouldn't make much sense.

\subsection{Input/Output File Locations}

\subsubsection{Control file}\label{loc:cf}

The control file is normally passed as the only argument to biber. It is
searched for in the following locations, in decreasing order of
priority:\\[2ex]

\noindent Absolute filename $\rightarrow$\\
\hspace*{1em}In the \verb+--output_directory+, if specified$\rightarrow$\\
\hspace*{2em}Relative to current directory$\rightarrow$\\
\hspace*{3em}Using \verb+kpsewhich+, if available

\subsubsection{Data sources}

Bibliography data sources of type «file» are searched for in the following
locations, in decreasing order of priority:\\[2ex]

\noindent Absolute filename $\rightarrow$\\
\hspace*{1em}In the \verb+--output_directory+, if specified$\rightarrow$\\
\hspace*{2em}Relative to current directory$\rightarrow$\\
\hspace*{3em}In the same directory as the control file$\rightarrow$\\
\hspace*{4em}Using \verb+kpsewhich+ for supported formats, if available\\[2ex]

\noindent Users do not specify explicitly the bibliography database
files; they are passed in the \verb+.bcf+ control file, which is
constructed from the \verb+biblatex+ \verb+\addbibresource{}+ macros.

\subsection{Logfile}

By default, the logfile for biber will be named \verb+\jobname.blg+,
so, if you run

\begin{verbatim}
  biber <options> test.bcf
\end{verbatim}

\noindent then the logfile will be called «\verb+test.blg+». Like the
\verb+.bbl+ output file, it will be created in the
\verb+--output_directory|-c+, if this option is defined. You can
override the logfile name by using the \verb+--logfile+ option:

\begin{verbatim}
  biber --logfile=lfname test.bcf
\end{verbatim}

\noindent results in a logfile called «\verb+lfname.blg+».\\

\noindent \textbf{Warning}: be careful if you are expecting \verb+biber+ to
write to directories which you don't have appropriate permissions to. This
is more commonly an issue on non-Windows OSes. For example, if you rely on
\verb+kpsewhich+ to find your database files which are in system TeX
directories, you may well not have write permission there so \verb+biber+
will not be able to write the \verb+.bbl+. Use the \verb+--outfile|-O+
option to specify the location to write the \verb+.bbl+ to in such cases.

\subsection{Collation and Localisation}\label{coll}

\verb+biber+ takes care of collating the bibliography for
\verb+biblatex+. It writes entries to the \verb+.bbl+ file sorted by a
completely customisable set of rules which are passed in the
\verb+.bcf+ file by \verb+biblatex+. \verb+biber+ has two ways of performing
collation:\\[2ex]

\biberex{--collate|-C}
  \noindent The default. This option makes \verb+biber+ use the
  \verb+Unicode::Collate+ module for collation which implements the full UCA (Unicode
  Collation Algorithm). It also has CLDR (Common Locale Data
  Repository) tailoring to deal with cases which are not covered by the
  UCA. It is a little slower than \verb+--fastsort|-f+ but the
  advantages are such that it's rarely worth using \verb+--fastsort|-f+\\[1ex]

\biberex{--fastsort|-f}
  \noindent Biber will sort using
  the OS locale collation tables. The drawback for this method is that special
  collation tailoring for various languages are not implemented in the
  collation tables for many OSes. For example, few OSes correctly sort 'å'
  before 'ä' in the Swedish (\verb+sv_SE+) locale. If you are using a
  common latin alphabet, then this is probably not a problem for you.\\[2ex]

\noindent The locale used for collation is determined by the following resource
chain which is given in decreasing precedence order:\\[2ex]

\noindent\verb+--collate_options|-c+ (e.g. \verb+-c 'locale => "de_DE"'+) $\rightarrow$\\
\hspace*{1em}\verb+--sortlocale|-l+ $\rightarrow$\\
\hspace*{2em}\verb+LC_COLLATE+ environment variable $\rightarrow$\\
\hspace*{3em}\verb+LANG+ environment variable $\rightarrow$\\
\hspace*{4em}\verb+LC_ALL+ environment variable\\[2ex]

\noindent With the default \verb+--collate|-C+ option, the locale will
be used to look for a collation tailoring for that locale. It will generate an
informational warning if it finds none. This is not a problem as the vast
majority of collation cases are covered by the standard UCA and many
locales neither have nor need any special collation tailoring.

With the \verb+--fastsort|-f+ option, the locale will be
used to locate an OS locale definition to use for the collation. This
may or may not be correctly tailored, depending on the locale and the OS.\\[1ex]

\noindent Collation is by default case sensitive. You can turn this
off using the \verb+biber+ option \verb+--sortcase=false+ or from
\verb+biblatex+ using its option \verb+sortcase=false+.\\[1ex]

\noindent\verb+--collate|-C+ by default collates uppercase before
lower. You can reverse this using the \verb+biber+ option \verb+--sortupper=false+
or from \verb+biblatex+ by using its option \verb+sortupper=false+. Be
aware though that some locales rightly enforce a particular setting for
this (for example, Danish). You will be able to override it but
\verb+biber+ will warn you if you do. \verb+sortupper+ has no effect when
using \verb+--fastsort|-f+--you are at the mercy of what your OS
locale does.\\[1ex]

There are in fact many options to \verb+Unicode::Collate+
which can tailor the collation in various ways in
addition to the locale tailoring which is automatically performed.
Users should see the the documentation to the module for the various
options, most of which the vast majority of users will never
need\footnote{For details on the various options, see
  \url{http://search.cpan.org/search?query=Unicode\%3A\%3ACollate&mode=all}}.
Options are passed using the \verb+--collate_options|-c+ option as a
single quoted string, each option separated by comma, each key and
value separated by «\verb+=>+». See examples.

\subsubsection{Examples}

\biberex{biber}

\noindent Call biber using all settings from the \verb+.bcf+ generated from the
LaTeX run. Case sensitive UCA sorting is performed taking the locale
for tailoring from the environment if no \verb+sortlocale+ is defined in
the \verb+.bcf+

\biberex{biber --sortlocale=de_DE}

\noindent Override any locale setting in the \verb+.bcf+ or
the environment.

\biberex{biber --fastsort}

\noindent Use slightly quicker internal sorting routine. This uses the OS locale
files which may or may not be accurate.

\biberex{biber --sortcase=false}

\noindent Case insensitive sorting.

\biberex{biber --sortupper=false --collate_options="backwards => 2"}

\noindent Collate lowercase before upper and collate French accents in
reverse order at UCA level 2.

\subsection{Encoding of files}

\verb+biber+ takes care of reencoding the \verb+.bib+ data as
necessary. In normal use, \verb+biblatex+ passes its
\verb+bibencoding+ option value to \verb+biber+ via the \verb+.bcf+
file. It also passes the value of its \verb+texencoding+ option (which
maps to \verb+biber+'s \verb+bblencoding|-E+ option) the default value
of which depends on which TeX engine and encoding packages you are
using (see \verb+biblatex+ manual for details).

\noindent \verb+biber+ performs the following tasks:

\begin{enumerate}
\item Decodes the \verb+.bib+ into UTF-8 if it is not UTF-8 already
\item Decodes LaTeX character macros into UTF-8 if \verb+--bblencoding|-E+
  is UTF-8
\item Encodes the output so that the \verb+.bbl+ is in
  the encoding that \verb+--bblencoding|-E+ specifies
\item Warns if it is asked to output to the \verb+.bbl+ any UTF-8
  decoded LaTeX character macros which are not in the
  \verb+--bblencoding|-E+ encoding. Replaces with a suitable LaTeX macro
\end{enumerate}

\noindent Normally, you do not need to set the encoding options on the
\verb+biber+ command line as they are passed in the \verb+.bcf+ via
the information in your \verb+biblatex+ environment. However, you can
override the \verb+.bcf+ settings with the command line or config
file. The resource chain for encoding settings is, in decreasing order
of preference:\\[2ex]

\noindent\verb+--bibencoding|-e+ and \verb+--bblencoding|-E+ $\rightarrow$\\
\hspace*{1em}\verb+biber+ config file $\rightarrow$\\
\hspace*{2em}\verb+.bcf+ control file

\subsubsection{LaTeX macro decoding}

\noindent As mentioned above, \verb+biber+ sometimes converts LaTeX
character macros into UTF-8. In fact there are two situations in which
this occurs.

\begin{enumerate}
\item When \verb+--bblencoding|-E+ is UTF-8
\item Always for internal sorting purposes
\end{enumerate}

\noindent This decoding is very useful but take note of the following
two scenarios, which relate to each of the two situations in which
LaTeX macro decoding occurs:

\minisec{Decoding when output is UTF-8}
If you are using PDFLaTeX and \verb+\usepackage[utf8]{inputenc}+, it
is possible that the UTF-8 characters resulting from \verb+biber+'s
internal LaTeX character macro decoding break \verb+inputenc+. This is
because \verb+inputenc+ does not implement all of UTF-8, only a
commonly used subset.

An example--if you had \verb+\DJ+ in your \verb+.bib+, \verb+biber+
decodes this correctly to «Đ» and this breaks \verb+inputenc+ because
it doesn't understand that UTF-8 character. The real solution here is
to switch to a TeX engine with full UTF-8 support like XeTeX or LuaTeX
as these don't use or need \verb+inputenc+. However, you can also try
the \verb+--bblsafechars+ option which will try to convert any UTF-8
chars into LaTeX macros on output. The \verb+biblatex+ option
«\verb+texencoding=ascii+» (which corresponds to the \verb+biber+
option «\verb+--bblencoding|-E+») will automatically set
\verb+--bblsafechars+.

See also the \verb+biber --help+ output for the
\verb+--bblsafecharsset+ option which can customise the set of
conversion characters to use.

\minisec{Decoding for internal sorting}

If your \verb+bblencoding+ is not UTF-8, and you are using some UTF-8
equivalent LaTeX character macros in your \verb+.bib+, then some
\verb+.bbl+ fields (currently only \verb+\sortinit{}+) might end up
with invalid characters in them, according to the \verb+.bbl+
encoding. This is because some fields must be generated from the final
sorting data which is only available after the LaTeX character macro
decoding step.

For example, suppose you are using PDFLaTeX with\\
\verb+\usepackage[latin1]{inputenc}+ and the following \verb+bibtex+
data source entry:

\begin{verbatim}
@BOOK{citekey1,
  AUTHOR = {{\v S}imple, Simon},
}
\end{verbatim}

\noindent With normal LaTeX character macro decoding, the
\verb+{\v S}+ is decoded into «Š» and so with name-first sorting,
\verb+\sortinit{}+ would be «Š». This is an invalid character in
latin1 encoding and so the \verb+.bbl+ would be broken. In such cases
when \verb+\sortinit{}+ is a char not valid in the \verb+bblencoding+,
\verb+biber+ tries to replace the character with a suitable LaTeX
macro. The solution is really to use UTF-8 \verb+.bbl+ encoding whenever
possible. In extreme cases where even with UTF-8 encoding,
the char is not recognised by LaTeX due to an incomplete UTF-8
implementation (as with \verb+inputenc+), this might also mean
switching TeX engines to one that supports full UTF-8.

\subsubsection{Examples}

\biberex{biber}

\noindent Set \verb+bibencoding+ and \verb+bblencoding+ from the
config file or \verb+.bcf+.

\biberex{biber --bblencoding=latin2}

\noindent Encode the \verb+.bbl+ as latin2, overriding the
\verb+.bcf+.

\biberex{biber --bblsafechars}

\noindent Set \verb+bibencoding+ and \verb+bblencoding+ from the
config file or \verb+.bcf+. Force encoding of UTF-8 chars to LaTeX
macros using default conversion set.

\biberex{biber --bblencoding=ascii}

\noindent Encode the \verb+.bbl+ as ascii, overriding the
\verb+.bcf+. Automatically sets \verb+--bblsafechars+ to force UTF-8
to LaTeX macro conversion.

\biberex{biber --bblencoding=ascii --bblsafecharsset=full}

\noindent Encode the \verb+.bbl+ as ascii, overriding the
\verb+.bcf+. Automatically sets \verb+--bblsafechars+ to force UTF-8
to LaTeX macro conversion using the full set of conversions

\biberex{biber --decodecharsset=full}

\noindent Set \verb+bibencoding+ and \verb+bblencoding+ from the
config file or \verb+.bcf+. Use the full LaTeX macro to UTF-8
conversion set because you have some more obscure character macros in
your \verb+.bib+ which you want to sort correctly

\biberex{biber -u}

\noindent Shortcut alias for \verb+biber --bibencoding=UTF-8+

\biberex{biber -U}

\noindent Shortcut alias for \verb+biber --bblencoding=UTF-8+

\subsection{Limitations}

Currently, users are restricted to a one-one mapping from datasource
entry types/fields to the \verb+biblatex+ supported entry type/fields.
This is mitigated a little by the type/field aliases which
\verb+biblatex+ supports. In the future, users will be able to
customise the data source driver config in order to define their own
entry type/field aliases so that there is more flexibility in mapping
data source entry type/fields to internal \verb+biblatex+ types/fields.

Currently it is not possible to automatically expand name lists to their
minimally unique truncation which is required by some styles (APA for
example). This is quite a hard problem, a solution to which is implemented
in an experimental \verb+biber+ branch but which also needs \verb+biblatex+
support, envisaged for version 2.x. It requires an enhanced \verb+.bbl+
format, amongst other things.

\subsection{Editor Integration}

Here is some information on how to integrate \verb+biber+ into some of the
more common editors

\subsubsection{Emacs}

Emacs has the very powerful AUcTeX mode for editing TeX and running
compilations. BibTeX is already integrated into AUCTeX and it is quite
simple to add support for \verb+biber+. Use the Emacs Customise interface to
modify the \verb+TeX-command-list+ variable and add a \verb+Biber+ command.

\begin{verbatim}
M-x customise-variable
TeX-command-list
\end{verbatim}

\noindent and then \verb+Ins+ somewhere a new command that looks like
Figure \ref{fig:biber-auctex}.

\begin{figure}[!htbp]
  \centering
  \includegraphics[width=4in,keepaspectratio=true]{biber-auctex.png}
  \caption{Screenshot of AUCTeX command setup for Biber}
  \label{fig:biber-auctex}
\end{figure}

\noindent Alternatively, you can add it directly in lisp to your \verb+.emacs+ like
this:

\begin{verbatim}
(add-to-list 'TeX-command-list
  (quote
    ("Biber" "biber %s" TeX-run-Biber nil t :help "Run Biber")))
\end{verbatim}

\noindent However you add the command to \verb+TeX-command-list+, customise the
actual \verb+Biber+ command parameters as you want them, using «\verb+%s+» as
the LaTeX file name place holder. Then define the following two functions
in your \verb+.emacs+.

\small
\begin{verbatim}
(eval-after-load "tex"
  (quote (defun TeX-run-Biber (name command file)
    "Create a process for NAME using COMMAND to format FILE with Biber." 
    (let ((process (TeX-run-command name command file)))
      (setq TeX-sentinel-function 'TeX-Biber-sentinel)
      (if TeX-process-asynchronous
          process
        (TeX-synchronous-sentinel name file process))))
         )
  )

(eval-after-load "tex"
  (quote (defun TeX-Biber-sentinel (process name)
    "Cleanup TeX output buffer after running Biber."
    (goto-char (point-max))
    (cond
     ;; Check whether Biber reports any warnings or errors.
     ((re-search-backward (concat
                           "^(There \\(?:was\\|were\\) \\([0-9]+\\) "
                           "\\(warnings?\\|error messages?\\))") nil t)
      ;; Tell the user their number so that she sees whether the
      ;; situation is getting better or worse.
      (message (concat "Biber finished with %s %s. "
                       "Type `%s' to display output.")
               (match-string 1) (match-string 2)
               (substitute-command-keys
                "\\<TeX-mode-map>\\[TeX-recenter-output-buffer]")))
     (t
      (message (concat "Biber finished successfully. "
                       "Run LaTeX again to get citations right."))))
    (setq TeX-command-next TeX-command-default))
         )
  )
\end{verbatim}
\normalsize

\noindent You'll then see a \verb+Biber+ option in your AUCTeX command menu or
you can just \verb+C-c C-c+ and type \verb+Biber+.

\subsubsection{TeXworks}

It's very easy to add \verb+biber+ support to TeXworks. In the Preferences,
select the Typesetting tab and then add a new Processing Tool as in Figure
\ref{fig:biber-texworks}.

\begin{figure}[!htbp]
  \centering
  \includegraphics[width=4in,keepaspectratio=true]{biber-texworks.png}
  \caption{Screenshot of TeXworks processing tool setup for Biber}
  \label{fig:biber-texworks}
\end{figure}

\subsection{BibTeX macros}

\verb+BibTeX+ defines automatically macros for month abbreviations
like «\verb+jan+», «\verb+feb+» etc. \verb+biber+ also does this,
defining them as numbers since that is what \verb+biblatex+ wants. In
case you are also defining these yourself (although if you are only
using \verb+biblatex+, there isn't much point), you will get macro
redefinition warnings from the \verb+btparse+ library. You can turn
off \verb+biber+'s macro definitions to avoid this by using the option
\verb+--nostdmacros+.

\section{Binaries}

The binary distributions of biber are made using the Perl \verb+PAR::Packer+
module. They can be used as a normal binary but have some behaviour which
is worth noting:

\begin{itemize}
\item Don't be worried by the size of the binaries. \verb+PAR::Packer+ essentially
  constructs a self-extracting archive which unpacks the needed files first
  and so the binaries look larger than what actually runs in memory.
\item On the first run of a new version (that is, with a specific hash),
  they actually unpack themselves to a temporary location which varies by
  operating system. This unpacking can take a little while and only happens
  on the first run of a new version. \textbf{Please don't kill the process
    if it seems to take some time to do anything on the first run of a new
    binary}. If you do, it will not unpack everything and it will almost
  certainly break \verb+biber+. You will then have to delete your binary
  cache (see section \ref{bc} below) and re-run the \verb+biber+ executable
  again for the first time to allow it to unpack properly.
\end{itemize}

\subsection{Binary Caches}\label{bc}

\verb+PAR::Packer+ works by unpacking the required files to a cache
location. It only does this on the first run of a binary 
by computing a hash of the binary and comparing it with
the cache directory name which contains the hash. So, if you run
several versions of a binary, you will end up with several cached
trees which are never used. This is particularly true if you are regularly
testing new versions of the \verb+biber+ binary. It is a good idea to
delete the caches for older binaries as they are not needed and can take up
a fair bit of space. The caches are located in a temporary location which
varies from OS to OS. The cache name is:\\[1ex]

\noindent\verb+par-<username>/cache-<hash>+ (Linux/Unix/OSX)\\
\verb+par-<username>\cache-<hash>+ (Windows)\\[1ex]

\noindent The temp location is not always obvious but these are sensible
places to look (where \verb+*+ can vary depending on username:

\begin{itemize}
\item \verb+/var/folders/*/*/-Tmp-/+ (OSX, local GUI login shell)
\item \verb+/var/tmp/+ (OSX, remote ssh login shell)
\item \verb+/tmp/+ (Linux)
\item \verb+C:\Documents and Settings\<username>\Local Settings\Temp+ (Windows)
\item \verb+C:\Windows\Temp+ (Windows)
\end{itemize}

\noindent To clean up, you can just remove the whole \verb+par-<username>+
directory/folder and then run the current binary again.

\subsection{Binary Architectures}

Binaries are available for the following architectures:

\begin{itemize}
\item \verb+linux_x86_32+ --- Linux x86 32-bit (built on Ubuntu 9.04)
\item \verb+linux_x86_64+ --- Linux x86 64-bit (built on Ubuntu 9.04)
\item \verb+MSWin+ --- Windows. Should work on 32 or 64 bit (built on XP)
\item \verb+darwin_x86_64+ --- OSX Intel 64-bit (built on OSX 10.6)
\end{itemize}

\subsection{Installing}

These instructions only apply to manually downloaded binaries. If
\verb+biber+ came with your TeX distribution just use it as normal.

Download the binary appropriate to you
OS/arch\footnote{\url{https://sourceforge.net/projects/biblatex-biber}}. Below
I assume it's on your desktop.

You have to move the binary to somewhere in you command-line or TeX utility
path so that it can be found. If you know how to do this, just ignore the
rest of this section which contains some instructions for users who are
not sure about this.

\subsubsection{OSX}

If you are using the TexLive MacTeX distribution:

\begin{verbatim}
sudo mv ~/Desktop/biber /usr/texbin/
sudo chmod +x /usr/texbin/biber
\end{verbatim}

\noindent If you are using the macports TexLive distribution:

\begin{verbatim}
sudo mv ~/Desktop/biber /opt/local/bin/
sudo chmod +x /opt/local/bin/biber
\end{verbatim}

\noindent The «\verb+sudo+» commands will prompt you for your password.

\subsubsection{Windows}

The easiest way is to just move the executable into your \verb+C:\Windows+ directory since
that is always in your path. A more elegant is to put it somewhere in
your TeX distribution that is already in your path. For example if you
are using MiKTeX:

\begin{verbatim}
C:\Program Files\MiKTeX 2.8\miktex\bin\
\end{verbatim}

\subsubsection{Unix/Linux}

\begin{verbatim}
sudo mv ~/Desktop/biber /usr/local/bin/biber
sudo chmod +x /usr/local/bin/biber
\end{verbatim}

\noindent Make sure \verb+/usr/local/bin+ is in your PATH. Search Google for «set PATH
linux» if unsure about this. There are many pages about this, for example:
\url{http://www.cyberciti.biz/faq/unix-linux-adding-path/}


\subsection{Building}

Instructions for those who want/need to build an executable from the
Perl version. For this, you will need to have a recent Perl,
preferably 5.12 at least with the following modules:

\begin{itemize}
\item \verb+PAR+
\item \verb+PAR::Packer+
\item All \verb+biber+ pre-requisites
\end{itemize}

\noindent You should have the latest CPAN versions of all required modules
as \verb+biber+ is very specific in some cases about module versions and
depends on recent fixes in many cases. You can see if you have the
\verb+biber+ Perl dependencies by the usual

\begin{verbatim}
perl ./Build.PL
\end{verbatim}

\noindent invocation in the biber Perl distribution tree
directory. Normally, the build procedure for the binaries is as
follows\footnote{On UNIXequse systems, you may need to specify a full
  path to the scripts e.g. \texttt{./Build}}:

\begin{itemize}
\item Get the biber source tree from SF and put it on the architecture
  you are building for
\item cd to the root of the source tree
\item \verb+perl Build.PL+ (this will check your module
  dependencies)
\item \verb+Build test+
\item \verb+Build install+ (may need to run this as sudo on
  UNIXesque systems)
\item \verb+cd dist/<arch>+
\item \verb+build.sh+ (\verb+build.bat+ on Windows)
\end{itemize}

\noindent This leaves a binary called «\verb+biber-<arch>+» (also with
a «\verb+.exe+» extension on Windows) in your current directory.
The tricky part is constructing the information for the build
script. There are two things that need to be configured, both of
which are required by the \verb+PAR::Packer+ module:

\begin{enumerate}
\item A list of modules/libraries to include in the binary which are not
  automatically detected by the \verb+PAR::Packer+ dependency
  scanner
\item A list of extra files to include in the binary which are not
  automatically detected by the \verb+PAR::Packer+ dependency
  scanner
\end{enumerate}

\noindent To build \verb+biber+ for a new architecture you need to
define these two things as part of constructing new build scripts:

\begin{itemize}
\item Make a new subfolder in the \verb+dist+ directory named after the
  architecture you are building for. This name is arbitrary but should
  be fairly obvious like «\verb+solaris-sparc-64+», for example.
\item Copy the \verb+biber.files+ file from an existing build
  architecture into this directory.
\item For all of the files with absolute pathnames in there (that is,
  ones we are not pulling from the \verb+biber+ tree itself), locate these
  files in your Perl installation tree and put the correct path in the
  file.
\item Copy the build script from a vaguely similar architecture
  (i.e. Windows/non-Windows \ldots) to your new architecture
  directory. 
\item Change the \verb+--link+ options to point to where the required
  libraries reside on your system.
\item Change the \verb+--output+ option to name the resulting binary
  for your architecture.
\item Run the build script
\end{itemize}

\noindent The \verb+--link+ options can be a little tricky
sometimes. It is usually best to build without them once and then run
\verb+ldd+ (or Windows equivalent) on the binary to see which
version/location of a library you should link to. You can also try
just running the binary and it should complain about missing libraries
and where it expected to find them. Put this path into the
\verb+--link+ option. The \verb+--module+ options are the same for all
architectures and do not need to be modified.
On architectures which have or can have case-insensitive file systems,
you should use the build script from either Windows or OSX as a reference
as these include a step to copy the main \verb+biber+ script to a new name
before packing the binary. This is required as otherwise a spurious
error is reported to the user on first run of the binary due to a name
collision when it unpacks itself.

\end{document}