datatool (28jul16)

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

18 files changed, 141 insertions, 8 deletions

diff --git a/Master/texmf-dist/doc/latex/datatool/CHANGES b/Master/texmf-dist/doc/latex/datatool/CHANGES
index 04a54a35c0e..32497e242ed 100644
--- a/Master/texmf-dist/doc/latex/datatool/CHANGES
+++ b/Master/texmf-dist/doc/latex/datatool/CHANGES
@@ -1,3 +1,20 @@
+v2.27:
+
+  * datatool-base:
+
+   - reverted \dtl@insertinto to pre v2.26. (The bug fixes
+     in v2.26 caused backward-compatibility issues, which 
+     break glossaries.sty's "noidx" code.)
+
+   - new commands \dtlsortlist and \dtlinsertinto (which
+     are how \dtl@sortlist and \dtl@insertinto ought to
+     behave but don't). The internal commands are left for
+     backward compatibility. The user commands should be
+     used for the correct function. (Added new section in
+     the user manual documenting these new commands.)
+
+   - new command \edtlinsertinto
+
 v2.26:
 
   * datatool-base:
diff --git a/Master/texmf-dist/doc/latex/datatool/README b/Master/texmf-dist/doc/latex/datatool/README
index 6bacaf67ec8..cbae48e774e 100644
--- a/Master/texmf-dist/doc/latex/datatool/README
+++ b/Master/texmf-dist/doc/latex/datatool/README
@@ -1,6 +1,6 @@
-LaTeX Bundle : datatool v2.26 
+LaTeX Bundle : datatool v2.27 
 
-Last Modified : 2016-07-20
+Last Modified : 2016-07-28
 
 Author        : Nicola Talbot
 
diff --git a/Master/texmf-dist/doc/latex/datatool/datatool-code.pdf b/Master/texmf-dist/doc/latex/datatool/datatool-code.pdf
index 23dcc06d45e..b2a076679c4 100644
--- a/Master/texmf-dist/doc/latex/datatool/datatool-code.pdf
+++ b/Master/texmf-dist/doc/latex/datatool/datatool-code.pdf
diff --git a/Master/texmf-dist/doc/latex/datatool/datatool-user.pdf b/Master/texmf-dist/doc/latex/datatool/datatool-user.pdf
index 333429d92cd..53f1d9cedf4 100644
--- a/Master/texmf-dist/doc/latex/datatool/datatool-user.pdf
+++ b/Master/texmf-dist/doc/latex/datatool/datatool-user.pdf
diff --git a/Master/texmf-dist/doc/latex/datatool/datatool-user.tex b/Master/texmf-dist/doc/latex/datatool/datatool-user.tex
index 140fe1f1282..b5e65957904 100644
--- a/Master/texmf-dist/doc/latex/datatool/datatool-user.tex
+++ b/Master/texmf-dist/doc/latex/datatool/datatool-user.tex
@@ -102,11 +102,11 @@
 
 \MakeShortVerb{"}
 
- \title{User Manual for datatool bundle version~2.26}
+ \title{User Manual for datatool bundle version~2.27}
  \author{Nicola L.C. Talbot\\
 \url{http://www.dickimaw-books.com/}}
 
- \date{2016-07-20}
+ \date{2016-07-28}
  \maketitle
 
 \pagenumbering{roman}
@@ -121,7 +121,7 @@ The \styfmt{datatool} bundle comes with the following documentation:
   \item[\url{datatool-code.pdf}]
   Advanced users wishing to know more about the inner workings of
   all the packages provided in the \styfmt{datatool} bundle should
-  read \qt{Documented Code for datatool v2.26}
+  read \qt{Documented Code for datatool v2.27}
 
   \item[INSTALL] Installation instructions.
 
@@ -2043,6 +2043,122 @@ produces:
 \renewcommand*{\DTLinitialhyphen}{}\relax
 \DTLinitials{Marie-{\'E}lise del~Rosario}}
 
+\chapter{Comma-Separated Lists}
+\label{sec:csvlists}
+
+The \styfmt{datatool-base} package automatically loads the
+\sty{etoolbox} package, so you can use any of the list
+commands provided by that package, or you can use
+the internal command \cs{@for} provided by the \LaTeX\ kernel
+(and modified by the \sty{xfor} package, which is also loaded
+by \styfmt{datatool-base}).
+
+In addition to those commands, \styfmt{datatool-base}
+provides some commands that deal with comma-separated lists.
+Note that this just refers to a control sequence that stores
+a list of elements separated by commands, for example:
+\begin{verbatim}
+\newcommand{\mylist}{elephant,ant,zebra,duck}
+\end{verbatim}
+This isn't the same as comma-separated files, which is dealt
+with in \sectionref{sec:databases}.
+
+\begin{definition}[\DescribeMacro\dtlsortlist]
+\cs{dtlsortlist}\marg{list cs}\marg{criteria cs}
+\end{definition}
+This sorts the comma-separated list stored in the command
+\meta{list cs} according to the criteria command
+\meta{criteria cs}. The criteria command must take three arguments:
+a count register in which to store the result, element \meta{A} and
+element \meta{B}. If \meta{A} is considered less that \meta{B}, the
+count register should be set to $-1$, if \meta{A} and \meta{B} are
+considered the same then the count register should be set to 0,
+and if \meta{A} is considered greater than \meta{B}, then the count
+register should be set to 1.
+
+The \styfmt{datatool-base} package provides some predefined
+criteria commands:
+\begin{definition}[\DescribeMacro\dtlcompare]
+\cs{dtlcompare}\marg{register}\marg{A}\marg{B}
+\end{definition}
+A case-sensitive comparison.
+\begin{definition}[\DescribeMacro\dtlicompare]
+\cs{dtlicompare}\marg{register}\marg{A}\marg{B}
+\end{definition}
+A case-insensitive comparison.
+\begin{definition}[\DescribeMacro\dtlwordindexcompare]
+\cs{dtlwordindexcompare}\marg{register}\marg{A}\marg{B}
+\end{definition}
+English word-ordering comparison for indexes, as described by 
+the Oxford Style Manual.
+\begin{definition}[\DescribeMacro\dtlletterindexcompare]
+\cs{dtlletterindexcompare}\marg{register}\marg{A}\marg{B}
+\end{definition}
+English letter-ordering comparison for indexes.
+Those last two commands are described in more detail in
+\sectionref{sec:sort}.
+
+For example:
+\begin{verbatim}
+\newcommand{\mylist}{elephant,ant,zebra,duck}
+\dtlsortlist{\mylist}{\dtlcompare}
+
+\mylist.
+\end{verbatim}
+produces:
+\begin{display}
+\newcommand{\mylist}{elephant,ant,zebra,duck}
+\dtlsortlist{\mylist}{\dtlcompare}
+
+\mylist.
+\end{display}
+
+If you are building up a list, you may prefer to use:
+\begin{definition}[\DescribeMacro\dtlinsertinto]
+\cs{dtlinsertinto}\marg{element}\marg{list cs}\marg{criteria cs}
+\end{definition}
+which inserts \meta{element} into the list stored in the
+command \meta{list cs} according to the criteria command
+\meta{criteria cs}. This is more efficient than first building the
+list and then sorting it.
+
+For example:
+\begin{verbatim}
+\newcommand{\mylist}{}
+\dtlinsertinto{elephant}{\mylist}{\dtlcompare}
+\dtlinsertinto{ant}{\mylist}{\dtlcompare}
+\dtlinsertinto{zebra}{\mylist}{\dtlcompare}
+\dtlinsertinto{duck}{\mylist}{\dtlcompare}
+
+\mylist.
+\end{verbatim}
+produces:
+\begin{display}
+\newcommand{\mylist}{}
+\dtlinsertinto{elephant}{\mylist}{\dtlcompare}
+\dtlinsertinto{ant}{\mylist}{\dtlcompare}
+\dtlinsertinto{zebra}{\mylist}{\dtlcompare}
+\dtlinsertinto{duck}{\mylist}{\dtlcompare}
+
+\mylist.
+\end{display}
+
+Note that \cs{dtlinsertinto} doesn't expand \meta{element}.
+If the element is stored in a command, you need to
+expand it first. For example:
+\begin{verbatim}
+\newcommand*{\element}{ant}
+\expandafter\dtlinsertinto\expandafter{\element}{\mylist}{\dtlcompare}
+\end{verbatim}
+
+To ensure that the element is first fully expanded, you can
+use:
+\begin{definition}[\DescribeMacro\edtlinsertinto]
+\cs{edtlinsertinto}\marg{element}\marg{list cs}\marg{criteria cs}
+\end{definition}
+This will fully expand \meta{element} using \cs{protected@edef}
+and then use \cs{dtlinsertinto}.
+
 \chapter{Databases}
 \label{sec:databases}
 
@@ -4522,9 +4638,9 @@ the data type for a given key, and uses this to determine whether
 an alphabetical or numerical sort is required.
 
 The final argument \meta{handler} is the command used for the
-comparisons. These handlers are described in more detail on
-page~\pageref*{src:dtlcompare} of the documented code (datatool-code.pdf). The following 
-handlers are provided:
+comparisons and is the same as the \meta{criteria cs} command
+used by \cs{dtlsortlist} and \cs{dtlinsertinto}, described
+in \sectionref{sec:csvlists}. The predefined handlers are:
 \begin{description}
 \item[\ics{dtlcompare}] A case-sensitive comparison.
 \item[\ics{dtlicompare}] A case-insensitive comparison.
diff --git a/Master/texmf-dist/doc/latex/datatool/samples/sample-autokeys.pdf b/Master/texmf-dist/doc/latex/datatool/samples/sample-autokeys.pdf
index d9f777bafbd..066a7dacb8d 100644
--- a/Master/texmf-dist/doc/latex/datatool/samples/sample-autokeys.pdf
+++ b/Master/texmf-dist/doc/latex/datatool/samples/sample-autokeys.pdf
diff --git a/Master/texmf-dist/doc/latex/datatool/samples/sample-barchart.pdf b/Master/texmf-dist/doc/latex/datatool/samples/sample-barchart.pdf
index 85179d1124e..8cfeed51c1f 100644
--- a/Master/texmf-dist/doc/latex/datatool/samples/sample-barchart.pdf
+++ b/Master/texmf-dist/doc/latex/datatool/samples/sample-barchart.pdf
diff --git a/Master/texmf-dist/doc/latex/datatool/samples/sample-datatooltk.pdf b/Master/texmf-dist/doc/latex/datatool/samples/sample-datatooltk.pdf
index adff6e25539..3edcf8f6282 100644
--- a/Master/texmf-dist/doc/latex/datatool/samples/sample-datatooltk.pdf
+++ b/Master/texmf-dist/doc/latex/datatool/samples/sample-datatooltk.pdf
diff --git a/Master/texmf-dist/doc/latex/datatool/samples/sample-dict.pdf b/Master/texmf-dist/doc/latex/datatool/samples/sample-dict.pdf
index 538a773ff66..0b3c08d8ea7 100644
--- a/Master/texmf-dist/doc/latex/datatool/samples/sample-dict.pdf
+++ b/Master/texmf-dist/doc/latex/datatool/samples/sample-dict.pdf
diff --git a/Master/texmf-dist/doc/latex/datatool/samples/sample-europecv-bib.pdf b/Master/texmf-dist/doc/latex/datatool/samples/sample-europecv-bib.pdf
index 87b21abc0f0..354505fe7c0 100644
--- a/Master/texmf-dist/doc/latex/datatool/samples/sample-europecv-bib.pdf
+++ b/Master/texmf-dist/doc/latex/datatool/samples/sample-europecv-bib.pdf
diff --git a/Master/texmf-dist/doc/latex/datatool/samples/sample-gidx.pdf b/Master/texmf-dist/doc/latex/datatool/samples/sample-gidx.pdf
index 0e6b95463da..3f45901c694 100644
--- a/Master/texmf-dist/doc/latex/datatool/samples/sample-gidx.pdf
+++ b/Master/texmf-dist/doc/latex/datatool/samples/sample-gidx.pdf
diff --git a/Master/texmf-dist/doc/latex/datatool/samples/sample-glossary.pdf b/Master/texmf-dist/doc/latex/datatool/samples/sample-glossary.pdf
index 06296653448..d2969ec2cb5 100644
--- a/Master/texmf-dist/doc/latex/datatool/samples/sample-glossary.pdf
+++ b/Master/texmf-dist/doc/latex/datatool/samples/sample-glossary.pdf
diff --git a/Master/texmf-dist/doc/latex/datatool/samples/sample-index.pdf b/Master/texmf-dist/doc/latex/datatool/samples/sample-index.pdf
index 2d5038a0451..35e8bdd2a68 100644
--- a/Master/texmf-dist/doc/latex/datatool/samples/sample-index.pdf
+++ b/Master/texmf-dist/doc/latex/datatool/samples/sample-index.pdf
diff --git a/Master/texmf-dist/doc/latex/datatool/samples/sample-mail-merge.pdf b/Master/texmf-dist/doc/latex/datatool/samples/sample-mail-merge.pdf
index 7a68eae9c54..b6966f6ef30 100644
--- a/Master/texmf-dist/doc/latex/datatool/samples/sample-mail-merge.pdf
+++ b/Master/texmf-dist/doc/latex/datatool/samples/sample-mail-merge.pdf
diff --git a/Master/texmf-dist/doc/latex/datatool/samples/sample-piechart.pdf b/Master/texmf-dist/doc/latex/datatool/samples/sample-piechart.pdf
index 50ffa2b949b..6bd3622cb87 100644
--- a/Master/texmf-dist/doc/latex/datatool/samples/sample-piechart.pdf
+++ b/Master/texmf-dist/doc/latex/datatool/samples/sample-piechart.pdf
diff --git a/Master/texmf-dist/doc/latex/datatool/samples/sample-sort.pdf b/Master/texmf-dist/doc/latex/datatool/samples/sample-sort.pdf
index 6fbc9418403..5a2b5fc0220 100644
--- a/Master/texmf-dist/doc/latex/datatool/samples/sample-sort.pdf
+++ b/Master/texmf-dist/doc/latex/datatool/samples/sample-sort.pdf
diff --git a/Master/texmf-dist/doc/latex/datatool/samples/sample-student-scores.pdf b/Master/texmf-dist/doc/latex/datatool/samples/sample-student-scores.pdf
index 773f0373444..7e6084b0e8d 100644
--- a/Master/texmf-dist/doc/latex/datatool/samples/sample-student-scores.pdf
+++ b/Master/texmf-dist/doc/latex/datatool/samples/sample-student-scores.pdf
diff --git a/Master/texmf-dist/doc/latex/datatool/samples/sample-two-per-row.pdf b/Master/texmf-dist/doc/latex/datatool/samples/sample-two-per-row.pdf
index 2490cf7f781..8d2778b94c4 100644
--- a/Master/texmf-dist/doc/latex/datatool/samples/sample-two-per-row.pdf
+++ b/Master/texmf-dist/doc/latex/datatool/samples/sample-two-per-row.pdf