summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/bibtex/biber/doc/biber.tex
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2011-03-06 22:31:53 +0000
committerKarl Berry <karl@freefriends.org>2011-03-06 22:31:53 +0000
commit0e6e50ca2549504070b29679d6159236bdf1b308 (patch)
tree0171343229c3531b47eefd984597c35b86922078 /Master/texmf-dist/source/bibtex/biber/doc/biber.tex
parent876cc70b39dad10fa8b3e5d2d600e0bad3c48f8d (diff)
adding biber, including binaries in both Master/bin and Build
git-svn-id: svn://tug.org/texlive/trunk@21617 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/bibtex/biber/doc/biber.tex')
-rw-r--r--Master/texmf-dist/source/bibtex/biber/doc/biber.tex988
1 files changed, 988 insertions, 0 deletions
diff --git a/Master/texmf-dist/source/bibtex/biber/doc/biber.tex b/Master/texmf-dist/source/bibtex/biber/doc/biber.tex
new file mode 100644
index 00000000000..1130e606879
--- /dev/null
+++ b/Master/texmf-dist/source/bibtex/biber/doc/biber.tex
@@ -0,0 +1,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}