summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/datatool
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2013-01-15 23:01:04 +0000
committerKarl Berry <karl@freefriends.org>2013-01-15 23:01:04 +0000
commit6d3800d3b164704c4038f84408b27f759a4ea744 (patch)
tree6d56ebd38457cb5f2d7bcbe628157f861fecdaae /Master/texmf-dist/doc/latex/datatool
parent607c25d782c2e57a60ab2f2ecf30c12e238b44ec (diff)
datatool (15jan13)
git-svn-id: svn://tug.org/texlive/trunk@28844 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex/datatool')
-rw-r--r--Master/texmf-dist/doc/latex/datatool/CHANGES60
-rw-r--r--Master/texmf-dist/doc/latex/datatool/README4
-rw-r--r--Master/texmf-dist/doc/latex/datatool/datatool-code.pdfbin0 -> 895574 bytes
-rw-r--r--Master/texmf-dist/doc/latex/datatool/datatool-user.pdfbin498420 -> 581788 bytes
-rw-r--r--Master/texmf-dist/doc/latex/datatool/datatool-user.tex1751
-rw-r--r--Master/texmf-dist/doc/latex/datatool/datatool.pdfbin732089 -> 0 bytes
-rw-r--r--Master/texmf-dist/doc/latex/datatool/samples/sample-barchart.pdfbin35087 -> 35075 bytes
-rw-r--r--Master/texmf-dist/doc/latex/datatool/samples/sample-dict.pdfbin0 -> 122644 bytes
-rw-r--r--Master/texmf-dist/doc/latex/datatool/samples/sample-dict.tex439
-rw-r--r--Master/texmf-dist/doc/latex/datatool/samples/sample-gidx.pdfbin0 -> 179583 bytes
-rw-r--r--Master/texmf-dist/doc/latex/datatool/samples/sample-gidx.tex644
-rw-r--r--Master/texmf-dist/doc/latex/datatool/samples/sample-glossary.pdfbin0 -> 104382 bytes
-rw-r--r--Master/texmf-dist/doc/latex/datatool/samples/sample-glossary.tex245
-rw-r--r--Master/texmf-dist/doc/latex/datatool/samples/sample-index.pdfbin0 -> 128860 bytes
-rw-r--r--Master/texmf-dist/doc/latex/datatool/samples/sample-index.tex735
-rw-r--r--Master/texmf-dist/doc/latex/datatool/samples/sample-mail-merge.pdfbin19543 -> 21893 bytes
-rw-r--r--Master/texmf-dist/doc/latex/datatool/samples/sample-mail-merge.tex2
-rw-r--r--Master/texmf-dist/doc/latex/datatool/samples/sample-piechart.pdfbin33969 -> 33957 bytes
-rw-r--r--Master/texmf-dist/doc/latex/datatool/samples/sample-sort.tex118
-rw-r--r--Master/texmf-dist/doc/latex/datatool/samples/sample-student-scores.pdfbin34628 -> 34615 bytes
-rw-r--r--Master/texmf-dist/doc/latex/datatool/samples/sample-two-per-row.pdfbin31764 -> 31752 bytes
21 files changed, 3965 insertions, 33 deletions
diff --git a/Master/texmf-dist/doc/latex/datatool/CHANGES b/Master/texmf-dist/doc/latex/datatool/CHANGES
index 10191efabdc..aafffbec6b0 100644
--- a/Master/texmf-dist/doc/latex/datatool/CHANGES
+++ b/Master/texmf-dist/doc/latex/datatool/CHANGES
@@ -1,5 +1,65 @@
+v2.13:
+
+ * Added new package `datagidx'
+
+ - create glossaries/indexes /without/ using an external tool such
+ as makeindex or xindy
+
+ * datatool.sty
+
+ - added \dtlsort (like \DTLsort but user supplies custom
+ comparison handler).
+
+ - added \DTLgnewdb, \DTLgdeletedb, \DTLgcleardb
+
+ - added \DTLsaverawdb
+
+ - added \ifDTLnewdbonload, \DTLnewdbonloadtrue,
+ \DTLnewdbonloadfalse
+
+ - added \dtlparsewords
+
+ - fixed bug in \@DTLnewrow (misspelt \PackageError command)
+
+ - removed spurious space in \@dtl@setheaderforindex
+
+ - removed spurious space in \DTLaddentryforrow
+
+ - removed spurious space in \DTLdisplaydb and \DTLdisplaylongdb
+
+ - removed spurious space in \@dtl@getsortdirection
+
+ - removed spurious space in \@dtl@readline
+
+ - removed spurious space in \DTLrawmap
+
+ - \dtl@setcharcode and \dtl@setlccharcode now check
+ for \@dtl@wordbreak instead of space and tilde
+
+ - \dtl@setlccharcode bug fix (characters without a lowercase
+ now correctly dealt with)
+
+ - \dtlicompare and \dtl@teststartswith now use
+ \dtl@setwordbreaksnohyphens to deal with spaces
+
+ - added \@dtlstringnull and \@dtlnumbernull and fixed bug in
+ \DTLifnull
+
+ - renamed datatool.pdf to datatool-code.pdf
+
+ * datatool-base.sty
+
+ - added \dtlwordindexcompare
+
v2.12:
+ * datatool.sty:
+
+ - fixed bug in \DTLiflastrow
+
+ - Fixed bug causing spurious space in \DTLloaddb
+
+
* datatool-pgfmath.sty:
- fixed bug in conditionals.
diff --git a/Master/texmf-dist/doc/latex/datatool/README b/Master/texmf-dist/doc/latex/datatool/README
index 8395e3a7e3c..b344b39a9bb 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.11
+LaTeX Bundle : datatool v2.13
-Last Modified : 2012-09-25
+Last Modified : 2013-01-15
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
new file mode 100644
index 00000000000..38a648fb1f4
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/datatool/datatool-code.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/latex/datatool/datatool-user.pdf b/Master/texmf-dist/doc/latex/datatool/datatool-user.pdf
index 96450e7b940..cc86ab5d26e 100644
--- a/Master/texmf-dist/doc/latex/datatool/datatool-user.pdf
+++ b/Master/texmf-dist/doc/latex/datatool/datatool-user.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/latex/datatool/datatool-user.tex b/Master/texmf-dist/doc/latex/datatool/datatool-user.tex
index 6560eb60c0c..a38dc6c7060 100644
--- a/Master/texmf-dist/doc/latex/datatool/datatool-user.tex
+++ b/Master/texmf-dist/doc/latex/datatool/datatool-user.tex
@@ -2,11 +2,13 @@
\usepackage{ifthen}
\usepackage[verbose=false]{datatool}
-\usepackage{datapie,databar,databib,person}
+\usepackage{datapie,databar,databib,person,datagidx}
\usepackage{textcomp}
\usepackage{graphicx}
\usepackage{colortbl}
+\usepackage{booktabs}
\usepackage{cmap}
+\usepackage{alltt}
\usepackage[T1]{fontenc}
\usepackage[utf8]{inputenc}
\ifpdf
@@ -29,7 +31,7 @@
\setcounter{IndexColumns}{2}
\ifpdf
- \externaldocument{datatool}
+ \externaldocument{datatool-code}
\fi
\doxitem{Counter}{counter}{counters}
@@ -47,6 +49,39 @@
\DTLnewdbentry{docbib}{Publisher}{Addison-Wesley}
\DTLnewdbentry{docbib}{Year}{1994}
+ % datagidx index example database
+
+\newgidx{gidx-index}{Index}% define a database for the index
+
+\DTLgidxSetDefaultDB{gidx-index}% set this as the default
+
+\newterm{mac\'edoine}
+\newterm{macram\'e}
+\newterm[label=elite]{{\'e}lite}
+\newterm{reptile}
+\newterm[seealso={reptile}]{crocodylian}
+
+\newterm
+ [%
+ parent=crocodylian
+ ]
+ {crocodile}
+
+\newterm
+ [%
+ parent=crocodylian
+ ]
+ {alligator}
+
+\newterm
+ [%
+ parent=crocodylian,
+ description={(also cayman)}
+ ]
+ {caiman}
+
+\newterm[see={caiman}]{cayman}
+
\begin{document}
% Some of the commands are too long to produce nicely formatted
@@ -56,11 +91,11 @@
\MakeShortVerb{"}
\DeleteShortVerb{\|}
- \title{User Manual for datatool bundle version~2.11}
+ \title{User Manual for datatool bundle version~2.13}
\author{Nicola L.C. Talbot\\
\url{http://www.dickimaw-books.com/}}
- \date{2012-09-25}
+ \date{2013-01-15}
\maketitle
\pagenumbering{roman}
@@ -72,10 +107,10 @@ The \styfmt{datatool} bundle comes with the following documentation:
This document is the main user guide for the \styfmt{datatool}
bundle.
- \item[\url{datatool.pdf}]
+ \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.11}
+ read \qt{Documented Code for datatool v2.13}
\item[INSTALL] Installation instructions.
@@ -85,11 +120,21 @@ The \styfmt{datatool} bundle comes with the following documentation:
\end{description}
\begin{important}
+There's an old adage, ``use the right tool for the right job.''
+A carpenter's fine chisel is the right tool for delicate carving,
+but if you try to use it to hack off a tree branch it will take a
+long time. That doesn't mean there's something wrong with the
+chisel. It just means you're using the wrong tool for the job.
+
The \styfmt{datatool} bundle is provided to help perform repetitive
commands, such as mail merging, but since \TeX\ is designed as a
typesetting language, don't expect this bundle to perform as
-efficiently as custom database systems or a dedicated mathematical or
-scripting language.
+efficiently as custom database systems or a dedicated mathematical
+or scripting language. If the provided packages take a frustratingly
+long time to compile your document, use another language to perform
+your calculations or data manipulation and save the results in a
+file that can be input into your document.
+
\end{important}
This bundle consists of the following packages:
@@ -1978,7 +2023,11 @@ from this package.
\begin{definition}[\DescribeMacro{\DTLnewdb}]%
\cs{DTLnewdb}\marg{db name}
\end{definition}
-This command creates a new empty database called \meta{db name}. You
+\begin{definition}[\DescribeMacro{\DTLgnewdb}]%
+\cs{DTLgnewdb}\marg{db name}
+\end{definition}
+This command creates a new empty database called \meta{db name}. The
+second form is for global definitions. You
can test if a database is empty using:
\begin{definition}[\DescribeMacro{\DTLifdbempty}]%
\cs{DTLifdbempty}\marg{db name}\marg{true part}\marg{false part}
@@ -2140,9 +2189,17 @@ in your document:
\usepackage[utf8]{inputenc}
\end{verbatim}
\end{important}
-This creates a new database called \meta{db name}, and fills
-it with the entries given in the file \meta{filename}.
-The filename may have a header row at the start of the file,
+By default, \cs{DTLloaddb} creates a new database called \meta{db
+name} before it loads the data given in the file \meta{filename}.
+If you want to append the data, use
+\begin{definition}[\DTLnewdbonloadfalse]
+\cs{DTLnewdbonloadfalse}
+\end{definition}
+before you use \cs{DTLloaddb}. You can reverse this using
+\begin{definition}[\DTLnewdbonloadtrue]
+\cs{DTLnewdbonloadtrue}
+\end{definition}
+The file (\meta{filename}) may have a header row at the start of the file,
which provides the \meta{key} when creating a new database entry
using \ics{DTLnewdbentry}. The optional argument \meta{options}
is a key=value list of options. Available options are:
@@ -2278,6 +2335,9 @@ is equivalent to:
\DTLnewdbentry{mydata}{Product}{Stationary}%
\DTLnewdbentry{mydata}{Cost}{\$0.80}%
\end{verbatim}
+As with \ics{DTLloaddb}, you can govern whether or not a new
+database should be created with \ics{DTLnewdbonloadtrue} and
+\ics{DTLnewdbonloadfalse}.
\begin{table}[htbp]
\caption[Special character mappings used by
@@ -2860,6 +2920,12 @@ the following conditionals may be used:
If the current row is the first row, then do \meta{true part},
otherwise do \meta{false part}.
+\begin{definition}[\DescribeMacro{\DTLiflastrow}]%
+\cs{DTLiflastrow}\marg{true part}\marg{false part}
+\end{definition}
+If the current row is the last row, then do \meta{true part},
+otherwise do \meta{false part}.
+
\begin{definition}[\DescribeMacro{\DTLifoddrow}]%
\cs{DTLifoddrow}\marg{true part}\marg{false part}
\end{definition}
@@ -2897,7 +2963,7 @@ until the end of the current iteration. There is no provision for
a "next" or "continue" style command.
Additional loop commands provided by \sty{datatool} are
-described in the documented code (datatool.pdf).
+described in the documented code (datatool-code.pdf).
\begin{example}{Student Scores---Labelling}{ex:label}
In the previous example, the student scores, stored in the
@@ -3048,6 +3114,54 @@ This produces \autoref{tab:Bscores}.
\end{example}
+\begin{example}{Checking for the First Row (booktabs)}{ex:iffirst}
+Suppose I want to use the \sty{booktabs} package and I want to use
+\ics{midrule} after the header row. I can use \ics{DTLiffirstrow} to
+check if the loop is on the first row of the iteration. (Remember
+that you need to load the \sty{booktabs} package in the preamble
+with \cs{usepackage}.) Using the same database as before:
+\begin{verbatim}
+\begin{table}[htbp]
+\caption{Student scores (booktabs)}
+\centering
+\begin{tabular}{llc}
+\toprule
+\bfseries First Name &
+\bfseries Surname &
+\bfseries Score (\%)%
+\DTLforeach*{scores}%
+ {\firstname=FirstName,\surname=Surname,\score=Score}%
+ {%
+ \DTLiffirstrow{\\\midrule}{\\}%
+ \firstname & \surname & \score
+ }% end of loop
+ \\\bottomrule
+\end{tabular}%
+\end{table}
+\end{verbatim}
+(The commands \ics{toprule}, \ics{midrule} and \ics{bottomrule} are
+all provided by \sty{booktabs}.) This produces
+\autoref{tab:iffirst}.
+
+\begin{table}[htbp]
+\caption{Student scores (booktabs)}
+\label{tab:iffirst}
+\centering
+\begin{tabular}{llc}
+\toprule
+\bfseries First Name &
+\bfseries Surname &
+\bfseries Score (\%)%
+\DTLforeach*{scores}{%
+\firstname=FirstName,\surname=Surname,\score=Score}{%
+\DTLiffirstrow{\\\midrule}{\\}%
+\firstname & \surname & \score}%
+\\\bottomrule
+\end{tabular}%
+\end{table}
+
+\end{example}
+
\begin{example}{Breaking Out of a Loop}{ex:dtlbreak}
Suppose I only want to display the first three rows of a database.
I could do:\footnote{Recall that \ctr{DTLrowi} is incremented
@@ -4219,11 +4333,9 @@ To determine a person's gender when mail merging, see
\section{Sorting a Database}
\label{sec:sort}
-\begin{definition}[\DescribeMacro{\DTLsort}]%
-\cs{DTLsort}\oarg{replacement key list}\marg{sort criteria}\marg{db name}
-\end{definition}
-\begin{definition}[\DescribeMacro{\DTLsort*}]%
-\cs{DTLsort*}\oarg{replacement key list}\marg{sort criteria}\marg{db name}
+\begin{definition}[\DescribeMacro{\dtlsort}]%
+\cs{dtlsort}\oarg{replacement key list}\marg{sort criteria}\marg{db
+name}\marg{handler}
\end{definition}
This will sort the database called \meta{db name} according to
the criteria given by \meta{sort criteria}, which must be a
@@ -4231,9 +4343,131 @@ comma separated list of keys and optionally "="\meta{order}, where
\meta{order} is either "ascending" or "descending". If the order
is omitted, "ascending" is assumed. The database keeps track of
the data type for a given key, and uses this to determine whether
-an alphabetical or numerical sort is required. (String comparisons
-are made using the command \cs{dtlcompare} or \cs{dtlicompare}
-described in \autoref{src:dtlcompare}.)
+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 in
+\autoref{src:dtlcompare} of the documented code. The following
+handlers are provided:
+\begin{description}
+\item[\ics{dtlcompare}] A case-sensitive comparison.
+\item[\ics{dtlicompare}] A case-insensitive comparison.
+\item[\ics{dtlwordindexcompare}] English word-ordering comparison
+for indexes, as described by the Oxford Style Manual.
+\item[\ics{dtlletterindexcompare}] English letter-ordering
+comparison for indexes.
+\end{description}
+The last two handlers, \cs{dtlwordindexcompare} and
+\cs{dtlletterindexcompare}, assume that inversion commas are
+indicated using one of the following commands:
+\begin{itemize}
+\item To indicate name inversion:
+\begin{definition}[\DescribeMacro\datatoolpersoncomma]
+\cs{datatoolpersoncomma}
+\end{definition}
+Example: \verb|Knuth\datatoolpersoncomma Donald E.|
+
+\item To indicate place inversion:
+\begin{definition}[\DescribeMacro\datatoolplacecomma]
+\cs{datatoolplacecomma}
+\end{definition}
+Example:
+\verb|New York\datatoolplacecomma USA|
+
+\item To indicate subject inversion:
+\begin{definition}[\DescribeMacro\datatoolsubjectcomma]
+\cs{datatoolsubjectcomma}
+\end{definition}
+Example: \verb|New York\datatoolsubjectcomma population|
+\end{itemize}
+In addition, the start of parenthetical material should be indicated
+with
+\begin{definition}[\DescribeMacro\datatoolparenstart]
+\cs{datatoolparenstart}
+\end{definition}
+Example: \verb|High Water\datatoolparenstart play|
+
+Following the guidelines of the Oxford Style Manual, when sorting
+terms that have identical pre-inversion parts, the following
+ordering is applied: people, places, subjects, no inversions and
+parenthetical.
+
+\begin{example}{Sorting a Database---Dealing with
+Inversions}{ex:sortinversion}
+This uses the example given in Chapter~16 of the Oxford Style
+Manual. Suppose I~define my database as follows:
+\begin{verbatim}
+\DTLnewdb{inversiondata}
+\DTLnewrow{inversiondata}
+\DTLnewdbentry{inversiondata}{Term}{New York, New York}
+\DTLnewrow{inversiondata}
+\DTLnewdbentry{inversiondata}{Term}{New York\datatoolsubjectcomma
+population}
+\DTLnewrow{inversiondata}
+\DTLnewdbentry{inversiondata}{Term}{New York\datatoolplacecomma
+USA}
+\DTLnewrow{inversiondata}
+\DTLnewdbentry{inversiondata}{Term}{New York\datatoolpersoncomma
+Earl of}
+\end{verbatim}
+\DTLnewdb{inversiondata}
+\DTLnewrow{inversiondata}
+\DTLnewdbentry{inversiondata}{Term}{New York, New York}
+\DTLnewrow{inversiondata}
+\DTLnewdbentry{inversiondata}{Term}{New York\datatoolsubjectcomma
+population}
+\DTLnewrow{inversiondata}
+\DTLnewdbentry{inversiondata}{Term}{New York\datatoolplacecomma
+USA}
+\DTLnewrow{inversiondata}
+\DTLnewdbentry{inversiondata}{Term}{New York\datatoolpersoncomma
+Earl of}
+
+First of all, display the unsorted data:
+\begin{verbatim}
+\DTLdisplaydb{inversiondata}
+\end{verbatim}
+This produces:
+
+\DTLdisplaydb{inversiondata}
+
+Now sort the data using the \ics{dtlwordindexcompare} handler:
+\begin{verbatim}
+\dtlsort{Term}{inversiondata}{\dtlwordindexcompare}
+\end{verbatim}
+\dtlsort{Term}{inversiondata}{\dtlwordindexcompare}%
+and display again:
+\begin{verbatim}
+\DTLdisplaydb{inversiondata}
+\end{verbatim}
+which now produces:
+
+\DTLdisplaydb{inversiondata}
+
+~here are three entries with pre-inversion text as simply
+\texttt{New York}. Since each of these three entries has the same
+pre-inversion text, they need to be sorted according to the type of
+inversion: person, place, subject. The fourth entry (New York, New
+York) doesn't have an inversion since the comma is part of the title
+of the named work. It's therefore sorted according to \texttt{New
+York, New York} rather than just \texttt{New York} and so comes
+after all the \texttt{New York} entries.
+\end{example}
+
+If you want to write your own comparison handler, see the documented
+code for details on the syntax of the handler. (You may want to
+consider uploading your handler as a separate package to CTAN if you
+think it will be of general use.)
+
+There are two shortcut commands:
+\begin{definition}[\DescribeMacro{\DTLsort}]%
+\cs{DTLsort}\oarg{replacement key list}\marg{sort criteria}\marg{db name}
+\end{definition}
+\begin{definition}[\DescribeMacro{\DTLsort*}]%
+\cs{DTLsort*}\oarg{replacement key list}\marg{sort criteria}\marg{db name}
+\end{definition}
+these use the \ics{dtlcompare} and \ics{dtlicompare} handlers,
+respectively.
The optional argument \meta{replacement key list} is a list of
keys to use if the current key given in \meta{sort criteria}
@@ -4511,6 +4745,12 @@ This produces \autoref{tab:influencesort}.
\section{Saving a Database to an External File}
\label{sec:savedb}
+\begin{important}
+\TeX's write mechanism automatically inserts linebreaks every 80
+characters. This may cause problems if you have long entries in your
+database.
+\end{important}
+
\begin{definition}[\DescribeMacro{\DTLsavedb}]%
\cs{DTLsavedb}\marg{db name}\marg{filename}
\end{definition}
@@ -4532,7 +4772,15 @@ given entry contains the separator character.)
This writes the database called \meta{db name} to a \LaTeX\ file
called \meta{filename}, where the database is stored as
a combination of \ics{DTLnewdb}, \ics{DTLnewrow} and
-\ics{DTLnewdbentry} commands.
+\ics{DTLnewdbentry} commands. This means that the file is in a
+user-friendly format, but may be so to load, particularly if the
+database is large. If you are more concerned with speed rather than
+readability you can use:
+\begin{definition}[\DescribeMacro{\DTLsaverawdb}]%
+\cs{DTLsaverawdb}\marg{db name}\marg{filename}
+\end{definition}
+This saves the database to \meta{filename} in its internal
+representation, which makes it faster to load.
\section{Deleting or Clearing a Database}\label{sec:deletedb}
@@ -4541,19 +4789,42 @@ longer required.
\begin{definition}[\DescribeMacro{\DTLcleardb}]
\cs{DTLcleardb}\marg{db name}
\end{definition}
+\begin{definition}[\DescribeMacro{\DTLgcleardb}]
+\cs{DTLgcleardb}\marg{db name}
+\end{definition}
Clears the database given by \meta{db name}. The database is emptied
-but remains defined.
+but remains defined. The second form is required if you want a
+global effect.
\begin{definition}[\DescribeMacro{\DTLdeletedb}]
\cs{DTLdeletedb}\marg{db name}
\end{definition}
-Deletes (undefines) the database given by \meta{db name}.
+\begin{definition}[\DescribeMacro{\DTLgdeletedb}]
+\cs{DTLgdeletedb}\marg{db name}
+\end{definition}
+Deletes (undefines) the database given by \meta{db name}. The second
+form is required if you want a global effect.
+
+\begin{important}
+Although \cs{DTLdeletedb} and \cs{DTLgdeletedb} undefine the macros
+associated with the database, they don't unassign the registers
+used. (\TeX\ doesn't provide a command that performs the reverse of
+commands such as \cs{newcount}.) If you want to keep making
+temporary databases, it's better to just define a single database
+(called, say, \texttt{temp}) and then just clear it rather than
+delete it and define a new database. For example, if you are
+iterating through a loop and want to have a temporary database
+on each iteration. In that case, define the database before the
+start of the loop and clear it on each iteration. If you are loading
+data from an external file, remember to use \ics{DTLnewdbonloadfalse}
+before \ics{DTLloaddb} (or \ics{DTLloadrawdb}).
+\end{important}
\section{Advanced Database Commands}
\label{sec:advanced}
This section describes more advanced commands. Further details
-can be found in the documented code (datatool.pdf).
+can be found in the documented code (datatool-code.pdf).
\begin{definition}[\DescribeMacro{\DTLgetdatatype}]
\cs{DTLgetdatatype}\marg{cs}\marg{db}\marg{key}
@@ -4836,7 +5107,8 @@ argument} error if you specify a row index that is out of range.
\end{definition}
Like \cs{dtlgetrow}, but this gets the row where the entry in column
\meta{column index} matches \meta{value}. This command produces an
-error if no match is found.
+error if no match is found. \textbf{Note that no expansion is
+performed when matching \meta{value}.}
You can use the commands below to access or edit \cs{dtlcurrentrow}, but
they won't change the database. Instead, once you've finished
@@ -4857,7 +5129,7 @@ assume that you haven't altered \cs{dtlrownum}, \cs{dtldbname},
\begin{important}
\cs{dtlcurrentrow} stores the row information using \sty{datatool}'s
-internal row syntax, described in the documented code (datatool.pdf).
+internal row syntax, described in the documented code (datatool-code.pdf).
Don't explicitly modify \cs{dtlcurrentrow} unless you have a good
understanding of the syntax.
\end{important}
@@ -4905,6 +5177,1423 @@ Behaves like \cs{dtlappendentrytocurrentrow} if the current row
doesn't contain an entry for the column given by \meta{key},
otherwise behaves like \cs{dtlreplaceentryincurrentrow}.
+\chapter{Creating an index, glossary or list of acronyms
+(\texorpdfstring{\sty{datagidx}}{datagidx} package)}
+\label{sec:datagidx}
+
+The \sty{datagidx} package is provided as an alternative to the
+\sty{glossaries} package. Rather than relying on an external
+indexing application, such as \app{xindy} or
+\app{makeindex}, it uses the database mechanism of the
+\sty{datatool} package. \emph{\sty{datagidx} and \sty{glossaries}
+are not compatible.}
+
+First a repeat of the caveat at the start of this manual:
+\begin{important}
+Use the right tool for the right job.
+\end{important}
+Don't expect \sty{datagidx} to perform as efficiently as an
+application that is designed specifically to sort and collate entries.
+
+If, however, you are happy to exchange efficiency for the
+convenience of not having to invoke an external application in
+between \LaTeX\ runs, read on.
+
+\section{Defining Index/Glossary Databases}
+
+\begin{important}
+The databases and their associated entries described here can only
+be defined in the preamble. This is because the database must be set
+up before the auxiliary file is read. If you don't want to lose your
+place by constantly returning to the preamble to add a new term
+while you edit your document, consider putting all your definitions
+in a separate file which can be \cs{input} in the preamble.
+You can then switch between files without losing your place
+(provided you are using a decent text editor).
+\end{important}
+
+First you need to define a customised database that will be used to
+store the entries in your index, glossary or list of acronyms:
+\begin{definition}[\DescribeMacro\newgidx]
+\cs{newgidx}\marg{label}\marg{title}
+\end{definition}
+This defines a new database with a unique label and a title.
+For example:
+\begin{verbatim}
+\newgidx{index}{Index}
+\end{verbatim}
+I can now identify this database using the label \texttt{index}. The
+title ``Index'' is the default heading when the database is
+displayed using \cs{printterms} (see \autoref{sec:printterms}).
+
+\section{Locations}
+\label{sec:locations}
+
+Each term in an index or glossary database has an associated
+location list. This is initially null. When you display the database
+using \ics{printterms} (see \autoref{sec:printterms}) only those
+entries with a non-null location list or with a ``see''
+cross-reference are displayed. The location by default is the page
+number on which the entry has been used. This may be changed to
+another counter by redefining
+\begin{definition}[\DescribeMacro\DTLgidxCounter]
+\cs{DTLgidxCounter}
+\end{definition}
+to the name of the required counter. For example:
+\begin{verbatim}
+\renewcommand*{\DTLgidxCounter}{section}
+\end{verbatim}
+The \styfmt{datagidx} package knows about the following counter
+styles: \texttt{arabic}, \texttt{roman}, \texttt{Roman},
+\texttt{alph} and \texttt{Alph}. If your location counter uses a
+different style, you will need to add a new location type. This will
+only work if the counter uses a command that expands to another
+command that takes a number as its argument. For example, suppose I
+want to use small caps Roman numeral page numbering. I need to
+define a command (say \cs{myscroman}) that takes a counter name as
+its argument but expands to another command that takes a number as
+its argument, like this:
+\begin{verbatim}
+\newcommand*{\myscroman}[1]{\myscrromannum{\value{#1}}}
+\newcommand*{\myscromannum}[1]{\textsc{\romannumeral#1}}
+\end{verbatim}
+Note that the font changing command \cs{textsc} is in the definition
+of \cs{myscromannum} not in the definition of \cs{myscroman}.
+The page counter can now be changed so that it uses \cs{myscroman}:
+\begin{verbatim}
+\renewcommand*{\thepage}{\myscroman{page}}
+\end{verbatim}
+I now have to indicate that \cs{myscromannum} is a valid location
+type using:
+\begin{definition}[\DescribeMacro\DTLgidxAddLocationType]
+\cs{DTLgidxAddLocationType}\marg{cs name}
+\end{definition}
+where \meta{cs name} is the name of the control sequence without the
+initial backslash. Like this:
+\begin{verbatim}
+\DTLgidxAddLocationType{myscromannum}
+\end{verbatim}
+Note that this is the command that takes a number as its argument
+(\cs{myscromannum}) not the command that takes a counter name as its
+argument (\cs{myscroman}).
+
+As with \app{makeindex} and \app{xindy}, locations may have
+a compositor. The default compositor is a full stop but may be
+changed by redefining
+\begin{definition}[\DescribeMacro\DTLgidxSetCompositor]
+\cs{DTLgidxSetCompositor}
+\end{definition}
+Alternatively, you can use the package option \pkgopt{compositor}.
+
+\section{Defining Terms}
+\label{sec:newterm}
+
+Once you have defined the database, you can now define terms
+associated with that database using
+\begin{definition}[\DescribeMacro\newterm]
+\cs{newterm}\oarg{options}\marg{name}
+\end{definition}
+where \meta{name} is the term and \meta{options} is a
+comma-separated list of \meta{key}=\meta{value} options. The
+following keys are available:
+\begin{description}
+\item[\csopt{newterm}{database}] Identifies the database in which to
+store this term. For example:
+\begin{verbatim}
+\newterm[database=index]{reptile}
+\end{verbatim}
+It can be somewhat cumbersome having to keep typing the database for
+each new term. Instead you can identify the default database using
+\begin{definition}[\DescribeMacro\DTLgidxSetDefaultDB]
+\cs{DTLgidxSetDefaultDB}\marg{label}
+\end{definition}
+Example:
+\begin{verbatim}
+ % define two indexes:
+ \newgidx{index}{Index}
+ \newgidx{people}{People}
+ % Set "index" as the default database:
+ \DTLgidxSetDefaultDB{index}
+ % This batch of terms will be added to database "index":
+ \newterm{reptile}
+ \newterm{mammal}
+ \newterm{insect}
+ % Set "people" as the default database:
+ \DTLgidxSetDefaultDB{people}
+ % This batch of terms will be added to database "people":
+ \newterm{Bob}
+ \newterm{Mary}
+ \newterm{Jane}
+\end{verbatim}
+
+\item[\csopt{newterm}{label}] A unique identifying label. This
+should not contain any active characters. If omitted, the label is
+extracted from \meta{name} (see below).
+
+\item[\csopt{newterm}{sort}] The sort key. If omitted, this is
+extracted from \meta{name} (see below).
+
+\item[\csopt{newterm}{parent}] The parent entry, if this is a
+sub-term.
+
+\item[\csopt{newterm}{text}] How the entry should appear in the
+document text. This is \meta{name} by default. If this option is
+used, \meta{name} indicates how the entry should appear in the
+index, glossary or list of acronyms.
+
+\item[\csopt{newterm}{description}] An optional description. This is
+usually not required for an index but needed for a glossary.
+
+\item[\csopt{newterm}{plural}] The plural form of the term. If
+omitted this is formed by appending ``s'' to \meta{name} (or the
+value of the \csopt{newterm}{text} key if supplied).
+
+\item[\csopt{newterm}{symbol}] An associated symbol if required.
+
+\item[\csopt{newterm}{short}] An associated short form if required.
+(Default \meta{name}.)
+
+\item[\csopt{newterm}{long}] An associated long form if required.
+(Default \meta{name}.)
+
+\item[\csopt{newterm}{shortplural}] An associated short plural if
+required. (Default formed by appending ``s'' to the value of the
+\csopt{newterm}{short} key.)
+
+\item[\csopt{newterm}{longplural}] An associated long plural if
+required. (Default formed by appending ``s'' to the value of the
+\csopt{newterm}{long} key.)
+
+\item[\csopt{newterm}{see}] A cross-reference to a synonym. The
+value should be the label of another entry. This entry will not have
+a location list, just the reference to the other term.
+
+\item[\csopt{newterm}{seealso}] A cross-reference to a closely
+related term. This entry should have both a location list and a
+reference to the other term.
+
+\end{description}
+
+If the \csopt{label} or \csopt{sort} key are omitted, \sty{datagidx}
+tries to form sensible defaults. At the moment, this involves
+stripping certain commands (\ics{MakeUppercase},
+\ics{MakeLowercase},
+\ics{MakeTextUppercase}, \ics{MakeTextLowercase}, \ics{acronymfont},
+\ics{textsc}, \ics{textbf}, \ics{textmd}, \ics{textit},
+\ics{textsl}, \ics{textrm}, \ics{texttt}, \ics{textsf}, \ics{emph},
+\ics{ensuremath} and \ics{textsuperscript}), stripping accents
+and replacing certain control characters or control sequences
+(\verb|~| is replace with a space and \verb|\&| is replaced with
+\ics{andname} (if defined) or ``and'' (if \cs{andname} isn't
+defined)). The Greek letter commands (\ics{alpha} etc) are converted
+to their name.
+
+Examples:
+\begin{enumerate}
+\item \ics{ensuremath} is stripped and \ics{alpha} is converted to
+``alpha'' so the following:
+\begin{verbatim}
+\newterm{\ensuremath{\alpha}}
+\end{verbatim}
+sets both the label and sort to \texttt{alpha} but the name and text
+fields are set to \verb|\ensuremath{\alpha}|.
+
+\item Accent commands are stripped so the following:
+\begin{verbatim}
+\newterm{mac\'edoine}
+\end{verbatim}
+sets both the label and sort fields to \texttt{macedoine} but the
+name and text fields are set to \verb|mac\'edoine|.
+
+\begin{important}
+The first letter must be grouped if it's an accent or ligature or a
+character outside the range \texttt{a}\ldots\texttt{z} or
+\texttt{A}\ldots\texttt{Z}.
+\end{important}
+
+\item This example must have the sort and label fields set manually
+because the first letter has an accent:
+\begin{verbatim}
+\newterm[label=elite,sort=elite]{{\'e}lite}
+\end{verbatim}
+
+\item The same applies if you are using the \sty{inputenc} package:
+\begin{verbatim}
+\newterm[label=elite,sort=elite]{{é}lite}
+\end{verbatim}
+
+\item The same applies to plural terms set explicitly:
+\begin{verbatim}
+\newterm
+ [%
+ plural={{œ}sophagi},%
+ label={oesophagus},%
+ sort={oesophagus}%
+ ]
+ {{œ}sophagus}
+\end{verbatim}
+
+\item Commands such as \ics{oe} aren't dealt with, so you must
+manually set the label and sort key:
+\begin{verbatim}
+\newterm[label=manoeuvre,sort=manoeuvre]{man\oe uvre}
+\end{verbatim}
+
+\item The same applies if you are using the \sty{inputenc} package:
+\begin{verbatim}
+\newterm[label=manoeuvre,sort=manoeuvre]{manœuvre}
+\end{verbatim}
+
+\begin{important}
+Take care if any of the values to fields contain a comma or equal
+sign. The value must be grouped.
+\end{important}
+
+\item This term contains a comma in some of the fields:
+\begin{verbatim}
+\newterm
+ [%
+ label={comma},%
+ sort={,},%
+ text={comma (,)}%
+ plural={commas (,)}%
+ ]
+ {, (comma)}
+\end{verbatim}
+In the text, the entry is \texttt{comma (,)} but in the index the
+entry is sorted according to the comma symbol and is displayed as
+\texttt{, (comma)}.
+
+\end{enumerate}
+
+\subsection{Commands to Assist Sorting}
+
+There are some situations where you will have to specify the sort
+key, for example:
+\begin{verbatim}
+\newterm
+[
+ sort={Ten Downing Street}
+]
+{10 Downing Street}
+\end{verbatim}
+
+However, there are some commands provided to help set the default
+sort for entries that are sorted differently from the way they are
+typeset in the index/glossary, which can help reduce the number of times you
+need to explicitly set the sort field.
+
+\begin{definition}[\DescribeMacro\DTLgidxParen]
+\cs{DTLgidxParen}\marg{text}
+\end{definition}
+This command is provided for parenthetical material that should be
+typeset in the index, but should not contribute to the sort unless
+there is an identical entry without parenthetical material.
+
+For example:
+\begin{verbatim}
+\newterm{0\DTLgidxParen{zero}}
+\end{verbatim}
+This term is typeset as \texttt{0 (zero)}, but has the sort and
+label fields set to \texttt{0}.
+
+The default sort used is word-order sorting. This has a special
+number group for entries where the sort field consists solely of
+digits and they are sorted numerically rather than by string
+comparison. Using \cs{DTLgidxParen} in this manner, the following
+terms will appear in numerical order in the index:
+\begin{verbatim}
+\newterm{0\DTLgidxParen{zero}}
+\newterm{1\DTLgidxParen{one}}
+\newterm{2\DTLgidxParen{two}}
+\newterm{3\DTLgidxParen{three}}
+\newterm{10\DTLgidxParen{ten}}
+\newterm{100\DTLgidxParen{one hundred}}
+\newterm{20\DTLgidxParen{twenty}}
+\end{verbatim}
+If \cs{DTLgidxParen} was not used and the parentheses were
+explicitly included, e.g.\ \texttt{0 (zero)}, then the entries would
+be placed in the symbol group instead and be sorted according to
+string (so \texttt{10 (ten)} would come before \texttt{2 (two)}).
+
+\begin{definition}[\DescribeMacro\DTLgidxPlace]
+\cs{DTLgidxPlace}\marg{country/county}\marg{city/town}
+\end{definition}
+Use this command to indicate a place. For example:
+\begin{verbatim}
+\newterm{\DTLgidxPlace{USA}{New York}}
+\end{verbatim}
+This sets the label and name to \texttt{New York, USA}, the text
+field is set to just \texttt{New York} and the sort field is set to
+\verb|New York\datatoolplacecomma USA| (see \autoref{sec:sort}).
+
+\begin{definition}[\DescribeMacro\DTLgidxSubject]
+\cs{DTLgidxSubject}\marg{subject}\marg{text}
+\end{definition}
+Use this to indicate a subject, concept or object. Example:
+\begin{verbatim}
+\newterm{\DTLgidxSubject{population}{New York}}
+\end{verbatim}
+Both the label and name fields default to \texttt{New York,
+population}, the text field defaults to \texttt{population} and the
+sort field is set to \verb|New York\datatoolsubjectcomma population|
+(see \autoref{sec:sort}).
+
+\begin{definition}[\DescribeMacro\DTLgidxName]
+\cs{DTLgidxName}\marg{forename(s)}\marg{surname}
+\end{definition}
+Use this command to index a person. The entry will be sorted
+according to the surname then the forenames. The entry will be
+displayed as \meta{surname}, \meta{forename(s)} in the index but
+will be displayed as \meta{forename(s)} \meta{surname} when
+referenced in the document. The label, on the other hand, is set to
+just the surname. Example:
+\begin{verbatim}
+\newterm{\DTLgidxName{Donald E.}{Knuth}}
+\end{verbatim}
+This sets the name field to \texttt{Knuth, Donald E.}, the text
+field to \texttt{Donald E. Knuth}, the label to \texttt{Knuth} and the sort field to
+\texttt{Knuth\ics{datatoolpersoncomma} Donald E.} (see
+\autoref{sec:sort}).
+
+A person's title (such as ``Dr'') should typically not affect the
+sort, unless there is another person with the same surname and
+forenames (or initials) without a title. To assist this, you can
+identify a person's title using:
+\begin{definition}[\DescribeMacro\DTLgidxRank]
+\cs{DTLgidxRank}\marg{title}\marg{forename(s)/initial(s)}
+\end{definition}
+Using examples from the Oxford Style Manual:
+\begin{verbatim}
+\newterm[label=AliceMeynell]{\DTLgidxName{Meynell}{Alice}}
+\newterm[label=DrMeynell]{\DTLgidxName{Meynell}{\DTLgidxRank{Dr}{A.}}}
+\newterm[label=AMeynell]{\DTLgidxName{Meynell}{A.}}
+\end{verbatim}
+Here the labels must be set as the surnames are identical for each
+entry, but the entries will be sorted in the order: ``Meynell, A.'',
+``Meynell, Dr~A.'' and ``Meynell, Alice''.
+
+You can use
+\begin{definition}[\DescribeMacro\DTLgidxNameNum]
+\cs{DTLgidxNameNum}\marg{number}
+\end{definition}
+to indicate a number associated with a name. The number is typeset
+as an uppercase Roman numeral in the text, but is sorted
+numerically.
+
+For example:
+\begin{verbatim}
+\newterm{James~\DTLgidxNameNum{1}}
+\end{verbatim}
+This is typeset as \verb|James~I|, but gets the label
+\texttt{James I} (note no tilde) and the sort field is set to
+\texttt{James 01}. This means that if I want to index all the Kings
+whose name is James, they will appear in the correct order in the
+index.
+
+If a term contains a variant of ``Mac'' you can also use:
+\begin{definition}[\DescribeMacro\DTLgidxMac]
+\cs{DTLgidxMac}\marg{text}
+\end{definition}
+The entry will be typeset with \meta{text} but the sort key will
+have \meta{text} replaced with \texttt{Mac}. Examples:
+\begin{verbatim}
+\newterm{\DTLgidxName{Joe}{\DTLgidxMac{Mc}Cullers}}
+\newterm{\DTLgidxName{Bob}{\DTLgidxMac{M'}Fingal}}
+\newterm{\DTLgidxMac{Mc}Carthyism}
+\newterm{\DTLgidxMac{Mc}Guffin}
+\end{verbatim}
+
+Similarly saints can be identified using:
+\begin{definition}[\DescribeMacro\DTLgidxSaint]
+\cs{DTLgidxSaint}\marg{text}
+\end{definition}
+Examples:
+\begin{verbatim}
+\newterm{\DTLgidxSaint{St} Julian}
+\newterm{\DTLgidxName{Q.}{\DTLgidxSaint{St}~John-Smythe}}
+\newterm{\DTLgidxPlace{\DTLgidxSaint{St}~Andrews}{Fife}}
+\end{verbatim}
+These will be sorted according to \texttt{Saint Julian},
+\verb|Saint John-Smythe\datatoolpersoncomma Q.| and
+\verb|Saint Andrews\datatoolplacecomma Fife|.
+
+Particles, such as ``de'', ``von'' or ``of'' are usually ignored
+when sorting. These can be identified using:
+\begin{definition}[\DescribeMacro\DTLgidxParticle]
+\cs{DTLgidxParticle}\marg{text}
+\end{definition}
+Examples:
+\begin{verbatim}
+\newterm{\DTLgidxName{Fred}{\DTLgidxParticle{de}{Winter}}}
+\newterm{\DTLgidxName{Gustav}{\DTLgidxParticle{von}{Aschenbach}}}
+\end{verbatim}
+Here the names are sorted according to
+\verb|Winter\datatoolpersoncomma Fred| and
+\verb|Aschenbach\datatoolpersoncomma Gustav| but the labels are set
+to \texttt{deWinter} and \texttt{vonAschenbach}.
+
+A person can also be indicated by their office, for example ``Henry,
+scribe of Bury St~Edmunds''. For this, you can use:
+\begin{definition}[\DescribeMacro\DTLgidxOffice]
+\cs{DTLgidxOffice}\marg{office}\marg{name}
+\end{definition}
+Here the label defaults to just \meta{name}, so you may need to set
+the label manually to ensure uniqueness. Examples:
+\begin{verbatim}
+\newterm
+[
+ label={HenrySonJohn}
+]
+{\DTLgidxOffice{son \DTLgidxParticle{of}{John}}{Henry}}
+
+\newterm
+[
+ label={HenryBeaumont}
+]
+{\DTLgidxOffice{bishop \DTLgidxParticle{of}{Bayeux}}{Henry
+\DTLgidxParticle{de}{Beaumont}}}
+
+\newterm
+[
+ label={HenryScribe}
+]
+{\DTLgidxOffice{scribe \DTLgidxParticle{of}{Bury}
+ \DTLgidxSaint{St}~Edmunds}{Henry}}
+
+
+\end{verbatim}
+
+You can hook into the mechanism that sets the default sort key by
+adding to the definition of
+\begin{definition}[\DescribeMacro\newtermlabelhook]
+\cs{newtermlabelhook}
+\end{definition}
+You can use \sty{etoolbox's} \ics{appto} command to append to this
+hook. For example, suppose you want to index the terms \verb|\TeX|,
+\verb|e\TeX| and \verb|pdf\TeX|, but you want the terms to have the
+label and sort fields to be just \verb|TeX|, \verb|eTeX| and
+\verb|pdfTeX|, then you can add to the hook so that it automatically
+converts \ics{TeX} to just \texttt{TeX}:
+\begin{verbatim}
+\appto\newtermlabelhook{\def\TeX{TeX}}
+\end{verbatim}
+(Note that it's important to use the local \ics{def} rather than the
+global \ics{gdef} to ensure the redefinition is localised.)
+
+Now the terms can simply be defined using:
+\begin{verbatim}
+\newterm{\TeX}
+\newterm{e\TeX}
+\newterm{pdf\TeX}
+\end{verbatim}
+
+To assist in using this mechanism, the following commands are
+available (these commands may also be used in the mandatory argument
+of \cs{newterm}):
+\begin{definition}[\DescribeMacro\DTLgidxNoFormat]
+\cs{DTLgidxNoFormat}\marg{text}
+\end{definition}
+This commands simply does its argument, so any commands that should
+be stripped from the label or sort field without the loss of their
+argument can be \ics{let} to \cs{DTLgidxNoFormat}. For example,
+suppose you want to define a command called, say, \cs{appname} that
+you want to use to identify application names, like this:
+\begin{verbatim}
+\newcommand*{\app}[1]{\texttt{#1}}
+\end{verbatim}
+This command needs to be stripped from the label and sort, so it can
+be added to the hook like this:
+\begin{verbatim}
+\appto\newtermlabelhook{\let\app\DTLgidxNoFormat}
+\end{verbatim}
+Now you can define terms like this:
+\begin{verbatim}
+\newterm{\app{makeindex}}
+\newterm{\app{xindy}}
+\end{verbatim}
+The label and sort keys are then set to \texttt{makeindex} (for the
+first term) and \texttt{xindy} (for the second term).
+
+\begin{definition}[\DescribeMacro\DTLgidxGobble]
+\cs{DTLgidxGobble}\marg{text}
+\end{definition}
+This command discards its argument, so it can be used if you not
+only want to strip a command but also its argument from the label
+and sort fields.
+
+For example, suppose you want some terms to have a footnote (both in the
+index/glossary and in the document text) but the footnote shouldn't
+form part of the sort or label fields. You can add to the hook like
+this:
+\begin{verbatim}
+\appto\newtermlabelhook{\let\footnote\DTLgidxGobble}
+\end{verbatim}
+Now you can define some terms with footnotes:
+\begin{verbatim}
+\newterm{foo\footnote{a note about foo}}
+\newterm{bar\footnote{a note about bar}}
+\end{verbatim}
+The label and sort keys are then set to \texttt{foo} (for the first
+term) and \texttt{bar} (for the second term).
+
+\begin{definition}[\DescribeMacro\DTLgidxIgnore]
+\cs{DTLgidxIgnore}
+\end{definition}
+This is similar to \cs{DTLgidxGobble} but only affects the sort key
+not the label. Example:
+\begin{verbatim}
+\newterm{de\DTLgidxIgnore{-}escalate}
+\end{verbatim}
+This is displayed as \texttt{de-escalate} and gets the label
+\texttt{de-escalate} but is sorted according to \texttt{deescalate}.
+
+\begin{definition}[\DescribeMacro\DTLgidxStripBackslash]
+\cs{DTLgidxStripBackslash}\marg{control sequence}
+\end{definition}
+This can be used to ``stringify'' a control sequence and remove the
+leading backslash. For example, suppose you want to index the
+ampersand symbol (\&) but you want to sort it according to the
+actual symbol \verb|&|, you can do:
+\begin{verbatim}
+\newterm
+ [%
+ label={amp},
+ sort={\DTLgidxStripBackslash{\&}},
+ text={ampersand (\&)},
+ plural={ampersands (\&)},
+ ]
+ {\& (ampersand)}
+\end{verbatim}
+
+\section{Referencing Terms}
+\label{sec:useentry}
+
+You can reference terms using
+\begin{definition}[\DescribeMacro\useentry]
+\cs{useentry}\marg{label}\marg{field}
+\end{definition}
+This fetches the given field for the term identified by
+\meta{label}, displays it and marks the term as having been used.
+Example, suppose I have previous (in the preamble) defined the term
+``reptile'' using:
+\begin{verbatim}
+\newterm{reptile}
+\end{verbatim}
+I can now reference this term in the document:
+\begin{verbatim}
+\useentry{reptile}{Text}
+\end{verbatim}
+or if I want the plural, I can use:
+\begin{verbatim}
+\useentry{reptile}{Plural}
+\end{verbatim}
+There are also uppercase versions:
+\begin{definition}[\DescribeMacro\Useentry]
+\cs{Useentry}\marg{label}\marg{field}
+\end{definition}
+This makes the first letter uppercase (using the \sty{mfirstuc}
+package) or to make the whole text uppercase use:
+\begin{definition}[\DescribeMacro\USEentry]
+\cs{USEentry}\marg{label}\marg{field}
+\end{definition}
+
+If you use the \sty{hyperref} package, the above commands will
+automatically create hyperlinks to the relevant entry in the
+index/glossary. You can suppress this action by using one of the
+following analogous commands instead:
+\begin{definition}[\DescribeMacro\useentrynl]
+\cs{useentrynl}\marg{label}\marg{field}
+\end{definition}
+\begin{definition}[\DescribeMacro\Useentrynl]
+\cs{Useentrynl}\marg{label}\marg{field}
+\end{definition}
+\begin{definition}[\DescribeMacro\USEentrynl]
+\cs{USEentrynl}\marg{label}\marg{field}
+\end{definition}
+
+In all the above commands, the \meta{label} argument may optionally
+start with \oarg{format}, where format is the name of a control
+name \emph{without} the preceding backslash. This command will be
+applied to this location in the entry's location list when it's
+displayed in the index/glossary.
+
+For example:
+\begin{verbatim}
+\useentry{[textbf]reptile}{Text}
+\end{verbatim}
+Note that the command (\cs{textbf} in the above example) should take
+one argument (the location). If you attempt to use, say, a
+declaration (such as \cs{bfseries}) the effect won't be localised.
+
+You can display the value of a field without indexing it using:
+\begin{definition}[\DescribeMacro\glsdispentry]
+\cs{glsdispentry}\marg{label}\marg{field}
+\end{definition}
+To make the first letter uppercase, use:
+\begin{definition}[\DescribeMacro\Glsdispentry]
+\cs{Glsdispentry}\marg{label}\marg{field}
+\end{definition}
+The above commands aren't expandable. If you want to fetch a value
+without displaying or using it, you can use:
+\begin{definition}[\DescribeMacro\DTLgidxFetchEntry]
+\cs{DTLgidxFetchEntry}\marg{cs}\marg{label}\marg{field}
+\end{definition}
+where \meta{cs} is a control sequence, \meta{label} is the label
+that uniquely identifies the entry and \meta{field} is the required
+field. The value of that field is stored in \meta{cs}.
+
+The predefined database fields are:
+\begin{description}
+\item[Name] How the term appears in the index/glossary (as specified
+by the mandatory argument of \ics{newterm}).
+\item[Text] The value of the \csopt{newterm}{text} field.
+\item[Plural] The value of the \csopt{newterm}{plural} field.
+\item[Description] The value of the \csopt{newterm}{description}
+field.
+\item[Symbol] The value of the \csopt{newterm}{symbol} field.
+\item[Long] The value of the \csopt{newterm}{long} field.
+\item[Short] The value of the \csopt{newterm}{short} field.
+\item[LongPlural] The value of the \csopt{newterm}{longplural}
+field.
+\item[ShortPlural] The value of the \csopt{newterm}{shortplural}
+field.
+\item[See] The value of the \csopt{newterm}{see} field.
+\item[SeeAlso] The value of the \csopt{newterm}{seealso} field.
+\item[Sort] The value of the \csopt{newterm}{sort} field.
+\item[Parent] The value of the \csopt{newterm}{parent} field.
+\item[Label] The entry's unique identifying label.
+\item[Used] Has the value 1 (entry has been used) or either 0 or
+undefined (entry hasn't been used).
+\item[Location] The entry's location list (picked up from the last
+\LaTeX\ run).
+\end{description}
+
+In addition, there are some fields designed for internal use:
+\texttt{Child}, \texttt{FirstId} and \texttt{CurrentLocation}.
+
+You can add an entry to the index/glossary without displaying any
+text using:
+\begin{definition}[\DescribeMacro\glsadd]
+\cs{glsadd}\marg{label}
+\end{definition}
+As with \cs{useentry}, \meta{label} maybe in the form
+\oarg{format}\marg{label} where \meta{format} is the name of a
+control sequence \emph{without} the leading backslash.
+
+You can also add all entries from a particular database using
+\begin{definition}[\DescribeMacro\glsaddall]
+\cs{glsaddall}\marg{db name}
+\end{definition}
+where \meta{db name} is the name of the database.
+
+Unlike the commands of the same name provided by the
+\sty{glossaries} package, here there is a difference between
+\cs{glsaddall} and using \cs{glsadd} on all entries in the database.
+In the case of \cs{glsadd} a location is added to the location list
+for that entry. However in the case of \cs{glsaddall} no location is
+added to each entry's location list, but the location list is set to
+non-null so the entry will appear in the index/glossary.
+
+\subsection{Shortcut Commands}
+
+There are some shortcuts to common fields (if you are used to the
+\sty{glossaries} package, note that these commands have different
+formats to the commands provided by \sty{glossaries} with the same
+name):
+\begin{definition}[\DescribeMacro\gls]
+\cs{gls}\marg{label}
+\end{definition}
+This is equivalent to \cs{useentry}\marg{label}\verb|{Text}|.
+\begin{definition}[\DescribeMacro\glspl]
+\cs{glspl}\marg{label}
+\end{definition}
+This is equivalent to \cs{useentry}\marg{label}\verb|{Plural}|.
+\begin{definition}[\DescribeMacro\glsnl]
+\cs{glsnl}\marg{label}
+\end{definition}
+This is equivalent to \cs{useentrynl}\marg{label}\verb|{Text}|.
+\begin{definition}[\DescribeMacro\glsplnl]
+\cs{glsplnl}\marg{label}
+\end{definition}
+This is equivalent to \cs{useentrynl}\marg{label}\verb|{Plural}|.
+
+\begin{definition}[\DescribeMacro\Gls]
+\cs{Gls}\marg{label}
+\end{definition}
+This is equivalent to \cs{Useentry}\marg{label}\verb|{Text}|.
+\begin{definition}[\DescribeMacro\Glspl]
+\cs{Glspl}\marg{label}
+\end{definition}
+This is equivalent to \cs{Useentry}\marg{label}\verb|{Plural}|.
+\begin{definition}[\DescribeMacro\Glsnl]
+\cs{Glsnl}\marg{label}
+\end{definition}
+This is equivalent to \cs{Useentrynl}\marg{label}\verb|{Text}|.
+\begin{definition}[\DescribeMacro\Glsplnl]
+\cs{Glsplnl}\marg{label}
+\end{definition}
+This is equivalent to \cs{Useentrynl}\marg{label}\verb|{Plural}|.
+
+\begin{definition}[\DescribeMacro\glssym]
+\cs{glssym}\marg{label}
+\end{definition}
+This is equivalent to \cs{useentry}\marg{label}\verb|{Symbol}|.
+\begin{definition}[\DescribeMacro\Glssym]
+\cs{Glssym}\marg{label}
+\end{definition}
+This is equivalent to \cs{Useentry}\marg{label}\verb|{Symbol}|.
+
+\section{Adding Extra Fields}
+
+You can add new fields to the index/glossary database using:
+\begin{definition}[\DescribeMacro\newtermaddfield]
+\cs{newtermaddfield}\oarg{db list}\marg{field name}\marg{key
+name}\marg{default value}
+\end{definition}
+The optional argument \meta{db list} is a comma-separated list of
+databases that should have this new field. If omitted, the field
+will be added to all the defined databases. The argument \meta{field
+name} is the label to give this new column in the database(s). The
+argument \meta{key name} is the name of the new key to use in the
+optional argument of \ics{newterm}. The final argument \meta{default
+value} is the default value if the key isn't used. Within
+\meta{default value}, you may use
+\begin{definition}[\DescribeMacro\field]
+\cs{field}\marg{key}
+\end{definition}
+to indicate the value of another key.
+
+
+For example, suppose I want to be able to specify an alternative
+plural. I can add a new field like this:
+\begin{verbatim}
+\newtermaddfield{AltPlural}{altplural}{}
+\end{verbatim}
+This adds a new column with the label \texttt{AltPlural} to each
+defined index/glossary database and adds a new key called
+\texttt{altplural} that I can now use in \ics{newterm}. The default
+is set to empty. Now I can define terms with an alternative plural:
+\begin{verbatim}
+\newterm[altplural=kine]{cow}
+\end{verbatim}
+In the document, I can use \verb|\gls{cow}| to display ``cow'',
+\verb|\glspl{cow}| to display ``cows'' and
+\verb|\useentry{cow}{AltPlural}| to display ``kine''. To make life a
+little easier, I can define a new command to save typing:
+\begin{verbatim}
+\newcommand*{\glsaltpl}[1]{\useentry{#1}{AltPlural}}
+\end{verbatim}
+Now I can just do \verb|\glsaltpl{cow}| to display ``kine''.
+
+Here's another example. Suppose I want to add a field that produces
+the past tense of a verb. In this case, the default should be formed
+by appending ``ed'' to the \csopt{newterm}{text} field. The new
+field can be defined as follows:
+\begin{verbatim}
+\newtermaddfield{Ed}{ed}{\field{text}ed}
+\end{verbatim}
+This adds a new column labelled ``Ed'' and defines a new key called
+``ed'' that can be used with \ics{newterm}. Now I can defined some
+verbs:
+\begin{verbatim}
+\newterm{jump}
+\newterm[ed=went]{go}
+\end{verbatim}
+
+Let's define a convenience command to access this field:
+\begin{verbatim}
+\newcommand*{\glsed}[1]{\useentry{#1}{Ed}}
+\end{verbatim}
+This new field can now be referenced in the document:
+\begin{verbatim}
+He \glsed{jump} over the gate.
+She \glsed{go} to the shop.
+\end{verbatim}
+The above will be displayed as: He jumped over the gate. She went to
+the shop.
+
+\section{Acronyms}
+
+You may have noticed that you can specify \csopt{newterm}{short} and
+\csopt{newterm}{long} fields when you define a new term. There is a
+convenient shortcut command which uses \ics{newterm} to define an
+acronym. The syntax is:
+\begin{definition}[\DescribeMacro\newacro]
+\cs{newacro}\oarg{options}\marg{short}\marg{long}
+\end{definition}
+This is a shortcut for
+\begin{alltt}
+\ics{newterm}
+ [%
+ description=\{\ics{capitalisewords}\marg{long}\},%
+ short=\{\cs{acronymfont}\marg{short}\},%
+ long=\marg{long},%
+ text=\{\cs{DTLgidxAcrStyle}\marg{long}\{\cs{acronymfont}\marg{short}\}\},%
+ plural=\{\cs{DTLgidxAcrStyle}\{\meta{long}s\}\{\cs{acronymfont}\{\meta{short}s\}\}\},%
+ sort=\marg{short},%
+ \meta{options}%
+ ]%
+ {\ics{MakeTextUppercase}\marg{short}}
+\end{alltt}
+where \ics{capitalisewords} is defined in \sty{mfirstuc}
+(automatically loaded by \styfmt{datagidx}) and
+\ics{MakeTextUppercase} is defined in \sty{textcase} (automatically
+loaded by \styfmt{datagidx}). The other commands used are defined by
+\styfmt{datagidx}:
+\begin{definition}[\DescribeMacro\acronymfont]
+\cs{acronymfont}
+\end{definition}
+By default this just typesets its argument but can be redefined if
+the acronyms need to be typeset in a certain style (such as small
+caps).
+\begin{definition}[\DescribeMacro\DTLgidxAcrStyle]
+\cs{DTLgidxAcrStyle}\marg{long}\marg{short}
+\end{definition}
+This governs how the acronym is typeset in the \csopt{newterm}{text}
+field. This defaults to: \meta{long} (\meta{short}).
+
+\subsection{Using Acronyms}
+
+You can use terms that represent acronyms via commands such as
+\ics{useentry}. For example, if you define the following in the
+preamble:
+\begin{verbatim}
+\newacro{css}{cascading style sheet}
+\end{verbatim}
+then later in the text you can use:
+\begin{verbatim}
+\useentry{css}{Short}
+\end{verbatim}
+to access the short form and
+\begin{verbatim}
+\useentry{css}{Long}
+\end{verbatim}
+to access the long form. You can also use
+\begin{verbatim}
+\useentry{css}{Text}
+\end{verbatim}
+(or \verb|\gls{css}|) to access the full version. However with
+acronyms you generally only want the full form on first use and just
+the short form on subsequent use. The following commands are
+provided to do that. The singular form is obtained using:
+\begin{definition}[\DescribeMacro\acr]
+\cs{acr}\marg{label}
+\end{definition}
+The plural form is obtained using:
+\begin{definition}[\DescribeMacro\acrpl]
+\cs{acrpl}\marg{label}
+\end{definition}
+
+Note that, unlike the \sty{glossaries} package, \cs{acr} isn't the
+same as \cs{gls}. With \styfmt{datagidx}, \cs{gls} always references
+the \csopt{newterm}{text} field. There is no ``first'' field.
+
+As a general rule, you're not supposed to capitalise the first
+letter of an acronym (especially if it is displayed in small caps) but if you need to
+you can use:
+\begin{definition}[\DescribeMacro\Acr]
+\cs{Acr}\marg{label}
+\end{definition}
+and
+\begin{definition}[\DescribeMacro\Acrpl]
+\cs{Acrpl}\marg{label}
+\end{definition}
+
+\subsection{Unsetting and Resetting Acronyms}
+
+You can reset a term so it's marked as not used with:
+\begin{definition}[\DescribeMacro\glsreset]
+\cs{glsreset}\marg{label}
+\end{definition}
+or you can unset a term so it's marked as used with:
+\begin{definition}[\DescribeMacro\glsunset]
+\cs{glsunset}\marg{label}
+\end{definition}
+
+You can reset all the terms defined in a given database using:
+\begin{definition}[\DescribeMacro\glsresetall]
+\cs{glsresetall}\marg{db name}
+\end{definition}
+or unset all the terms defined in a given database using:
+\begin{definition}[\DescribeMacro\glsunsetall]
+\cs{glsunsetall}\marg{db name}
+\end{definition}
+where \meta{db name} is the name of the database as supplied when
+the database was defined using \ics{newgidx}.
+
+\section{Conditionals}
+
+You can test if a term exists using
+\begin{definition}[\DescribeMacro\iftermexists]
+\cs{iftermexists}\marg{label}\marg{true part}\marg{false part}
+\end{definition}
+You can test if a term has been used using:
+\begin{definition}[\DescribeMacro\ifentryused]
+\cs{ifentryused}\marg{label}\marg{true part}\marg{false part}
+\end{definition}
+
+\section{Displaying the Index or Glossary}
+\label{sec:printterms}
+
+The index or glossary can be displayed using
+\begin{definition}[\DescribeMacro\printterms]
+\cs{printterms}\oarg{options}
+\end{definition}
+You will need to run \LaTeX\ at least twice to ensure your
+index/glossary is up-to-date. The first run will only display any
+entries that have a ``See'' field defined.
+
+The optional argument \meta{options} is a comma-separated list of
+\meta{key}=\meta{value} options. Available keys:
+\begin{description}
+\item[\csopt{printterms}{database}] The name of the database (as
+given in \ics{newgidx}).
+
+\item[\csopt{printterms}{postdesc}] This may have the value
+\textsf{dot} (put a full stop after the description) or
+\textsf{none} (don't put a full stop after the description).
+
+\item[\csopt{printterms}{prelocation}] This indicates what to put
+before the location list. Available values:
+\begin{description}
+\item[\textsf{none}] Nothing.
+\item[\textsf{enspace}] An en-space.
+\item[\textsf{space}] An ordinary space.
+\item[\textsf{dotfill}] A dotted line (\ics{dotfill}).
+\item[\textsf{hfill}] Expandable space (\ics{hfill}).
+\end{description}
+
+\item[\csopt{printterms}{location}] This indicates how to display
+the location list. Available values:
+\begin{description}
+\item[\textsf{hide}] Don't display the location list.
+\item[\textsf{list}] Display the location list.
+\item[\textsf{first}] Only display the first location in the list.
+\end{description}
+
+\item[\csopt{printterms}{symboldesc}] How to format the symbol in
+relation to the description. Available values:
+\begin{description}
+\item[\textsf{symbol}] Display the symbol but not the description.
+\item[\textsf{desc}] Display the description but not the symbol
+field.
+\item[\textsf{(symbol) desc}] Display the symbol (if defined) in parentheses
+followed by the description.
+\item[\textsf{desc (symbol)}] Display the description followed by
+the symbol (if defined) in parentheses.
+\item[\textsf{symbol desc}] Display the symbol (if defined) followed
+by the description.
+\item[\textsf{desc symbol}] Display the description followed by the
+symbol (if defined).
+\end{description}
+
+\item[\csopt{printterms}{columns}] This should be a positive number
+that indicates the page column layout. If the value is greater
+than~1, the \env{multicols} environment is used (defined in the
+\sty{multicol} package, which is automatically loaded).
+
+\item[\csopt{printterms}{namecase}] Indicates whether any case
+change should be applied to the entry's name field. Available
+values:
+\begin{description}
+\item[\textsf{nochange}] Don't apply a case change.
+\item[\textsf{uc}] Convert the name to uppercase.
+\item[\textsf{lc}] Convert the name to lowercase.
+\item[\textsf{firstuc}] Convert the first letter to uppercase (using
+\ics{makefirstuc} defined in \sty{mfirstuc}).
+\item[\textsf{capitalise}] Capitalise initial letters of each word
+in the name (using \ics{capitalisewords} defined in \sty{mfirstuc}).
+\end{description}
+
+\item[\csopt{printterms}{namefont}] The font changing command to
+apply to the name. (Include the initial backslash.) Declarations may
+be used.
+
+\item[\csopt{printterms}{postname}] What to put after the name.
+
+\item[\csopt{printterms}{see}] Indicates how the cross-reference
+(given in the ``See'' field) should be displayed. Available values:
+\begin{description}
+\item[\textsf{comma}] Insert a comma followed by a space in front of
+the cross-reference.
+\item[\textsf{brackets}] Insert a space before the cross-reference
+and put the cross-reference in parentheses.
+\item[\textsf{dot}] Insert a full stop followed by a space in front
+of the cross-reference.
+\item[\textsf{space}] Insert a space before the cross-reference.
+\item[\textsf{nosep}] Don't insert anything before the
+cross-reference.
+\item[\textsf{semicolon}] Insert a semi-colon followed by a space in
+front of the cross-reference.
+\item[\textsf{location}] Display the cross-reference in the same way
+as a location.
+\end{description}
+
+\item[\csopt{printterms}{child}] Indicates whether child entries
+should have their name displayed. Available values: \textsf{named}
+(display the child's name) and \textsf{noname} (don't display the
+child's name).
+
+\item[\csopt{printterms}{showgroups}] Boolean option that indicates
+whether or not to insert group headings (and a group separator)
+between index groups, if headings are supported by the given style.
+If no value is supplied, \textsf{true} is assumed.
+
+\item[\csopt{printterms}{style}] The style to use. The value should
+be the name of the style. Available styles are listed in
+\autoref{sec:indexstyles}.
+
+\item[\csopt{printterms}{symbolwidth}] Some of the styles allow you
+to specify a width for the symbol field. This width can be specified
+with this option. The value will be ignored by some of the styles.
+
+\item[\csopt{printterms}{locationwidth}] Some of the styles allow you
+to specify a width for the location field. This width can be specified
+with this option. The value will be ignored by some of the styles.
+
+\item[\csopt{printterms}{childsort}] A boolean option that indicates
+whether or not the child entries should be sorted. If \textsf{true}, the
+child entries are listed using the same sort order as the sort
+applied to the database. If \textsf{false}, the child entries are
+listed in the order they were defined. If the value is missing,
+\textsf{true} is assumed.
+
+\item[\csopt{printterms}{heading}] The heading at the start of the
+index/glossary.
+
+\item[\csopt{printterms}{postheading}] What to put immediately after
+the heading.
+
+\item[\csopt{printterms}{sort}] How to sort the database. See
+\autoref{sec:indexsort} for further details.
+
+\item[\csopt{printterms}{balance}] This is a boolean option that
+is only applied if \csopt{printterms}{columns} is greater than~1.
+If \textsf{true}, the columns are balanced. If \textsf{false}, the
+columns aren't balanced. If no value is specified, \textsf{true} is
+assumed.
+
+\end{description}
+
+\subsection{Index or Glossary Styles}
+\label{sec:indexstyles}
+
+The index or glossary style is given by the
+\csopt{newgidx,printterms}{style} key in the optional argument of
+\ics{newgidx} or \ics{printterms}. The following styles are
+available:
+
+\begin{description}
+\item[index]
+The ``index'' style is a basic style for an index. This style
+accepts the \csopt{printterms}{locationwidth} and
+\csopt{printterms}{symbolwidth} keys in \ics{printterms}. This is
+the default style.
+
+\item[indexalign]
+The ``indexalign'' style is similar to the ``index'' style but
+aligns the descriptions.
+
+\item[align]
+The ``align'' style aligns the fields. This style
+accepts the \csopt{printterms}{locationwidth} and
+\csopt{printterms}{symbolwidth} keys in \ics{printterms}.
+
+\item[gloss]
+The ``gloss'' style is a basic glossary style. This style uses
+\begin{definition}[\DescribeMacro\DTLgidxChildSep]
+\cs{DTLgidxChildSep}
+\end{definition}
+as the separator between child entries (defaults to a space) and
+\begin{definition}[\DescribeMacro\DTLgidxPostChild]
+\cs{DTLgidxPostChild}
+\end{definition}
+to indicate what to put after the list of child entries (defaults to
+nothing).
+
+\item[dict]
+The ``dict'' style is designed for dictionary-like glossaries. This
+assumes a hierarchical structure where the top level entries have a
+name. The next level is used to indicate a category (such as
+``adjective'' or ``noun''). If there is only one meaning for the
+term, this level also has a description. If there is more than one
+meaning, each meaning should be a child of the category entry. Only
+third level entries are numbered. No further levels are expected.
+The symbol field is ignored.
+
+If \csopt{printterms}{showgroups} is set, the group headers will be
+placed in a \ics{chapter} (if defined) or in a \ics{section} (if
+\ics{chapter} isn't defined).
+
+This style uses:
+\begin{definition}[\DescribeMacro\DTLgidxCategoryNameFont]
+\cs{DTLgidxCategoryNameFont}\marg{text}
+\end{definition}
+The font used to display the name of the category (first child
+level).
+\begin{definition}[\DescribeMacro\DTLgidxCategorySep]
+\cs{DTLgidxCategorySep}
+\end{definition}
+The category separator. (Defaults to a space).
+\begin{definition}[\DescribeMacro\DTLgidxSubCategorySep]
+\cs{DTLgidxSubCategorySep}
+\end{definition}
+The category separator. (Defaults to a space).
+\begin{definition}[\DescribeMacro\DTLgidxDictPostItem]
+\cs{DTLgidxDictPostItem}
+\end{definition}
+Indicates what to do at the end of each top-level item. (Defaults to
+\cs{par}).
+
+The indentation is given by the length register
+\begin{definition}[\DescribeMacro\datagidxdictindent]
+\cs{datagidxdictindent}
+\end{definition}
+This value defaults to 1em.
+
+\end{description}
+
+For additional commands that affect the style of the indexes or
+glossaries, see the documented code \texttt{datatool-code.pdf}.
+
+\subsection{Sorting the Index or Glossary Database}
+\label{sec:indexsort}
+
+By default the index/glossary databases are sorted according to the
+\texttt{Sort} field using the \ics{dtlwordindexcompare} handler (see
+\autoref{sec:sort}). Note that the \emph{entire} database is sorted,
+which is less efficient that using external indexing applications,
+such as \app{makeindex} or \app{xindy}, which only sort the
+terms that have been used in the document. In addition, the sorting
+algorithm used by \styfmt{datatool} is less efficient than that used
+by a custom-built sorting and collation application.
+
+The database is sorted at the start of \ics{printterms} according to
+the value of the \csopt{printterms}{sort} key supplied by
+\ics{printterms}. To completely suppress the sorting, set this key
+to empty. Example:
+\begin{verbatim}
+\printterms[database=index,sort={},showgroups=false]
+\end{verbatim}
+Note that in the above, I also switched off the group headers as
+they don't make sense with an unsorted index or glossary.
+
+If you want to use a different comparison handler, you can set the
+\csopt{printterms}{sort} key to the required sort command, where you
+can use
+\begin{definition}[\DescribeMacro\DTLgidxCurrentdb]
+\cs{DTLgidxCurrentdb}
+\end{definition}
+to indicate the current database.
+
+For example, to sort using letter rather than word comparison:
+\begin{verbatim}
+\printterms[database=index,
+ sort={\dtlsort{Sort}{\DTLgidxCurrentdb}{\dtlletterindexcompare}}]
+\end{verbatim}
+
+You may recall from earlier that the index/glossary databases have a
+column labelled ``FirstId''. This can be used if you want to sort
+the database according to the order of usage. Example:
+\begin{verbatim}
+\printterms[database=index,
+ sort={\dtlsort{FirstId}{\DTLgidxCurrentdb}{\dtlcompare}}]
+\end{verbatim}
+Note that here I've used the \ics{dtlcompare} handler (which is the
+fastest handler) as I'm only concerned with a numerical rather than
+a string comparison.
+
+The default value of the \csopt{printterms}{sort} key is actually:
+\begin{verbatim}
+\dtlsort{Sort,FirstId}{\DTLgidxCurrentdb}{\dtlwordindexcompare}}
+\end{verbatim}
+This means that entries with duplicate ``Sort'' fields are then
+sorted according to use.
+
+\subsubsection{Optimization}
+\label{sec:optimize}
+
+If you have used \app{xindy} or \app{makeindex}, you'll be
+familiar with the document creation process. The document is first
+compiled, then the indexing application is run to sort and collate
+the entries, then the document is compiled again (and possible once
+more). This involves two (or three) \LaTeX\ runs and one sort and
+collate run. With the \styfmt{datagidx} package, the sorting and
+collation is done every \LaTeX\ run. For a large index, this can be
+quite slow. If you're not editing the index or glossary, you might
+prefer not to have to keep sorting the database whenever you update
+the document. To assist this, \styfmt{datagidx} provides the
+\pkgopt{optimize} package option. This may take the following
+values:
+\begin{description}
+\item[\pkgoptval{off}{optimize}] Don't use the optimize facility.
+(The index/glossary databases will be sorted every run, unless the
+sort is switched off by setting the \csopt{printterms}{sort} key to
+empty.)
+
+\item[\pkgoptval{low}{optimize}] Use the ``low'' optimize setting.
+This only sorts the index/glossary databases every other run.
+(Assuming that the sorting is done via the \cs{printterms}{sort} key
+rather than explicitly using \ics{dtlsort} or \ics{DTLsort}
+somewhere else in the document.) Don't use this option if sorting
+the databases makes the document out-of-date. (For example, the
+group headers use sectioning commands.)
+
+\item[\pkgoptval{high}{optimize}] Use the ``high'' optimize setting.
+This sorts the index/glossary databases on the first run, then
+writes the sorted databases to external files, which are read in on
+subsequent runs. Again this assumes that the sorting is done via the
+\cs{printterms}{sort} key. Don't use this option if you want to edit
+the index/glossary database.
+\end{description}
+
+\section{Package Options}
+\label{sec:datagidxoptions}
+
+The following package options are available for \styfmt{datagidx}:
+\begin{description}
+\item[\pkgopt{optimize}] Sets the optimization. (See
+\autoref{sec:optimize}.)
+
+\item[\pkgopt{columns}] Sets the default number of columns to use
+for the indexes or glossaries. (See \autoref{sec:printterms}.)
+
+\item[\pkgopt{child}] Sets whether or not to show the name in child
+entries, where the style supports this option. (See \autoref{sec:printterms}.)
+
+\item[\pkgopt{namecase}] Sets the case change for the entry's name.
+(See \autoref{sec:printterms}.)
+
+\item[\pkgopt{namefont}] Sets the font for the entry's name.
+(See \autoref{sec:printterms}.)
+
+\item[\pkgopt{postname}] Indicates what to put after the entry's name.
+(See \autoref{sec:printterms}.)
+
+\item[\pkgopt{postdesc}] Indicates what to put after the entry's
+description. (See \autoref{sec:printterms}.)
+
+\item[\pkgopt{prelocation}] Indicates what to put before the entry's
+location. (See \autoref{sec:printterms}.)
+
+\item[\pkgopt{location}] Indicates how to display the entry's
+location. (See \autoref{sec:printterms}.)
+
+\item[\pkgopt{see}] Indicates how to display the entry's
+cross-reference list. (See \autoref{sec:printterms}.)
+
+\item[\pkgopt{symboldesc}] Indicates how to display the entry's
+symbol in relation to the description. (See \autoref{sec:printterms}.)
+
+\item[\pkgopt{compositor}] Sets the location compositor. (See
+\autoref{sec:locations}.)
+
+\item[\pkgopt{draft}] Displays additional information, such as
+target names.
+
+\item[\pkgopt{final}] Hides the draft information.
+
+\item[\pkgopt{verbose}] Use \sty{datatool}'s verbose mode.
+
+\end{description}
+
+\begin{example}{Creating an Index}{ex:index}
+In this document, I have used the \sty{datagidx} package and the
+\sty{hyperref} package. In the preamble, I have the following:
+\begin{verbatim}
+\usepackage{datagidx}
+\usepackage[colorlinks]{hyperref}
+
+\newgidx{index}{Index}% define a database for the index
+
+\DTLgidxSetDefaultDB{index}% set this as the default
+
+\newterm{mac\'edoine}
+\newterm{macram\'e}
+\newterm[label=elite]{{\'e}lite}
+\newterm{reptile}
+\newterm[seealso={reptile}]{crocodylian}
+
+\newterm
+ [%
+ parent=crocodylian
+ ]
+ {crocodile}
+
+\newterm
+ [%
+ parent=crocodylian
+ ]
+ {alligator}
+
+\newterm
+ [%
+ parent=crocodylian,
+ description={(also cayman)}
+ ]
+ {caiman}
+
+\newterm[see={caiman}]{cayman}
+\end{verbatim}
+
+Now here's some code to go in the document:
+\begin{verbatim}
+Here are some words containing accents: \gls{macedoine},
+\gls{macrame} and \gls{elite}. \Gls{elite} requires extra care as it
+starts with an accented letter. A \gls{crocodylian} is a family of
+\glspl{reptile} consisting of \glspl{crocodile}, \glspl{alligator} and
+\glspl{caiman}.
+\end{verbatim}
+This produces the following:
+
+Here are some words containing accents: \gls{macedoine},
+\gls{macrame} and \gls{elite}. \Gls{elite} requires extra care as it
+starts with an accented letter. A \gls{crocodylian} is a family of
+\glspl{reptile} consisting of \glspl{crocodile}, \glspl{alligator} and
+\glspl{caiman}.
+
+The index can then be displayed using:
+\begin{verbatim}
+\printterms
+ [
+ heading={\section*},
+ database=index
+ ]
+\end{verbatim}
+This requires two runs to ensure the index is up-to-date. The
+resulting index is as follows:
+
+\newpage
+\printterms
+ [
+ heading={\section*},
+ database={gidx-index}
+ ]
+
+\par\vskip\baselineskip\noindent
+Here's the code if you want to add the letter groups (I've also
+added a dotted line before the location):
+\begin{verbatim}
+\printterms
+ [
+ heading={\section*},
+ database=index,
+ prelocation=dotfill,
+ showgroups
+ ]
+\end{verbatim}
+which produces:
+\printterms
+ [
+ heading={\section*},
+ database=gidx-index,
+ prelocation=dotfill,
+ showgroups
+ ]
+
+\end{example}
+
\chapter{Pie Charts (\texorpdfstring{\sty{datapie}}{datapie} package)}
\label{sec:datapie}
@@ -5081,7 +6770,9 @@ Now create a pie chart in a figure:
\caption{A pie chart}
\end{figure}
\end{verbatim}
-This creates \autoref{fig:piechart}.
+This creates \autoref{fig:piechart}. The colours used are the
+defaults. See \autoref{ex:piecolours} for an example that changes
+the default colours.
\begin{figure}[htbp]
\centering
@@ -8174,7 +9865,7 @@ Whereas the body of the second letter appears as follows:
This section describes additional commands provided by the
\sty{person} package. More detail can be found in
-the documented code (datatool.pdf).
+the documented code (datatool-code.pdf).
\subsection{Conditionals}
@@ -8242,7 +9933,7 @@ name, full name, gender and label, respectively. (These arguments
must all be command names.) Note that the gender is set to
the definition of \DescribeMacro{\malename}\cs{malename} or
\DescribeMacro{\femalename}\cs{femalename}, as appropriate.\footnote{Predefined names provided by the \sty{person} package are described
-in the documented code (datatool.pdf).} Once these
+in the documented code (datatool-code.pdf).} Once these
commands are set, \meta{body} is applied.
If you only want to iterate through a subset of defined people,
diff --git a/Master/texmf-dist/doc/latex/datatool/datatool.pdf b/Master/texmf-dist/doc/latex/datatool/datatool.pdf
deleted file mode 100644
index 480ffef9ddf..00000000000
--- a/Master/texmf-dist/doc/latex/datatool/datatool.pdf
+++ /dev/null
Binary files 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 89ea8bf27c2..60711b2cfcd 100644
--- a/Master/texmf-dist/doc/latex/datatool/samples/sample-barchart.pdf
+++ b/Master/texmf-dist/doc/latex/datatool/samples/sample-barchart.pdf
Binary files 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
new file mode 100644
index 00000000000..90a504b882b
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/datatool/samples/sample-dict.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/latex/datatool/samples/sample-dict.tex b/Master/texmf-dist/doc/latex/datatool/samples/sample-dict.tex
new file mode 100644
index 00000000000..5f2dbee76dc
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/datatool/samples/sample-dict.tex
@@ -0,0 +1,439 @@
+\documentclass[oneside]{scrbook}
+
+\usepackage[T1]{fontenc}
+\usepackage[utf8]{inputenc}
+\usepackage{mathpazo}
+
+% The low optimize setting won't work for this example
+\usepackage[optimize=high]{datagidx}
+
+\usepackage[colorlinks]{hyperref}
+
+% This is an example document that uses datagidx to create a
+% sorted dictionary, using datatool to do the sorting.
+
+% Make a database labelled 'index' with the given title
+
+\newgidx[heading={\title}]{index}{Sample Dictionary Created Using datagidx}
+
+% Define some terms for the dictionary
+
+% First set the default database, so we don't have to keep using the
+% "database" key:
+\DTLgidxSetDefaultDB{index}
+
+% Add some custom fields
+
+\newtermaddfield{Derivatives}{derivatives}{}
+
+\newtermaddfield{Origin}{origin}{}
+
+\newtermaddfield{Phrases}{phrases}{}
+
+\newtermaddfield{Subject}{subject}{}
+
+\newtermaddfield{Variation}{variation}{}
+
+\newtermaddfield{Phonetic}{phonetic}{}
+
+\newtermaddfield{AltPlural}{altplural}{}
+
+\newtermaddfield{Parenthetical}{parenthetical}{}
+
+% Provide a convenient interface to define words:
+
+% Syntax: \newentry[main option list][cat opt list]{word}{category}{definition}
+
+\newcommand*{\newentry}[1][]{%
+ \def\newentryopts{#1}%
+ \nnewentry
+}
+
+\newcommand*{\nnewentry}[4][]{%
+ \expandafter\newterm\expandafter[\newentryopts]{#2}%
+ \newterm
+ [%
+ label={\datagidxlastlabel-#3},%
+ parent={\datagidxlastlabel},%
+ description={#4},%
+ text={#3},%
+ #1%
+ ]%
+ {#3}%
+ \setcounter{newentrysubcat}{0}%
+}
+
+% Syntax: \newentrycat{parent label}{category}{definition}
+
+\newcommand*{\newentrycat}[3]{%
+ \newterm
+ [%
+ label={#1-#2},%
+ parent={#1},%
+ description={#3}%
+ ]%
+ {#2}%
+ \setcounter{newentrysubcat}{0}%
+}
+
+% Syntax: \newentrysubcat[option list]{parent label}{description}
+
+\newcounter{newentrysubcat}
+
+\newcommand*{\newentrysubcat}[3][]{%
+ \stepcounter{newentrysubcat}%
+ \newterm
+ [%
+ label={#2-\arabic{newentrysubcat}},%
+ sort={#2-\arabic{newentrysubcat}},%
+ parent={#2},%
+ description={#3},%
+ #1%
+ ]
+ {}%
+}
+
+\newcommand*{\categoryand}{ \& }
+
+% hook into the mechanism that constructs the label and sort fields from
+% the name:
+
+\appto\newtermlabelhook{\def\categoryand{+}}
+
+\newcommand*{\namefont}[1]{\textbf{\sffamily #1}}
+\newcommand*{\subjectfont}[1]{\textsf{#1}}
+\newcommand*{\categoryfont}[1]{\namefont{#1}}
+\newcommand*{\originfont}[1]{\emph{#1}}
+\newcommand*{\derivativeformat}[2]{\textbf{#1}\space\textsf{#2}}
+\newcommand*{\phoneticformat}[1]{/#1/}
+
+\newcommand*{\stress}[1]{\textbf{#1}}
+
+\newcommand*{\crossref}[1]{\textbf{\useentry{#1}{Name}}}
+\newcommand*{\Crossref}[1]{\textbf{\textsc{\useentry{#1}{Name}}}}
+
+% Words and their definitions taken from the Compact Oxford English
+% Dictionary
+
+% label and sort must both be specified here as \newterm can't cope
+% with {\ae} when automatically generating the label and sort from
+% the name
+\newentry
+ [%
+ phonetic={ee-\stress{oh}-li-uhn},
+ origin={from \originfont{\AE olus}, the Greek god of the winds},
+ label=aeolian,
+ sort=aeolian
+ ]
+ {{\ae}olian harp}{noun}{a stringed instrument that produces musical
+sounds when a current of air passes through it}
+
+% Similarly label and sort are needed here
+\newentry
+ [%
+ phonetic={i-\stress{sof}-fuh-guhss},
+ plural={{œ}sophagi},
+ origin={Greek \originfont{oisophagos}},
+ label={oesophagus},
+ sort={oesophagus}
+ ]
+ {{œ}sophagus}{noun}{the muscular tube which connects throat to
+stomach}
+
+\newentry
+ [% additional info
+ origin={Old English}
+ ]%
+ [%
+ subject={literary}
+ ]
+ {asunder}{adverb}{apart}
+
+\newentry
+ [% additional info
+ origin={Old English},
+ parenthetical={\subjectfont{US} \namefont{adz}}
+ ]
+ {adze}{noun}{a tool similar to an axe, with an arched blade at right angles to
+ the handle}
+
+\newentry
+ [% additional info
+ origin={Latin \originfont{astutus}},
+ derivatives={\derivativeformat{astutely}{adverb}
+ \derivativeformat{astuteness}{noun}}
+ ]
+ {astute}{adjective}{good at making accurate judgements; shrewd}
+
+\newentry{astern}{adverb}{behind or towards the rear of a ship}
+
+\newentry{thunderbolt}{noun}{flash of lightning with a crash of
+thunder at the same time}
+
+\newentry{thunderclap}{noun}{a crash of thunder}
+
+\newentry
+ [%
+ origin={Italian \originfont{ticchio}}
+ ]
+ {tic}{noun}{a recurring spasm of the muscles, most often in
+the face}
+
+\newentry
+ [%
+ phonetic={thwort},
+ origin={from Old Norse, `transverse'}
+ ]
+ {thwart}{verb}{}
+
+\newentrysubcat{thwart-verb}{prevent someone from accomplishing
+something}
+
+\newentrysubcat{thwart-verb}{prevent something from succeeding}
+
+\newentrycat{thwart}{noun}{a crosspiece forming a seat for a rower
+in a boat}
+
+\newentry
+ [% additional info
+ origin={from an old sense of \Crossref{thwart}, meaning
+`across'},
+ phonetic={uh-\stress{thwart}}
+ ]
+ {athwart}{preposition\categoryand adverb}{from side to side of something;
+ across}
+
+\newentry
+ [%
+ phonetic={aw-\stress{bree}-shuh},
+ parenthetical={also \namefont{aubrietia}},
+ origin={named after the French botanist Claude \originfont{Aubriet}}
+ ]
+ {aubretia}{noun}{a trailing plant with purple, pink, or white
+flowers}
+
+\newentry
+ [%
+ phonetic={aw-\stress{day}-shuhss},
+ derivatives={\derivativeformat{audaciously}{adverb}
+ \derivativeformat{audaciousness}{noun}
+ \derivativeformat{audacity}{noun}},
+ origin={Latin \originfont{audax} `bold'}
+ ]
+ {audacious}{adjective}{}
+
+\newentrysubcat{audacious-adjective}{willing to take daring risks}
+\newentrysubcat{audacious-adjective}{showing lack of respect; rude
+or impudent}
+
+\newentry
+ [%
+ parenthetical={pl.\ \namefont{attorneys}},
+ phonetic={uh-\stress{ter}-ni},
+ origin={Old French \originfont{atorner} `assign'}
+ ]
+ {attorney}{noun}{}
+
+\newentrysubcat{attorney-noun}{a person appointed to act for another
+in legal matters}
+
+\newentrysubcat
+ [%
+ subject={chiefly US}%
+ ]
+ {attorney-noun}{a lawyer}
+
+\newentry
+ [
+ phonetic={\stress{ay}-tri-uhm},
+ altplural={atria},
+ parenthetical={pl.\ \namefont{atria}
+ \phoneticformat{\stress{ay}-tri-uh}
+ or \namefont{atriums}},
+ derivatives={\derivativeformat{atrial}{adjective}},
+ origin={Latin}
+ ]
+ {atrium}{noun}{}
+
+\newentrysubcat{atrium-noun}{a central hall rising through several
+storeys and having a glazed roof}
+
+\newentrysubcat{atrium-noun}{an open area in the centre of an
+ancient Roman house}
+
+\newentrysubcat{atrium-noun}{each of the two cavities of the heart}
+
+\newentry
+ [%
+ plural={austerities},
+ phonetic={oss-\stress{te}-ri-ti}
+ ]
+ {austerity}{noun}{}
+
+\newentrysubcat{austerity-noun}{strictness or severity of appearance
+or manner}
+\newentrysubcat{austerity-noun}{difficult economic conditions
+resulting from a cut in public spending}
+
+\newentry
+[
+ plural={cacti},
+ altplural={cactuses},
+ origin={Greek \originfont{kaktos} `cardoon'}
+]
+{cactus}{noun}{a succulent plant with thick fleshy stems bearing
+spikes but no leaves}
+
+\newentry
+ [%
+ phonetic={chahf},
+ phrases={\namefont{separate} (or \namefont{sort}) \namefont{the
+ wheat from the chaff} distinguish valuable people or things from
+ worthless ones},
+ origin={Old English}
+ ]
+ {chaff\textsuperscript{1}}{noun}{}
+
+\newentrysubcat{chaff1-noun}{the husks of grain from the seed by
+winnowing or threshing}
+
+\newentrysubcat{chaff1-noun}{chopped hay and straw used in cattle
+fodder}
+
+\newentry
+ [
+ phonetic={chaff},
+ ]
+ {chaff\textsuperscript{2}}{noun}{light-hearted joking}
+
+\newentrycat{chaff2}{verb}{tease someone}
+
+\newterm
+[
+ plural={elves},%
+ derivatives={\derivativeformat{elfish}{adjective}
+ \derivativeformat{elven}{adjective (literary)}
+ \derivativeformat{elvish}{adjective}},%
+ origin={Old English},%
+ description={a supernatural creature of folk tales, represented as
+ a small human figure with pointed ears}
+]
+{elf}
+
+% Be careful of words starting with an accent.
+
+\newterm
+ [
+ label={elite},%
+ phonetic={i-\stress{leet}},%
+ origin={French, `selection, choice'}%
+ ]
+ {{é}lite}
+
+\newentrycat{elite}{noun}{a group of people regarded as the best in a
+particular society or organisation}
+
+\newterm
+ [
+ description={plural of \Crossref{elf}}%
+ ]
+ {elves}
+
+% Add all entries
+
+\glsaddall{index}
+
+% Customise index format
+
+\renewcommand{\DTLgidxNameFont}[1]{\namefont{\large#1}}
+
+\newcommand{\postnamespace}{\space}
+
+\renewcommand{\DTLgidxPostName}{%
+ \ifdefempty\Subject
+ {%
+ }%
+ {%
+ \space\subjectfont{\Subject}%
+ }%
+ \ifdefempty\Phonetic
+ {%
+ }%
+ {%
+ \space\phoneticformat{\Phonetic}%
+ }%
+ \ifdefempty\Parenthetical
+ {%
+ \ifdefempty\AltPlural
+ {%
+ \ifthenelse{\equal{\Plural}{\Text s}}%
+ {%
+ }%
+ {%
+ \space (pl.\ \namefont{\Plural})%
+ }%
+ }%
+ {%
+ \space (pl. \namefont{\Plural} or \namefont{\AltPlural})%
+ }%
+ }%
+ {%
+ \space (\Parenthetical)%
+ }%
+ \postnamespace
+}
+
+\renewcommand{\DTLgidxCategoryNameFont}[1]{\categoryfont{#1}}
+\renewcommand{\DTLgidxCategorySep}{\space\textbullet\space}
+\renewcommand*{\DTLgidxChildCountLabel}{%
+ \def\postnamespace{~\def\postnamespace{\space}}%
+ \textbf{\sffamily\theDTLgidxChildCount}%
+}
+
+\renewcommand{\DTLgidxDictPostItem}{%
+ \ifdefempty\Derivatives
+ {}
+ {%
+ \par
+ \datagidxdictparshape
+ -- \textsc{derivatives} \Derivatives.
+ }%
+ \ifdefempty\Phrases
+ {}
+ {%
+ \par
+ \datagidxdictparshape
+ -- \textsc{phrases} \Phrases.
+ }%
+ \ifdefempty\Origin
+ {}
+ {%
+ \par
+ \datagidxdictparshape
+ -- \textsc{origin} \Origin.
+ }%
+ \par
+}
+
+% Title information
+\author{}
+\date{}
+
+\begin{document}
+% don't number the chapters
+\setcounter{secnumdepth}{-1}
+
+\printterms
+[
+ database=index,
+ postheading={\maketitle This is an example document illustrating
+ the use of the datagidx package. The examples here are taken from
+ the Compact Oxford English Dictionary.
+ },
+ columns=2,
+ postdesc=dot,%
+ childsort=false,% don't sort the child lists
+ style={dict} % use the 'dict' style
+]
+
+\end{document}
diff --git a/Master/texmf-dist/doc/latex/datatool/samples/sample-gidx.pdf b/Master/texmf-dist/doc/latex/datatool/samples/sample-gidx.pdf
new file mode 100644
index 00000000000..eb3c2b9f78f
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/datatool/samples/sample-gidx.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/latex/datatool/samples/sample-gidx.tex b/Master/texmf-dist/doc/latex/datatool/samples/sample-gidx.tex
new file mode 100644
index 00000000000..e5c0d2eafb5
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/datatool/samples/sample-gidx.tex
@@ -0,0 +1,644 @@
+\documentclass{book}
+
+\usepackage{datagidx}
+
+\usepackage[colorlinks]{hyperref}
+
+\usepackage{fmtcount}
+
+\DTLgidxAddLocationType{numberstringnum}
+
+ % Define some convenient commands
+
+\newcommand*{\principleloc}[1]{\textbf{#1}}
+\newcommand*{\glossaryloc}[1]{\textit{#1}}
+\newcommand*{\appname}[1]{\texttt{#1}}
+
+ % Don't let \appname interfere with the sorting and labelling of
+ % terms:
+
+\appto\newtermlabelhook{\let\appname\DTLgidxNoFormat}
+
+ % (datagidx also does this for \MakeUppercase, \MakeTextUppercase,
+ % \MakeLowercase, \MakeTextLowercase, \textsc and \acronymfont.)
+
+ % Make an index database labelled 'index' with given title.
+ % (Omit optional argument to affect all indexing databases
+ % or use a comma-separated list of labels for each database
+ % to affect.)
+
+\newgidx[heading=\chapter]{index}{Index}
+
+ % Add custom fields to the 'index' database
+
+\newtermaddfield[index]{Ed}{ed}{\field{text}ed}
+
+\newtermaddfield[index]{Ing}{ing}{\field{text}ing}
+
+\newtermaddfield[index]{AltPlural}{altplural}{}% no default value
+
+ % Define some convenience commands to access these fields
+
+\newcommand*{\glsed}[1]{\useentry{#1}{Ed}}
+\newcommand*{\glsing}[1]{\useentry{#1}{Ing}}
+\newcommand*{\glsaltpl}[1]{\useentry{#1}{AltPlural}}
+
+ % Make a glossary database labelled 'glossary' with given title.
+
+\newgidx[heading=\section]{glossary}{Glossary}
+
+ % Make an acronym database labelled 'acronyms' with given title.
+ % A different heading for the table of contents is supplied.
+
+\newgidx[heading={\section[Acronyms]}]{acronyms}{List of Acronyms}
+
+ % Make a notation database labelled 'notation' with given title
+
+\newgidx[heading=\section]{notation}{Notation}
+
+ % Define some terms for the index
+
+ % Either use "database" key in optional argument
+ % or set the default database. It's less typing to set the default
+ % database, so let's do that:
+
+\DTLgidxSetDefaultDB{index}
+
+ % These definitions will add terms to the "index" database:
+
+\newterm{singular}
+\newterm{plural}
+\newterm
+ [% options
+ label=pluralalt,
+ parent=plural,
+ see={altplural}
+ ]
+ {alternative}
+\newterm[label=altplural]{alternative plural}
+\newterm{group}
+\newterm[see=group]{scope}
+\newterm[label={ind-glossary}]{glossary}
+\newterm
+ [%
+ label={ind-index},
+ seealso={ind-glossary},
+ ]
+ {index}
+\newterm
+ [
+ seealso={ind-glossary}
+ ]
+ {acronym}
+\newterm[parent=acronym]{reset}
+\newterm
+ [%
+ parent=acronym,
+ label={firstuse},
+ ]
+ {first use}
+\newterm
+ [%
+ parent=acronym,
+ label={acronymlist},
+ text={list of acronyms},
+ plural={lists of acronyms}
+ ]
+ {list}
+
+ % Be careful if a value contains a comma or an equal sign. The
+ % entire value must be grouped.
+\newterm
+ [%
+ label={comma},
+ sort={,},
+ text={comma (,)},
+ plural={commas (,)}
+ ]%
+ {, (comma)}
+
+\newterm
+ [%
+ label={equals},
+ sort={=},
+ text={equal sign (=)},
+ plural={equal signs (=)},
+ ]%
+ {= (equal sign)}
+
+ % Don't need to worry about makeindex's special characters (since
+ % we're not using makeindex!)
+\newterm
+ [%
+ label={"},
+ sort={"},
+ text={double quote (")},
+ plural={double quotes (")},
+ ]%
+ {" (double quote)}
+
+\newterm
+ [%
+ label={!},
+ sort={!},
+ text={exclamation mark (!)},
+ plural={exclamation marks (!)},
+ ]%
+ {! (exclamation mark)}
+
+\newterm
+ [%
+ label={|},
+ sort={|},
+ text={vertical bar (\textbar)},
+ plural={vertical bars (\textbar)},
+ ]%
+ {\textbar\ (vertical bar)}
+
+
+ % Be careful of special characters
+
+\newterm
+ [%
+ label={amp},
+ sort={\DTLgidxStripBackslash{\&}},
+ text={ampersand (\&)},
+ plural={ampersands (\&)},
+ ]
+ {\& (ampersand)}
+
+\newterm
+ [%
+ label={underscore},
+ sort={\DTLgidxStripBackslash{\_}},
+ text={underscore (\_)},
+ plural={underscores (\_)},
+ ]
+ {\_ (underscore)}
+
+\newterm
+ [%
+ label={dollar},
+ sort={\DTLgidxStripBackslash{\$}},
+ text={dollar (\$)},
+ plural={dollars (\$)},
+ ]
+ {\$ (dollar)}
+
+\newterm
+ [%
+ label={circum},
+ sort={\DTLgidxStripBackslash{\^}},
+ text={circumflex (\textasciicircum)},
+ plural={circumflexes (\textasciicircum)},
+ ]
+ {\textasciicircum\ (circumflex)}
+
+\newterm
+ [%
+ label={tilde},
+ sort={\string~},
+ text={tilde (\textasciitilde)},
+ plural={tildes (\textasciitilde)},
+ ]
+ {\textasciitilde\ (tilde)}
+
+\newterm
+ [
+ label={0},
+ sort={0},
+ ]
+ {0 (zero)}
+
+\newterm
+ [
+ label={1},
+ sort={1},
+ ]
+ {1 (one)}
+
+\newterm
+ [
+ label={2},
+ sort={2},
+ ]
+ {2 (two)}
+
+\newterm
+ [
+ label={3},
+ sort={3},
+ ]
+ {3 (three)}
+
+ % Let's index a person
+\newterm
+ [%
+ label={knuth},
+ text={Knuth},
+ ]
+ {Knuth, Donald E.}
+
+ % and have a few more entries in the same letter group to test case
+ % ordering:
+\newterm{kite}
+\newterm{koala}
+
+ % Earlier I modified \newtermlabelhook so
+ % that \appname won't interfere with the sorting
+ % and labelling mechanism, so I don't need to specify separate sort
+ % and label keys here:
+
+\newterm{\appname{makeindex}}% label and sort both set to just 'makeindex'
+\newterm{\appname{xindy}}% label and sort both set to just 'xindy'
+
+ % Define some terms for the glossary
+
+\DTLgidxSetDefaultDB{glossary}
+
+\newterm[description={sea mammal with flippers that eats fish}]{seal}
+\newterm[description={large seal}]{sea lion}
+
+\newterm{bravo}
+\newterm
+ [%
+ label=bravocry,
+ description={cry of approval (pl.\ bravos)},
+ parent=bravo
+ ]
+ {bravo}
+\newterm
+ [% options
+ label=bravokiller,
+ description={hired ruffian or killer (pl.\ bravoes)},
+ plural=bravoes,
+ parent=bravo
+ ]
+ {bravo}
+
+\newterm
+ [% options
+ text={glossary\glsadd{ind-glossary}},
+ plural={glossaries\glsadd{ind-glossary}},
+ ]%
+ {glossary\glsadd{ind-glossary}}
+
+\newterm
+ [% options
+ label=glossarycol,
+ text={glossary\glsadd{ind-glossary}},
+ plural={glossaries\glsadd{ind-glossary}},
+ description={collection of glosses},
+ parent=glossary
+ ]
+ {glossary\glsadd{[glossaryloc]ind-glossary}}
+
+\newterm
+ [% options
+ label=glossarylist,
+ text={glossary\glsadd{ind-glossary}},
+ plural={glossaries\glsadd{ind-glossary}},
+ description={list of technical words},
+ parent=glossary
+ ]
+ {glossary\glsadd{[glossaryloc]ind-glossary}}
+
+\newterm
+ [%
+ plural={indices\glsadd{ind-index}},
+ altplural={indexes},
+ text={index\glsadd{ind-index}},
+ description={an alphabetical list of names or subjects with
+ references to their location in the document (pl.\ indices or
+ indexes)}
+ ]
+ {index\glsadd{[glossaryloc]ind-index}}
+
+\newterm
+ [% options
+ label=pglist,
+ % description contains commas so it must be grouped
+ description={a list of individual pages or page ranges
+ (e.g.\ 1,2,4,7--9)}
+ ]
+ {page list}
+
+ % define some acronyms
+
+\DTLgidxSetDefaultDB{acronyms}
+
+ % Let's redefine \newacro so that the short form is also indexed:
+
+\renewcommand{\newacro}[3][]{%
+ \newterm[database=index,label={ind-#2-long},see={ind-#2}]{#3}%
+ \newterm[database=index,label={ind-#2}]{\acronymfont{#2}}%
+ \newterm
+ [%
+ description={\capitalisewords{#3}},% long form capitalised
+ text={\DTLgidxAcrStyle{#3}{\acronymfont{#2}}},% produced via \gls
+ plural={\DTLgidxAcrStyle{#3}{\acronymfont{#2}}},% produced via \glspl
+ short={\acronymfont{#2}\glsadd{ind-#2}},% short form
+ long={#3},% long form
+ sort={#2},% sort on short form
+ #1%
+ ]%
+ {#2\glsadd{[glossaryloc]ind-#2}}
+}
+
+\newacro{html}{hyper-text markup language}
+\newacro{css}{cascading style sheet}
+\newacro{xml}{extensible markup language}
+
+% define some notation
+
+\DTLgidxSetDefaultDB{notation}
+
+\newterm
+ [%
+ symbol={\ensuremath{\mathcal{S}}},
+ description={a collection of distinct objects},
+ ]%
+ {set}
+
+\newterm
+ [%
+ parent=set,
+ symbol={\ensuremath{\mathcal{U}}},
+ text={universal set},
+ description={the set containing everything}
+ ]%
+ {universal}
+
+\newterm
+ [%
+ parent=set,
+ symbol={\ensuremath{\emptyset}},
+ text={empty set},
+ description={the set with no elements}
+ ]%
+ {empty}
+
+\newterm
+ [%
+ symbol={\ensuremath{|\mathcal{S}|}},
+ description={the number of elements in the set \ensuremath{\mathcal{S}}}
+ ]%
+ {cardinality}
+
+\title{Sample Document Using the datagidx Package}
+\author{Nicola L. C. Talbot}
+
+\begin{document}
+\pagenumbering{alph}% Stop hyperref complaining about duplicate page identifiers
+\maketitle
+\thispagestyle{empty}%
+
+\frontmatter
+
+\tableofcontents
+
+\chapter{Summary}
+
+This is a sample document illustrating the use of the
+\texttt{datagidx} package to create document \glspl{index},
+\glspl{glossarylist} and \glspl{acronymlist} without the use of
+external \glsing{index} % custom command defined earlier
+applications, such as \gls{makeindex} or
+\gls{xindy}. Please read the user guide (datatool-user.pdf) for
+further guidance.
+
+\mainmatter
+
+\chapter{Introduction}
+%\renewcommand{\thepage}{\numberstring{page}}
+
+Words can be \glsed{index}. % custom command defined earlier.
+
+A \gls{glossarylist}\glsadd{[principleloc]ind-glossary} is a useful addition to any technical document,
+although a \gls{glossarycol} can also simply be a collection of
+glosses, which is another thing entirely. Some documents have
+multiple \glspl{glossarylist}.
+
+A \gls{bravocry} is a cry of approval (plural \glspl{bravocry}) but a
+\gls{bravokiller} can also be a hired ruffian or killer (plural
+\glspl{bravokiller}).
+
+\section{Characters}
+
+When defining entries be careful of \glspl{comma} and \glspl{equals}
+so they don't interfere with the key=value mechanism. The sort and
+label keys get expanded so be careful of special characters, such as
+\gls{amp}, \gls{underscore}, \gls{circum}, \gls{dollar} and \gls{tilde}.
+
+Since we're not using \gls{makeindex}, we don't need to worry about
+\gls{makeindex}'s special characters, such as \gls{"}, \gls{!} and
+\gls{|}. (Unless they've been made active by packages such as
+\texttt{ngerman} or \texttt{babel}.)
+
+Non-alphabetical characters are usually grouped at the start of an
+index, and are usually followed by the number group. That is, the
+group of entries that are numerical, such as \gls{0}, \gls{1},
+\gls{2} and \gls{3}.
+
+\section{Custom Fields}
+
+You can add custom fields. For example, this document has added
+three custom fields to the `index' database.
+
+\section{Plurals}
+
+The \gls{plural} of \gls{glossarylist} is
+\glspl{glossarylist}. The \gls{plural} of \gls{index} is
+\glspl{index}. Some words have an \gls{altplural}. For example,
+an alternative to \glspl{index} is
+\glsaltpl{index}.% custom command defined earlier
+
+\section{Sorting}
+
+The only type of sorting available is letter sorting. If you want
+word sorting you'll need to use \gls{makeindex} or \gls{xindy}.
+So ``\gls{sea lion}'' comes after ``\gls{seal}''.
+
+The default sort is case-insensitive so \gls{kite} before
+\gls{knuth} and \gls{knuth} before \gls{koala}.
+
+\section{Using without indexing}
+
+Here's a defined entry that won't get into the glossary.
+Name: \glsdispentry{pglist}{Name}.
+Description: \glsdispentry{pglist}{Description}.
+(Unless I~later reference it using a command like \verb|\gls|.)
+
+\section{Links to Entries}
+
+You can reference and index entries using \verb|\gls|, \verb|\Gls|,
+\verb|\glspl|, \verb|\Glspl|, \verb|\glssym| and \verb|\Glssym|.
+(Note, if you're used to using the \texttt{glossaries} package
+the syntax is different.)
+
+Or you can reference a particular field using \verb|\useentry| or
+\verb|\Useentry|. So here's the description for \gls{seal}:
+\useentry{seal}{Description}.
+
+If the \texttt{hyperref} package has been loaded, commands like
+\verb|\gls| will link to the relevant entry in the glossary or
+index. Referencing using \verb|\glsdispentry| and
+\verb|\Glsdispentry| won't have hyperlinks.
+
+\subsection{Enabling and Disabling Hyperlinks}
+
+If the \texttt{hyperref} package has been loaded, hyperlinks can be
+enabled and disabled. Either globally
+\DTLgidxDisableHyper
+(here's a reference to \gls{seal} without a hyperlink
+\DTLgidxEnableHyper
+ and here's a reference to \gls{seal} with a hyperlink)
+or locally
+({%
+ \DTLgidxDisableHyper
+ here's a reference to \gls{seal} without a hyperlink
+}%
+and here's a reference to \gls{seal} with a hyperlink).
+
+\section{Acronyms}
+
+\glsadd{firstuse}Here's an \gls{acronym} referenced using \verb|\acr|: \acr{html}. And here
+it is again: \acr{html}. If you're used to the \texttt{glossaries}
+package, note the difference in using \verb|\gls|: \gls{html}.
+And again (no difference): \gls{html}.
+
+Now let's switch to displaying acronyms with a footnote.
+ % syntax: \DTLgidxAcrStyle{long}{short}
+\renewcommand*{\DTLgidxAcrStyle}[2]{%
+ #2\footnote{#1.}%
+}%
+First use: \acr{xml}. Next use: \acr{xml}.
+
+However it would look better if the footnote text started with a
+capital letter, so let's tweak things a bit.
+ % syntax: \DTLgidxFormatAcr{label}{long field}{short field}
+\renewcommand*{\DTLgidxFormatAcr}[3]{%
+ \DTLgidxAcrStyle{\Glsdispentry{#1}{#2}}{\useentry{#1}{#3}}%
+}%
+ % syntax: \DTLgidxFormatAcr{label}{long field}{short field}
+\renewcommand*{\DTLgidxFormatAcrUC}[3]{%
+ \DTLgidxAcrStyle{\Glsdispentry{#1}{#2}}{\Useentry{#1}{#3}}%
+}%
+Try with another acronym: \acr{css}. Next use: \acr{css}.
+
+\glsadd{reset}Reset: \glsresetall{acronyms}%
+\renewcommand*{\DTLgidxAcrStyle}[2]{#1 (#2)}%
+\renewcommand*{\DTLgidxFormatAcr}[3]{%
+ \DTLgidxAcrStyle{\glsdispentry{#1}{#2}}{\useentry{#1}{#3}}%
+}%
+\renewcommand*{\DTLgidxFormatAcrUC}[3]{%
+ \DTLgidxAcrStyle{\Glsdispentry{#1}{#2}}{\useentry{#1}{#3}}%
+}%
+Here are the acronyms again:
+\acr{html}, \acr{xml} and \acr{css}.
+Next use:
+\acr{html}, \acr{xml} and \acr{css}.
+Full form:
+\gls{html}, \gls{xml} and \gls{css}.
+
+Reset again. \glsresetall{acronyms}%
+Start with a capital. \Acr{html}.
+Next: \Acr{html}. Full: \Gls{html}.
+
+Prefer small-caps?
+\renewcommand{\acronymfont}[1]{\textsc{#1}}%
+\Acr{css}. Next: \acr{css}. Full: \gls{css}.
+
+Prefer capitals?
+\renewcommand{\acronymfont}[1]{\MakeTextUppercase{#1}}%
+\Acr{xml}. Next: \acr{xml}. Full: \gls{xml}.
+
+\section{Conditionals}
+
+You can test if a term has been defined using \verb|\iftermexists|.
+For example: \iftermexists{seal}{seal exists}{seal doesn't exist}.
+Another example: \iftermexists{jabberwocky}{jabberwocky
+exists}{jabberwocky doesn't exist}.
+
+You can test if a term has been used via \verb|ifentryused|.
+For example: \ifentryused{seal}{seal has been used}{seal hasn't been
+used.}
+Another example: \ifentryused{pglist}{pglist has been used}{pglist
+hasn't been used}.
+
+
+\section{Symbols}
+
+Terms may have an associated symbol. The symbol can be accessed
+using \verb|\glssym| or if you don't want to add information to the
+location list you can use \verb|\glsdispentry|. Here's the symbol
+associated with the \gls{cardinality} entry:
+\glsdispentry{cardinality}{Symbol}.
+
+A \gls{set} (denoted \glssym{set}) is a collection of objects.
+The \gls{universal} is the set of everything.
+The \gls{empty} contains no elements.
+The \gls{cardinality} of a set (denoted \glssym{cardinality}) is the
+number of elements in the set.
+
+\section{Location Ranges}
+
+A range is formed if a location sequence contains more than 2
+locations. Here's \gls{seal} again.
+
+\backmatter
+ % suppress section numbering
+\setcounter{secnumdepth}{-1}
+
+\chapter{Glossaries}
+
+\printterms
+ [
+ database=glossary,% 'glossary' database
+ columns=1,% one column page layout
+ postdesc=dot,% put a full stop after the description
+ style=gloss,% use 'gloss' style (sub-entries numbered)
+ namefont={\textbf},% put the name in bold
+ namecase=firstuc,% make the first letter of the name upper case
+ child=noname,% don't print sub item names
+ childsort=false,% don't sort the child lists
+% location=hide% hide the location list
+ ]
+
+\printterms
+ [
+ database=acronyms,% 'acronyms' database
+ postdesc=dot,% put a full stop after the description
+ columns=1,% one column page layout
+ namefont={\textbf},% put the name (i.e. the abbreviation) in bold
+ namecase=uc,% make the name upper case
+ style=align,% use the 'align' style
+% location=hide% hide the location list
+ ]
+
+\printterms
+ [
+ database=notation,% 'notation' database
+ postdesc=dot,% put a full stop after the description
+ columns=1,% one page column layout
+ namefont={\textbf},% make the name bold
+ style=indexalign,
+ namecase=firstuc,% make first letter of name a capital
+ symboldesc={desc (symbol)},% put symbol to the right of the description
+ sort={}% don't sort
+ ]
+
+\printterms
+ [
+ database=index,% 'index' database
+ prelocation=dotfill,% put a dotted line before the location list
+ columns=2,% page layout
+ style=index,% use 'index' style
+ %balance=false,% don't balance columns
+ postheading={Locations in bold indicate primary reference.
+ Locations in italic indicate definitions in the
+ glossaries.}
+ ]
+
+
+\end{document}
diff --git a/Master/texmf-dist/doc/latex/datatool/samples/sample-glossary.pdf b/Master/texmf-dist/doc/latex/datatool/samples/sample-glossary.pdf
new file mode 100644
index 00000000000..df054ced862
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/datatool/samples/sample-glossary.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/latex/datatool/samples/sample-glossary.tex b/Master/texmf-dist/doc/latex/datatool/samples/sample-glossary.tex
new file mode 100644
index 00000000000..b24fa252894
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/datatool/samples/sample-glossary.tex
@@ -0,0 +1,245 @@
+\documentclass{article}
+
+\usepackage{datagidx}
+
+\usepackage[colorlinks]{hyperref}
+
+ % Make a glossary database labelled 'glossary' with given title.
+
+\newgidx[heading=\section]{glossary}{Glossary}
+
+ % Make an acronym database labelled 'acronyms' with given title.
+ % A different heading for the table of contents is supplied.
+
+\newgidx[heading={\section[Acronyms]}]{acronyms}{List of Acronyms}
+
+ % Make a notation database labelled 'notation' with given title
+ % Make it an unnumbered section
+
+\newgidx[heading=\section*]{notation}{Notation}
+
+ % Define some terms for the glossary
+
+\DTLgidxSetDefaultDB{glossary}
+
+\newterm[description={sea mammal with flippers that eats
+fish}]{seal}
+\newterm[description={large seal}]{sea lion}
+
+\newterm{bravo}
+\newterm
+ [%
+ label=bravocry,
+ description={cry of approval (pl.\ bravos)},
+ parent=bravo
+ ]
+ {bravo}
+\newterm
+ [% options
+ label=bravokiller,
+ description={hired ruffian or killer (pl.\ bravoes)},
+ plural=bravoes,
+ parent=bravo
+ ]
+ {bravo}
+
+\newterm
+ [% options
+ plural={glossaries},
+ ]%
+ {glossary}
+
+\newterm
+ [% options
+ label=glossarycol,
+ plural={glossaries},
+ description={collection of glosses},
+ parent=glossary
+ ]
+ {glossary}
+
+\newterm
+ [% options
+ label=glossarylist,
+ plural={glossaries},
+ description={list of technical words},
+ parent=glossary
+ ]
+ {glossary}
+
+\newterm
+ [% options
+ % description contains commas so it must be grouped
+ description={a list of individual pages or page ranges
+ (e.g.\ 1,2,4,7--9)}
+ ]
+ {page list}
+
+\newterm
+ [%
+ plural={indices},
+ description={an alphabetical list of names or subjects with
+ references to their location in the document (pl.\ indices or
+ indexes)}
+ ]
+ {index}
+
+ % define some acronyms
+
+\DTLgidxSetDefaultDB{acronyms}
+
+\newacro{html}{hyper-text markup language}
+\newacro{css}{cascading style sheet}
+
+% override default description on this one:
+\newacro[description={eXtensible Markup Language}]{xml}{extensible markup language}
+
+% define some notation
+
+\DTLgidxSetDefaultDB{notation}
+
+\newterm
+ [%
+ symbol={\ensuremath{\mathcal{S}}},
+ description={a collection of distinct objects},
+ ]%
+ {set}
+
+\newterm
+ [%
+ symbol={\ensuremath{\mathcal{U}}},
+ description={the set containing everything}
+ ]%
+ {universal set}
+
+\newterm
+ [%
+ symbol={\ensuremath{\emptyset}},
+ description={the set with no elements}
+ ]%
+ {empty set}
+
+\newterm
+ [%
+ symbol={\ensuremath{|\mathcal{S}|}},
+ description={the number of elements in the set
+\ensuremath{\mathcal{S}}}
+ ]%
+ {cardinality}
+
+\title{Sample Document Using the datagidx Package}
+\author{Nicola L. C. Talbot}
+
+\begin{document}
+
+\maketitle
+
+Here's an acronym referenced using \verb|\acr|: \acr{html}.
+And here
+it is again: \acr{html}. If you're used to the \texttt{glossaries}
+package, note the difference in using \verb|\gls|: \gls{html}.
+And again (no difference): \gls{html}.
+
+Here are some more entries:
+
+\acr{xml} and \acr{css}.
+Next use:
+\acr{xml} and \acr{css}.
+Full form:
+\gls{xml} and \gls{css}.
+
+Reset again. \glsresetall{acronyms}%
+Start with a capital. \Acr{html}.
+Next: \Acr{html}. Full: \Gls{html}.
+
+Prefer capitals?
+\renewcommand{\acronymfont}[1]{\MakeTextUppercase{#1}}%
+\Acr{xml}. Next: \acr{xml}. Full: \gls{xml}.
+
+Prefer small-caps?
+\renewcommand{\acronymfont}[1]{\textsc{#1}}%
+\Acr{css}. Next: \acr{css}. Full: \gls{css}.
+
+A \gls{set} (denoted \glssym{set}) is a collection of objects.
+The \gls{universal set} is the set of everything.
+The \gls{empty set} contains no elements.
+The \gls{cardinality} of a set (denoted \glssym{cardinality}) is the
+number of elements in the set.
+
+A \gls{glossarylist} is a useful
+addition to any technical document,
+although a \gls{glossarycol} can also simply be a collection of
+glosses, which is another thing entirely. Some documents have
+multiple \glspl{glossarylist}. Entries in a \gls{glossarylist} or
+\gls{index} have an associated \gls{page list}.
+
+A \gls{bravocry} is a cry of approval (plural \glspl{bravocry}) but
+a
+\gls{bravokiller} can also be a hired ruffian or killer (plural
+\glspl{bravokiller}).
+
+\newpage
+
+Resetting all acronyms.\glsresetall{acronyms}
+
+Here are the acronyms again:
+
+\Acr{html}, \acr{xml} and \acr{css}.
+
+Next use:
+\Acr{html}, \acr{xml} and \acr{css}.
+
+Full form:
+\Gls{html}, \gls{xml} and \gls{css}.
+
+
+\newpage
+
+\printterms
+ [
+ database=glossary,% 'glossary' database
+ columns=1,% one column page layout
+ postdesc=dot,% put a full stop after the description
+ style=gloss,% use 'gloss' style (sub-entries numbered)
+ namefont={\textbf},% put the name in bold
+ namecase=firstuc,% make the first letter of the name upper case
+ child=noname,% don't print sub item names
+ location=hide% hide the location list
+ ]
+
+\printterms
+ [
+ database=acronyms,% 'acronyms' database
+ postdesc=dot,% put a full stop after the description
+ columns=1,% one column page layout
+ namefont={\textbf},% put the name (i.e. the abbreviation) in bold
+ namecase=uc,% make the name upper case
+ style=align,% use the 'align' style
+ ]
+
+% Change the way the description is formatted (the argument to
+% \DTLgidxFormatDesc will always be a control sequence so
+% \xmakefirstuc is needed instead of \makefirstuc)
+\renewcommand{\DTLgidxFormatDesc}[1]{\xmakefirstuc{#1}}
+
+\printterms
+ [
+ database=notation,% 'notation' database
+ postdesc=dot,% put a full stop after the description
+ columns=1,% one page column layout
+ namefont={\textbf},% make the name bold
+ style=indexalign,
+ namecase=firstuc,% make first letter of name a capital
+ symboldesc={symbol desc},% put symbol to the left of description
+ %symboldesc={desc (symbol)},% put symbol to the right of the description
+ sort={},% don't sort
+% If the following widths are 0 (default) they take up their natural
+% amount of space. If the widths are greater than 0, those fields
+% are put in a box of the given width.
+ symbolwidth={2cm},% width taken up by symbol
+ locationwidth={1cm},% width taken up by location list
+ ]
+
+
+
+\end{document}
diff --git a/Master/texmf-dist/doc/latex/datatool/samples/sample-index.pdf b/Master/texmf-dist/doc/latex/datatool/samples/sample-index.pdf
new file mode 100644
index 00000000000..03e95157250
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/datatool/samples/sample-index.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/latex/datatool/samples/sample-index.tex b/Master/texmf-dist/doc/latex/datatool/samples/sample-index.tex
new file mode 100644
index 00000000000..2a2673d0cc7
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/datatool/samples/sample-index.tex
@@ -0,0 +1,735 @@
+\documentclass{article}
+
+\usepackage[T1]{fontenc}
+\usepackage[utf8]{inputenc}
+
+ % Two LaTeX runs are required to ensure this document is up-to-date
+
+ % It can take a long time to sort the index, so use the optimize
+ % option. This has values: off (no optimize, sorting is done every
+ % run), low (sort every second run) or high (write sorted database
+ % to file and read in next time round). Don't modify the
+ % index/glossary databases while the optimize option is set to
+ % high. Do the modifications while the optimize option is set to
+ % low or off. Alternatively, delete the .aux and .gidx files before rerunning
+ % LaTeX.
+
+%\usepackage[optimize=high]{datagidx}
+\usepackage[optimize=off]{datagidx}
+
+\usepackage[colorlinks]{hyperref}
+
+ % Define some convenient commands
+
+\newcommand*{\principleloc}[1]{\textbf{#1}}
+\newcommand*{\appname}[1]{\texttt{#1}}
+
+ % Later we'll switch to a fancy small caps Roman page numbering
+
+\newcommand*{\myscroman}[1]{%
+ \myscromannum{\value{#1}}%
+}
+
+\newcommand*{\myscromannum}[1]{%
+ \textsc{\romannumeral#1}%
+}
+
+ % Now we need to add this as a possible location type
+
+\DTLgidxAddLocationType{myscromannum}
+
+ % Don't let \appname interfere with the sorting and labelling of
+ % terms:
+
+\appto\newtermlabelhook{\let\appname\DTLgidxNoFormat}
+
+ % (datagidx also does this for \MakeUppercase, \MakeTextUppercase,
+ % \MakeLowercase, \MakeTextLowercase, \textsc and \acronymfont.)
+
+ % Make an index database labelled 'index' with given title.
+
+\newgidx{index}{Index}
+
+ % Define some terms for the index (entries must be defined in the
+ % preamble).
+
+ % Either use "database" key in optional argument
+ % or set the default database. It's less typing to set the default
+ % database, so let's do that:
+
+\DTLgidxSetDefaultDB{index}
+
+ % All the following definitions will add terms to the "index" database:
+
+ % accent commands get stripped from the default label and sort
+ % so the following gets both the label and sort set to 'macedoine'
+\newterm{mac\'edoine}
+
+ % The following gets both the label and sort set to 'macrame'
+ % (This is only tested with utf8. It most likely won't work with
+ % other encodings.)
+\newterm{macramé}
+
+ % Take care if the first letter starts with an accent.
+ % The initial accented letter must be grouped to ensure it works
+ % with \makefirstuc, but this will make the default label '{e}lite'
+ % rather than 'elite', so let's override the default:
+
+\newterm[label=elite]{{é}lite}
+
+ % Sometimes the default sort may not suit your requirements. In
+ % which case you can override it:
+
+\newterm
+[
+ sort={Ten Downing Street}
+]
+{10 Downing Street}
+
+\newterm{singular}
+\newterm{plural}
+\newterm{group}
+\newterm[see=group]{scope}
+\newterm[label={glossary}]{glossary}
+\newterm
+ [%
+ label={index},
+ seealso={glossary},
+ ]
+ {index}
+\newterm
+ [
+ seealso={glossary}
+ ]
+ {acronym}
+
+\newterm[parent=acronym]{reset}
+\newterm[parent=acronym]{unset}
+
+\newterm
+ [%
+ parent=acronym,
+ label={firstuse},
+ ]
+ {first use}
+\newterm
+ [%
+ parent=acronym,
+ label={acronymlist},
+ text={list of acronyms},
+ plural={lists of acronyms}
+ ]
+ {list}
+
+\newterm{reptile}
+
+\newterm
+ [%
+ seealso={reptile}
+ ]
+ {crocodylian}
+
+\newterm
+ [%
+ parent=crocodylian
+ ]
+ {crocodile}
+
+\newterm
+ [%
+ parent=crocodylian
+ ]
+ {caiman}
+
+\newterm
+ [%
+ parent=crocodylian
+ ]
+ {alligator}
+
+\newterm{seal}
+\newterm{sea lion}
+\newterm{sea}
+\newterm{sea anchor}
+\newterm{sea urchin}
+\newterm{seam bowler}
+\newterm{seam}
+
+ % Be careful if a value contains a comma or an equal sign. The
+ % entire value must be grouped.
+\newterm
+ [%
+ label={comma},
+ sort={,},
+ text={comma (,)},
+ plural={commas (,)}
+ ]%
+ {, (comma)}
+
+\newterm
+ [%
+ label={equals},
+ sort={=},
+ text={equal sign (=)},
+ plural={equal signs (=)},
+ ]%
+ {= (equal sign)}
+
+ % Don't need to worry about makeindex's special characters (since
+ % we're not using makeindex!)
+\newterm
+ [%
+ label={"},
+ sort={"},
+ text={double quote (")},
+ plural={double quotes (")},
+ ]%
+ {" (double quote)}
+
+\newterm
+ [%
+ label={!},
+ sort={!},
+ text={exclamation mark (!)},
+ plural={exclamation marks (!)},
+ ]%
+ {! (exclamation mark)}
+
+\newterm
+ [%
+ label={|},
+ sort={|},
+ text={vertical bar (\textbar)},
+ plural={vertical bars (\textbar)},
+ ]%
+ {\textbar\ (vertical bar)}
+
+
+ % Be careful of special characters
+
+\newterm
+ [%
+ label={amp},
+ sort={\DTLgidxStripBackslash{\&}},
+ text={ampersand (\&)},
+ plural={ampersands (\&)},
+ ]
+ {\& (ampersand)}
+
+\newterm
+ [%
+ label={underscore},
+ sort={\DTLgidxStripBackslash{\_}},
+ text={underscore (\_)},
+ plural={underscores (\_)},
+ ]
+ {\_ (underscore)}
+
+\newterm
+ [%
+ label={dollar},
+ sort={\DTLgidxStripBackslash{\$}},
+ text={dollar (\$)},
+ plural={dollars (\$)},
+ ]
+ {\$ (dollar)}
+
+\newterm
+ [%
+ label={circum},
+ sort={\DTLgidxStripBackslash{\^}},
+ text={circumflex (\textasciicircum)},
+ plural={circumflexes (\textasciicircum)},
+ ]
+ {\textasciicircum\ (circumflex)}
+
+\newterm
+ [%
+ label={tilde},
+ sort={\string~},
+ text={tilde (\textasciitilde)},
+ plural={tildes (\textasciitilde)},
+ ]
+ {\textasciitilde\ (tilde)}
+
+\newterm{0\DTLgidxParen{zero}}
+
+\newterm{1\DTLgidxParen{one}}
+
+\newterm{2\DTLgidxParen{two}}
+
+\newterm{3\DTLgidxParen{three}}
+
+\newterm{10\DTLgidxParen{ten}}
+
+\newterm{100\DTLgidxParen{one hundred}}
+
+\newterm{20\DTLgidxParen{twenty}}
+
+\newterm{alpine}
+
+ % Let's index a person
+ % The label is formed from the surname.
+ % If you are indexing more than one person with the same surname,
+ % you'll have to provide your own labels via the label key.
+
+\newterm{\DTLgidxName{Donald E.}{Knuth}}
+
+ % Let's have some examples from the Oxford Style Manual:
+
+\newterm{highwater}
+\newterm{highlights}
+\newterm{highbrow}
+\newterm{Highclere Castle}
+\newterm{highball}
+\newterm{high chair}
+\newterm{high heels}
+\newterm{high-fliers}
+
+ % parenthetical material
+\newterm{high\DTLgidxParen{light-headed}}
+
+\newterm
+[% label needed to distinguish from previous entry
+ label=highheight,
+]
+{high\DTLgidxParen{height}}
+
+\newterm{\emph{High Water}\DTLgidxParen{play}}
+
+\newterm{high water}
+
+\newterm{\emph{New York, New York}}
+
+ % Using \DTLgidxName allows the sort key to work with \dtlwordindexcompare
+
+\newterm{\DTLgidxName{J.}{High}}
+
+\newterm{\DTLgidxName{P.}{High-Smith}}
+
+\newterm{\DTLgidxName{A.}{Highsmith}}
+
+\newterm{\DTLgidxName{Earl of}{New York}}
+
+ % Some more examples from the Oxford Style Manual
+
+\newterm
+ [
+ label={DrMeynell}
+ ]
+ {\DTLgidxName{\DTLgidxRank{Dr}{A.}}{Meynell}}
+
+\newterm
+ [%
+ label={AliceMeynell}
+ ]
+ {\DTLgidxName{Alice}{Meynell}}
+
+\newterm
+ [%
+ label={AMeynell}
+ ]
+ {\DTLgidxName{A}{Meynell}}
+
+\newterm
+ [%
+ label={FMeynell}
+ ]
+ {\DTLgidxName{F.}{Meynell}}
+
+\newterm
+ [%
+ label={WGMeynell}
+ ]
+ {\DTLgidxName{W.~G.}{Meynell}}
+
+\newterm
+ [%
+ label={WMeynell}
+ ]
+ {\DTLgidxName{W.}{Meynell}}
+
+\newterm
+ [%
+ label={SirMeynell}
+ ]
+ {\DTLgidxName{\DTLgidxRank{Sir}{F.}}{Meynell}}
+
+
+ % Using \DTLgidxMac allows the sort key to sort on ``Mac'' rather
+ % than the argument to \DTLgidxMac
+
+\newterm{\DTLgidxName{Joe}{\DTLgidxMac{Mc}Cullers}}
+
+\newterm{\DTLgidxName{Bob}{\DTLgidxMac{M'}Fingal}}
+
+ % The labels need to be set here as we have identical surnames
+
+\newterm
+ [%
+ label={TomMacFarlane}
+ ]%
+ {\DTLgidxName{Tom}{\DTLgidxMac{Mac}Farlane}}
+
+\newterm
+ [%
+ label={DickMacFarlane}
+ ]%
+ {\DTLgidxName{Dick}{\DTLgidxMac{Mac}Farlane}}
+
+\newterm{\DTLgidxName{Harry}{\DTLgidxMac{Mc}Namee}}
+
+\newterm{\DTLgidxMac{Mc}Carthyism}
+\newterm{\DTLgidxMac{Mc}Guffin}
+\newterm{\DTLgidxMac{Mc}Coy}
+
+\newterm{macadam}
+\newterm{ma'am}
+\newterm{ma}
+\newterm{macabre}
+\newterm{machete}
+
+
+\newterm{deem}
+\newterm{demote}
+\newterm{deerstalker}
+\newterm{deface}
+\newterm{de facto}
+
+ % Don't let the hyphen be considered a word boundary:
+\newterm{de\DTLgidxIgnore{-}escalate}
+
+ % Ignore particles such as "de", "von", "of"
+ % The label defaults to deWinter but the name is displayed as
+ % de~Winter
+
+\newterm{\DTLgidxName{Fred}{\DTLgidxParticle{de}{Winter}}}
+
+\newterm{\DTLgidxName{Wilma}{Winter}}
+
+\newterm{\DTLgidxName{Betty}{Winters}}
+
+ % these all need labels added to ensure uniqueness:
+
+\newterm
+[
+ label={HenrySonJohn}
+]
+{\DTLgidxOffice{son \DTLgidxParticle{of}{John}}{Henry}}
+
+\newterm
+[
+ label={HenryBeaumont}
+]
+{\DTLgidxOffice{bishop \DTLgidxParticle{of}{Bayeux}}{Henry
+\DTLgidxParticle{de}{Beaumont}}}
+
+\newterm
+[
+ label={HenryScribe}
+]
+{\DTLgidxOffice{scribe \DTLgidxParticle{of}{Bury}
+ \DTLgidxSaint{St}~Edmunds}{Henry}}
+
+\newterm
+[
+ label={HenryKing}
+]
+{\DTLgidxOffice{king \DTLgidxParticle{of}{England}}{Henry}}
+
+\newterm
+[
+ label={HenryBlois}
+]
+{\DTLgidxOffice{bishop \DTLgidxParticle{of}{Winchester}}{Henry
+\DTLgidxParticle{of}{Blois}}}
+
+\newterm
+[
+ label={HenryBlund}
+]
+{Henry Blund}
+
+\newterm
+[
+ label={HenryEssex}
+]
+{Henry \DTLgidxParticle{of}{Essex}}
+
+\newterm
+[
+ label={HenryLittle}
+]
+{Henry \DTLgidxParticle{the}{Little}}
+
+\newterm
+[
+ label={HenryMowbray}
+]
+{Henry \DTLgidxParticle{de}{Mowbray}}
+
+\newterm
+[
+ label={HenryFitzRobert}
+]
+{Henry \DTLgidxParticle{Fitz}{Robert}}
+
+\newterm
+[
+ label={JBSaint}
+]
+{\DTLgidxName{J.~B.}{Saint}}
+
+\newterm
+[
+ label={StAndrews}
+]
+{\DTLgidxPlace{\DTLgidxSaint{St}~Andrews}{Fife}}
+
+\newterm
+[
+ label={StBenetsHall}
+]
+{\DTLgidxSaint{St}~Benet's Hall}
+
+\newterm
+[
+ label={StJamesInfirmary}
+]
+{\DTLgidxSaint{St}~James Infirmary}
+
+\newterm
+[
+ label={QStJohnSmythe}
+]
+{\DTLgidxName{Q.}{\DTLgidxSaint{St}~John-Smythe}}
+
+\newterm
+[
+ label={SaintJulian}
+]
+{\DTLgidxSaint{Saint}-Julian}
+
+\newterm
+[
+ label={StJustinRoseland}
+]
+{\DTLgidxSaint{St}~Just-in-Roseland}
+
+ % Names with an associated number
+
+ % The following gets the label 'James I' and sort 'James 01'
+
+\newterm{James~\DTLgidxNameNum{1}}
+
+ % The following gets the label 'James II' and sort 'James 02'
+
+\newterm{James~\DTLgidxNameNum{2}}
+
+ % etc
+\newterm{James~\DTLgidxNameNum{3}}
+\newterm{James~\DTLgidxNameNum{4}}
+\newterm{James~\DTLgidxNameNum{5}}
+
+ % In the following, the label and name default to 'New York, population'
+ % The text defaults to 'population'.
+ % Using \DTLgidxSubject allows the sort key to work with \dtlwordindexcompare
+ % Here both the label and the text have been changed from their
+ % defaults.
+\newterm
+[
+ label={popNY},% give it a short, easy to type label
+ text={population of New York}
+]
+{\DTLgidxSubject{population}{New York}}
+
+ % In the following, the label and name become 'New York, USA'
+ % The text becomes 'New York'.
+ % The sort key is adjusted to work with \dtlwordindexcompare
+\newterm{\DTLgidxPlace{USA}{New York}}
+
+\newterm{\ensuremath{\alpha}-iron}% gets label and sort keys 'alpha-iron'
+
+\newterm{\ensuremath{\alpha} chain}% label & sort -> 'alpha chain'
+
+\newterm{\ensuremath{\alpha} Centauri}% label & sort -> 'alpha Centauri'
+
+\newterm{alphabet}
+
+\newterm{\ensuremath{\Lambda} calculus}% label & sort -> 'Lambda calculus'
+
+ % and have a few more entries in the same letter group to test case
+ % ordering:
+\newterm{kite}
+\newterm{koala}
+
+ % Earlier I modified \newtermlabelhook so
+ % that \appname won't interfere with the sorting
+ % and labelling mechanism, so I don't need to specify separate sort
+ % and label keys here:
+
+\newterm{\appname{makeindex}}% label and sort both set to just 'makeindex'
+\newterm{\appname{xindy}}% label and sort both set to just 'xindy'
+
+\title{Sample Document Using the datagidx Package}
+\author{Nicola L. C. Talbot}
+
+\begin{document}
+\pagenumbering{roman}
+
+The datagidx package was developed to follow the word order indexing
+style described by the Oxford Style Manual. Many of the examples
+here are taken from that manual. Two \LaTeX\ runs are required. If
+you get a pdfTeX warning that a destination has been referenced but
+does not exist, this may mean the index is out-of-date and you need
+to do another \LaTeX\ run.
+
+With word ordering a word break (space or hyphen) comes before all
+other letters of the alphabet (\gls{sea lion} comes before \gls{seal}).
+With letter ordering word breaks are ignored (so \gls{seal} comes
+before \gls{sea lion}).
+
+Use a few terms here: \gls{index}, \gls{group}, \gls{singular}, \gls{plural}.
+
+\newpage
+
+\Gls{singular}, \glspl{plural}. \gls{glossary}.
+\Gls{acronym}: \gls{reset}, \gls{firstuse}.
+
+\newpage
+\pagenumbering{arabic}
+
+Switched page numbering style. \Gls{singular}, \gls{kite},
+\gls{koala}, \gls{crocodile}, \gls{seal}.
+
+\Gls{sea},
+\gls{sea anchor},
+\gls{sea urchin}.
+
+Some characters: \gls{comma}, \gls{equals}, \gls{"}, \gls{!}, \gls{|}
+\gls{amp}, \gls{underscore}, \gls{dollar}, \gls{circum},
+\gls{tilde}.
+
+Some numbers: \gls{0}, \gls{1}, \gls{2}, \gls{3}, \gls{20}, \gls{10}.
+
+\newpage
+
+Some numbers again: \gls{0}, \gls{1}, \gls{2}, \gls{3}, \gls{100},
+\gls{10}, \gls{20}.
+
+Case mixture: \gls{kite},
+\gls{Knuth} and
+\gls{[principleloc]koala}.
+
+\Gls{de-escalate}, \gls{deem}, \gls{demote}.
+
+We don't need to use \gls{makeindex} or \gls{xindy}!
+However, \TeX\ takes longer to sort and collate than either
+\gls{makeindex} or \gls{xindy}, so document compilation time will
+take longer.
+
+\newpage
+
+\Gls{kite}, \gls{highwater}, \gls{koala}, \gls{caiman}, \gls{sea
+lion}, \gls{high},
+\gls{highbrow}, \gls{high chair}, \gls{highball}, \gls{reptile},
+\gls{highlights}, \gls{high heels}, \gls{high-fliers}.
+\Gls{seam} and \gls{seam bowler}.
+
+\gls{New York, New York}. \gls{New York}.
+\Gls{popNY}. \gls{New York, USA}.
+\gls{Highclere Castle}.
+
+\gls{High}. \gls{High-Smith}, \gls{Highsmith}, \gls{High Water}
+as opposed to \gls{high water}. \Gls{alphabet}. \Gls{alpine}.
+
+Some terms with Greek letters: \gls{alpha-iron},
+\gls{Lambda calculus}, \gls{alpha chain}, \gls{alpha Centauri}.
+
+\newpage
+
+\renewcommand{\thepage}{\myscroman{page}}%
+Switching to small caps Roman page numbering.
+
+\Gls{kite}. \Glspl{alligator}. \Gls{highheight}.
+
+\gls{deWinter}.
+\gls{Winter}.
+\gls{Winters}.
+
+\gls{McCullers}.
+
+\gls{M'Fingal}.
+
+\gls{TomMacFarlane}.
+
+\gls{DickMacFarlane}.
+
+\gls{McNamee}.
+
+\gls{McCarthyism},
+\gls{McGuffin},
+\gls{McCoy}.
+
+\Gls{macadam},
+\gls{ma'am},
+\gls{ma},
+\gls{macabre},
+\gls{macrame},
+\gls{macedoine}.
+
+\Gls{elite},
+\gls{deem},
+\gls{demote},
+\gls{deerstalker},
+\gls{deface},
+\gls{de facto}.
+
+
+\gls{AliceMeynell}.
+\gls{AMeynell}.
+\gls{DrMeynell}.
+\gls{SirMeynell}.
+\gls{FMeynell}.
+\gls{WGMeynell}.
+\gls{WMeynell}.
+
+\gls{HenrySonJohn}. \gls{HenryBlois}.
+\gls{HenryBeaumont}. \gls{HenryBlund}.
+\gls{HenryLittle}. \gls{HenryEssex}. \gls{HenryMowbray}.
+\gls{HenryFitzRobert}.
+\gls{HenryKing}. \gls{HenryScribe}.
+
+\gls{James V}.
+\gls{James I}.
+\gls{James IV}.
+\gls{James III}.
+\gls{James II}.
+
+\gls{JBSaint}.
+\gls{StAndrews}.
+\gls{StBenetsHall}.
+\gls{StJamesInfirmary}.
+\gls{QStJohnSmythe}.
+\gls{SaintJulian}.
+\gls{StJustinRoseland}.
+
+\gls{10 Downing Street}.
+
+\newpage
+
+% This will take a while as the sorting algorithm is complex.
+
+\printterms
+ [
+ heading={\section[Word Sorted Index]},% make a numbered section
+ database=index,% 'index' database
+ prelocation=dotfill,% put a dotted line before the location list
+ columns=3,% page layout
+ style=index,% use 'index' style
+ %balance=false,% don't balance columns
+ postheading={Locations in bold indicate primary reference.
+ (Word sort.)}
+ ]
+
+\end{document}
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 73fb2f1c83e..bbc7a7dfb5f 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
Binary files differ
diff --git a/Master/texmf-dist/doc/latex/datatool/samples/sample-mail-merge.tex b/Master/texmf-dist/doc/latex/datatool/samples/sample-mail-merge.tex
index 384584e540e..12566e4aba0 100644
--- a/Master/texmf-dist/doc/latex/datatool/samples/sample-mail-merge.tex
+++ b/Master/texmf-dist/doc/latex/datatool/samples/sample-mail-merge.tex
@@ -1,5 +1,5 @@
% This file is public domain.
-\documentclass{scrlttr2}
+\documentclass{letter}
\usepackage{datatool}
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 43d1a30f341..99d2c261975 100644
--- a/Master/texmf-dist/doc/latex/datatool/samples/sample-piechart.pdf
+++ b/Master/texmf-dist/doc/latex/datatool/samples/sample-piechart.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/latex/datatool/samples/sample-sort.tex b/Master/texmf-dist/doc/latex/datatool/samples/sample-sort.tex
new file mode 100644
index 00000000000..bce750819dc
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/datatool/samples/sample-sort.tex
@@ -0,0 +1,118 @@
+% This file is public domain
+
+\documentclass{article}
+
+\usepackage{datatool}
+
+% Sample database
+
+\DTLnewdb{data}
+
+% Add a word to the database. (The Definition column is provided to
+% distinguish the entries when the database is displayed. The
+% Definition column is not used by the sort code.)
+
+% Syntax: \newword{string}
+
+\makeatletter
+\newcommand*{\newword}[1]{%
+ \DTLnewrow{data}%
+ \DTLnewdbentry{data}{Word}{#1}%
+% Convert word to its definition and add
+ {%
+ \def\thisword{#1}\@onelevel@sanitize\thisword
+ \dtlexpandnewvalue % ensure \theword gets expanded
+ \DTLnewdbentry{data}{Definition}{\thisword}%
+ }%
+}
+\makeatother
+
+\newword{High Water}
+\newword{!}
+\newword{[}
+\newword{~}
+\newword{\#define}
+\newword{High water}
+\newword{highwater}
+\newword{1st Street}
+\newword{high water}
+\newword{1st~Street}
+\newword{10~Downing Street}
+\newword{10~Downing Avenue}
+\newword{10 Downing Road}
+\newword{\#include}
+\newword{1 (one)}
+\newword{1\datatoolparenstart(one)}
+\newword{10\datatoolparenstart(ten)}
+\newword{10 (ten)}
+\newword{42\datatoolparenstart(forty-two)}
+\newword{42 (forty-two)}
+\newword{100\datatoolparenstart(one hundred)}
+\newword{100 (one hundred)}
+\newword{4\datatoolparenstart(four)}
+\newword{4 (four)}
+\newword{The Ten Samurai}
+\newword{London, Jack}
+\newword{London}
+\newword{10 Samurai, The}
+\newword{10 Samurai}
+\newword{Ten Samurai, The}
+\newword{Ten Samurai}
+\newword{10 Samurai\datatoolsubjectcomma The}
+\newword{Ten Samurai\datatoolsubjectcomma The}
+\newword{London\datatoolpersoncomma Jack}
+\newword{London\datatoolplacecomma UK}
+\newword{London\datatoolsubjectcomma History of}
+\newword{Zebra}
+\newword{zebra}
+\newword{alpha}
+\newword{Alpha}
+\newword{seal}
+\newword{sea lion}
+
+\begin{document}
+
+\section{Unsorted data}
+
+\begin{tabular}{ll}
+\bfseries Word & \bfseries Definition
+\DTLforeach*{data}{\Word=Word,\Definition=Definition}{%
+\\\Word & \ttfamily \Definition
+}
+\end{tabular}
+
+\section{Case-Insensitive Sort}
+
+\DTLsort*{Word}{data}
+
+\begin{tabular}{ll}
+\bfseries Word & \bfseries Definition
+\DTLforeach*{data}{\Word=Word,\Definition=Definition}{%
+\\\Word & \ttfamily \Definition
+}
+\end{tabular}
+
+
+\section{Case-Sensitive Sort}
+
+\DTLsort{Word}{data}
+
+\begin{tabular}{ll}
+\bfseries Word & \bfseries Definition
+\DTLforeach*{data}{\Word=Word,\Definition=Definition}{%
+\\\Word & \ttfamily \Definition
+}
+\end{tabular}
+
+\section{Word-Order Sort}
+
+\dtlsort{Word}{data}{\dtlwordindexcompare}
+
+\begin{tabular}{ll}
+\bfseries Word & \bfseries Definition
+\DTLforeach*{data}{\Word=Word,\Definition=Definition}{%
+\\\Word & \ttfamily \Definition
+}
+\end{tabular}
+
+\end{document}
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 1abee68d126..6e640ed055c 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
Binary files 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 17676a1093f..2f9b601552d 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
Binary files differ