datatool (10jul13)

git-svn-id: svn://tug.org/texlive/trunk@31174 c570f23f-e606-0410-a88d-b1316a301751

1 files changed, 183 insertions, 52 deletions

diff --git a/Master/texmf-dist/doc/latex/datatool/datatool-user.tex b/Master/texmf-dist/doc/latex/datatool/datatool-user.tex
index d2cb0a0eb38..2caff13201c 100644
--- a/Master/texmf-dist/doc/latex/datatool/datatool-user.tex
+++ b/Master/texmf-dist/doc/latex/datatool/datatool-user.tex
@@ -91,11 +91,11 @@
 \MakeShortVerb{"}
 \DeleteShortVerb{\|}
 
- \title{User Manual for datatool bundle version~2.14}
+ \title{User Manual for datatool bundle version~2.15}
  \author{Nicola L.C. Talbot\\
 \url{http://www.dickimaw-books.com/}}
 
- \date{2013-06-28}
+ \date{2013-07-10}
  \maketitle
 
 \pagenumbering{roman}
@@ -110,7 +110,7 @@ The \styfmt{datatool} bundle comes with the following documentation:
   \item[\url{datatool-code.pdf}]
   Advanced users wishing to know more about the inner workings of
   all the packages provided in the \styfmt{datatool} bundle should
-  read \qt{Documented Code for datatool v2.14}
+  read \qt{Documented Code for datatool v2.15}
 
   \item[INSTALL] Installation instructions.
 
@@ -147,6 +147,9 @@ numerical and string functions. Automatically
 loads \sty{datatool-fp} or \sty{datatool-pgfmath} depending on
 package options.
 
+\item[\sty{datagidx}] Package for generating indexes and glossaries.
+Automatically loads \sty{datatool}.
+
 \item[\sty{databar}] Package for drawing bar charts.
 Automatically loads \sty{datatool}.
 
@@ -211,18 +214,20 @@ and the second uses the \sty{pgfmath} package:
 
  \changes{1.0}{2007 July 22}{Initial version}
 The \sty{datatool} bundle consists of the following
-packages: \sty{datatool} (which loads \sty{datatool-base} and either \sty{datatool-fp} or \sty{datatool-pgfmath}), \sty{datapie}, \sty{dataplot},
-\sty{databar} and \sty{databib}. 
+packages: \sty{datatool} (which loads \sty{datatool-base} and either
+\sty{datatool-fp} or \sty{datatool-pgfmath}), \sty{datagidx}, \sty{datapie}, \sty{dataplot},
+\sty{databar}, \sty{databib} and \sty{person}. 
 
-The \sty{datatool} package can be used to:
+\begin{itemize}
+\item The \sty{datatool} package can be used to:
 \begin{itemize}
 \item Create or load databases.
 \item Sort rows of a database (either numerically or alphabetically,
 ascending or descending).
 \item Perform repetitive operations on each row of a database
 (e.g.\ mail merging). Conditions may be imposed to exclude rows.
-
-\item Package Options:
+\end{itemize}
+Package Options:
   \begin{description}
    \item[\pkgopt{verbose}] Boolean key. If
     \pkgoptval{true}{verbose}, prints informational messages in
@@ -236,9 +241,8 @@ ascending or descending).
    \item[\pkgopt{separator}] Delimiter used in CSV files.
    Default is a comma (\texttt{,}).
   \end{description}
-\end{itemize}
 
-The \sty{datatool-base} package can be used to:
+\item The \sty{datatool-base} package can be used to:
 \begin{itemize}
 \item Determine whether an argument is an integer, a real number,
 currency or a string. (Scientific notation is currently not
@@ -251,8 +255,8 @@ arithmetic to be performed on elements of the database.
 \item Names can be converted to initials.
 \item Determine if strings are all upper or lower case.
 \item Perform string comparisons (both case sensitive and case insensitive).
-
-\item Package Options:
+\end{itemize}
+Package Options:
   \begin{description}
    \item[\pkgopt{verbose}] Boolean key. If
     \pkgoptval{true}{verbose}, prints informational messages in
@@ -262,9 +266,12 @@ arithmetic to be performed on elements of the database.
     \pkgoptval{pgfmath}{math} (load \sty{datatool-pgfmath}). Default is:
     \pkgoptval{fp}{math}.
   \end{description}
-\end{itemize}
 
-The \sty{datapie} package (see \autoref{sec:datapie}) can be used to convert a database into
+\item The \sty{datagidx} package (see \autoref{sec:datagidx}) can be used
+to generate indexes or glossaries as an alternative to packages
+such as \sty{glossaries}.
+
+\item The \sty{datapie} package (see \autoref{sec:datapie}) can be used to convert a database into
 a pie chart:
 \begin{itemize}
 \item Segments can be separated from the rest of the chart to make
@@ -274,7 +281,7 @@ them stand out.
 \item Hooks provided to add extra information to the chart
 \end{itemize}
 
-The \sty{databar} package (see \autoref{sec:databar}) can be used to convert a database into
+\item The \sty{databar} package (see \autoref{sec:databar}) can be used to convert a database into
 a bar chart:
 \begin{itemize}
 \item Colour/grey scale options.
@@ -290,13 +297,19 @@ dimensional graphics cause distortion, which can result in misleading
 impressions. The \sty{pgf} manual provides a more in-depth 
 discussion on the matter.)
 
-The \sty{dataplot} package (see \autoref{sec:dataplot}) can be used to convert a database into
+\item The \sty{dataplot} package (see \autoref{sec:dataplot}) can be used to convert a database into
 a two dimensional plot using markers and/or lines. Three dimensional
 plots are currently not supported.
 
-The \sty{databib} package (see \autoref{sec:databib}) can be used to convert a \BibTeX\ database
+\item The \sty{databib} package (see \autoref{sec:databib}) can be used to convert a \BibTeX\ database
 into a \sty{datatool} database.
 
+\item The \sty{person} package (see \autoref{sec:person}) can be
+used for gender-specific mail-merging and similar uses to avoid the
+cumbersome use of the impersonal \qt{he\slash she}.
+
+\end{itemize}
+
 \chapter{Data Types}
 \label{sec:datatypes}
 
@@ -2017,12 +2030,12 @@ described in \autoref{sec:advanced}, but using \TeX\ is nowhere near
 as efficient as, say, using a SQL database, so don't expect too much
 from this package.
 
-
+\label{datatooltk}%
 I'm working on a Java helper application to accompany \sty{datatool}
 called \app{datatooltk}. The source code is available on GitHub at
 \url{https://github.com/nlct/datatooltk}. I'll upload it to CTAN
 when it's ready for release. The application will allow you to edit
-files saved using \ics{DTLsaverawdb} in a~graphical interface or
+files saved using \ics{DTLsaverawdb} or \ics{DTLprotectedsaverawdb} in a~graphical interface or
 import data from a~SQL database, a~CSV file or a~\sty{probsoln}
 dataset.
 
@@ -2184,12 +2197,23 @@ exists.
 \section{Loading a Database from an External ASCII File}
 \label{sec:loaddb}
 
+\begin{important}
+\cs{DTLloaddb} and \cs{DTLloadrawdb}, described in this section, can't 
+parse files that have newline characters within entries. The 
+\app{datatooltk} application (see page~\pageref{datatooltk}) can 
+parse them, so if you have multilined entries in a CSV file, you 
+can convert it to \sty{datatool}'s internal database format using 
+\app{datatooltk} and the input it using \ics{input}. See the 
+\app{datatooltk} documentation for further details.
+\end{important}
+
 Instead of using the commands described in \autoref{sec:newdb}
 to create a new database, you can load a database from an
 external ASCII file using:
 \begin{definition}[\DescribeMacro{\DTLloaddb}]%
 \cs{DTLloaddb}\oarg{options}\marg{db name}\marg{filename}
 \end{definition}
+
 \begin{important}
 Make sure your document uses the same encoding as \meta{filename}.
 For example, if \meta{filename} is UTF-8, then include the following
@@ -4789,7 +4813,32 @@ readability you can use:
 \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.
+representation, which makes it faster to load. Fragile commands 
+cause a~problem for \cs{DTLsaverawdb} so if your database contains
+any use:
+\begin{definition}[\DescribeMacro{\DTLprotectedsaverawdb}]%
+\cs{DTLprotectedsaverawdb}\marg{db name}\marg{filename}
+\end{definition}
+instead.
+
+\begin{important}
+If you find a~problem caused by \TeX's automatic insertion of a line
+break every 80 characters when writing to a file, try loading the
+\sty{morewrites} package before \sty{datatool}.
+\end{important}
+
+Databases saved using \cs{DTLsavetexdb}, \cs{DTLsaverawdb} and
+\cs{DTLprotectedsaverawdb} can be loaded using \LaTeX's standard
+\ics{input} command. As from version 2.15, the last line of the
+database file defines
+\begin{definition}[\DescribeMacro{\dtllastloadeddb}]
+\cs{dtllastloadeddb}
+\end{definition}
+to the name of the database, in case it's required.
+
+Databases saved using \cs{DTLsaverawdb} and
+\cs{DTLprotectedsaverawdb} can also be loaded and edited by 
+\app{datatooltk} (see page~\pageref{datatooltk}).
 
 \section{Deleting or Clearing a Database}\label{sec:deletedb}
 
@@ -5208,7 +5257,45 @@ 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.
 
+Sections~\ref{sec:newgidx} and~\ref{sec:newterm} describe how to
+create and populate a database that's used to store terms or
+acronyms. By default the database is sorted when it's displayed
+using \ics{printterms} (see section~\ref{sec:printterms}). This is
+where the main inefficiency lies in this package. A~faster
+alternative is to use \app{datatooltk} (see page~\pageref{datatooltk})
+and its \texttt{datagidx} plugin, which will allow you to enter
+terms in a graphical environment and sort the terms. This way, you
+only need to sort the database after you enter a new term and the
+sorting is done by a more efficient language than \TeX. Note that
+this means returning to using an external helper application, but it
+only needs to be used when you add a new term rather than between
+each pair of \LaTeX\ runs.
+
+Once you've edited and sorted the database in \app{datatooltk}, 
+you can then just load it using:
+\begin{definition}[\DescribeMacro{\loadgidx}]
+\cs{loadgidx}\oarg{options}\marg{filename}\marg{title}
+\end{definition}
+where \meta{filename} is the name of the file saved in
+\app{datatooltk}. The remaining arguments \meta{options} and
+\meta{title} are the same as for \cs{newgidx}, described in
+section~\ref{sec:newgidx}. This command automatically sets the
+default database to the loaded database. You can change the default
+database using \cs{DTLgidxSetDefaultDB}, described in
+section~\ref{sec:newterm}.
+
+Since \cs{loadgidx} is intended for use with presorted databases,
+the \csopt{loadgidx}{sort} key defaults to nothing.
+
+\begin{important}
+If you've opted to use \sty{datagidx} over \sty{glossaries} because
+you don't want to install Perl, then don't bother with
+\app{datatooltk} because, although it's a Java application, it requires 
+Perl for the plugins.
+\end{important}
+
 \section{Defining Index/Glossary Databases}
+\label{sec:newgidx}
 
 \begin{important}
 The databases and their associated entries described here can only
@@ -5218,13 +5305,14 @@ 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).
+(provided you are using a decent text editor). Alternatively, use 
+\app{datatooltk}'s \texttt{datagidx} plugin as described above.
 \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}
+\cs{newgidx}\oarg{options}\marg{label}\marg{title}
 \end{definition}
 This defines a new database with a unique label and a title.
 For example:
@@ -5235,6 +5323,35 @@ 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}).
 
+The optional argument \meta{options} should be a key=value list.
+Available options:
+\begin{description}
+\item[\csopt{newgidx}{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{newgidx}{style}] The style to use. The value should
+be the name of the style. Available styles are listed in
+\autoref{sec:indexstyles}.
+
+\item[\csopt{newgidx}{sort}] How to sort the database. See
+\autoref{sec:indexsort} for further details.
+
+\item[\csopt{newgidx}{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.
+
+\item[\csopt{newgidx}{heading}] The heading at the start of the
+index/glossary.
+
+\item[\csopt{newgidx}{postheading}] What to put immediately after
+the heading.
+
+\end{description}
+
 \section{Locations}
 \label{sec:locations}
 
@@ -5316,6 +5433,8 @@ each new term. Instead you can identify the default database using
 \begin{definition}[\DescribeMacro\DTLgidxSetDefaultDB]
 \cs{DTLgidxSetDefaultDB}\marg{label}
 \end{definition}
+\textbf{Note:} the argument \meta{label} is not expanded.
+
 Example:
 \begin{verbatim}
  % define two indexes:
@@ -5343,7 +5462,11 @@ extracted from \meta{name} (see below).
 extracted from \meta{name} (see below).
 
 \item[\csopt{newterm}{parent}] The parent entry, if this is a
-sub-term.
+sub-term. An entry may only have one parent. If you want the same
+term to appear under two different parents, you'll have to define
+two separate terms with the same name but different parents (and
+different labels). This is the only way to avoid ambiguity with the
+hyperlinks (if enabled).
 
 \item[\csopt{newterm}{text}] How the entry should appear in the
 document text. This is \meta{name} by default. If this option is
@@ -6513,6 +6636,9 @@ target names.
 
 \item[\pkgopt{verbose}] Use \sty{datatool}'s verbose mode.
 
+\item[\pkgopt{nowarn}] A boolean option that suppresses
+\sty{datagidx}'s rerun warnings.
+
 \end{description}
 
 \begin{example}{Creating an Index}{ex:index}
@@ -6572,16 +6698,11 @@ starts with an accented letter. A \gls{crocodylian} is a family of
 
 The index can then be displayed using:
 \begin{verbatim}
-\printterms
- [
-   heading={\section*},
-   database=index
- ]
+\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*},
@@ -7540,7 +7661,17 @@ and
 They are both defined to do nothing by default, but can be redefined
 to add commands to the image. The unit vectors are set prior to
 using these hooks, so you can use the same co-ordinates as those
-in the data sets.
+in the data sets.  However, to reduce the problem of exceeding \TeX's 
+maximum dimension, \cs{DTLplot} scales the plot which may distort
+plot marks. To get around this use
+\begin{definition}[\DescribeMacro{\dtlplothandlermark}]
+\cs{dtlplothandlermark}\marg{pgf code}
+\end{definition}
+instead of \ics{pgfplothandlermark}\marg{pgf code}. (See 
+\autoref{ex:multikey}.) Note that \cs{dtlplothandlermark} is only
+intended for use within the definition of \cs{DTLplotatbegintikz} or
+\cs{DTLplotatendtikz}. If used elsewhere it will produce a warning
+and act as though you'd just used \cs{pgfplothandlermark}.
 
 \begin{definition}[\DescribeMacro{\DTLaddtoplotlegend}]%
 \cs{DTLaddtoplotlegend}\marg{marker}\marg{line style}\marg{text}
@@ -7855,28 +7986,28 @@ in \autoref{ex:2db}. Instead I can use a combination of
 \begin{verbatim}
 \begin{figure}[tbhp]
 \centering
- % computer bounds
+ % compute bounds
 \DTLminforkeys{growth}{Time}{\minX}
 \DTLminforkeys{growth}{Experiment 1,Experiment 2}{\minY}
 \DTLmaxforkeys{growth}{Time}{\maxX}
 \DTLmaxforkeys{growth}{Experiment 1,Experiment 2}{\maxY}
- % round x tick labels
-\setcounter{DTLplotroundXvar}{0}
+ % round x tick labels to 1 d.p.
+\setcounter{DTLplotroundXvar}{1}
  % redefine \DTLplotatbegintikz to plot the data for Experiment 1
 \renewcommand*{\DTLplotatbegintikz}{%
- % set plot mark
-\pgfplothandlermark{\color{green}\pgfuseplotmark{x}}
- % start plot stream
-\pgfplotstreamstart
- % add data from Experiment 1 to plot stream
-\DTLplotstream{growth}{Time}{Experiment 1}%
- % end plot stream
-\pgfplotstreamend
- % stroke path
-\pgfusepath{stroke}
- % add information to legend (no line is require so use \relax)
-\DTLaddtoplotlegend{\color{green}%
-\pgfuseplotmark{x}}{\relax}{Experiment 1}
+  % set plot mark
+  \dtlplothandlermark{\color{green}\pgfuseplotmark{x}}
+  % start plot stream
+  \pgfplotstreamstart
+  % add data from Experiment 1 to plot stream
+  \DTLplotstream{growth}{Time}{Experiment 1}%
+  % end plot stream
+  \pgfplotstreamend
+  % stroke path
+  \pgfusepath{stroke}
+  % add information to legend (no line is require so use \relax)
+  \DTLaddtoplotlegend{\color{green}%
+  \pgfuseplotmark{x}}{\relax}{Experiment 1}
 }
  % now plot the data for Experiment 2
 \DTLplot{growth}{x=Time,y=Experiment 2,legend,
@@ -7893,12 +8024,12 @@ Notes:
 the new plot to the legend, since \ics{DTLplotatendtikz} is 
 used after the legend is plotted. The $x$ and $y$ unit vectors
 are set before \ics{DTLplotatbegintikz} so I don't need to 
-worry about the co-ordinates.
-\item I set the counter \ctr{DTLplotroundXvar} to zero 
-otherwise the $x$ axis would have looked too cluttered.
+worry about the co-ordinates, however I've had to use
+\ics{dtlplothandlermark} instead of \ics{pgfplothandlermark}
+to prevent the plot marks from being distorted.
 \item I have used \ics{DTLminforkeys} and \ics{DTLmaxforkeys} to
 determine the bounds since \ics{DTLplot} won't take the data
-for Experiment 1 into account when computing the bounds.
+for Experiment~1 into account when computing the bounds.
 \end{itemize}
 
 \begin{figure}[htbp]
@@ -7906,9 +8037,9 @@ for Experiment 1 into account when computing the bounds.
 \DTLminforkeys{growth}{Experiment 1,Experiment 2}{\minY}
 \DTLmaxforkeys{growth}{Time}{\maxX}
 \DTLmaxforkeys{growth}{Experiment 1,Experiment 2}{\maxY}
-\setcounter{DTLplotroundXvar}{0}
+\setcounter{DTLplotroundXvar}{1}
 \renewcommand*{\DTLplotatbegintikz}{%
-\pgfplothandlermark{\color{green}\pgfuseplotmark{x}}
+\dtlplothandlermark{\color{green}\pgfuseplotmark{x}}
 \pgfplotstreamstart
 \DTLplotstream{growth}{Time}{Experiment 1}%
 \pgfplotstreamend