summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/bibtex/biber/doc
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/bibtex/biber/doc')
-rw-r--r--Master/texmf-dist/source/bibtex/biber/doc/biber-auctex.pngbin11009 -> 0 bytes
-rw-r--r--Master/texmf-dist/source/bibtex/biber/doc/biber-texworks.pngbin26963 -> 0 bytes
-rw-r--r--Master/texmf-dist/source/bibtex/biber/doc/biber.tex988
3 files changed, 0 insertions, 988 deletions
diff --git a/Master/texmf-dist/source/bibtex/biber/doc/biber-auctex.png b/Master/texmf-dist/source/bibtex/biber/doc/biber-auctex.png
deleted file mode 100644
index c172c5cb2ec..00000000000
--- a/Master/texmf-dist/source/bibtex/biber/doc/biber-auctex.png
+++ /dev/null
Binary files differ
diff --git a/Master/texmf-dist/source/bibtex/biber/doc/biber-texworks.png b/Master/texmf-dist/source/bibtex/biber/doc/biber-texworks.png
deleted file mode 100644
index 35ad65391ff..00000000000
--- a/Master/texmf-dist/source/bibtex/biber/doc/biber-texworks.png
+++ /dev/null
Binary files differ
diff --git a/Master/texmf-dist/source/bibtex/biber/doc/biber.tex b/Master/texmf-dist/source/bibtex/biber/doc/biber.tex
deleted file mode 100644
index 1130e606879..00000000000
--- a/Master/texmf-dist/source/bibtex/biber/doc/biber.tex
+++ /dev/null
@@ -1,988 +0,0 @@
-\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}