diff options
Diffstat (limited to 'Master/texmf-dist/doc/latex/biblatex/biblatex.tex')
| -rw-r--r-- | Master/texmf-dist/doc/latex/biblatex/biblatex.tex | 128 |
1 files changed, 63 insertions, 65 deletions
diff --git a/Master/texmf-dist/doc/latex/biblatex/biblatex.tex b/Master/texmf-dist/doc/latex/biblatex/biblatex.tex index 1716985cf0b..a44602b0fa0 100644 --- a/Master/texmf-dist/doc/latex/biblatex/biblatex.tex +++ b/Master/texmf-dist/doc/latex/biblatex/biblatex.tex @@ -1,4 +1,4 @@ -% $Id: biblatex.tex,v 1.1a 2011/01/08 13:30:00 lehman stable $ +% $Id: biblatex.tex,v 1.1b 2011/02/04 11:36:21 lehman stable $ \documentclass{ltxdockit}[2010/11/19] \usepackage{btxdockit} \usepackage[latin9]{inputenc} @@ -11,7 +11,7 @@ \MakeAutoQuote*{<}{>} \MakeShortVerb{\|} -\rcsid{$Id: biblatex.tex,v 1.1a 2011/01/08 13:30:00 lehman stable $} +\rcsid{$Id: biblatex.tex,v 1.1b 2011/02/04 11:36:21 lehman stable $} \newcommand*{\BiblatexHome}{http://sourceforge.net/projects/biblatex/} \newcommand*{\BiblatexOnCTAN}{http://www.ctan.org/tex-archive/macros/latex/contrib/biblatex/} @@ -236,7 +236,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 \xetex or \luatex instead. +The \sty{ucs} package provides support for \utf encoded input. Either use \sty{inputenc}'s standard \file{utf8} module or a Unicode enabled engine such as \xetex or \luatex instead. \end{marglist} @@ -453,7 +453,7 @@ Audio recordings, typically on audio \acr{CD}, \acr{DVD}, audio casette, or simi \typeitem{bibnote} -This special entry type is not meant to be used in the \file{bib} file like other types. It is provided for third-party packages like \sty{notes2bib} which merge notes into the bibliography. The notes should go into the \bibfield{note} field. By advised that the \bibtype{bibnote} type is not related to the \cmd{defbibnote} command in any way. \cmd{defbibnote} is for adding comments at the beginning or the end of the bibliography, whereas the \bibtype{bibnote} type is meant for packages which render endnotes as bibliography entries. +This special entry type is not meant to be used in the \file{bib} file like other types. It is provided for third-party packages like \sty{notes2bib} which merge notes into the bibliography. The notes should go into the \bibfield{note} field. Be advised that the \bibtype{bibnote} type is not related to the \cmd{defbibnote} command in any way. \cmd{defbibnote} is for adding comments at the beginning or the end of the bibliography, whereas the \bibtype{bibnote} type is meant for packages which render endnotes as bibliography entries. \typeitem{commentary} @@ -1531,7 +1531,7 @@ sortname = {Ba<<sszz>>mann, Paul}, Not only \bibtex, \latex needs to know about the encoding as well. See \secref{bib:cav:enc:enc} on how to specify encodings. \paragraph{Biber} -Biber handles Ascii, 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 far 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} is of a very general nature and not limited to the lack of \utf support.\fnurl{http://unicode.org/reports/tr10/#Common_Misperceptions} +Biber handles Ascii, 8-bit encodings such as Latin\,1, and \utf. 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 far 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} is of a very general nature and not limited to the lack of \utf support.\fnurl{http://unicode.org/reports/tr10/#Common_Misperceptions} Supporting Unicode implies much more than handling \utf input. Unicode is a complex standard covering more than its most well-known parts, the Unicode character encoding and transport encodings such as \utf. It also standardizes aspects such as string collation, which is 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: @@ -1576,27 +1576,27 @@ Since \kvopt{bibencoding}{auto} is the default setting, the option is omissible. \usepackage{biblatex} \end{lstlisting} -\item \acr{UTF-8} encoding in the \file{tex} file, Latin\,1 (\acr{ISO}-8859-1) in the \file{bib} file with \pdftex or traditional \tex (\file{bibtex8}, Biber): +\item \utf encoding in the \file{tex} file, Latin\,1 (\acr{ISO}-8859-1) in the \file{bib} file with \pdftex or traditional \tex (\file{bibtex8}, Biber): \begin{lstlisting}[style=latex]{} \usepackage[utf8]{inputenc} \usepackage[bibencoding=latin1]{biblatex} \end{lstlisting} -The same scenario with \xetex or \luatex in native \acr{UTF-8} mode: +The same scenario with \xetex or \luatex in native \utf 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: +\item Using \utf 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 \utf. 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[bibencoding=ascii]{biblatex} \end{lstlisting} -The same scenario with \xetex or \luatex in native \acr{UTF-8} mode: +The same scenario with \xetex or \luatex in native \utf mode: \begin{lstlisting}[style=latex]{} \usepackage[bibencoding=ascii]{biblatex} @@ -1604,11 +1604,11 @@ The same scenario with \xetex or \luatex in native \acr{UTF-8} mode: \end{itemize} -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 limited macro-level reencoding feature 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: +Biber can handle Ascii notation, 8-bit encodings such as Latin\,1, and \utf. It is also capable of reencoding the \file{bib} data on the fly (replacing the limited macro-level reencoding feature 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 with \pdftex or traditional \tex: +\item Transparent \utf workflow, \ie \utf encoding in both the \file{tex} and the \file{bib} file with \pdftex or traditional \tex: \begin{lstlisting}[style=latex]{} \usepackage[utf8]{inputenc} @@ -1622,13 +1622,13 @@ Since \kvopt{bibencoding}{auto} is the default setting, the option is omissible: \usepackage{biblatex} \end{lstlisting} -The same scenario with \xetex or \luatex in native \acr{UTF-8} mode: +The same scenario with \xetex or \luatex in native \utf mode: \begin{lstlisting}[style=latex]{} \usepackage{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 covered by the selected 8-bit encoding: +\item It is even possible to combine an 8-bit encoded \file{tex} file with \utf encoding in the \file{bib} file, provided that all characters in the \file{bib} file are also covered by the selected 8-bit encoding: \begin{lstlisting}[style=latex]{} \usepackage[latin1]{inputenc} @@ -1637,6 +1637,23 @@ The same scenario with \xetex or \luatex in native \acr{UTF-8} mode: \end{itemize} +Some workarounds may be required when using traditional \tex or \pdftex with \utf encoding because \sty{inputenc}'s \file{utf8} module does not cover all of Unicode. Roughly speaking, it only convers the Western European Unicode range. When loading \sty{inputenc} with the \file{utf8} option, \sty{biblatex} will normally instruct Biber to reencode the \file{bib} data to \utf. This may lead to \sty{inputenc} errors if some of the characters in the \file{bib} file are outside the limited Unicode range supported by \sty{inputenc}. + +\begin{itemize} + +\item If you are affected by this problem, try setting the \opt{safeinputenc} option: + +\begin{lstlisting}[style=latex]{} +\usepackage[utf8]{inputenc} +\usepackage[safeinputenc]{biblatex} +\end{lstlisting} +% +If this option is enabled, \sty{biblatex} will ignore \sty{inputenc}'s \opt{utf8} option and use Ascii. Biber will then try to convert the \file{bib} data to Ascii notation. For example, it will convert \texttt{\k{S}} to |\k{S}|. This option is similar to setting \kvopt{texencoding}{ascii} but will only take effect in this specific scenario (\sty{inputenc}\slash \sty{inputenx} with \utf). This workaround takes advantage of the fact that both Unicode and the \utf transport encoding are backwards compatible with Ascii. + +\end{itemize} + +This solution may be acceptable as a workaround if the data in the \file{bib} file is mostly Ascii anyway, with only a few strings, such as some authors' names, causing problems. However, keep in mind that it will not magically make traditional \tex or \pdftex support Unicode. It may help if the occasional odd character is not supported by \sty{inputenc}, but may still be processed by \tex when using an accent command (\eg |\d{S}| instead of \texttt{\d{S}}). If you need full Unicode support, however, switch to \xetex or \luatex. + \subsubsection{Editors and Compiler Scripts} \label{bib:cav:ide} @@ -2058,19 +2075,37 @@ Specifies the database backend. The following backends are supported: This option will typically be set permanently in the configuration file, see \secref{use:cfg} for details. Also see \secref{bib:cav:enc} for further instructions concerning the encoding of \file{bib} files. +\optitem[auto]{texencoding}{\opt{auto}, \prm{encoding}} + +Specifies the encoding of the \file{tex} file. This option affects the data transfered from the backend to \sty{biblatex}. When using Biber, this corresponds to Biber's |--bblencoding| option. The following choices are available: + +\begin{valuelist} + +\item[auto] Try to auto-detect the input encoding. If the \sty{inputenc}\slash \sty{inputenx}\slash \sty{luainputenc} package is available, \sty{biblatex} will get the main encoding from that package. If not, it assumes \utf encoding if \xetex or \luatex has been detected, and Ascii otherwise. + +\item[\prm{encoding}] Specifies the \prm{encoding} explicitly. This is for odd cases in which auto-detection fails or you want to force a certain encoding for some reason. + +\end{valuelist} +% +Note that setting \kvopt{texencoding}{\prm{encoding}} will also affect the \opt{bibencoding} option if \kvopt{bibencoding}{auto}. + \optitem[auto]{bibencoding}{\opt{auto}, \prm{encoding}} -Specifies the encoding of the \file{bib} files. The following choices are available: +Specifies the encoding of the \file{bib} files. When using Biber, this corresponds to Biber's |--bibencoding| option. The following choices are available: \begin{valuelist} -\item[auto] Use this option if the workflow is transparent, \ie if the encoding of the \file{bib} file is identical to the encoding of the \file{tex} file. The \sty{biblatex} package will try to auto-detect the encoding of the \file{tex} file. If the \sty{inputenc}\slash\sty{inputenx}\slash\sty{luainputenc} package is available, \sty{biblatex} will get the main encoding from that package. If not, it assumes \texttt{utf8} if \xetex or \luatex has been detected, and \texttt{ascii} otherwise. +\item[auto] Use this option if the workflow is transparent, \ie if the encoding of the \file{bib} file is identical to the encoding of the \file{tex} file. -\item[\prm{encoding}] If the encoding of the \file{bib} file is different from the one of the \file{tex} file, you need to specify it explicitly. When using the \sty{inputenc}\slash\sty{inputenx}\slash\sty{luainputenc} package, the \prm{encoding} must be an encoding name known to that package. +\item[\prm{encoding}] If the encoding of the \file{bib} file is different from the one of the \file{tex} file, you need to specify it explicitly. \end{valuelist} -By default, \sty{biblatex} assumes that the \file{tex} file and the \file{bib} file use the same encoding. Note that some backends only support a limited number of encodings. See \secref{bib:cav:enc} for further instructions. +By default, \sty{biblatex} assumes that the \file{tex} file and the \file{bib} file use the same encoding (\kvopt{bibencoding}{auto}). Note that some backends only support a limited number of encodings. See \secref{bib:cav:enc} for further instructions. + +\boolitem[false]{safeinputenc}[\BiberOnly] + +If this option is enabled, \sty{biblatex} will automatically force \kvopt{texencoding}{ascii} if the \sty{inputenc}\slash \sty{inputenx} package has been loaded and the input encoding is \utf, \ie it will ignore any macro-based \utf support and use Ascii only. Biber will then try to convert any non-Ascii data in the \file{bib} file to Ascii. For example, it will convert \texttt{\d{S}} to |\d{S}|. See \secref{bib:cav:enc:enc} for an explanation of why you may want to enable this option. \boolitem[true]{bibwarn} @@ -5291,10 +5326,6 @@ The sort direction, which may be either \texttt{ascending} or \texttt{descending This option marks a \cmd{sort} directive as the final one in the \prm{specification}. If one of the \prm{elements} is available, the remainder of the \prm{specification} will be ignored. The short form \opt{final} is equivalent to \kvopt{final}{true}. -\choitem[both]{pass}{label, final} - -When generating special fields such as \bibfield{extraalpha}, the sorting routine may need to sort the entries twice because label generation may require a sort order different from the final order of the bibliography. This option indicates that the directive should be considered on the first (\texttt{label}) or the second (\texttt{final}) pass only. See the examples below for details. - \boolitem{sortcase} Whether to sort case"=sensitively. The default setting depends on the global \opt{sortcase} option. @@ -5349,7 +5380,7 @@ The number of characters to match. \cmditem{literal}{string} -The \cmd{literal} element adds a literal \prm{string} to the sorting specification. This is useful as a fallback if certain fields are not available. +The \cmd{literal} element adds a literal \prm{string} to the sorting specification. This is useful as a fallback if some fields are not available. \csitem{citeorder} @@ -5409,48 +5440,6 @@ In the next example, we define the same scheme in a more elaborate way, consider } } \end{lstlisting} -% -The next example is more complex still. In some cases, the backend needs to sort the entries twice. An example is the \texttt{anyt} scheme, which includes the automatically generated \bibfield{labelalpha} and \bibfield{extraalpha} fields. We want the \bibfield{extraalpha} field to be considered in the sorting process because the bibliography of \texttt{alphabetic} styles is usually sorted by label and it would be odd to have |Abc95a| after |Abc95b|. However, generating \bibfield{extraalpha} requires that the entries be already sorted (by \bibfield{labelalpha}). Therefore, we establish the sorting order required for the generation of the \bibfield{extraalpha} field on the first pass. On the second and final pass, the newly generated field is considered in the sorting process. Note that \bibfield{labelalpha} is shifting positions: - -\begin{lstlisting}[style=latex]{} -\DeclareSortingScheme{anyt}{% - \sort{ - \field{presort} - } - \sort[<<pass=label>>]{ - \field{<<labelalpha>>} - } - \sort{ - \field[final]{sortkey} - } - \sort[<<pass=final>>]{ - \field{<<labelalpha>>} - } - \sort[<<pass=final>>]{ - \field[padside=left,padwidth=4,padchar=0]{<<extraalpha>>} - } - \sort{ - \name{sortname} - \name{author} - \name{editor} - \name{translator} - \field{sorttitle} - \field{title} - } - \sort{ - \field{sortyear} - \field{year} - } - \sort{ - \field{sorttitle} - \field{title} - } - \sort{ - \field[padside=left,padwidth=4,padchar=0]{volume} - \literal{0000} - } -} -\end{lstlisting} \begin{ltxsyntax} @@ -7895,9 +7884,18 @@ This revision history is a list of changes relevant to users of this package. Ch \begin{changelog} +\begin{release}{1.1b}{2011-02-04} +\item Added option \opt{texencoding}\see{use:opt:pre:gen}\BiberOnlyMark +\item Added option \opt{safeinputenc}\see{use:opt:pre:gen}\BiberOnlyMark +\item Expanded documentation\see{bib:cav:enc:enc} +\item Improved \opt{mergedate} option of bibliography style \texttt{authoryear}\see{use:xbx:bbx} +\item Removed \opt{pass} option of \cmd{DeclareSortingScheme}\see{aut:ctm:srt}\BiberOnlyMark +\item Fixed some bugs +\end{release} + \begin{release}{1.1a}{2011-01-08} \item Added unsupported entry type \bibtype{bibnote}\see{bib:typ:ctm} -\item Added \cmd{bibliography*}\see{use:bib:sec} +\item Added \cmd{bibliography*}\see{use:bib:bib} \item Fixed some bugs \end{release} |