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