datatool (11jul15)

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

1 files changed, 79 insertions, 38 deletions

diff --git a/Master/texmf-dist/doc/latex/datatool/datatool-user.tex b/Master/texmf-dist/doc/latex/datatool/datatool-user.tex
index 32208ad80e5..91a26817787 100644
--- a/Master/texmf-dist/doc/latex/datatool/datatool-user.tex
+++ b/Master/texmf-dist/doc/latex/datatool/datatool-user.tex
@@ -37,7 +37,14 @@
 \doxitem{Counter}{counter}{counters}
 \doxitem{Option}{option}{package options}
 
-\newcommand*{\desctr}[1]{\ctrfmt{#1}\DescribeCounter{#1}}
+\newcommand*{\desctr}[1]{\DescribeCounter{#1}\ctrfmt{#1}}
+
+\newrobustcmd{\dbs}{\texttt{\string\\}}
+
+\newcommand{\idbs}{%
+ \dbs\index{\string\\\actualchar\dbs\encapchar usage}%
+}
+
 
  %bibliography database
 \DTLnewdb{docbib}
@@ -91,11 +98,11 @@
 \MakeShortVerb{"}
 \DeleteShortVerb{\|}
 
- \title{User Manual for datatool bundle version~2.22}
+ \title{User Manual for datatool bundle version~2.23}
  \author{Nicola L.C. Talbot\\
 \url{http://www.dickimaw-books.com/}}
 
- \date{2014-06-10}
+ \date{2015-07-11}
  \maketitle
 
 \pagenumbering{roman}
@@ -110,7 +117,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.22}
+  read \qt{Documented Code for datatool v2.23}
 
   \item[INSTALL] Installation instructions.
 
@@ -1325,6 +1332,12 @@ The remarks about \cs{DTLifStartsWith} also apply to
 \cs{DTLisPrefix}. This command performs a case sensitive
 match.
 
+\begin{definition}[\DescribeMacro{\DTLisinlist}]%
+\cs{DTLisinlist}\marg{element}\marg{list}
+\end{definition}
+This checks if \meta{element} is in \meta{list}. (Internally uses
+\cs{DTLifinlist}.)
+
 \chapter{Fixed Point Arithmetic}
 \label{sec:fp}
 
@@ -2323,6 +2336,14 @@ to a tab separator using the command:
 \begin{definition}[\DescribeMacro{\DTLsettabseparator}]%
 \cs{DTLsettabseparator}
 \end{definition}
+Note that this command changes the category code of the tab
+character to~12 (other). If, after you have loaded your data, you want to
+reset the tab category code to~10 (space), you can use:
+\begin{definition}[\DescribeMacro{\DTLmaketabspace}]%
+\cs{DTLmaketabspace}
+\end{definition}
+Don't use this command before you load any tab-separated data.
+
 To set the separator to a character other than a tab, you need to use
 \begin{definition}[\DescribeMacro{\DTLsetseparator}]%
 \cs{DTLsetseparator}\marg{character}
@@ -2332,8 +2353,8 @@ The delimiter can be changed using
 \cs{DTLsetdelimiter}\marg{character}
 \end{definition}
 \begin{important}
-Note that spaces count in the default \TeX\ manner (unless you
-specify a whitespace character as the delimiter).
+Note that spaces count in the usual \TeX\ manner and won't be
+trimmed from either side of the separators.
 \end{important}
 
 For example, suppose you have a file called \texttt{mydata.csv}
@@ -2951,7 +2972,7 @@ you can then display the database in a table as follows:
 \bfseries Score (\%)%
 \DTLforeach{scores}{%
 \firstname=FirstName,\surname=Surname,\score=Score}{%
-\\
+\\% start new row
 \firstname & \surname & \score}
 \end{tabular}
 \end{table}
@@ -2960,6 +2981,13 @@ This produces \autoref{tab:scores}. (Note that since I didn't
 need the student registration number, I didn't bother to 
 assign a command to the key "StudentNo".)
 
+\begin{important}
+Note that the new row command \idbs\ has been placed at the
+start of the final argument in the above example. This is necessary
+as placing it at the end of the argument will cause an unwanted row
+at the end of the table. This is a feature of the loop mechanism.
+\end{important}
+
 \begin{table}[htbp]
 \caption[Student scores (displaying a database in a 
 table)]{Student scores}\label{tab:scores}
@@ -3794,9 +3822,17 @@ If a database is created using \cs{DTLnewdb}, \cs{DTLnewrow}
 and \cs{DTLnewdbentry} (rather than loading it from an ASCII
 file), it is possible for some of the entries to have null values
 when a value is not assigned to a given key for a given row.
-(Note that a null value is not the same as an empty value. Empty
+It's also possible for data fetched from a~SQL database using
+\app{datatooltk} to contain null values\footnote{You can also use
+the \app{datatooltk} GUI to assign null values.}, but data loaded using
+\cs{DTLloaddb} (or \cs{DTLloadrawdb}) will have empty not null
+values for any blank cells.
+
+\begin{important}
+Note that a null value is not the same as an empty value. Empty
 values can be tested using \sty{etoolbox}'s \ics{ifdefempty} or
-similar.)
+similar.
+\end{important}
 
 When you iterate through the database using \cs{DTLforeach}
 (described in \autoref{sec:dbforeach}), 
@@ -3818,8 +3854,7 @@ This is the null value for a number.
 \cs{DTLifnull}\marg{cmd}\marg{true part}\marg{false part}
 \end{definition}
 This checks if \meta{cmd} is null where \meta{cmd} is a control
-sequence, 
-if it is, then \meta{true part}
+sequence, if it is, then \meta{true part}
 is done, otherwise \meta{false part} is done. This macro is
 illustrated in \autoref{ex:null} below.
 
@@ -3830,7 +3865,7 @@ This checks if \meta{cmd} is null or empty, where \meta{cmd} is a
 control sequence. If it is it does \meta{true part}, otherwise
 \meta{false part}.
 
-\begin{example}{Null Values}{ex:null}
+\begin{example}{Null vs Empty Values}{ex:null}
 Consider the following (which creates a database called "emailDB"):
 \begin{verbatim}
 \DTLnewdb{emailDB}
@@ -3859,7 +3894,8 @@ Consider the following (which creates a database called "emailDB"):
 In the above example, the first row of the database contains
 an entry with the key "Email2", but the second row doesn't.
 Whereas the second row contains an entry with the key "RegNum",
-but the first row doesn't.
+but the first row doesn't. That is, this database has two null (not
+empty) values.
 
 The following code puts the information in a \env{tabular} 
 environment:
@@ -3961,7 +3997,7 @@ Surname,FirstName,RegNum,Email1,Email2
 \end{ttfamily}\par\vskip\baselineskip\noindent
 and you load the data from this file using \cs{DTLloaddb}
 (defined in \autoref{sec:loaddb}). Now the
-database has no null values, but has an empty value for the
+database has \emph{no null values}, but has an \emph{empty} value for the
 key "RegNum" on the first row of the database, and an empty
 value for the key "Email2" on the second row of the database.
 Now, the following code
@@ -3992,6 +4028,11 @@ produces:\par\vskip\baselineskip\noindent
 =Surname,\emailI=Email1,\emailII=Email2,\regnum=RegNum}{\relax
 \\\firstname & \surname & \emailI & \DTLifnull{\emailII}{}{\emailII} & \DTLifnull{\regnum}{}{\regnum}}\relax
 \end{tabular}
+
+Now the missing entries are simply blank instead of containing
+\emph{Missing}. This is because they're empty not null. In this
+case, you may prefer to use \cs{DTLifnullorempty} instead of
+\cs{DTLifnull}.
 \end{example}
 
 \section{Editing Database Rows}
@@ -7121,17 +7162,17 @@ commands defined in this section. You will also need to have the
 \sty{pgf}/\sty{tikz} packages installed. The \sty{datapie} package 
 may be given the following options:
 \begin{description}
-\item[{\pkgopt[datapie]{color}}] Colour option (default).
-\item[{\pkgopt[datapie]{gray}}] Grey scale option.
-\item[{\pkgopt[datapie]{rotateinner}}] 
+\item[{\pkgopt{color}}] Colour option (default).
+\item[{\pkgopt{gray}}] Grey scale option.
+\item[{\pkgopt{rotateinner}}] 
 Rotate inner labels so that they are aligned
 with the pie chart radial axis.
-\item[{\pkgopt[datapie]{norotateinner}}] 
+\item[{\pkgopt{norotateinner}}] 
 Don't rotate inner labels (default).
-\item[{\pkgopt[datapie]{rotateouter}}] 
+\item[{\pkgopt{rotateouter}}] 
 Rotate outer labels so that they are aligned
 with the pie chart radial axis.
-\item[{\pkgopt[datapie]{norotateouter}}] 
+\item[{\pkgopt{norotateouter}}] 
 Don't rotate outer labels (default).
 \end{description}
 
@@ -7168,26 +7209,26 @@ is 2cm.
 \item[\csopt{DTLpiechart}{innerratio}] 
 The distance from the centre of the
 pie chart to the point where the inner labels are placed is given
-by this value multiplied by the ratio. The default value is 0.5. 
+by this value multiplied by the radius. The default value is 0.5. 
 
 \item[\csopt{DTLpiechart}{outerratio}]
 The distance from the centre of the
 pie chart to the point where the outer labels are placed is given
-by this value multiplied by the ratio. The default value is 1.25.
+by this value multiplied by the radius. The default value is 1.25.
 
 \item[\csopt{DTLpiechart}{cutawayratio}]
 The distance from the centre of the pie chart
 to the point of cutaway segments is given by this value multiplied
-by the ratio. The default value is 0.2.
+by the radius. The default value is 0.2.
 
 \item[\csopt{DTLpiechart}{inneroffset}] 
 This is the absolute distance from the centre
 of the pie chart to the point where the inner labels are placed.
 You should use only one or other of \csopt{DTLpiechart}{innerratio}
 and \csopt{DTLpiechart}{inneroffset}, not both. If you also want to 
-specify the radius, you must use \csopt{DTLpiechart}{ratio}
+specify the radius, you must use \csopt{DTLpiechart}{radius}
 before \csopt{DTLpiechart}{inneroffset}. If omitted, the inner 
-offset is obtained from the ratio multiplied by the 
+offset is obtained from the radius multiplied by the 
 \csopt{DTLpiechart}{innerratio} value.
 
 \item[\csopt{DTLpiechart}{outeroffset}] 
@@ -7195,9 +7236,9 @@ This is the absolute distance from the centre
 of the pie chart to the point where the outer labels are placed.
 You should use only one or other of \csopt{DTLpiechart}{outerratio} 
 and \csopt{DTLpiechart}{outeroffset}, not both. If you also want to 
-specify the radius, you must use \csopt{DTLpiechart}{ratio}
+specify the radius, you must use \csopt{DTLpiechart}{radius}
 before \csopt{DTLpiechart}{outeroffset}. If omitted, the outer 
-offset is obtained from the ratio multiplied by the 
+offset is obtained from the radius multiplied by the 
 \csopt{DTLpiechart}{outerratio} value.
 
 \item[\csopt{DTLpiechart}{cutawayoffset}] 
@@ -7237,7 +7278,7 @@ so it can only take the values "true" and "false". If the value is
 omitted "true" is assumed. If true, the inner labels are rotated 
 along the spokes of the pie chart, otherwise the inner labels are not 
 rotated.  There are analogous package options 
-\pkgopt[datapie]{rotateinner} and \pkgopt[datapie]{norotateinner}.
+\pkgopt{rotateinner} and \pkgopt{norotateinner}.
 
 \item[\csopt{DTLpiechart}{rotateouter}] 
 This is a boolean setting, so it can only take
@@ -7245,7 +7286,7 @@ the values "true" and "false". If the value is omitted "true" is
 assumed. If true, the outer labels are rotated along the spokes of
 the pie chart, otherwise the outer labels are not rotated.
 There are analogous package options 
-\pkgopt[datapie]{rotateouter} and \pkgopt[datapie]{norotateouter}.
+\pkgopt{rotateouter} and \pkgopt{norotateouter}.
 
 \end{description}
 
@@ -7520,7 +7561,7 @@ appropriate for apples and green is appropriate for pears, blue
 doesn't really correspond to lemons or limes.
 
 \begin{definition}[\DescribeMacro{\DTLdopiesegmentcolor}]%
-\cs{DTLdopiesegmentcolor}\meta{n}
+\cs{DTLdopiesegmentcolor}\marg{n}
 \end{definition}
 This sets the current text colour to that of the \meta{n}th
 segment.
@@ -8468,15 +8509,15 @@ direction.)
 
 The \sty{databar} package options are as follows:
 \begin{description}
-\item[{\pkgopt[databar]{color}}] Created coloured bar charts 
+\item[{\pkgopt{color}}] Created coloured bar charts 
 (default).
 
-\item[{\pkgopt[databar]{gray}}] Created grey scale bar charts.
+\item[{\pkgopt{gray}}] Created grey scale bar charts.
 
-\item[{\pkgopt[databar]{vertical}}] Created vertical bar charts
+\item[{\pkgopt{vertical}}] Created vertical bar charts
 (default).
 
-\item[{\pkgopt[databar]{horizontal}}] Created horizontal bar charts.
+\item[{\pkgopt{horizontal}}] Created horizontal bar charts.
 \end{description}
 
 
@@ -8706,9 +8747,9 @@ horizontal bars.
 \cs{DTLbarXlabelalign}
 \end{definition}
 This specifies the text alignment of the lower bar labels. This
-defaults to "left,rotate=-90" if you use the \pkgopt[databar]{vertical}
+defaults to "left,rotate=-90" if you use the \pkgopt{vertical}
 package option or the \csopt{DTLbarchart}{verticalbars} setting,
-and defaults to "right" if you use the \pkgopt[databar]{horizontal}
+and defaults to "right" if you use the \pkgopt{horizontal}
 package option or the \csopt{DTLbarchart}{verticalbars}"=false"
 setting.
 
@@ -9480,7 +9521,7 @@ before the month name in the bibliography file, e.g.\
 
 \item Once I have loaded and sorted my database, I can then
 display it using \cs{DTLbibliography}. This uses the style
-given by the \sty{databib} \pkgopt[databib]{style} package option,
+given by the \sty{databib} \pkgopt{style} package option,
 or the \cs{DTLbibliographystyle} command, both of which are
 described in \autoref{sec:bibstyle}.
 
@@ -9519,7 +9560,7 @@ document as follows:
 \section{Changing the bibliography style}
 \label{sec:bibstyle}
 The style of the bibliography produced using \cs{DTLbibliography} 
-depends on the \pkgopt[databib]{style}
+depends on the \pkgopt{style}
 package option, or can be set using
 \begin{definition}[\DescribeMacro{\DTLbibliographystyle}]%
 \cs{DTLbibliographystyle}\marg{style}