summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/datatool/datatool-user.tex
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/datatool-user.tex
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/datatool-user.tex')
-rw-r--r--Master/texmf-dist/doc/latex/datatool/datatool-user.tex1751
1 files changed, 1721 insertions, 30 deletions
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,