From e8825f013e999a146ec53c7646086ac24d4adc8e Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Sat, 30 Jul 2016 23:10:06 +0000 Subject: datatool (28jul16) git-svn-id: svn://tug.org/texlive/trunk@41772 c570f23f-e606-0410-a88d-b1316a301751 --- Master/texmf-dist/doc/latex/datatool/CHANGES | 17 +++ Master/texmf-dist/doc/latex/datatool/README | 4 +- .../doc/latex/datatool/datatool-code.pdf | Bin 1170895 -> 1175201 bytes .../doc/latex/datatool/datatool-user.pdf | Bin 613586 -> 631018 bytes .../doc/latex/datatool/datatool-user.tex | 128 ++++++++++++++++++++- .../doc/latex/datatool/samples/sample-autokeys.pdf | Bin 24923 -> 24923 bytes .../doc/latex/datatool/samples/sample-barchart.pdf | Bin 35068 -> 35068 bytes .../latex/datatool/samples/sample-datatooltk.pdf | Bin 22860 -> 22860 bytes .../doc/latex/datatool/samples/sample-dict.pdf | Bin 122588 -> 122588 bytes .../latex/datatool/samples/sample-europecv-bib.pdf | Bin 89557 -> 89557 bytes .../doc/latex/datatool/samples/sample-gidx.pdf | Bin 179545 -> 179722 bytes .../doc/latex/datatool/samples/sample-glossary.pdf | Bin 104200 -> 104379 bytes .../doc/latex/datatool/samples/sample-index.pdf | Bin 128779 -> 128779 bytes .../latex/datatool/samples/sample-mail-merge.pdf | Bin 21618 -> 21631 bytes .../doc/latex/datatool/samples/sample-piechart.pdf | Bin 33957 -> 33957 bytes .../doc/latex/datatool/samples/sample-sort.pdf | Bin 89724 -> 89724 bytes .../datatool/samples/sample-student-scores.pdf | Bin 34614 -> 34614 bytes .../latex/datatool/samples/sample-two-per-row.pdf | Bin 31751 -> 31751 bytes 18 files changed, 141 insertions(+), 8 deletions(-) (limited to 'Master/texmf-dist/doc') 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 Binary files a/Master/texmf-dist/doc/latex/datatool/datatool-code.pdf and b/Master/texmf-dist/doc/latex/datatool/datatool-code.pdf differ 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 Binary files a/Master/texmf-dist/doc/latex/datatool/datatool-user.pdf and b/Master/texmf-dist/doc/latex/datatool/datatool-user.pdf differ 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 Binary files a/Master/texmf-dist/doc/latex/datatool/samples/sample-autokeys.pdf and b/Master/texmf-dist/doc/latex/datatool/samples/sample-autokeys.pdf differ 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 Binary files a/Master/texmf-dist/doc/latex/datatool/samples/sample-barchart.pdf and b/Master/texmf-dist/doc/latex/datatool/samples/sample-barchart.pdf differ 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 Binary files a/Master/texmf-dist/doc/latex/datatool/samples/sample-datatooltk.pdf and b/Master/texmf-dist/doc/latex/datatool/samples/sample-datatooltk.pdf differ 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 Binary files a/Master/texmf-dist/doc/latex/datatool/samples/sample-dict.pdf and b/Master/texmf-dist/doc/latex/datatool/samples/sample-dict.pdf differ 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 Binary files a/Master/texmf-dist/doc/latex/datatool/samples/sample-europecv-bib.pdf and b/Master/texmf-dist/doc/latex/datatool/samples/sample-europecv-bib.pdf differ 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 Binary files a/Master/texmf-dist/doc/latex/datatool/samples/sample-gidx.pdf and b/Master/texmf-dist/doc/latex/datatool/samples/sample-gidx.pdf differ 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 Binary files a/Master/texmf-dist/doc/latex/datatool/samples/sample-glossary.pdf and b/Master/texmf-dist/doc/latex/datatool/samples/sample-glossary.pdf differ 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 Binary files a/Master/texmf-dist/doc/latex/datatool/samples/sample-index.pdf and b/Master/texmf-dist/doc/latex/datatool/samples/sample-index.pdf differ 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 Binary files a/Master/texmf-dist/doc/latex/datatool/samples/sample-mail-merge.pdf and b/Master/texmf-dist/doc/latex/datatool/samples/sample-mail-merge.pdf differ 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 Binary files a/Master/texmf-dist/doc/latex/datatool/samples/sample-piechart.pdf and b/Master/texmf-dist/doc/latex/datatool/samples/sample-piechart.pdf differ 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 Binary files a/Master/texmf-dist/doc/latex/datatool/samples/sample-sort.pdf and b/Master/texmf-dist/doc/latex/datatool/samples/sample-sort.pdf differ 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 Binary files a/Master/texmf-dist/doc/latex/datatool/samples/sample-student-scores.pdf and b/Master/texmf-dist/doc/latex/datatool/samples/sample-student-scores.pdf differ 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 Binary files a/Master/texmf-dist/doc/latex/datatool/samples/sample-two-per-row.pdf and b/Master/texmf-dist/doc/latex/datatool/samples/sample-two-per-row.pdf differ -- cgit v1.2.3