summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/datatool/datatool-user.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/latex/datatool/datatool-user.tex')
-rw-r--r--Master/texmf-dist/doc/latex/datatool/datatool-user.tex246
1 files changed, 228 insertions, 18 deletions
diff --git a/Master/texmf-dist/doc/latex/datatool/datatool-user.tex b/Master/texmf-dist/doc/latex/datatool/datatool-user.tex
index 91a26817787..885b832c301 100644
--- a/Master/texmf-dist/doc/latex/datatool/datatool-user.tex
+++ b/Master/texmf-dist/doc/latex/datatool/datatool-user.tex
@@ -1,5 +1,7 @@
\documentclass[report,widecs]{nlctdoc}
+\usepackage[T1]{fontenc}
+\usepackage[utf8]{inputenc}
\usepackage{ifthen}
\usepackage[verbose=false]{datatool}
\usepackage{datapie,databar,databib,person,datagidx}
@@ -7,10 +9,9 @@
\usepackage{graphicx}
\usepackage{colortbl}
\usepackage{booktabs}
+\usepackage{metalogo}
\usepackage{cmap}
\usepackage{alltt}
-\usepackage[T1]{fontenc}
-\usepackage[utf8]{inputenc}
\ifpdf
\usepackage{mathpazo}
\usepackage[scaled=.88]{helvet}
@@ -98,11 +99,11 @@
\MakeShortVerb{"}
\DeleteShortVerb{\|}
- \title{User Manual for datatool bundle version~2.23}
+ \title{User Manual for datatool bundle version~2.24}
\author{Nicola L.C. Talbot\\
\url{http://www.dickimaw-books.com/}}
- \date{2015-07-11}
+ \date{2016-01-12}
\maketitle
\pagenumbering{roman}
@@ -117,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.23}
+ read \qt{Documented Code for datatool v2.24}
\item[INSTALL] Installation instructions.
@@ -3906,7 +3907,7 @@ environment:
\bfseries Email 1 &
\bfseries Email 2 &
\bfseries Reg Num%
-\DTLforeach{emailDB}{\firstname=FirstName,\surname=Surname,%
+\DTLforeach*{emailDB}{\firstname=FirstName,\surname=Surname,%
\emailI=Email1,\emailII=Email2,\regnum=RegNum}{%
\\\firstname & \surname & \emailI & \emailII & \regnum}%
\end{tabular}
@@ -3918,7 +3919,7 @@ This produces the following:\par\vskip\baselineskip\noindent
\bfseries Email 1 &
\bfseries Email 2 &
\bfseries Reg Num\relax
-\DTLforeach{emailDB}{\firstname=FirstName,\surname
+\DTLforeach*{emailDB}{\firstname=FirstName,\surname
=Surname,\emailI=Email1,\emailII=Email2,\regnum=RegNum}{\relax
\\\firstname & \surname & \emailI & \emailII & \regnum}\relax
\end{tabular}
@@ -4570,8 +4571,9 @@ First of all, display the unsorted data:
\DTLdisplaydb{inversiondata}
\end{verbatim}
This produces:
-
+\begin{display}
\DTLdisplaydb{inversiondata}
+\end{display}
Now sort the data using the \ics{dtlwordindexcompare} handler:
\begin{verbatim}
@@ -4583,10 +4585,10 @@ and display again:
\DTLdisplaydb{inversiondata}
\end{verbatim}
which now produces:
-
+\begin{display}
\DTLdisplaydb{inversiondata}
-
-~here are three entries with pre-inversion text as simply
+\end{display}
+There are three entries here with pre-inversion text that's 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
@@ -4601,7 +4603,221 @@ 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:
+As from version 2.24, the predefined handlers now have limited support for UTF-8
+characters. \emph{This is still experimental.} The support will
+automatically be switched on if the \sty{inputenc} package is loaded
+with the \pkgopt{utf8} option before loading \sty{datatool-base}
+(which is automatically loaded by \sty{datatool}). If \sty{inputenc}
+is loaded after \sty{datatool-base}, you can use the (boolean) \pkgopt{utf8}
+option when you load \sty{datatool-base} to enable it. For example,
+either:
+\begin{verbatim}
+\usepackage[utf8]{inputenc}
+\usepackage{datatool-base}
+\end{verbatim}
+or
+\begin{verbatim}
+\usepackage[utf8]{datatool-base}
+\usepackage[utf8]{inputenc}
+\end{verbatim}
+You can also enable this option after \sty{datatool-base} has been loaded
+using
+\begin{definition}[\DescribeMacro\dtlenableUTFviii]
+\cs{dtlenableUTFviii}
+\end{definition}
+or disable it with
+\begin{definition}[\DescribeMacro\dtldisableUTFviii]
+\cs{dtldisableUTFviii}
+\end{definition}
+For example:
+\begin{verbatim}
+\usepackage[utf8]{inputenc}
+\usepackage{datatool}
+\dtldisableUTFviii
+\end{verbatim}
+This option isn't required for \XeLaTeX, which treats each UTF-8
+character as an individual token.
+
+With regular (pdf)\LaTeX\ (as opposed to \XeLaTeX) each UTF-8 character is
+actually treated as two tokens that represent the first and second
+octet of the UTF-8 character. This means that it's not possible for
+\TeX\ to obtain a character code using the usual backtick method, so
+(with this option enabled) if a UTF-8 character is detected, the handlers
+described above will pass both octet tokens to one of the following commands:
+\begin{definition}[\DescribeMacro\dtlsetUTFviiicharcode]
+\cs{dtlsetUTFviiicharcode}\marg{octet tokens}\marg{count}
+\end{definition}
+(for the case-sensitive handler \ics{dltcompare}) and
+\begin{definition}[\DescribeMacro\dtlsetUTFviiilccharcode]
+\cs{dtlsetUTFviiilccharcode}\marg{octet tokens}\marg{count}
+\end{definition}
+(for the case-insensitive handlers).
+
+By default the first simply does:
+\begin{definition}[\DescribeMacro\dtlsetdefaultUTFviiicharcode]
+\cs{dtlsetdefaultUTFviiicharcode}\marg{octet tokens}\marg{count}
+\end{definition}
+and the second does
+\begin{definition}[\DescribeMacro\dtlsetdefaultUTFviiilccharcode]
+\cs{dtlsetdefaultUTFviiilccharcode}\marg{octet tokens}\marg{count}
+\end{definition}
+
+In all the above \meta{octet tokens} are the two octets forming the
+UTF-8 character and \meta{count} is a count register in which to
+store the relevant character code.
+
+The default commands simply set the character code for certain
+common accented Latin characters (such as \'e) to the code for their
+unaccented version (such as e). You can redefine
+\cs{dtlsetUTFviiicharcode} and \cs{dtlsetUTFviiilccharcode} to test
+for additional characters. For example, to add the Norwegian
+characters \ae, \o\ and \aa\ to the end of the Latin alphabet, you
+can do:
+\begin{verbatim}
+\renewcommand*{\dtlsetUTFviiicharcode}[2]{%
+ \ifstrequal{#1}{Æ}%
+ {%
+ #2=91\relax
+ }%
+ {%
+ \ifstrequal{#1}{Ø}%
+ {%
+ #2=92\relax
+ }%
+ {%
+ \ifstrequal{#1}{Å}%
+ {%
+ #2=93\relax
+ }%
+ {%
+ \ifstrequal{#1}{æ}%
+ {%
+ #2=123\relax
+ }%
+ {%
+ \ifstrequal{#1}{ø}%
+ {%
+ #2=124\relax
+ }%
+ {%
+ \ifstrequal{#1}{å}%
+ {%
+ #2=125\relax
+ }%
+ {%
+ \dtlsetdefaultUTFviiicharcode{#1}{#2}%
+ }%
+ }%
+ }%
+ }%
+ }%
+ }%
+}
+
+\renewcommand*{\dtlsetUTFviiilccharcode}[2]{%
+ \ifstrequal{#1}{Æ}%
+ {%
+ #2=123\relax
+ }%
+ {%
+ \ifstrequal{#1}{Ø}%
+ {%
+ #2=124\relax
+ }%
+ {%
+ \ifstrequal{#1}{Å}%
+ {%
+ #2=125\relax
+ }%
+ {%
+ \ifstrequal{#1}{æ}%
+ {%
+ #2=123\relax
+ }%
+ {%
+ \ifstrequal{#1}{ø}%
+ {%
+ #2=124\relax
+ }%
+ {%
+ \ifstrequal{#1}{å}%
+ {%
+ #2=125\relax
+ }%
+ {%
+ \dtlsetdefaultUTFviiilccharcode{#1}{#2}%
+ }%
+ }%
+ }%
+ }%
+ }%
+ }%
+}
+\end{verbatim}
+
+In the case where a~character is a single token (for example, with
+Latin-1 encoding), the code associated with that character is set
+using
+\begin{definition}[\DescribeMacro\dtlsetcharcode]
+\cs{dtlsetcharcode}\marg{c}\marg{count register}
+\end{definition}
+(for case-sensitive comparison) and
+\begin{definition}[\DescribeMacro\dtlsetlccharcode]
+\cs{dtlsetlccharcode}\marg{c}\marg{count register}
+\end{definition}
+(for case-insensitive comparison), where \meta{c} is the character
+and \meta{count register} is a count register. The default
+definitions are:
+\begin{verbatim}
+\newcommand*{\dtlsetcharcode}[2]{#2=`#1\relax}
+\newcommand*{\dtlsetlccharcode}[2]{#2=\lccode`#1\relax}
+\end{verbatim}
+So, for example, the letter \qt{e} has the code \number`e\ whereas
+(with the Latin-1 encoding) the letter \qt{\'e} has the code 233.
+This means that \qt{\'e} will be sorted after \qt{e}. It may be that
+you want \qt{\'e} to be treated the same as \qt{e} when making the
+comparison. In this case, you need to redefine \cs{dtlsetcharcode}
+and \cs{dtlsetlccharcode}. For example, for the case-sensitive
+comparisons:
+\begin{verbatim}
+\renewcommand*{\dtlsetcharcode}[2]{%
+ \ifstrequal{#1}{É}%
+ {%
+ #2=`E\relax
+ }%
+ {%
+ \ifstrequal{#1}{é}%
+ {%
+ #2=`e\relax
+ }%
+ {%
+ #2=`#1\relax
+ }%
+ }%
+}
+\end{verbatim}
+and for the case-insensitive comparisons:
+\begin{verbatim}
+\renewcommand*{\dtlsetlccharcode}[2]{%
+ \ifboolexpr
+ {%
+ test {\ifstrequal{#1}{é}}
+ or test {\ifstrequal{#1}{É}}
+ }%
+ {%
+ #2=`e\relax
+ }%
+ {%
+ #2=\lccode`#1\relax
+ }%
+}
+\end{verbatim}
+(Extra conditionals will need to be added for other diacritics.
+Alternative conditionals, such as \cs{ifx} or \cs{ifnum}, may be more
+efficient. In the above I've used the \sty{etoolbox} commands for
+clarity.)
+
+There are two shortcut commands for \cs{dtlsort}:
\begin{definition}[\DescribeMacro{\DTLsort}]%
\cs{DTLsort}\oarg{replacement key list}\marg{sort criteria}\marg{db name}
\end{definition}
@@ -4887,12 +5103,6 @@ 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}