summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc')
-rw-r--r--Master/texmf-dist/doc/latex/datatool/CHANGES12
-rw-r--r--Master/texmf-dist/doc/latex/datatool/README4
-rw-r--r--Master/texmf-dist/doc/latex/datatool/datatool-code.pdfbin1165367 -> 1166199 bytes
-rw-r--r--Master/texmf-dist/doc/latex/datatool/datatool-user.pdfbin607877 -> 614504 bytes
-rw-r--r--Master/texmf-dist/doc/latex/datatool/datatool-user.tex319
-rw-r--r--Master/texmf-dist/doc/latex/datatool/samples/sample-autokeys.pdfbin24911 -> 24911 bytes
-rw-r--r--Master/texmf-dist/doc/latex/datatool/samples/sample-barchart.pdfbin35056 -> 35056 bytes
-rw-r--r--Master/texmf-dist/doc/latex/datatool/samples/sample-datatooltk.pdfbin22848 -> 22848 bytes
-rw-r--r--Master/texmf-dist/doc/latex/datatool/samples/sample-dict.pdfbin122578 -> 122578 bytes
-rw-r--r--Master/texmf-dist/doc/latex/datatool/samples/sample-europecv-bib.pdfbin89544 -> 89544 bytes
-rw-r--r--Master/texmf-dist/doc/latex/datatool/samples/sample-gidx.pdfbin180135 -> 180112 bytes
-rw-r--r--Master/texmf-dist/doc/latex/datatool/samples/sample-glossary.pdfbin104788 -> 104765 bytes
-rw-r--r--Master/texmf-dist/doc/latex/datatool/samples/sample-index.pdfbin128764 -> 128764 bytes
-rw-r--r--Master/texmf-dist/doc/latex/datatool/samples/sample-mail-merge.pdfbin21890 -> 21635 bytes
-rw-r--r--Master/texmf-dist/doc/latex/datatool/samples/sample-piechart.pdfbin33954 -> 33954 bytes
-rw-r--r--Master/texmf-dist/doc/latex/datatool/samples/sample-sort.pdfbin89727 -> 89713 bytes
-rw-r--r--Master/texmf-dist/doc/latex/datatool/samples/sample-student-scores.pdfbin34602 -> 34602 bytes
-rw-r--r--Master/texmf-dist/doc/latex/datatool/samples/sample-two-per-row.pdfbin31739 -> 31739 bytes
18 files changed, 300 insertions, 35 deletions
diff --git a/Master/texmf-dist/doc/latex/datatool/CHANGES b/Master/texmf-dist/doc/latex/datatool/CHANGES
index e29220008d8..62d514e10de 100644
--- a/Master/texmf-dist/doc/latex/datatool/CHANGES
+++ b/Master/texmf-dist/doc/latex/datatool/CHANGES
@@ -1,3 +1,15 @@
+v2.25:
+
+ * datatool-base:
+
+ - \dtlcompare, \dtlicompare, \@dtldictcompare:
+ added \expandonce to definitions of \dtl@donext to
+ prevent unwanted expansion of non-ASCII characters.
+
+ * datatool user guide:
+
+ - Added section "Advanced Iteration".
+
v2.24:
* datatool-base:
diff --git a/Master/texmf-dist/doc/latex/datatool/README b/Master/texmf-dist/doc/latex/datatool/README
index 38aad314e74..cf0a98f620c 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.24
+LaTeX Bundle : datatool v2.25
-Last Modified : 2016-01-12
+Last Modified : 2016-01-18
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
index e9a74d5c7a1..c963f7d3914 100644
--- a/Master/texmf-dist/doc/latex/datatool/datatool-code.pdf
+++ b/Master/texmf-dist/doc/latex/datatool/datatool-code.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/latex/datatool/datatool-user.pdf b/Master/texmf-dist/doc/latex/datatool/datatool-user.pdf
index 5360d80b0c1..0f107ea3220 100644
--- a/Master/texmf-dist/doc/latex/datatool/datatool-user.pdf
+++ b/Master/texmf-dist/doc/latex/datatool/datatool-user.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/latex/datatool/datatool-user.tex b/Master/texmf-dist/doc/latex/datatool/datatool-user.tex
index 885b832c301..a1bc741c631 100644
--- a/Master/texmf-dist/doc/latex/datatool/datatool-user.tex
+++ b/Master/texmf-dist/doc/latex/datatool/datatool-user.tex
@@ -99,11 +99,11 @@
\MakeShortVerb{"}
\DeleteShortVerb{\|}
- \title{User Manual for datatool bundle version~2.24}
+ \title{User Manual for datatool bundle version~2.25}
\author{Nicola L.C. Talbot\\
\url{http://www.dickimaw-books.com/}}
- \date{2016-01-12}
+ \date{2016-01-18}
\maketitle
\pagenumbering{roman}
@@ -118,7 +118,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.24}
+ read \qt{Documented Code for datatool v2.25}
\item[INSTALL] Installation instructions.
@@ -2859,6 +2859,15 @@ external file, as described in \autoref{sec:loaddb}, or using the
commands described in \autoref{sec:newdb}, you can then iterate
through each row of the database and access elements in that row.
+\begin{important}
+The \cs{DTLforeach} command is provided as a convenient way of
+iterating through databases with the option to filter rows,
+cross-reference rows or have nested loops, but for large databases it can be
+\emph{extremely slow}, especially if the unstarred version is used.
+If you have a large database, consider pre-processing the data using
+an external script. See also \sectionref{sec:advancediter}.
+\end{important}
+
\begin{definition}[\DescribeMacro{\DTLforeach}]%
\cs{DTLforeach}\oarg{condition}\marg{db name}\marg{assign list}\marg{text}
\end{definition}
@@ -5224,36 +5233,6 @@ must be a command name. The type will be one of:
\item\DescribeMacro{\DTLcurrencytype}\cs{DTLcurrenttype} (currency).
\end{itemize}
-\begin{definition}[\DescribeMacro{\dtlforeachkey}]%
-\cs{dtlforeachkey}(\meta{key cs},\meta{col cs},\meta{type
-cs},\meta{header cs})\cs{in}\marg{db}\cs{do}\marg{body}
-\end{definition}
-This iterates through all the keys in the database given by
-\meta{db}. In each iteration, \meta{key cs} is set to the key,
-\meta{col cs} is set to the column index, \meta{type cs} is set to
-the data type (as for \cs{DTLgetdatatype}), \meta{header cs} is set
-to the header for that column, and then \meta{body} is done. Note
-that \meta{key cs}, \meta{col cs}, \meta{type cs} and \meta{header
-cs} must all be control sequences. No check is performed to
-determine if that control sequence already exists, and the control
-sequences are defined globally (since it's likely that
-\cs{dtlforeachkey} may be used within a \env{tabular} environment),
-so you need to make sure you don't override an existing command of
-the same name.
-
-\begin{definition}[\DescribeMacro{\dtlforcolumn}]%
-\cs{dtlforcolumn}\marg{cs}\marg{db}\marg{key}\marg{body}
-\end{definition}
-This iterates through the column given by \meta{key} in the
-database given by \meta{db} and applies \meta{body}. In each
-iteration, \meta{cs} (which must be a control sequence) is set to
-the current element in the column and may be used in \meta{body}.
-Alternatively, if you want to identify the column by its index
-rather than its key, use:
-\begin{definition}[\DescribeMacro{\dtlforcolumnidx}]%
-\cs{dtlforcolumnidx}\marg{cs}\marg{db}\marg{col index}\marg{body}
-\end{definition}
-
\begin{definition}[\DescribeMacro{\DTLifdbexists}]
\cs{DTLifdbexists}\marg{db name}\marg{true part}\marg{false part}
\end{definition}
@@ -5854,6 +5833,280 @@ The result is shown in \autoref{tab:join3}.
\end{table}
\end{example}
+\subsection{Advanced Iteration}
+\label{sec:advancediter}
+
+The \ics{DTLforeach} command described in \sectionref{sec:dbforeach}
+has some limitations, especially when trying to iterate through
+large databases. This section describes lower-level user commands
+that may be used for iteration instead of \cs{DTLforeach}.
+
+\begin{definition}[\DescribeMacro{\dtlforeachkey}]%
+\cs{dtlforeachkey}(\meta{key cs},\meta{col cs},\meta{type
+cs},\meta{header cs})\cs{in}\marg{db}\cs{do}\marg{body}
+\end{definition}
+This iterates through all the keys in the database given by
+\meta{db}. In each iteration, \meta{key cs} is set to the key,
+\meta{col cs} is set to the column index, \meta{type cs} is set to
+the data type (as for \cs{DTLgetdatatype}), \meta{header cs} is set
+to the header for that column, and then \meta{body} is done. Note
+that \meta{key cs}, \meta{col cs}, \meta{type cs} and \meta{header
+cs} must all be control sequences. No check is performed to
+determine if that control sequence already exists, and the control
+sequences are defined globally (since it's likely that
+\cs{dtlforeachkey} may be used within a \env{tabular} environment),
+so you need to make sure you don't override an existing command of
+the same name.
+
+\begin{definition}[\DescribeMacro{\dtlforcolumn}]%
+\cs{dtlforcolumn}\marg{cs}\marg{db}\marg{key}\marg{body}
+\end{definition}
+This iterates through the column given by \meta{key} in the
+database given by \meta{db} and applies \meta{body}. In each
+iteration, \meta{cs} (which must be a control sequence) is set to
+the current element in the column and may be used in \meta{body}.
+Alternatively, if you want to identify the column by its index
+rather than its key, use:
+\begin{definition}[\DescribeMacro{\dtlforcolumnidx}]%
+\cs{dtlforcolumnidx}\marg{cs}\marg{db}\marg{col index}\marg{body}
+\end{definition}
+Both \cs{dtlforcolumn} and \cs{dtlforcolumnidx} have a starred
+version that doesn't check for the existence of the given database.
+You may use \ics{dtlbreak} within \meta{body} to break out of the loop
+at the end of the current iteration.
+
+An alternative to \cs{DTLforeach} is to use \TeX's primitive
+\ics{loop} with \ics{DTLgetvalue}, but this may not be faster.
+For example, suppose I have a CSV
+file with a single column (labelled \qt{Word}) with 1000 rows of
+data (where the CSV file is called \texttt{test-data-1000.csv}).
+First, let's use the unstarred version of \cs{DTLforeach}:
+\begin{verbatim}
+\batchmode
+\documentclass{article}
+\usepackage{datatool}
+
+\DTLloaddb{data}{test-data-1000.csv}
+
+\begin{document}
+\DTLforeach{data}{\Word=Word}{\Word.\par}
+\end{document}
+\end{verbatim}
+On my 64bit Linux computer, this document took 4.942s to compile.
+Result from \texttt{time pdflatex test}:
+\begin{verbatim}
+real 0m4.942s
+user 0m4.934s
+sys 0m0.015s
+\end{verbatim}
+Now using the starred version of \cs{DTLforeach}:
+\begin{verbatim}
+\batchmode
+\documentclass{article}
+\usepackage{datatool}
+
+\DTLloaddb{data}{test-data-1000.csv}
+
+\begin{document}
+\DTLforeach*{data}{\Word=Word}{\Word.\par}
+\end{document}
+\end{verbatim}
+This took 2.138s to compile:
+\begin{verbatim}
+real 0m2.138s
+user 0m2.122s
+sys 0m0.020s
+\end{verbatim}
+Now using \TeX's \cs{loop}:
+\begin{verbatim}
+\batchmode
+\documentclass{article}
+\usepackage{datatool}
+
+\DTLloaddb{data}{test-data-1000.csv}
+
+\begin{document}
+
+\newcount\rowctr
+\loop
+ \advance\rowctr by 1\relax
+ \DTLgetvalue{\Word}{data}{\rowctr}{1}%
+ \Word.\par
+\ifnum\rowctr<\DTLrowcount{data}
+\repeat
+
+\end{document}
+\end{verbatim}
+(This takes advantage of the fact that I know I only have one column
+of data, so I only need to reference column~1 in \cs{DTLgetvalue}.)
+This takes 2.638s to compile:
+\begin{verbatim}
+real 0m2.638s
+user 0m2.622s
+sys 0m0.020s
+\end{verbatim}
+which is slightly longer than using \cs{DTLforeach*} (but not nearly
+as long as using the unstarred version). Another possible method is
+to use \cs{dtlgetrow} and \cs{dtlgetentryfromcurrentrow}:
+\begin{verbatim}
+\batchmode
+\documentclass{article}
+\usepackage{datatool}
+
+\DTLloaddb{data}{test-data-1000.csv}
+
+\begin{document}
+
+\newcount\rowctr
+\loop
+ \advance\rowctr by 1\relax
+ \dtlgetrow{data}{\rowctr}%
+ \dtlgetentryfromcurrentrow{\Word}{1}%
+ \Word.\par
+\ifnum\rowctr<\DTLrowcount{data}
+\repeat
+
+\end{document}
+\end{verbatim}
+This took 3.596s to compile:
+\begin{verbatim}
+real 0m3.596s
+user 0m3.582s
+sys 0m0.019s
+\end{verbatim}
+Another possibility is to use \cs{dtlforcolumnidx}, described above:
+\begin{verbatim}
+\batchmode
+\documentclass{article}
+\usepackage{datatool}
+
+\DTLloaddb{data}{test-data-1000.csv}
+
+\begin{document}
+
+\dtlforcolumnidx{\Word}{data}{1}{\Word.\par}
+
+\end{document}
+\end{verbatim}
+This took 2.093s to compile:
+\begin{verbatim}
+real 0m2.093s
+user 0m2.083s
+sys 0m0.013s
+\end{verbatim}
+So if you only want to iterate through one column, this is the
+fastest method, but it's still more efficient to pre-process the
+data using an external script that creates a \texttt{.tex} file that
+can be \cs{input} into the document.
+
+Note that the build time increases with extra columns, \emph{even if
+they're not required in the document}. For example, I created a new
+CSV file called \texttt{test-data-1000-5.csv} that had four extra
+columns (which were actually duplicates of the first column with
+different headers, for simplicity). Just iterating through the first
+column to obtain the same PDF as previously significantly increases
+the time taken. The only modification to the above examples was an
+edit to the \cs{DTLloaddb} line:
+\begin{verbatim}
+\DTLloaddb{data}{test-data-1000-5.csv}
+\end{verbatim}
+The fastest method using \cs{dtlforcolumnidx} took 25.688s:
+\begin{verbatim}
+real 0m25.688s
+user 0m25.712s
+sys 0m0.013s
+\end{verbatim}
+Using \cs{DTLforeach*} took 25.725s:
+\begin{verbatim}
+real 0m25.725s
+user 0m25.744s
+sys 0m0.018s
+\end{verbatim}
+The unstarred version took 35.665s:
+\begin{verbatim}
+real 0m35.665s
+user 0m35.692s
+sys 0m0.022s
+\end{verbatim}
+Using \cs{loop} and \cs{DTLgetvalue} took 27.844s:
+\begin{verbatim}
+real 0m27.844s
+user 0m27.866s
+sys 0m0.019s
+\end{verbatim}
+Using \cs{loop} and \cs{dtlgetrow} took 31.770s:
+\begin{verbatim}
+real 0m31.770s
+user 0m31.785s
+sys 0m0.028s
+\end{verbatim}
+
+On the other hand, if I want to only iterate through, say, the last
+100 rows of the data, it's simpler to use \cs{loop}. For example:
+\begin{verbatim}
+\batchmode
+\documentclass{article}
+
+\usepackage{datatool}
+
+\DTLloaddb{data}{test-data-1000-5.csv}
+
+\begin{document}
+\newcount\rowctr
+\rowctr=\numexpr\DTLrowcount{data}-100\relax
+\loop
+ \advance\rowctr by 1\relax
+ \DTLgetvalue{\Word}{data}{\rowctr}{1}%
+ \Word.\par
+\ifnum\rowctr<\DTLrowcount{data}
+\repeat
+\end{document}
+\end{verbatim}
+This took 25.124s:
+\begin{verbatim}
+real 0m25.124s
+user 0m25.138s
+sys 0m0.023s
+\end{verbatim}
+The equivalent using \cs{DTLforeach} is:
+\begin{verbatim}
+\batchmode
+\documentclass{article}
+
+\usepackage{datatool}
+
+\DTLloaddb{data}{test-data-1000-5.csv}
+
+\begin{document}
+\newcount\firstidx
+\firstidx=\numexpr\DTLrowcount{data}-100\relax
+\DTLforeach*{data}{\Word=Word}%
+ {\ifnum\DTLcurrentindex>\firstidx\relax\Word.\par\fi}
+\end{document}
+\end{verbatim}
+(Remember that the row count can't be used in the optional argument
+of \cs{DTLforeach} as it's only incremented when the condition is
+true.) This took 26.375s:
+\begin{verbatim}
+real 0m26.375s
+user 0m26.381s
+sys 0m0.029s
+\end{verbatim}
+This takes longer because it's still iterating over every row of the
+database and is applying the condition to each row.
+
+\minisec{Summary}
+\begin{itemize}
+\item If possible, use an external script to pre-process the data so
+that you can simply \cs{input} valid \LaTeX\ code into the document.
+\item If you only want to iterate through one column of the data,
+use \cs{dtlforcolumnidx}.
+\item Remove\footnote{Naturally, make a copy of the original data, if
+necessary.}\ unwanted columns and\slash or rows from the CSV file (and sort, if
+necessary) using the spreadsheet application (or whatever) that was
+used to generate the original CSV file.
+\end{itemize}
+
\chapter{Creating an index, glossary or list of acronyms
(\texorpdfstring{\sty{datagidx}}{datagidx} package)}
\label{sec:datagidx}
diff --git a/Master/texmf-dist/doc/latex/datatool/samples/sample-autokeys.pdf b/Master/texmf-dist/doc/latex/datatool/samples/sample-autokeys.pdf
index dfba3d43cc7..c70a2191333 100644
--- a/Master/texmf-dist/doc/latex/datatool/samples/sample-autokeys.pdf
+++ b/Master/texmf-dist/doc/latex/datatool/samples/sample-autokeys.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/latex/datatool/samples/sample-barchart.pdf b/Master/texmf-dist/doc/latex/datatool/samples/sample-barchart.pdf
index c6aadfaa097..6f63f265704 100644
--- a/Master/texmf-dist/doc/latex/datatool/samples/sample-barchart.pdf
+++ b/Master/texmf-dist/doc/latex/datatool/samples/sample-barchart.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/latex/datatool/samples/sample-datatooltk.pdf b/Master/texmf-dist/doc/latex/datatool/samples/sample-datatooltk.pdf
index efc79437a63..8136c89a988 100644
--- a/Master/texmf-dist/doc/latex/datatool/samples/sample-datatooltk.pdf
+++ b/Master/texmf-dist/doc/latex/datatool/samples/sample-datatooltk.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/latex/datatool/samples/sample-dict.pdf b/Master/texmf-dist/doc/latex/datatool/samples/sample-dict.pdf
index 5339715bd16..4733aadcc99 100644
--- a/Master/texmf-dist/doc/latex/datatool/samples/sample-dict.pdf
+++ b/Master/texmf-dist/doc/latex/datatool/samples/sample-dict.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/latex/datatool/samples/sample-europecv-bib.pdf b/Master/texmf-dist/doc/latex/datatool/samples/sample-europecv-bib.pdf
index 25761b21490..d9dcf7af68d 100644
--- a/Master/texmf-dist/doc/latex/datatool/samples/sample-europecv-bib.pdf
+++ b/Master/texmf-dist/doc/latex/datatool/samples/sample-europecv-bib.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/latex/datatool/samples/sample-gidx.pdf b/Master/texmf-dist/doc/latex/datatool/samples/sample-gidx.pdf
index 32fb87b3ab5..41ced44b248 100644
--- a/Master/texmf-dist/doc/latex/datatool/samples/sample-gidx.pdf
+++ b/Master/texmf-dist/doc/latex/datatool/samples/sample-gidx.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/latex/datatool/samples/sample-glossary.pdf b/Master/texmf-dist/doc/latex/datatool/samples/sample-glossary.pdf
index 7b88dbfa57a..1363763115f 100644
--- a/Master/texmf-dist/doc/latex/datatool/samples/sample-glossary.pdf
+++ b/Master/texmf-dist/doc/latex/datatool/samples/sample-glossary.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/latex/datatool/samples/sample-index.pdf b/Master/texmf-dist/doc/latex/datatool/samples/sample-index.pdf
index aaed390088c..e6904d7064c 100644
--- a/Master/texmf-dist/doc/latex/datatool/samples/sample-index.pdf
+++ b/Master/texmf-dist/doc/latex/datatool/samples/sample-index.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/latex/datatool/samples/sample-mail-merge.pdf b/Master/texmf-dist/doc/latex/datatool/samples/sample-mail-merge.pdf
index b007bf31bbc..6a62cb9d4e1 100644
--- a/Master/texmf-dist/doc/latex/datatool/samples/sample-mail-merge.pdf
+++ b/Master/texmf-dist/doc/latex/datatool/samples/sample-mail-merge.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/latex/datatool/samples/sample-piechart.pdf b/Master/texmf-dist/doc/latex/datatool/samples/sample-piechart.pdf
index 6ea6b930502..c7745fbda38 100644
--- a/Master/texmf-dist/doc/latex/datatool/samples/sample-piechart.pdf
+++ b/Master/texmf-dist/doc/latex/datatool/samples/sample-piechart.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/latex/datatool/samples/sample-sort.pdf b/Master/texmf-dist/doc/latex/datatool/samples/sample-sort.pdf
index 9737968d009..f3ddb731633 100644
--- a/Master/texmf-dist/doc/latex/datatool/samples/sample-sort.pdf
+++ b/Master/texmf-dist/doc/latex/datatool/samples/sample-sort.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/latex/datatool/samples/sample-student-scores.pdf b/Master/texmf-dist/doc/latex/datatool/samples/sample-student-scores.pdf
index ccff004636c..9388c14b910 100644
--- a/Master/texmf-dist/doc/latex/datatool/samples/sample-student-scores.pdf
+++ b/Master/texmf-dist/doc/latex/datatool/samples/sample-student-scores.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/latex/datatool/samples/sample-two-per-row.pdf b/Master/texmf-dist/doc/latex/datatool/samples/sample-two-per-row.pdf
index 7e6e918a0cb..5a88b830118 100644
--- a/Master/texmf-dist/doc/latex/datatool/samples/sample-two-per-row.pdf
+++ b/Master/texmf-dist/doc/latex/datatool/samples/sample-two-per-row.pdf
Binary files differ