diff options
author | Karl Berry <karl@freefriends.org> | 2013-01-15 23:01:04 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2013-01-15 23:01:04 +0000 |
commit | 6d3800d3b164704c4038f84408b27f759a4ea744 (patch) | |
tree | 6d56ebd38457cb5f2d7bcbe628157f861fecdaae /Master/texmf-dist/doc/latex/datatool/datatool-user.tex | |
parent | 607c25d782c2e57a60ab2f2ecf30c12e238b44ec (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.tex | 1751 |
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, |