diff options
author | Karl Berry <karl@freefriends.org> | 2013-08-31 22:45:45 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2013-08-31 22:45:45 +0000 |
commit | 3327dfbc00f9422625c9a574826755a56a9cbee5 (patch) | |
tree | 9c374a829933d190cee9d576fb1c43cabbc495de /Master/texmf-dist/doc/latex/datatool | |
parent | 1483696754d202b1c75304be8bd6004c4349cd09 (diff) |
datatool (31aug13)
git-svn-id: svn://tug.org/texlive/trunk@31551 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex/datatool')
14 files changed, 310 insertions, 13 deletions
diff --git a/Master/texmf-dist/doc/latex/datatool/CHANGES b/Master/texmf-dist/doc/latex/datatool/CHANGES index 2621cba5d8e..ebf870514c8 100644 --- a/Master/texmf-dist/doc/latex/datatool/CHANGES +++ b/Master/texmf-dist/doc/latex/datatool/CHANGES @@ -1,3 +1,15 @@ +v2.17: + + * datatool: + + - added \edtlgetrowforvalue and \DTLfetch + + - added joining two databases in a single table example to user manual + + * databib: + + - fixed packaging of databib.bst + v2.16: * datatool: diff --git a/Master/texmf-dist/doc/latex/datatool/README b/Master/texmf-dist/doc/latex/datatool/README index 9e39650fbea..e13a8ecc48b 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.16 +LaTeX Bundle : datatool v2.17 -Last Modified : 2013-08-16 +Last Modified : 2013-08-29 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 differindex 657be69514f..1994ba47f93 100644 --- a/Master/texmf-dist/doc/latex/datatool/datatool-code.pdf +++ 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 27c4682aeae..343f339834d 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 fbc7cad8a99..07da5dd87a8 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.16} + \title{User Manual for datatool bundle version~2.17} \author{Nicola L.C. Talbot\\ \url{http://www.dickimaw-books.com/}} - \date{2013-08-16} + \date{2013-08-29} \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.16} + read \qt{Documented Code for datatool v2.17} \item[INSTALL] Installation instructions. @@ -130,11 +130,15 @@ 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. If the provided packages take a frustratingly +or scripting language. \textbf{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. - +file that can be input into your document.} For large amounts of +data that need to be sorted or filtered or joined, consider storing your data +in an~SQL database and use +\app{datatooltk}\footnote{\url{http://www.dickimaw-books.com/apps/datatooltk/}} to import the data, +using SQL syntax to filter, sort and otherwise +manipulate the values. \end{important} This bundle consists of the following packages: @@ -329,8 +333,10 @@ and decimal characters may be changed using \begin{definition}[\DescribeMacro{\DTLsetnumberchars}]% \cs{DTLsetnumberchars}\marg{number group character}\marg{decimal character} \end{definition} +\begin{important} Note that scientific notation is not supported, and the number group character may not be used after the decimal character. +\end{important} \item[Currency] A currency symbol followed by an integer or real number is considered to be the currency data type. @@ -2031,10 +2037,10 @@ 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 +I've written a Java helper application to accompany \sty{datatool} +called \app{datatooltk}. The installer is available +on CTAN at +\url{http://mirrors.ctan.org/support/datatooltk/datatooltk-installer.jar}. The application will allow you to edit 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. @@ -5001,6 +5007,22 @@ value of the key specified by \meta{key} in the first row of the database called \meta{db name} which contains the key \meta{ref key} which has the value \meta{value}. +\begin{definition}[\DescribeMacro{\DTLfetch}] +\cs{DTLfetch}\marg{db name}\marg{column1 name}\marg{column1 +value}\marg{column2 name} +\end{definition} +This fetches and displays the value for \meta{column2 name} in the +first row where the value of \meta{column1 name} is \meta{column1 +value}. (Note that all arguments are expanded.) So, for example, if +you have a column labelled ``regnum'' and a column labelled +``tutor'', then to fetch and display the value of the tutor in the +row where ``regnum'' is ``12345'' from the database called +``students'' you can do: +\begin{verbatim} +\DTLfetch{students}{regnum}{12345}{tutor} +\end{verbatim} +See \autoref{ex:join} on page~\pageref{ex:join}. + \begin{definition}[\DescribeMacro{\DTLassign}] \cs{DTLassign}\marg{db name}\marg{row idx}\marg{assign list} \end{definition} @@ -5166,7 +5188,11 @@ argument} error if you specify a row index that is out of range. 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. \textbf{Note that no expansion is -performed when matching \meta{value}.} +performed when matching \meta{value}.} If you want \meta{value} +expanded before comparison, use: +\begin{definition}[\DescribeMacro{\edtlgetrowforvalue}] +\cs{edtlgetrowforvalue}\marg{db name}\marg{column index}\marg{value} +\end{definition} You can use the commands below to access or edit \cs{dtlcurrentrow}, but they won't change the database. Instead, once you've finished @@ -5235,6 +5261,265 @@ 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}. +\begin{example}{Joining Two Databases in a Single Table}{ex:join} +\DTLnewdb{cmp101}\DTLnewrow{cmp101}\relax +\DTLnewdbentry{cmp101}{regnum}{12345}\relax +\DTLnewdbentry{cmp101}{Autumn Marks}{80}\relax +\DTLnewdbentry{cmp101}{Spring Marks}{85}\relax +\DTLnewrow{cmp101}\relax +\DTLnewdbentry{cmp101}{regnum}{12346}\relax +\DTLnewdbentry{cmp101}{Autumn Marks}{70}\relax +\DTLnewdbentry{cmp101}{Spring Marks}{90}\relax +\DTLnewrow{cmp101}\relax +\DTLnewdbentry{cmp101}{regnum}{12347}\relax +\DTLnewdbentry{cmp101}{Autumn Marks}{75}\relax +\DTLnewdbentry{cmp101}{Spring Marks}{60}\relax +\DTLnewdb{students}\relax +\DTLnewrow{students}\relax +\DTLnewdbentry{students}{regnum}{12344}\relax +\DTLnewdbentry{students}{name}{Mary Brown}\relax +\DTLnewrow{students}\relax +\DTLnewdbentry{students}{regnum}{12345}\relax +\DTLnewdbentry{students}{name}{Joe Bloggs}\relax +\DTLnewrow{students}\relax +\DTLnewdbentry{students}{regnum}{12346}\relax +\DTLnewdbentry{students}{name}{Jane Doe}\relax +\DTLnewrow{students}\relax +\DTLnewdbentry{students}{regnum}{12347}\relax +\DTLnewdbentry{students}{name}{John Smith}\relax +\DTLnewrow{students}\relax +\DTLnewdbentry{students}{regnum}{12348}\relax +\DTLnewdbentry{students}{name}{Alice Jones}\relax +Suppose a lecturer has a CSV file for a particular course that +contains student registration numbers and marks for the Autumn and +Spring semesters. The file is called, say, \texttt{cmp101.csv} and +contains the following: + +\vskip\baselineskip +\begin{ttfamily}\par +regnum,Autumn Marks,Spring Marks\par +\DTLforeach*{cmp101}{\RegNum=regnum,\Autumn=Autumn Marks,\Spring=Spring Marks} +{\RegNum,\Autumn,\Spring\par} +\end{ttfamily} +\vskip\baselineskip\noindent + +This only contains the student registration numbers, not their +names, but suppose there's another CSV file that contains the +registration numbers and names for all students at the department +(or university). This file called, say, \texttt{students.csv} may +look something like: + +\vskip\baselineskip +\begin{ttfamily}\par +regnum,name\par +\DTLforeach*{students}{\RegNum=regnum,\Name=name} +{\RegNum,\Name\par} +\end{ttfamily} +\vskip\baselineskip\noindent + +Now suppose the lecturer wants a table of all the students on course +CMP101 listing each student's name and marks. Here's the code: +\begin{verbatim} +\DTLloaddb{cmp101}{cmp101.csv}% load course data +\DTLloaddb{students}{students.csv}% load student data + +\begin{table}[htbp] + \caption{Student Marks (Joining Databases)} + \centering + \begin{tabular}{lrr} + \bfseries Name & \bfseries Autumn Marks & \bfseries Spring Marks% + \DTLforeach*{cmp101}% + {\RegNum=regnum,\Autumn=Autumn Marks,\Spring=Spring Marks}% + {\\\DTLfetch{students}{regnum}{\RegNum}{name} & \Autumn & \Spring}% + \end{tabular} +\end{table} +\end{verbatim} + +The result is shown in \autoref{tab:join}. + +\begin{table}[htbp] + \caption{Student Marks (Joining Databases)}\label{tab:join} + \centering + \begin{tabular}{lrr} + \bfseries Name & \bfseries Autumn Marks & \bfseries Spring Marks% + \DTLforeach*{cmp101}{\RegNum=regnum,\Autumn=Autumn Marks,\Spring=Spring Marks} + {\\\DTLfetch{students}{regnum}{\RegNum}{name} & \Autumn & \Spring}% + \end{tabular} +\end{table} + +Let's suppose now that the \texttt{students.csv} file has the first +name and surname in separate columns rather than single columns. So +the CSV file looks like: +\DTLcleardb{students}\relax +\DTLnewrow{students}\relax +\DTLnewdbentry{students}{regnum}{12344}\relax +\DTLnewdbentry{students}{forename}{Mary}\relax +\DTLnewdbentry{students}{surname}{Brown}\relax +\DTLnewrow{students}\relax +\DTLnewdbentry{students}{regnum}{12345}\relax +\DTLnewdbentry{students}{forename}{Joe}\relax +\DTLnewdbentry{students}{surname}{Bloggs}\relax +\DTLnewrow{students}\relax +\DTLnewdbentry{students}{regnum}{12346}\relax +\DTLnewdbentry{students}{forename}{Jane}\relax +\DTLnewdbentry{students}{surname}{Doe}\relax +\DTLnewrow{students}\relax +\DTLnewdbentry{students}{regnum}{12347}\relax +\DTLnewdbentry{students}{forename}{John}\relax +\DTLnewdbentry{students}{surname}{Smith}\relax +\DTLnewrow{students}\relax +\DTLnewdbentry{students}{regnum}{12348}\relax +\DTLnewdbentry{students}{forename}{Alice}\relax +\DTLnewdbentry{students}{surname}{Jones}\relax + +\vskip\baselineskip +\begin{ttfamily}\par +regnum,forename,surname\par +\DTLforeach*{students}{\RegNum=regnum,\Forename=forename,\Surname=surname} +{\RegNum,\Forename,\Surname\par} +\end{ttfamily} +\vskip\baselineskip\noindent + +You may be tempted to replace +\begin{verbatim} +\DTLfetch{students}{regnum}{\RegNum}{name} +\end{verbatim} +with +\begin{verbatim} +\DTLfetch{students}{regnum}{\RegNum}{forename}\space +\DTLfetch{students}{regnum}{\RegNum}{surname} +\end{verbatim} +in the above code, but this is inefficient as it requires two +searches for the same row. Instead, you can do: +\begin{verbatim} +\DTLfetch{students}{regnum}{\RegNum}{forename}\space +\dtlgetentryfromcurrentrow{\Surname}{\dtlcolumnindex{students}{surname}}% +\Surname +\end{verbatim} +This can be done because +\begin{verbatim} +\DTLfetch{students}{regnum}{\RegNum}{forename} +\end{verbatim} +is equivalent to +\begin{verbatim} +\edtlgetrowforvalue{students}{\dtlcolumnindex{students}{regnum}}{\RegNum}% +\dtlgetentryfromcurrentrow + {\dtlcurrentvalue}{\dtlcolumnindex{students}{forename}}% +\dtlcurrentvalue +\end{verbatim} +This means that \cs{dtlcurrentrow} has already been set by +\cs{DTLfetch} so we can just do another +\cs{dtlgetentryfromcurrentrow} for the surname field. +The new code for the table is now: + +\begin{verbatim} +\DTLloaddb{cmp101}{cmp101.csv}% load course data +\DTLloaddb{students}{students.csv}% load student data + +\begin{table}[htbp] + \caption{Student Marks (Joining Databases)} + \centering + \begin{tabular}{lrr} + \bfseries Name & \bfseries Autumn Marks & \bfseries Spring Marks% + \DTLforeach*{cmp101}% + {\RegNum=regnum,\Autumn=Autumn Marks,\Spring=Spring Marks}% + {\\% + \DTLfetch{students}{regnum}{\RegNum}{forename}\space + \dtlgetentryfromcurrentrow{\Surname}{\dtlcolumnindex{students}{surname}}% + \Surname + & \Autumn & \Spring}% + \end{tabular} +\end{table} +\end{verbatim} + +The result is shown in \autoref{tab:join2}. + +\begin{table}[htbp] + \caption{Student Marks (Joining Databases)}\label{tab:join2} + \centering + \begin{tabular}{lrr} + \bfseries Name & \bfseries Autumn Marks & \bfseries Spring Marks% + \DTLforeach*{cmp101}% + {\RegNum=regnum,\Autumn=Autumn Marks,\Spring=Spring Marks}% + {\\% + \DTLfetch{students}{regnum}{\RegNum}{forename}\space + \dtlgetentryfromcurrentrow{\Surname}{\dtlcolumnindex{students}{surname}}% + \Surname + & \Autumn & \Spring}% + \end{tabular} +\end{table} + +\textbf{Caveat:} be careful of scoping issues. Suppose you want the +first name and surname in separate columns, you may consider doing: +\begin{verbatim} + \DTLfetch{students}{regnum}{\RegNum}{forename}% + & + \dtlgetentryfromcurrentrow{\Surname}{\dtlcolumnindex{students}{surname}}% + \Surname +\end{verbatim} +(and adding an extra column to the \env{tabular} environment). +However this will result in undefined values for \cs{Surname} as +\cs{dtlcurrentrow} is only locally set. After the \verb|&| special +character \cs{dtlcurrentrow} has lost its value as it's no longer in the same +scope. You can fix this problem in a~number of ways. Firstly you can +make \cs{dtlcurrentrow} global after \cs{DTLfetch} via +\begin{verbatim} +\global\dtlcurrentrow=\dtlcurrentrow +\end{verbatim} +or you could move the column break to just before \cs{Surname} and +make \cs{Surname} global: +\begin{verbatim} + \DTLfetch{students}{regnum}{\RegNum}{forename}% + \dtlgetentryfromcurrentrow{\Surname}{\dtlcolumnindex{students}{surname}}% + \global\let\Surname\Surname + & + \Surname +\end{verbatim} +There are other possibilities as well, but the first method is +probably the best, especially if you have multiple columns you want +to fetch. + +Here's the updated code: +\begin{verbatim} +\begin{table}[htbp] + \caption{Student Marks (Joining Databases)} + \centering + \begin{tabular}{llrr} + \bfseries Forename & \bfseries Surname & + \bfseries Autumn Marks & \bfseries Spring Marks% + \DTLforeach*{cmp101}% + {\RegNum=regnum,\Autumn=Autumn Marks,\Spring=Spring Marks}% + {\\% + \DTLfetch{students}{regnum}{\RegNum}{forename}% + \global\dtlcurrentrow=\dtlcurrentrow + & + \dtlgetentryfromcurrentrow{\Surname}{\dtlcolumnindex{students}{surname}}% + \Surname + & \Autumn & \Spring}% + \end{tabular} +\end{table} +\end{verbatim} +The result is shown in \autoref{tab:join3}. + +\begin{table}[htbp] + \caption{Student Marks (Joining Databases)}\label{tab:join3} + \centering + \begin{tabular}{llrr} + \bfseries Forename & \bfseries Surname & + \bfseries Autumn Marks & \bfseries Spring Marks% + \DTLforeach*{cmp101}% + {\RegNum=regnum,\Autumn=Autumn Marks,\Spring=Spring Marks}% + {\\% + \DTLfetch{students}{regnum}{\RegNum}{forename}% + \global\dtlcurrentrow=\dtlcurrentrow + & + \dtlgetentryfromcurrentrow{\Surname}{\dtlcolumnindex{students}{surname}}% + \Surname + & \Autumn & \Spring}% + \end{tabular} +\end{table} +\end{example} + \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-barchart.pdf b/Master/texmf-dist/doc/latex/datatool/samples/sample-barchart.pdf Binary files differindex bdb343e3dc5..62314cbc6bd 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 differindex 9899148d876..2741b9732f1 100644 --- a/Master/texmf-dist/doc/latex/datatool/samples/sample-dict.pdf +++ b/Master/texmf-dist/doc/latex/datatool/samples/sample-dict.pdf 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 differindex 20cc564ac16..9899165d244 100644 --- a/Master/texmf-dist/doc/latex/datatool/samples/sample-gidx.pdf +++ b/Master/texmf-dist/doc/latex/datatool/samples/sample-gidx.pdf 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 differindex c54a75176af..2672317ae55 100644 --- a/Master/texmf-dist/doc/latex/datatool/samples/sample-glossary.pdf +++ b/Master/texmf-dist/doc/latex/datatool/samples/sample-glossary.pdf 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 differindex 80060752d9d..ebc16da0672 100644 --- a/Master/texmf-dist/doc/latex/datatool/samples/sample-index.pdf +++ b/Master/texmf-dist/doc/latex/datatool/samples/sample-index.pdf 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 da04184da04..43a32ddde60 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-piechart.pdf b/Master/texmf-dist/doc/latex/datatool/samples/sample-piechart.pdf Binary files differindex 7c503175ca9..66e135f9b5d 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-student-scores.pdf b/Master/texmf-dist/doc/latex/datatool/samples/sample-student-scores.pdf Binary files differindex 5061df422ce..e9691d084a4 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 ac91bad3ee2..c892444e75b 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 |