biblatex (29oct15)

git-svn-id: svn://tug.org/texlive/trunk@38737 c570f23f-e606-0410-a88d-b1316a301751

3 files changed, 108 insertions, 18 deletions

diff --git a/Master/texmf-dist/doc/latex/biblatex/RELEASE b/Master/texmf-dist/doc/latex/biblatex/RELEASE
index c9117079c0b..011ec39a266 100644
--- a/Master/texmf-dist/doc/latex/biblatex/RELEASE
+++ b/Master/texmf-dist/doc/latex/biblatex/RELEASE
@@ -1,3 +1,10 @@
+RELEASE NOTES FOR VERSION 3.1
+
+* Biber version 2.2 is required for biblatex 3.1
+* Added new macros \DeclareNolabel and \DeclareNolabelwidthcount for fine-tuning label generation
+* Improved Finnish and Russian localisation
+* Many bug fixes
+
 RELEASE NOTES FOR VERSION 3.0
 
 * Biber version 2.0 is required for biblatex 3.0
diff --git a/Master/texmf-dist/doc/latex/biblatex/biblatex.pdf b/Master/texmf-dist/doc/latex/biblatex/biblatex.pdf
index d5227f7510d..4093e7bd936 100644
--- a/Master/texmf-dist/doc/latex/biblatex/biblatex.pdf
+++ b/Master/texmf-dist/doc/latex/biblatex/biblatex.pdf
diff --git a/Master/texmf-dist/doc/latex/biblatex/biblatex.tex b/Master/texmf-dist/doc/latex/biblatex/biblatex.tex
index c8e393f40f6..e180357653f 100644
--- a/Master/texmf-dist/doc/latex/biblatex/biblatex.tex
+++ b/Master/texmf-dist/doc/latex/biblatex/biblatex.tex
@@ -49,8 +49,8 @@
   url={\biblatexhome},
   author={Philipp Lehman \\(with Philip Kime, Audrey Boruvka and Joseph Wright)},
   email={},
-  revision={3.0},
-  date={20/04/2015}}
+  revision={3.1},
+  date={21/10/2015}}
 
 \hypersetup{%
   pdftitle={The \biblatex Package},
@@ -346,6 +346,9 @@ compatibility matrix for the recent versions.
 \sffamily\bfseries\spotcolor Biber version
   & \sffamily\bfseries\spotcolor \biblatex\ version\\
 \midrule
+2.2 & 3.1\\
+2.1 & 3.0\\
+2.0 & 3.0\\
 1.9 & 2.9\\
 1.8 & 2.8\\
 1.7 & 2.7\\
@@ -3514,29 +3517,61 @@ See the author guide, in particular \secref{aut:aux:tst,aut:aux:ife}, for furthe
 
 \end{ltxsyntax}
 
-\subsubsection{Bibliography Contexts}
+\subsubsection{Bibliography Contexts}\BiberOnlyMark
 \label{use:bib:context}
 
-References in a bibliography are cited and printed in a <context>. The context determines the data which is actually used for an entry. A context consists currently of the following information (the <context> concept is designed for future extensibility):
+References in a bibliography are cited and printed in a <context>. The context determines the data which is actually used to cite or provide bibliographic data for an entry. A context consists currently of the following information (the <context> concept is designed for future extensibility):
 
 \begin{itemize}
- \item A specific sorting scheme
+ \item A sorting scheme
 \end{itemize}
 %
-The data for an entry can vary depending on the context. This is most obvious in the case of the \opt{extra*} fields like \opt{extrayear} which are generated by the backend according to the order of entries \emph{after} sorting so that they come out in the expected <a, b, c> order. This clearly shows that the \emph{data} in an entry can be different between sorting schemes. If a document contains more than one bibliography list with different sorting schemes, it can happen then that the \file{.bbl} contains sorting lists with the same entry but containing different data (a different value for \bibfield{extrayear}, for example). The purpose of bibliography contexts is to encapsulate things inside a context so that \biblatex can use the correct entry data. An example is printing a bibliography list with a different sorting order to the global sorting order:
+The point of bibliography contexts is twofold. Firstly, they are used to set options which influence a printed bibliography and secondly to influence the data printed by citation commands.
+The former use is the most common when one needs to print more than one bibliography list with different, for example, sorting.
 
 \begin{lstlisting}[style=latex]{}
 \usepackage[sorting=nyt]{biblatex}
+\begin{document}
+\cite{one}
+\cite{two}
+\printbibliography
+\newrefcontext[sorting=ydnt]
+\printbibliography
+\end{lstlisting}
+%
+Here we print two bibliographies, one with the default <nyt> sorting scheme and one with the <ydnt> sorting scheme.
+
+To demonstrate the second type of use of bibliography contexts, we have to understand that the actual data for an entry can vary depending on the context. This is most obvious in the case of the \opt{extra*} fields like \opt{extrayear} which are generated by the backend according to the order of entries \emph{after} sorting so that they come out in the expected <a, b, c> order. This clearly shows that the \emph{data} in an entry can be different between sorting schemes. If a document contains more than one bibliography list with different sorting schemes, it can happen then that the \file{.bbl} contains sorting lists with the same entry but containing different data (a different value for \bibfield{extrayear}, for example). The purpose of bibliography contexts is to encapsulate things inside a context so that \biblatex can use the correct entry data. An example is printing a bibliography list with a different sorting order to the global sorting order where the \opt{extra*} fields are different for the same entry between sorting lists:
+
+\begin{lstlisting}[style=latex]{}
+\usepackage[sorting=nyt,style=authoryear]{biblatex}
+\DeclareSortingScheme{yntd}{
+  \sort{
+    \field[strside=left,strwidth=4]{sortyear}
+    \field[strside=left,strwidth=4]{year}
+    \literal{9999}
+  }
+  \sort{
+    \field{sortname}
+    \field{author}
+    \field{editor}
+  }
+  \sort[direction=descending]{
+    \field{sorttitle}
+    \field{title}
+  }
+}
+\begin{document}
 \cite{one}
 \cite{two}
 \printbibliography
-\newrefcontext[sorting=yndt]
+\newrefcontext[sorting=yntd]
 \cite{one}
 \cite{two}
 \printbibliography
 \end{lstlisting}
 %
-Here, the second use of the citations, along with the \cmd{printbibliography} command will use data from the context of the <yndt> sorting scheme which may well be different from the data associated with the default <nyt> scheme.
+Here, the second use of the citations, along with the \cmd{printbibliography} command will use data from the context of the custom <yntd> sorting scheme which may well be different from the data associated with the default <nyt> scheme. That is, the citation labels (in an authoryear style which uses \opt{extrayear}) may be different \emph{for the exact same entries} between different bibliography contexts and so the citations themselves may look different.
 
 \begin{ltxsyntax}
 
@@ -5573,12 +5608,14 @@ Holds the prefix coming before <date> of the date field name chosen by \cmd{Decl
 \begin{lstlisting}[style=latex]{}
 \iffieldundef{datelabelsource}
   {
-    % labeldate package option is not set or \DeclareLabeldate resolved to a literal string
+    % labeldate package option is not set or
+    % \DeclareLabeldate resolved to a literal string
   }
   {
-    \iffieldundef{\thefield{datelabelsource}}
+    \iffieldundef{\thefield{datelabelsource}date}
       {
-        % datelabelsource contains a date field name prefix like "", "event", "url" or "orig"
+        % datelabelsource contains a date field name
+        % prefix like "", "event", "url" or "orig"
       }
       {
         % datelabelsource contains a non-date field
@@ -6506,9 +6543,9 @@ If an entry has a \bibfield{lista} field which matches regular expression <regex
 \end{lstlisting}
 %$<- to stop emacs highlighting breaking
 For any entry with an \bibfield{author} field, try to set
-\bibfield{sortname} to the same as \bibfield{author}. If this fails because
-\bibfield{sortname} already exists, stop, otherwise truncate
-\bibfield{sortname} to just the first name in the name list.
+\bibfield{editor} to the same as \bibfield{author}. If this fails because
+\bibfield{editor} already exists, stop, otherwise truncate
+\bibfield{editor} to just the first name in the name list.
 %
 \begin{lstlisting}[style=latex]{}
 \DeclareSourcemap{
@@ -7160,6 +7197,47 @@ would resulting a label looking like this:
 [>%YY__&&T07]
 \end{verbatim}
 
+Generating labels from fields may involve some difficulties when you have fields containing diacritics, hyphens, spaces etc. Often, you want to ignore things like separator characters or spaces when generating labels. An option is provided to customise the regular expression(s) to strip from a field before it is passed to the label generation system.
+
+\begin{ltxsyntax}
+
+\cmditem{DeclareNolabel}{specification}\BiberOnlyMark
+
+Defines regular expressions to strip from any field before generating a label part for the field. The \prm{specification} is an undelimited list of \cmd{nolabel} directives which specify the regular expressions to remove from fields. Spaces, tabs and line endings may be used freely to visually arrange the \prm{specification}. Blank lines are not permissible. This command may only be used in the preamble.
+
+\cmditem{nolabel}{regexp}
+
+Any number of \cmd{nolabel} commands can be given each of which specifies to remove the \prm{regexp} from the copy of the field which the label generation system sees. Since regular expressions usually contain special characters, it is best to enclose them in the provided \cmd{regexp} macro as shown---this will pass the expression through to \biber correctly.
+
+\end{ltxsyntax}
+
+If there is no \cmd{DeclareNolabel} specification, \biber will default to:
+
+\begin{lstlisting}[style=latex]{}
+\DeclareNolabel{
+  % strip punctuation, symbols, separator and control characters
+  \nolabel{\regexp{<<[\p{P}\p{S}\p{C}]+>>}}
+}
+\end{lstlisting}
+%
+This \biber default strips punctuation, symbol, separator and control characters from fields before passing the field string to the label generation system.
+
+\begin{ltxsyntax}
+
+\cmditem{DeclareNolabelwidthcount}{specification}\BiberOnlyMark
+
+Defines regular expressions to ignore from any field when counting characters in fixed-width substrings. The \prm{specification} is an undelimited list of \cmd{nolabelwidthcount} directives which specify the regular expressions to ignore when counting characters for fixed-width substrings. Spaces, tabs and line endings may be used freely to visually arrange the \prm{specification}. Blank lines are not permissible. This command may only be used in the preamble.
+
+\cmditem{nolabelwidthcount}{regexp}
+
+Any number of \cmd{nolabelwidthcount} commands can be given each of which specifies to ignore the \prm{regexp} when generating fixed-width substrings during label generation. Since regular expressions usually contain special characters, it is best to enclose them in the provided \cmd{regexp} macro as shown---this will pass the expression through to \biber correctly.
+
+\end{ltxsyntax}
+
+There is no default \cmd{DeclareNolabelwidthcount} specification. Note that
+this setting is only taken into account when using fixed-width substrings
+(non-varwidth) during label part generation. See \secref{aut:ctm:lab}.
+
 \subsubsection{Sorting}
 \label{aut:ctm:srt}
 
@@ -7363,9 +7441,9 @@ When using customisable bibliography lists (See \secref{use:bib:biblist}), usual
 
 Defines a bibliography list filter with \prm{name}. The \prm{specification} consists of one or more \cmd{filter} or \cmd{filteror} macros, all of which must be satisfied for the entry to pass the filter:
 
-\cmditem{filter}{type}{filter}
+\cmditem{filter}[filterspec]{filter}
 
-Filter entries according to the \prm{type} and \prm{filter}. \prm{type} can be one of:
+Filter entries according to the \prm{filterspec} and \prm{filter}. \prm{filterspec} can be one of:
 
 \end{ltxsyntax}
 
@@ -11057,8 +11135,8 @@ Please refer to \secref{bib:cav:ref, aut:ctm:ref} for explanation.
 \begin{longtable}[l]{%
 	@{}V{0.2\textwidth}%
 	@{}V{0.4\textwidth}%
-	@{}V{0.2\textwidth}%
-	@{}V{0.2\textwidth}@{}}
+	@{}V{0.3\textwidth}%
+	@{}V{0.3\textwidth}@{}}
 \toprule
 \multicolumn{2}{@{}H}{Types} & \multicolumn{2}{@{}H}{Fields} \\
 \cmidrule(r){1-2}\cmidrule{3-4}
@@ -11378,6 +11456,11 @@ This revision history is a list of changes relevant to users of this package. Ch
 
 \begin{changelog}
 
+\begin{release}{3.1}{2015-09}
+\item Added \cmd{DeclareNolabel}\see{aut:ctm:lab}\BiberOnlyMark
+\item Added \cmd{DeclareNolabelwidthcount}\see{aut:ctm:lab}\BiberOnlyMark
+\end{release}
+
 \begin{release}{3.0}{2015-04-20}
 \item Improved Danish (Jonas Nyrup) and Spanish (ludenticus) translations
 \item \bibfield{labelname} and \bibfield{labeltitle} are now resolved by \biblatex instead of \biber for more flexibility and future extensibility