diff options
Diffstat (limited to 'Master/texmf-dist/source/bibtex/biber/doc/biber.tex')
-rw-r--r-- | Master/texmf-dist/source/bibtex/biber/doc/biber.tex | 988 |
1 files changed, 0 insertions, 988 deletions
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} |