summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/biblatex/biblatex.tex
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2010-10-09 23:32:31 +0000
committerKarl Berry <karl@freefriends.org>2010-10-09 23:32:31 +0000
commit2b1aece05c5cfa5fb2237f33be13352b8152c50d (patch)
treee6fa6a1b23534f63f5f03213f5378c2eb43a6966 /Master/texmf-dist/doc/latex/biblatex/biblatex.tex
parentad2a0c99a6985997ce7dadc86f280f1f54817c0a (diff)
biblatex 0.9e (9oct10)
git-svn-id: svn://tug.org/texlive/trunk@20029 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex/biblatex/biblatex.tex')
-rw-r--r--Master/texmf-dist/doc/latex/biblatex/biblatex.tex162
1 files changed, 136 insertions, 26 deletions
diff --git a/Master/texmf-dist/doc/latex/biblatex/biblatex.tex b/Master/texmf-dist/doc/latex/biblatex/biblatex.tex
index 008aa423da0..bdc2dad4fe6 100644
--- a/Master/texmf-dist/doc/latex/biblatex/biblatex.tex
+++ b/Master/texmf-dist/doc/latex/biblatex/biblatex.tex
@@ -1,5 +1,5 @@
-% $Id: biblatex.tex,v 0.9d 2010/09/03 20:11:58 lehman beta $
-\documentclass{ltxdockit}[2010/02/12]
+% $Id: biblatex.tex,v 0.9e 2010/10/09 16:39:36 lehman beta $
+\documentclass{ltxdockit}[2010/09/26]
\usepackage{btxdockit}
\usepackage[latin9]{inputenc}
\usepackage[american]{babel}
@@ -11,7 +11,7 @@
\MakeAutoQuote*{<}{>}
\MakeShortVerb{\|}
-\rcsid{$Id: biblatex.tex,v 0.9d 2010/09/03 20:11:58 lehman beta $}
+\rcsid{$Id: biblatex.tex,v 0.9e 2010/10/09 16:39:36 lehman beta $}
\newcommand*{\BiblatexHome}{http://sourceforge.net/projects/biblatex/}
\newcommand*{\BiblatexOnCTAN}{http://www.ctan.org/tex-archive/macros/latex/exptl/biblatex/}
@@ -229,7 +229,7 @@ The \sty{natbib} package supports numeric and author"=year citation schemes, inc
The \sty{splitbib} package provides support for bibliographies subdivided by topic. See \sty{bibtopic}.
\item[ucs]
-The \sty{ucs} package provides support for \acr{utf-8} encoded input. Either use \sty{inputenc}'s standard \file{utf8} module or a Unicode enabled engine such as \xelatex instead.
+The \sty{ucs} package provides support for \acr{UTF-8} encoded input. Either use \sty{inputenc}'s standard \file{utf8} module or a Unicode enabled engine such as \xelatex instead.
\end{marglist}
@@ -1416,9 +1416,10 @@ This section provides some additional hints concerning the \bibtex interface of
\bibtex's \bibfield{crossref} field provides a handy cross-referencing mechanism which inherits data missing in a child entry from the corresponding parent entry indicated by the value of the \bibfield{crossref} field. Unfortunately, this mechanism is static and uses a one-on-one field mapping. This reduces its usefulness significantly because it will cause problems in quite a few cases. For example, the \bibfield{subtitle} of a cross-referenced \bibtype{collection} entry may end up in the \bibfield{subtitle} field, rather than in the \bibfield{booksubtitle} field, of the corresponding \bibtype{incollection} child entry. It is possible to work around this problem by including an empty \bibfield{subtitle} in the child entry. This package also provides an alternative cross-referencing mechanism. The \bibfield{xref} field differs from \bibfield{crossref} in that the child entry will not inherit \emph{any} data from the parent entry specified in the \bibfield{xref} field. This implies that child entries must include all bibliographic data. The \bibfield{xref} field is merely a pointer which may be used by bibliography styles which format child entries in a special way (see \secref{aut:cav:mif} for an example). If the parent entry is referenced by a certain number of child entries, \sty{biblatex} will automatically execute the equivalent of a \cmd{nocite} command to request it from \bibtex. The threshold is controlled by the \opt{mincrossrefs} package option from \secref{use:opt:pre}. Style authors should note that whether or not the \bibfield{xref} fields of the child entries are defined on the \sty{biblatex} level depends on the availability of the parent entry. If the parent entry is available, the \bibfield{xref} fields of the child entries will be defined. If not, their \bibfield{xref} fields will be undefined. Whether the parent entry is added to the bibliography implicitly because of the threshold or because it has been cited explicitly in the document does not matter.
-\subsubsection{\bibtex Capacity Issues}
+\subsubsection{Capacity Issues}
\label{bib:cav:btx}
+\paragraph{\bibtex}
A venerable tool originally developed in the 1980s, \bibtex uses static memory allocation, much to the dismay of users working with large bibliographical databases. With a large \file{bib} file which contains several hundred entries, \bibtex is very likely to run out of memory. The number of entries it can cope with depends on the number of fields defined by the \bibtex style (\file{bst}). Style files which define a considerable number of fields, such as \path{biblatex.bst}, are more likely to trigger such problems. Unfortunately, traditional \bibtex does not output a clear error message when it runs out of memory but exposes a rather cryptical kind of faulty behavior. The warning messages printed in this case look like this:
\begin{lstlisting}[style=plain]{}
@@ -1428,7 +1429,10 @@ Warning--I'm ignoring Jones1995's extra "volume" field
--line 423 of file huge.bib
\end{lstlisting}
%
-These warning messages could indeed indicate that the entry \texttt{Jones1995} is faulty because it includes two \bibfield{year} and two \bibfield{volume} fields. If that is not the case and the \file{bib} file is fairly large, this is most likely a capacity issue. What makes these warnings so confusing is that they are not tied to a specific entry. If you remove the allegedly faulty entry, a different one will trigger similar warnings. This is one reason why switching to \file{bibtex8}, the 8-bit implementation of \bibtex, is advisable. Alas, \file{bibtex8} is a venerable tool as well and will also run out of memory with its default capacity. Switching from traditional \bibtex to \file{bibtex8} is still an improvement because the capacity of the latter may be increased at run"=time via command"=line switches and it also prints unambiguous error messages, for example:
+These warning messages could indeed indicate that the entry \texttt{Jones1995} is faulty because it includes two \bibfield{year} and two \bibfield{volume} fields. If that is not the case and the \file{bib} file is fairly large, this is most likely a capacity issue. What makes these warnings so confusing is that they are not tied to a specific entry. If you remove the allegedly faulty entry, a different one will trigger similar warnings. This is one reason why switching to \file{bibtex8} or Biber is advisable.
+
+\paragraph{\file{bibtex8}}
+\file{bibtex8} is a venerable tool as well and will also run out of memory with its default capacity. Switching from traditional \bibtex to \file{bibtex8} is still an improvement because the capacity of the latter may be increased at run"=time via command"=line switches and it also prints unambiguous error messages, for example:
\begin{table}
\numtablesetup
@@ -1471,11 +1475,16 @@ bibtex8 --wolfgang --mcites 30000 --mentints 30000 --mentstrs 40000
auxfile
\end{lstlisting}
%
-When taking a closer look at \tabref{bib:cav:tab1}, you will notice that there are two parameters which can not be modified directly, |hash_prime| and |hash_size|. Increasing these values is only possible with the high"=level switches. That is why the above command includes the |--wolfgang| switch in addition to the low"=level switches. This situation is very unfortunate because the hash size effectively sets a cap on some other parameters. For example, |max_strings| can not be greater than |hash_size|. If you hit this cap, all you can do is recompile \file{bibtex8} with a larger capacity. Also note that the |wiz_fn_space| parameter is not related to the \file{bib} file but to the memory requirements of the \file{bst} file. \file{biblatex.bst} needs a value of about 6000. The value 10000 implicitly used by the |--wolfgang| switch is fine. Note that Biber, the next"=generation database backend of \sty{biblatex}, eliminates all of the above limitations.
+When taking a closer look at \tabref{bib:cav:tab1}, you will notice that there are two parameters which can not be modified directly, |hash_prime| and |hash_size|. Increasing these values is only possible with the high"=level switches. That is why the above command includes the |--wolfgang| switch in addition to the low"=level switches. This situation is very unfortunate because the hash size effectively sets a cap on some other parameters. For example, |max_strings| can not be greater than |hash_size|. If you hit this cap, all you can do is recompile \file{bibtex8} with a larger capacity. Also note that the |wiz_fn_space| parameter is not related to the \file{bib} file but to the memory requirements of the \file{bst} file. \file{biblatex.bst} needs a value of about 6000. The value 10000 implicitly used by the |--wolfgang| switch is fine.
+
+\paragraph{Biber}
+Biber eliminates all of the above limitations.
-\subsubsection{\bibtex Sorting and Encoding Issues}
+\subsubsection{Sorting and Encoding Issues}
\label{bib:cav:enc}
+\paragraph{\bibtex}
+\label{bib:cav:enc:btx}
Traditional \bibtex can only alphabetize Ascii characters correctly. If the bibliographic data includes non"=Ascii characters, they have to be given in Ascii notation. For example, instead of typing a letter like <ä> directly, you need to input it as |\"a|, using an accent command and the Ascii letter. This Ascii notation needs to be wrapped in a pair of curly braces. Traditional \bibtex will then ignore the accent and use the Ascii letter for sorting. Here are a few examples:
\begin{lstlisting}[style=bibtex,upquote]{}
@@ -1485,9 +1494,11 @@ translator = {Ferdi<<{\`e}>>re, Fr<<{\c{c}}>>ois},
title = {<<{\OE}>>uvres compl<<{\`e}>>tes},
\end{lstlisting}
%
-Apart from it being inconvenient, there are two major issues with this convention. One subtle problem is that the extra set of braces suppresses the kerning on both sides of all non"=Ascii letters. But first and foremost, simply ignoring all accents may not be the correct way to handle them. For example, in Danish, the letter <å> is the very last letter of the alphabet, so it should be alphabetized after <z>. \bibtex will sort it like an <a>. The <æ> ligature and the letter <ø> are also sorted after <z> in this language. There are similar cases in Norwegian. In Swedish, the letter <ö> is the very last letter of the alphabet and the letters <å> and <ä> are also alphabetized after <z>, rather than like an <a>. What's more, even the sorting of Ascii characters is done in a rather peculiar way by traditional \bibtex because the sorting algorithm uses Ascii codepage order (\texttt{0-9,A-Z,a-z}). This implies that the lowercase letter <a> would end up after the uppercase <Z>, which is not even acceptable in the language \bibtex was originally designed for. The traditional \file{bst} files work around this problem by converting all strings used for sorting to lowercase, \ie sorting is effectively case"=insensitive.
+Apart from it being inconvenient, there are two major issues with this convention. One subtle problem is that the extra set of braces suppresses the kerning on both sides of all non"=Ascii letters. But first and foremost, simply ignoring all accents may not be the correct way to handle them. For example, in Danish, the letter <å> is the very last letter of the alphabet, so it should be alphabetized after <z>. \bibtex will sort it like an <a>. The <æ> ligature and the letter <ø> are also sorted after <z> in this language. There are similar cases in Norwegian. In Swedish, the letter <ö> is the very last letter of the alphabet and the letters <å> and <ä> are also alphabetized after <z>, rather than like an <a>. What's more, even the sorting of Ascii characters is done in a rather peculiar way by traditional \bibtex because the sorting algorithm uses Ascii codepage order (\texttt{0-9,A-Z,a-z}). This implies that the lowercase letter <a> would end up after the uppercase <Z>, which is not even acceptable in the language \bibtex was originally designed for. The traditional \file{bst} files work around this problem by converting all strings used for sorting to lowercase, \ie sorting is effectively case"=insensitive. See also \secref{bib:cav:enc:enc}.
-These are the major reasons why switching to \file{bibtex8}, the 8-bit implementation of \bibtex, is advisable. \file{bibtex8} can sort in a case"=sensitive way and it can handle (single byte) non"=Ascii characters properly, provided that you supply it with a suitable \file{csf} file and give the |--csfile| switch on the command line. This also implies that it is possible to apply language specific sorting rules to the bibliography. The \sty{biblatex} package comes with \file{csf} files for some common Western European encodings. \bin{bibtex8} also ships with a few \file{csf} files. Note that \file{biblatex.bst} can not detect if it is running under traditional \bibtex or \file{bibtex8}, hence the \opt{bibtex8} package option. By default, sorting is case-insensitive since this is required for traditional \bibtex. If the \opt{bibtex8} package option is enabled, sorting is case-sensitive.
+\paragraph{\file{bibtex8}}
+\label{bib:cav:enc:bt8}
+Switching to \file{bibtex8} will help in such cases. \file{bibtex8} can sort in a case"=sensitive way and it can handle 8-bit characters properly, provided that you supply it with a suitable \file{csf} file and give the |--csfile| switch on the command line. This also implies that it is possible to apply language specific sorting rules to the bibliography. The \sty{biblatex} package comes with \file{csf} files for some common Western European encodings. \bin{bibtex8} also ships with a few \file{csf} files. Note that \file{biblatex.bst} can not detect if it is running under traditional \bibtex or \file{bibtex8}, hence the \opt{bibtex8} package option. By default, sorting is case-insensitive since this is required for traditional \bibtex. If the \opt{bibtex8} package option is enabled, sorting is case-sensitive.
Since \file{bibtex8} is backwards compatible with traditional \bibtex, it is possible to mix 8-bit input and Ascii notation. This is useful if the encoding used in the \file{bib} file does not cover all required characters. There are also a few marginal cases in which the Ascii notation scheme would yield better sorting results. A typical example is the ligature <½>. \file{bibtex8} will handle this ligature like a single character. Depending on the sorting scheme defined in the \file{csf} file, it could be treated like an <o> or alphabetized after the letter <o> but it can not be sorted as <oe>. The Ascii notation (|\oe|) is equivalent to <oe> during sorting:
@@ -1509,55 +1520,102 @@ author = {Ba<<ß>>mann, Paul},
sortname = {Ba<<sszz>>mann, Paul},
\end{lstlisting}
%
-Not only \bibtex, \tex needs to know about the encoding as well. When using non"=Ascii characters in a \file{bib} file, load the \sty{inputenc} package and specify the encoding as usual. The \sty{biblatex} package is also capable of handling conflicting encodings in \file{tex} and \file{bib} files, provided that you specify the encoding of the \file{bib} file with the \opt{bibencoding} package option. Here are a few typical cases along with the relevant lines from the document preamble:
+Not only \bibtex, \tex needs to know about the encoding as well. When using non"=Ascii characters in a \file{bib} file, load the \sty{inputenc} package and specify the encoding as usual. The \sty{biblatex} package is also capable of handling conflicting encodings in \file{tex} and \file{bib} files, provided that you specify the encoding of the \file{bib} file with the \opt{bibencoding} package option. See \secref{bib:cav:enc:enc} for details.
+
+\paragraph{Biber}
+Biber can handle Ascii notation, 8-bit encodings such as Latin\,1, and \acr{UTF-8}. It features true Unicode support and is capable of reencoding the \file{bib} data on the fly in a robust way. For sorting, Biber uses a Perl implementation of the Unicode Collation Algorithm (\acr{UCA}), as outlined in Unicode Technical Standard \#10.\fnurl{http://unicode.org/reports/tr10/} Collation tailoring based on the Unicode Common Locale Data Repository (\acr{CLDR}) is in the process of being added.\fnurl{http://cldr.unicode.org/} The bottom line is that Biber will deliver sorting results superior to both \bibtex and \file{bibtex8} in many cases. If you are interested in the technical details, section 1.8 of Unicode Technical Standard \#10 will provide you with a very concise summary of why the inadequateness of traditional \bibtex and even \bin{bibtex8} in a contemporary text processing environment is of a very general nature and not limited to the lack of \utf support.\fnurl{http://unicode.org/reports/tr10/#Common_Misperceptions}
+
+Implementing Unicode includes much more than handling \utf input. Unicode is a very complex standard covering more than its most well known part, the Unicode character encoding and transport encodings such as \utf. It also covers aspects such as string collation which are required for language-sensitive sorting. For example, by using the Unicode Collation Algorithm, Biber can handle the character <ß> mentioned as an example in \secref{bib:cav:enc:bt8} without any manual intervention. All you need to do to get localized sorting is specify the locale:
+
+\begin{lstlisting}[style=latex]{}
+\usepackage[backend=biber,sortlocale=de_DE]{biblatex}
+\end{lstlisting}
+%
+If the language of the document corresponds to the main locale of the operating system, \opt{sortlocale} is
+omissible as Biber will detect the locale settings of the environment automatically. Note that this will also work with 8-bit encodings such as Latin\,9, \ie you can take advantage of Unicode-based sorting even though you are not using \utf input. See \secref{bib:cav:enc:enc} on how to specify input and data encodings properly.
+
+\paragraph{Specifying Encodings}
+\label{bib:cav:enc:enc}
+When using a non-Ascii encoding in the \file{bib} file, it is important to understand what \sty{biblatex} can do for you and what may require manual intervention. The package takes care of the \latex side, \ie it ensures that the data imported from the \file{bbl} file is interpreted correctly, provided that the \opt{bibencoding} package option is set properly. Depending on the backend, the \bibtex side may demand attention, too. When using \bin{bibtex8}, you need to supply \bin{bibtex8} with a matching \file{csf} file as it needs to know about the encoding of the \file{bib} file to be able to alphabetize the entries correctly. Unfortunately, there is no way for \sty{biblatex} to pass this information to \bin{bibtex8} automatically. The only way is setting the |--csfile| switch on the command line when executing \bin{bibtex8}. When using Biber, this happends automatically and no further steps, apart from setting the \opt{bibencoding} option, are required.
+
+Here are a few typical usage scenarios along with the relevant lines from the document preamble:
\begin{itemize}
\setlength{\itemsep}{0pt}
-\item Ascii notation in both the \file{tex} and the \file{bib} file:
+\item Ascii notation in both the \file{tex} and the \file{bib} file (this will work with \bibtex, \file{bibtex8}, and Biber):
\begin{lstlisting}[style=latex]{}
\usepackage{biblatex}
\end{lstlisting}
-\item Latin\,1 encoding (\acr{ISO}-8859-1) in the \file{tex} file, Ascii notation in the \file{bib} file:
+\item Latin\,1 encoding (\acr{ISO}-8859-1) in the \file{tex} file, Ascii notation in the \file{bib} file (\bibtex, \file{bibtex8}, Biber):
\begin{lstlisting}[style=latex]{}
\usepackage[latin1]{inputenc}
\usepackage{biblatex}
\end{lstlisting}
-\item Latin\,9 encoding (\acr{ISO}-8859-15) in both the \file{tex} and the \file{bib} file:
+\item Latin\,9 encoding (\acr{ISO}-8859-15) in both the \file{tex} and the \file{bib} file (\file{bibtex8}, Biber):
\begin{lstlisting}[style=latex]{}
\usepackage[latin9]{inputenc}
-\usepackage[bibencoding=inputenc,backend=bibtex8]{biblatex}
+\usepackage[bibencoding=inputenc]{biblatex}
\end{lstlisting}
-\item \acr{utf-8} encoding in the \file{tex} file, Latin\,1 (\acr{ISO}-8859-1) in the \file{bib} file:
+\item \acr{UTF-8} encoding in the \file{tex} file, Latin\,1 (\acr{ISO}-8859-1) in the \file{bib} file (\file{bibtex8}, Biber):
\begin{lstlisting}[style=latex]{}
\usepackage[utf8]{inputenc}
-\usepackage[bibencoding=latin1,backend=bibtex8]{biblatex}
+\usepackage[bibencoding=latin1]{biblatex}
\end{lstlisting}
-\item Using \acr{utf-8} encoding in both the \file{tex} and the \file{bib} file is not possible with traditional \bibtex or \bin{bibtex8} since neither of them is capable of handling multi"=byte encodings such as \acr{utf-8}. In this case, you need to use a single"=byte encoding such as Latin 1 (see above) or resort to Ascii notation in the \file{bib} file:
+\item Same scenario with Xe\tex or Lua\tex in native \acr{UTF-8} mode:
+
+\begin{lstlisting}[style=latex]{}
+\usepackage[bibencoding=latin1]{biblatex}
+\end{lstlisting}
+
+\item Using \acr{UTF-8} encoding in both the \file{tex} and the \file{bib} file is not possible with traditional \bibtex or \bin{bibtex8} since neither of them is capable of handling \acr{UTF-8}. Unless you switch to Biber, you need to use an 8-bit encoding such as Latin\,1 (see above) or resort to Ascii notation in this case:
\begin{lstlisting}[style=latex]{}
\usepackage[utf8]{inputenc}
\usepackage{biblatex}
\end{lstlisting}
-\item When using Biber as the database backend, it is possible to have a transparent \acr{utf-8} workflow, \ie to use \acr{utf-8} encoding in both the \file{tex} and the \file{bib} file:
+\item Same scenario with Xe\tex or Lua\tex in native \acr{UTF-8} mode:
\begin{lstlisting}[style=latex]{}
-\usepackage[utf8]{inputenc}
-\usepackage[backend=biber]{biblatex}
+\usepackage{biblatex}
\end{lstlisting}
\end{itemize}
-When using a non"=Ascii encoding in the \file{bib} file, it is important to understand what \sty{biblatex} can do for you and what requires manual intervention. The package takes care of the \latex side, \ie it ensures that the bibliographic data is interpreted correctly as it is imported from the \file{bbl} file, provided that the \opt{bibencoding} package option is set properly and the \sty{inputenc} package is available. However, the \bibtex side demands attention, too. As mentioned above, you have to use \bin{bibtex8} and you need to supply it with a matching \file{csf} file. \bibtex needs to know about the encoding of the \file{bib} file to be able to alphabetize the entries correctly. Unfortunately, there is no way for \sty{biblatex} to pass this information to \bin{bibtex8} automatically. The only way is setting the |--csfile| switch on the command line when executing \bin{bibtex8}. When using Biber, see the Biber manual for instructions.
+Biber can handle Ascii notation, 8-bit encodings such as Latin\,1, and \acr{UTF-8}. It is also capable of reencoding the \file{bib} data on the fly (replacing the somewhat less robust macro-level reencoding routine of \sty{biblatex}). This will happen automatically if required, provided that you specify the encoding of the \file{bib} files properly. In addition to the scenarios discussed above, Biber can also handle the following cases:
+
+\begin{itemize}
+
+\item Transparent \acr{UTF-8} workflow, \ie \acr{UTF-8} encoding in both the \file{tex} and the \file{bib} file:
+
+\begin{lstlisting}[style=latex]{}
+\usepackage[utf8]{inputenc}
+\usepackage[bibencoding=inputenc]{biblatex}
+\end{lstlisting}
+
+\item Same scenario with Xe\tex or Lua\tex in native \acr{UTF-8} mode:
+
+\begin{lstlisting}[style=latex]{}
+\usepackage[bibencoding=inputenc]{biblatex}
+\end{lstlisting}
+
+\item It is even possible to combine an 8-bit-encoded \file{tex} file with \acr{UTF-8} encoding in the \file{bib} file, provided that all characters in the \file{bib} file are also available in the selected 8-bit encoding:
+
+\begin{lstlisting}[style=latex]{}
+\usepackage[latin1]{inputenc}
+\usepackage[bibencoding=utf8]{biblatex}
+\end{lstlisting}
+
+\end{itemize}
\subsubsection{Editors and Compiler Scripts}
\label{bib:cav:ide}
@@ -1631,6 +1689,15 @@ Please refer to \secref{use:srt} for an in"=depth explanation of the above sorti
Whether to sort the bibliography and the list of shorthands in a case"=sensitive way. Note that case"=sensitive sorting is only supported by the \bin{bibtex8} and Biber backends. Sorting is always case"=insensitive with legacy \bibtex. See the \opt{backend} option for details.
+\boolitem[true]{sortupper}
+
+This option is specific to Biber and corresponds to Biber's |--sortupper| command-line option. It has no effect with any other backend. If enabled, the bibliography is sorted in <uppercase before lowercase> order. Disabling this option means <lowercase before uppercase> order.
+
+\optitem{sortlocale}{\prm{locale}}
+
+This option is specific to Biber and corresponds to Biber's |--sortlocale| command-line option.
+It has no effect with any other backend. If set, it specifies the locale to be used for sorting. Note that, while \sty{biblatex} provides no default value for this option, Biber will inherit the locale settings from the environment if no locale has been specified explicitly.
+
\optitem[los]{sortlos}{\opt{bib}, \opt{los}}
The sorting order of the list of shorthands. The following choices are available:
@@ -1791,6 +1858,25 @@ This option controls how sequences of consecutive pages in the list of back refe
All styles support both Arabic and Roman numerals. In order to avoid potentially ambiguous lists, different sets of numerals will not be mixed when generating ranges, \eg the list <iii, iv, v, 6, 7, 8> is compressed to <iii--v, 6--8>.
+\optitem[setonly]{backrefsetstyle}{\opt{setonly}, \opt{memonly}, \opt{setormem}, \opt{setandmem}, \opt{memandset}, \opt{setplusmem}}
+
+This option controls how back references to \bibtype{set} entires and their members are handled. The following options are available:
+
+\begin{valuelist}
+\item[setonly] All back references are added to the \bibtype{set} entry. The \bibfield{pageref} lists of set members remain blank.
+
+\item[memonly] References to set members are added to the respective member. References to the \bibtype{set} entry are added to all members. The \bibfield{pageref} list of the \bibtype{set} entry remains blank.
+
+\item[setormem] References to the \bibtype{set} entry are added to the \bibtype{set} entry. References to set members are added to the respective member.
+
+\item[setandmem] References to the \bibtype{set} entry are added to the \bibtype{set} entry. References to set members are added to the respective member and to the \bibtype{set} entry.
+
+\item[memandset] References to the \bibtype{set} entry are added to the \bibtype{set} entry and to all members. References to set members are added to the respective member.
+
+\item[setplusmem] References to the \bibtype{set} entry are added to the \bibtype{set} entry and to all members. References to set members are added to the respective member and to the \bibtype{set} entry.
+
+\end{valuelist}
+
\optitem[false]{indexing}{\opt{true}, \opt{false}, \opt{cite}, \opt{bib}}
This option controls indexing in citations and in the bibliography. More precisely, it affects the \cmd{ifciteindex} and \cmd{ifbibindex} commands from \secref{aut:aux:tst}. The possible choices are:
@@ -3269,6 +3355,10 @@ The separator between the word «in» and the following title in entry types such
The separator printed before the \bibfield{pages} field. The default is a comma plus an interword space.
+\csitem{bibpagerefpunct}
+
+The separator printed before the \bibfield{pageref} field. The default is an interword space.
+
\csitem{multinamedelim}
The delimiter printed between multiple items in a name list like \bibfield{author} or \bibfield{editor} if there are more than two names in the list. The default is a comma plus an interword space. See \cmd{finalnamedelim} for an example.\footnote{Note that \cmd{multinamedelim} is not used at all if there are only two names in the list. In this case, the default styles use the \cmd{finalnamedelim}.}
@@ -5536,11 +5626,15 @@ This command is similar to \cmd{PackageWarning} but prints the entry key of the
\boolitem{pagetracker}
-These commands activate or deactivate the citation tracker locally (this will affect the \cmd{iffirstonpage} and \cmd{ifsamepage} test from \secref{aut:aux:tst}). They are intended for use in the definition of citation commands. If a citation command is to be excluded from page tracking, use \cmd{pagetrackerfalse} in the \prm{precode} argument of \cmd{DeclareCiteCommand}. See \secref{aut:cbx:cbx} for details. Note that these commands have no effect if page tracking has been disabled globally.
+These commands activate or deactivate the citation tracker locally (this will affect the \cmd{iffirstonpage} and \cmd{ifsamepage} test from \secref{aut:aux:tst}). They are intended for use in the definition of citation commands or anywhere in the document body. If a citation command is to be excluded from page tracking, use \cmd{pagetrackerfalse} in the \prm{precode} argument of \cmd{DeclareCiteCommand}. See \secref{aut:cbx:cbx} for details. Note that these commands have no effect if page tracking has been disabled globally.
\boolitem{citetracker}
-These commands activate or deactivate all citation trackers locally (this will affect the \cmd{ifciteseen}, \cmd{ifentryseen}, \cmd{ifciteibid}, and \cmd{ifciteidem} tests from \secref{aut:aux:tst}). They are intended for use in the definition of citation commands. If a citation command is to be excluded from tracking, use \cmd{citetrackerfalse} in the \prm{precode} argument of \cmd{DeclareCiteCommand}. See \secref{aut:cbx:cbx} for details. Note that these commands have no effect if tracking has been disabled globally.
+These commands activate or deactivate all citation trackers locally (this will affect the \cmd{ifciteseen}, \cmd{ifentryseen}, \cmd{ifciteibid}, and \cmd{ifciteidem} tests from \secref{aut:aux:tst}). They are intended for use in the definition of citation commands or anywhere in the document body. If a citation command is to be excluded from tracking, use \cmd{citetrackerfalse} in the \prm{precode} argument of \cmd{DeclareCiteCommand}. See \secref{aut:cbx:cbx} for details. Note that these commands have no effect if tracking has been disabled globally.
+
+\boolitem{backtracker}
+
+These commands activate or deactivate the \texttt{backref} tracker locally. They are intended for use in the definition of citation commands or anywhere in the document body. If a citation command is to be excluded from backtracking, use \cmd{backtrackerfalse} in the \prm{precode} argument of \cmd{DeclareCiteCommand}. Note that these commands have no effect if the \texttt{backref} option has been not been set globally.
\end{ltxsyntax}
@@ -6501,6 +6595,10 @@ The separator to be printed between the word «in» and the following title in ent
The separator to be printed before the \bibfield{pages} field. Use this separator instead of \cmd{newunitpunct} at this location. The default is a comma plus an interword space.
+\csitem{bibpagerefpunct}
+
+The separator to be printed before the \bibfield{pageref} field. Use this separator instead of \cmd{newunitpunct} at this location. The default is an interword space.
+
\csitem{multinamedelim}
The delimiter to be printed between multiple items in a name list like \bibfield{author} or \bibfield{editor} if there are more than two names in the list. If there are only two names in the list, use the \cmd{finalnamedelim} instead. This command should be incorporated in all formatting directives for name lists.
@@ -7030,10 +7128,10 @@ The \bibfield{entrysetcount} field holds an integer indicating the position of a
%
Since this field is only defined when processing citations referring to a set member, there is no need to add any additional tests.
-\subsubsection{Citation/Page Trackers in Floats and \acr{TOC}/\acr{LOT}/\acr{LOF}}
+\subsubsection{Trackers in Floats and \acr{TOC}/\acr{LOT}/\acr{LOF}}
\label{aut:cav:flt}
-If a citation is given in a float (typically in the caption of a figure or table), scholarly back references like <ibidem> or back references based on the page tracker may get ambiguous because floats are objects which are (physically and logically) placed outside the flow of text, hence the logic of such back references applies poorly to them. To avoid any such ambiguities, the citation trackers are temporarily disabled in all floats. This is equivalent to setting \cmd{citetrackerfalse} locally and affects all of the following tests from \secref{aut:aux:tst}: \cmd{ifciteseen}, \cmd{ifentryseen}, \cmd{ifciteibid}, \cmd{ifciteidem}, \cmd{ifopcit}, and \cmd{ifloccit}. The page tracker is disabled as well. This is equivalent to setting \cmd{pagetrackerfalse} locally and affects the \cmd{ifsamepage} and \cmd{iffirstonpage} tests. The trackers are also disabled in the table of contents, the list of figures, and the list of tables for similar reasons.
+If a citation is given in a float (typically in the caption of a figure or table), scholarly back references like <ibidem> or back references based on the page tracker get ambiguous because floats are objects which are (physically and logically) placed outside the flow of text, hence the logic of such references applies poorly to them. To avoid any such ambiguities, the citation and page trackers are temporarily disabled in all floats. In addition to that, these trackers plus the back reference tracker (\opt{backref}) are temporarily disabled in the table of contents, the list of figures, and the list of tables.
\subsubsection{Using the Punctuation Tracker}
\label{aut:cav:pct}
@@ -7359,6 +7457,18 @@ This revision history is a list of changes relevant to users of this package. Ch
\begin{changelog}
+\begin{release}{0.9e}{2010-10-09}
+\item Updated and expanded manual\see{bib:cav:enc}
+\item Added option \opt{sortupper}\see{use:opt:pre}
+\item Added option \opt{sortlocale}\see{use:opt:pre}
+\item Added option \opt{backrefsetstyle}\see{use:opt:pre}
+\item Added \cmd{bibpagerefpunct}\see{use:fmt:fmt}
+\item Added \cmd{backtrackertrue} and \cmd{backtrackerfalse}\see{aut:aux:msc}
+\item Disable back reference tracking in \acr{TOC}/\acr{LOT}/\acr{LOF}\see{aut:cav:flt}
+\item Improved back reference tracking for \bibtype{set} entries
+\item Fixed some bugs
+\end{release}
+
\begin{release}{0.9d}{2010-09-03}
\item Added workaround for \sty{hyperref} space factor issue
\item Added workaround for \sty{xkeyval}'s flawed class option inheritance