#540 Implementing customisable extradate

bibtex/bst/biblatex/biblatex.bst

@@ -159,7 +159,7 @@ ENTRY {
     verbc
   }
   { skipbib skiplos skiplab useauthor useeditor usetranslator useprefix singletitle }
-  { entryoptions labelhash namehash fullhash dateyear dateendyear extrayear labelalpha extraalpha 
+  { entryoptions labelhash namehash fullhash dateyear dateendyear extradate labelalpha extraalpha 
     sortinit label.name label.year sortkey.nosort sortkey.name sortkey.year
     sortkey.title sortkey.alpha sort.year sort.alph warningmsg }
 
@@ -1443,7 +1443,7 @@ FUNCTION {output:specials} {
           if$
         }
       if$
-      "extrayear"   extrayear       output:write:field
+      "extradate"   extradate       output:write:field
       "labeldatesource" "year"      output:write:field
     }
     'skip$
@@ -2552,10 +2552,10 @@ FUNCTION {labelsort:main:year:iterate} {
       'label.year :=
       label.year last.year =
         { last.extra.num #1 + 'last.extra.num :=
-          last.extra.num int.to.str$ 'extrayear :=
+          last.extra.num int.to.str$ 'extradate :=
         }
         { #1 'last.extra.num :=
-          "" 'extrayear :=
+          "" 'extradate :=
           label.year 'last.year :=
         }
       if$
@@ -2567,10 +2567,10 @@ FUNCTION {labelsort:main:year:iterate} {
 FUNCTION {labelsort:main:year:reverse} {
   ctrl:labeldate
     { last.extra "2" =
-        { "1" 'extrayear := }
+        { "1" 'extradate := }
         'skip$
       if$
-      extrayear 'last.extra :=
+      extradate 'last.extra :=
     }
     'skip$
   if$

doc/latex/biblatex/biblatex.tex

@@ -8841,6 +8841,121 @@ \subsubsection{Special Fields}
 Note that the \bibfield{date} field is split by the backend into \bibfield{year}, \bibfield{month} which are also valid fields in the default data model. In order to support legacy data which directly sets \bibfield{year} and/or \bibfield{month}, the specification <\bibfield{date}> in \cmd{DeclareLabeldate} will also match \bibfield{year} and \bibfield{month} fields, if present.
 The \bibfield{label*} fields may be customized globally or on a per-type basis. If the optional \prm{entrytype} argument is given, the specification applies to the respective entry type. If not, it is applied globally. The \prm{entrytype} argument may be a comma"=separated list of values. This command may only be used in the preamble. See also \secref{aut:bbx:fld:dat}.
 
+\cmditem{DeclareExtradate}{specification}
+
+Defines how \biber tracks information used to construct the \bibfield{extradate} field. This field (see \secref{aut:bbx:fld:lab}) is printed to disambiguate works by the same author which occur in the same date scope. By default, the date scope is the year and so two works by the same author within the same year will have different \bibfield{extrayear} values which are used to disambiguate the works in the bibliography in the usual manner seen in many authoryear type styles. The \prm{specification} is one or more \cmd{scope} specifications which can contain one or more \cmd{field} specifications. Within a \cmd{scope}, the existence of each \cmd{field} will be checked and if found, the first \cmd{field} is used and the rest are ignored. This allows a fallback in case certain fields are not available in all entries. All \cmd{scope}s are used to track information. The default definition is:
+
+\begin{ltxexample}
+\DeclareExtradate{%
+  \scope{
+    \field{labelyear}
+    \field{year}
+  }
+}
+\end{ltxexample}
+%
+This means that the \bibfield{labelyear} field only (or \bibfield{year} if this does not exist) will be used to track works by the same author. With the following datasource entries:
+
+\begin{lstlisting}[style=bibtex]{}
+@BOOK{extra1,
+  AUTHOR = {John Doe},
+  DATE   = {2001-01}
+}
+
+@BOOK{extra2,
+  AUTHOR = {John Doe},
+  DATE   = {2001-02}
+}
+\end{lstlisting}
+%
+The default definition would result in:
+
+\begin{lstlisting}{}
+Doe 2001a
+Doe 2001b
+\end{lstlisting}
+%
+Here, \bibfield{extradate} only considers the \bibfield((label)year) information and since this is identical, disambiguation is required. However, consider the following definition:
+\begin{ltxexample}
+\DeclareExtradate{%
+  \scope{
+    \field{labelyear}
+    \field{year}
+  }
+  \scope{
+    \field{labelmonth}
+  }
+}
+\end{ltxexample}
+%
+The result would be:
+\begin{lstlisting}{}
+Doe 2001
+Doe 2001
+\end{lstlisting}
+%
+If only years were printed, this would be ambiguous because \bibfield{extradate} now considers \bibfield{labelmonth} and since this differs, no disambiguation is necessary. Care should therefore be taken to synchronise the printed information with the \bibfield{extradate} disambiguation settings. Notice that the second definition is <month-in-year> disambiguation and quite different from:
+\begin{ltxexample}
+\DeclareExtradate{%
+  \scope{
+    \field{labelmonth}
+  }
+}
+\end{ltxexample}
+%
+which is just plain <month> disambiguation which is very unlikely to be what you ever want to do since this disambiguation only based on month and ignores the year entirely. \bibfield{extradate} calculation should almost always be based on all information down to the resolution you require. For example, if you wish to disambiguate right down to the hour level (perhaps useful in large bibliographies of rapidly changing online material), you would specify something like this:
+\begin{ltxexample}
+\DeclareExtradate{%
+  \scope{
+    \field{labelyear}
+    \field{year}
+  }
+  \scope{
+    \field{labelmonth}
+  }
+  \scope{
+    \field{labelday}
+  }
+  \scope{
+    \field{labelhour}
+  }
+}
+\end{ltxexample}
+% 
+Entries without the specified granularity of information will disambiguate at the lowest granularity they contain, so, for example, with:
+\begin{ltxexample}
+\DeclareExtradate{%
+  \scope{
+    \field{labelyear}
+    \field{year}
+  }
+  \scope{
+    \field{labelmonth}
+  }
+}
+\end{ltxexample}
+%
+\begin{lstlisting}[style=bibtex]{}
+@BOOK{extra1,
+  AUTHOR = {John Doe},
+  DATE   = {2001}
+}
+
+@BOOK{extra2,
+  AUTHOR = {John Doe},
+  DATE   = {2001}
+}
+\end{lstlisting}
+%
+The result would still be:
+
+\begin{lstlisting}{}
+Doe 2001a
+Doe 2001b
+\end{lstlisting}
+%
+This command may only be used in the preamble.
+
 \cmditem{DeclareLabeltitle}[entrytype, \dots]{specification}
 
 Defines the fields to consider when generating the \bibfield{labeltitle} field (see \secref{aut:bbx:fld:lab}). The \prm{specification} is an ordered list of \cmd{field} commands. The fields are checked in the order listed and the first field which is available will be used as \bibfield{labeltitle}. This is the default definition:
@@ -13065,6 +13180,7 @@ \section{Revision History}
 \begin{changelog}
 
 \begin{release}{3.8}{2017-?}
+\item Added \cmd{DeclareExtradate}\see{aut:ctm:fld}
 \item Renamed \opt{extrayear} to \opt{extradate}\see{aut:bbx:fld:lab}
 \item Added \opt{sortsets} global option\see{use:opt:pre:gen}
 \item Added \cmd{iflabelalphanametemplatename} and \cmd{uniquenametemplatename}\see{aut:aux:tst}

tex/latex/biblatex/biblatex.def

@@ -1262,6 +1262,13 @@
   \literal{nodate}
 }
 
+\DeclareExtradate{%
+  \scope{
+    \field{labelyear}
+    \field{year}
+  }
+}
+
 \DeclareLabeltitle{%
   \field{shorttitle}
   \field{title}

tex/latex/biblatex/biblatex.sty

@@ -10679,6 +10679,15 @@
 \xdef\blx@xml@labelalpha@part#1#2{%
   ~~~~~~<bcf:labelpart#1>#2</bcf:labelpart>\blx@nl}
 
+\xdef\blx@xml@extradate#1{%
+  ~~<bcf:extradatespec>\blx@nl
+  #1%
+  ~~</bcf:extradatespec>\blx@nl}
+\xdef\blx@xml@extradatescope#1{%
+  ~~~~<bcf:scope>\blx@nl
+  #1%
+  ~~~~</bcf:scope>\blx@nl}
+
 \xdef\blx@xml@inheritance#1{%
   ~~<bcf:inheritance>\blx@nl
   #1%
@@ -11034,53 +11043,45 @@
   \def\do##1{%
     \eappto\blx@tempa{%
       \blx@xml@labelalphatemplate{##1}{%
-      \csuse{blx@labelalphatemplate@##1}}%
-      }%
-    }%
+      \csuse{blx@labelalphatemplate@##1}}}}%
   \dolistloop\blx@latem@type
+  % extradate specification
+  \eappto\blx@tempa{%
+    \blx@xml@comment{EXTRADATE}%
+    \blx@xml@extradate{\csuse{blx@bcf@extradatespec}}}%
   % data inheritance
   \eappto\blx@tempa{%
     \blx@xml@comment{INHERITANCE}%
     \blx@xml@inheritance{%
       \csuse{blx@inherit@default}%
-      \csuse{blx@inherit@data}%
-    }%
-  }%
+      \csuse{blx@inherit@data}}}%
   % noinit
   \ifcsdef{blx@noinit}
     {\eappto\blx@tempa{%
       \blx@xml@comment{NOINIT}%
       \blx@xml@noinits{%
-        \csuse{blx@noinit}%
-      }%
-    }}
+        \csuse{blx@noinit}}}}%
     {}%
   % nolabel
   \ifcsdef{blx@nolabel}
     {\eappto\blx@tempa{%
       \blx@xml@comment{NOLABEL}%
       \blx@xml@nolabels{%
-        \csuse{blx@nolabel}%
-      }%
-    }}
+        \csuse{blx@nolabel}}}}%
     {}%
   % nolabel
   \ifcsdef{blx@nolabelwidthcount}
     {\eappto\blx@tempa{%
       \blx@xml@comment{NOLABELWIDTHCOUNT}%
       \blx@xml@nolabelwidthcounts{%
-        \csuse{blx@nolabelwidthcount}%
-      }%
-    }}
+        \csuse{blx@nolabelwidthcount}}}}%
     {}%
   % nosort
   \ifcsdef{blx@nosort}
     {\eappto\blx@tempa{%
       \blx@xml@comment{NOSORT}%
       \blx@xml@nosorts{%
-        \csuse{blx@nosort}%
-      }%
-    }}
+        \csuse{blx@nosort}}}}%
     {}%
   % transliteration
   \ifdefempty\blx@translits
@@ -11977,7 +11978,6 @@
     \blx@xml@sortitem{order="\the\blx@tempcntb"}{\blx@tempe}}}
 
 % [<type,type,...>]{<string>}
-
 \newrobustcmd*{\DeclarePresort}[2][]{%
   \begingroup
   \blx@xmlsanitizeafter{\def\blx@tempa}{#2}%
@@ -12035,6 +12035,29 @@
 \def\blx@sortinclude@i#1{%
   \appto\blx@tempa{\blx@xml@include{#1}}}
 
+% {<field,field,...>}
+\newrobustcmd*{\DeclareExtradate}[1]{%
+  \begingroup
+  \let\blx@tempa\@empty
+  \let\scope\blx@extradate@scope
+  #1%
+  \global\let\blx@bcf@extradatespec\blx@tempa
+  \endgroup}
+\@onlypreamble\DeclareExtradate
+\blx@collectopts{xml}{blx@globalopts}{extradatespec}% for passing to the .bcf
+
+\newrobustcmd*{\blx@extradate@scope}[1]{%
+  \let\blx@tempb\@empty
+  \let\field\blx@ordereded@field
+  #1%
+  \csxappto{blx@tempa}{%
+    \noexpand\blx@xml@extradatescope{\blx@tempb}}}
+
+\newcommand*{\blx@ordereded@field}[1]{%
+  \advance\blx@tempcnta\@ne
+    \csxappto{blx@tempb}{%
+      \noexpand\blx@xml@ordered{\the\blx@tempcnta}{}{#1}}}
+
 % [<type,type,...>]{<field,field,...>}
 \newrobustcmd*{\DeclareLabelname}[2][]{%
   \begingroup

tex/latex/biblatex/blx-bibtex.def

@@ -443,6 +443,7 @@
 % Disable some interfaces
 
 \renewrobustcmd*{\DeclareSortingScheme}[3][]{}
+\renewrobustcmd*{\DeclareExtradate}[1]{}
 
 \def\blx@checkencoding{}