path: root/Master/texmf-dist/source/bibtex/biber/doc/biber.tex

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