summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/csvtools/csvtools.html
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/latex/csvtools/csvtools.html')
-rw-r--r--Master/texmf-dist/doc/latex/csvtools/csvtools.html806
1 files changed, 806 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/latex/csvtools/csvtools.html b/Master/texmf-dist/doc/latex/csvtools/csvtools.html
new file mode 100644
index 00000000000..3e0937c4d80
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/csvtools/csvtools.html
@@ -0,0 +1,806 @@
+<html>
+<title>csvtools.sty v 1.1</title>
+<body>
+<a href=http://theoval.cmp.uea.ac.uk/~nlct>Dr Nicola Talbot</a> |
+<a href=http://www.cmp.uea.ac.uk/>School of Computing Sciences</a> |
+<a href=http://www.uea.ac.uk/>University of East Anglia</a>
+
+<h1>csvtools.sty v1.1 : A LaTeX2e Package Providing Access to Data Saved in a CSV File</h1>
+
+<hr>
+<h2>Contents</h2>
+<ul>
+<li><a href=#intro>Introduction</a>
+<li><a href=#mailmerge>Mail Merging and Similar Applications</a>
+<li><a href=#csv2tab>Converting CSV file into a tabular environment</a>
+<li><a href=#longtable>Converting CSV file into a longtable environment</a>
+<li><a href=#counters>Associated Counters</a>
+<li><a href=#crossref>Cross-Referencing</a>
+<li><a href=#save>Saving Entries</a>
+<li><a href=#perl>The csvtools.pl Perl Script</a>
+<li><a href=#drawbacks>Bugs/Drawbacks/``Features''</a>
+</ul>
+
+<h2>Examples</h2>
+<ul>
+<li><a href=#ex:mail>Example 1 (Mail Merging)</a>
+<li><a href=#ex:ps>Example 2 (Multiple Figures)</a>
+<li><a href=#ex:field>Example 3 (Mail Merging using <tt>\field</tt>)</a>
+<li><a href=#ex:tab1>Example 4 (Aligning Data from a CSV file)</a>
+<li><a href=#ex:tab2>Example 5 (Adding Lines)</a>
+<li><a href=#ex:tab3>Example 6 (Added Complexity)</a>
+<li><a href=#ex:longtab>Example 7 (Using a longtable environment)</a>
+<li><a href=#ex:stripy>Example 8 (Stripy Table)</a>
+<li><a href=#ex:mail2>Example 9 (More Mail Merging)</a>
+<li><a href=#ex:ref1>Example 10 (Labelling within <tt>\applyCSVfile</tt>)</a>
+<li><a href=#ex:ref2>Example 11 (Labelling within <tt>\applyCSVfile</tt>)</a>
+<li><a href=#ex:timetogrowth>Example 12 (Labelling within <tt>\CSVtotabular</tt>)</a>
+<li><a href=#ex:t2g2>Example 13 (Labelling within <tt>\CSVtotabular</tt>)</a>
+<li><a href=#ex:index>Example 14 (Saving Entries)</a>
+<li><a href=#ex:perl>Example 15 (csvtools.pl - Aligning Data)</a>
+</ul>
+<hr>
+
+<h2><a name=intro>Introduction</a></h2>
+ The <tt>csvtools</tt> package allows you to repeatedly perform
+ a set of LaTeX commands on data in each row
+ of a comma separated variable (CSV) file.
+ This can be used for mail merging, generating
+ tables etc.
+
+<h2><a name=mailmerge>Mail Merging and Similar Applications</a></h2>
+
+<tt>\applyCSVfile[</tt><em>n</em><tt>]{</tt><em>filename</em><tt>}{</tt><em>text</em><tt>}</tt>
+<p>
+ Letters can be generated using data given in
+ each line from <em>filename</em>.
+ If the CSV file contains a header row, the
+ unstarred version of <tt>\applyCSVfile</tt> should
+ be used, otherwise the starred version <tt>\applyCSVfile*</tt>
+ should be used. The optional argument <em>n</em>
+ specifies on which line the actual data (not header line)
+ starts. The unstarred version defaults to line 2
+ (the header row is always assumed to be on line 1)
+ and the starred version defaults to 1.
+<p>
+With the unstarred version, the entries in the header row
+ are used to generate commands of the form
+ <tt>\insert</tt><em>identifier</em> (See <a href=#itm:insert>Note 1</a>)
+ to access corresponding elements
+ in the row currently being processed. For example,
+ suppose the first line of the CSV file looks like:
+<pre>
+Name,Address,Time,Date
+</pre>
+ then the commands <tt>\insertName</tt>, <tt>\insertAddress</tt>,
+ <tt>\insertTime</tt> and <tt>\insertDate</tt> are
+ created, allowing you to use the entries in the first,
+ second, third and fourth columns of the current row.
+ If the header text contains non-alphabetical characters,
+ e.g. <tt>Full Name</tt>, then you will need to use
+ <tt>\insertbyname{</tt><em>text</em><tt>}</tt>,
+ e.g. <tt>\insertbyname{Full Name}</tt>.
+
+<h3><a name=ex:mail>Example 1 (Mail Merging)</a></h3>
+ Suppose there is a file called <tt>details.csv</tt> that has the
+ following contents:
+<pre>
+Name,Address,Time,Date
+Miss A. Person,1 The Road\\The Town\\AB1 2XY,15.00,4th May 2004
+Mr A. N. Other,2 The Road\\The Town\\AB1 2XY,15.30,11th May 2004
+</pre>
+ then the following code can be used to generate a letter for each person
+ in the CSV file:
+<pre>
+\applyCSVfile{details.csv}{%
+\begin{letter}{\insertName\\\insertAddress}
+\opening{Dear \insertName}
+
+You are invited to an interview at \insertTime\ on the \insertDate.
+
+\closing{Yours Sincerely}
+\end{letter}}
+</pre>
+ Note that you could also use <tt>\insertbyname{Name}</tt> etc instead
+ of <tt>\insertName</tt> etc. Also note that you need to specify the
+ file extension when specifying the filename.
+
+<h3><a name=ex:ps>Example 2 (Multiple Figures)</a></h3>
+
+Suppose <tt>details.csv</tt> looks like:
+<pre>
+File,Caption
+circle.ps,A Circle
+rectangle.ps,A Rectangle
+triangle.ps,A Triangle
+</pre>
+
+ Assuming that the files <tt>circle.ps</tt>, <tt>rectangle.ps</tt>
+ and <tt>triangle.ps</tt> exist, then the following code will
+ generate a figure for each graphics file (the
+ <tt>graphicx</tt> package will be needed):
+<pre>
+\applyCSVfile{sample3.csv}{
+\begin{figure}
+\centerline{\includegraphics{\insertFile}}
+\caption{\insertCaption}
+\end{figure}}
+</pre>
+ Note that in this example, you can't use <tt>\insertbyname{File}</tt>.
+ (See <a href=#itm:psbyname>Note 3</a>)
+<p>
+<tt>\applyCSVfile*[</tt><em>n</em><tt>]{</tt><em>filename</em><tt>}{</tt><em>text</em><tt>}</tt>
+<p>
+In this case the CSV file has no header row, so
+ there are no <tt>\insert</tt><em>identifier</em> or <tt>\insertbyname{</tt><em>label</em><tt>}</tt> commands available,
+ instead, the command <tt>\field{</tt><em>col</em><tt>}</tt> should be used,
+ where <em>col</em> is the column number.
+
+<h3><a name=ex:field>Example 3 (Mail Merging using <tt>\field</tt>)</a></h3>
+
+ Suppose there is a file called <tt>details.csv</tt> that has the
+ following contents:
+<pre>
+Miss A. Person,1 The Road\\The Town\\AB1 2XY,15.00,4th May 2004
+Mr A. N. Other,2 The Road\\The Town\\AB1 2XY,15.30,11th May 2004
+</pre>
+ then the following code can be used to generate a letter for each person
+ in the CSV file:
+<pre>
+\applyCSVfile*{details.csv}{%
+\begin{letter}{\field{1}\\\field{2}}
+\opening{Dear \field{1}}
+
+You are invited to an interview at \field{3}\ on the \field{4}.
+
+\closing{Yours Sincerely}
+\end{letter}}
+</pre>
+
+<h2><a name=csv2tab>Converting CSV file into a tabular environment</a></h2>
+
+<tt>\CSVtotabular{</tt><em>filename</em><tt>}{</tt><em>col-align</em><tt>}{</tt><em>first</em><tt>}{</tt><em>middle</em><tt>}{</tt><em>last</em><tt>}</tt>
+<p>
+<em>filename</em> is the name of the CSV file which must have a header row on line 1,
+ <em>col-align</em> is the column alignment argument that gets passed
+ to the <tt>tabular</tt> environment, <em>first</em>
+ is the code for the first line, <em>middle</em> is the code
+ for the middle lines and <em>last</em> is the code for the last line.
+ This is best demonstrated with an example.
+
+<h3><a name=ex:tab1>Example 4 (Aligning Data from a CSV file)</a></h3>
+
+Suppose the file <tt>sample.csv</tt> looks like:
+<pre>
+Name,Assignment 1,Assignment 2,Total
+A. Smith,80,70,150
+B. Jones,60,80,140
+J. Doe,85,75,160
+,75,75,150
+</pre>
+ then the following code can be used to align the data:
+<pre>
+\CSVtotabular{sample.csv}{lccc}{%
+\bfseries Name &
+\bfseries Assignment 1&
+\bfseries Assignment 2&
+\bfseries Total\\}{%
+\insertName &
+\insertbyname{Assignment 1} &
+\insertbyname{Assignment 2} &
+\insertTotal\\}{%
+ &
+\insertbyname{Assignment 1} &
+\insertbyname{Assignment 2} &
+\insertTotal}
+</pre>
+ The result of this code is shown in
+ <a href=#tab:ex1>Table 1</a>. (Note that <tt>\CSVtotabular</tt> only
+ puts the data in a <tt>tabular</tt> environment not in a table).
+<p>
+<table>
+<a name=tab:ex1><caption align=top>Table 1 : Example 4</caption></a>
+<tr><th>Name</th>
+<th>Assignment 1</th>
+<th>Assignment 2</th>
+<th>Total</th></tr>
+<tr><td>A. Smith</td><td>80</td><td>70</td><td>150</td></tr>
+<tr><td>B. Jones</td><td>60</td><td>80</td><td>140</td><tr>
+<tr><td>J. Doe</td><td>85</td><td>75</td><td>160</td></tr>
+<tr><td> </td><td>75</td><td>75</td><td>150</td></tr>
+</table>
+<p>
+<tt>\ifnextrowlast{</tt><em>last-code</em><tt>}{</tt><em>not-last-code</em><tt>}</tt>
+<p>
+ The command <tt>\ifnextrowlast</tt> can be used to vary what happens
+ on the last but one row. The following example illustrates
+ this by placing <tt>\hline\hline</tt> after the penultimate row.
+
+<h3><a name=ex:tab2>Example 5 (Adding Lines)</a></h3>
+<pre>
+\CSVtotabular{sample.csv}{|l|ccc|}{%
+\hline\bfseries Name &
+\bfseries Assignment 1&
+\bfseries Assignment 2&
+\bfseries Total\\\hline\hline}{%
+\insertName &
+\insertbyname{Assignment 1} &
+\insertbyname{Assignment 2} &
+\insertTotal
+\ifnextrowlast{\\\hline\hline}{\\}}{%
+ &
+\insertbyname{Assignment 1} &
+\insertbyname{Assignment 2} &
+\insertTotal\\\hline}
+</pre>
+
+<h3><a name=ex:tab3>Example 6 (Added Complexity)</a></h3>
+
+ In this example, <tt>\multicolumn</tt> is used to override
+ the column specifier for the first column in the
+ last row.
+<pre>
+\CSVtotabular{sample2.csv}{|l|ccc|}{%
+\hline\bfseries Name &
+\bfseries Assignment 1 &
+\bfseries Assignment 2 &
+\bfseries Total\\\hline\hline
+}{%
+\insertName &
+\insertbyname{Assignment 1} &
+\insertbyname{Assignment 2} &
+\insertTotal
+\ifnextrowlast{\\\hline\multicolumn{1}{l|}{}}{\\}
+}{%
+ &
+\insertbyname{Assignment 1} &
+\insertbyname{Assignment 2} &
+\insertTotal\\\cline{2-4}
+}
+</pre>
+ Notice that instead of placing <tt>\multicolumn{1}{l|}{}</tt>
+ at the start of the final argument, it is instead
+ placed in the first argument to <tt>\ifnextrowlast</tt> (See
+ <a href=#itm:noalign>Note 4</a>).
+
+<h2><a name=longtable>Converting CSV file into longtable environment</a></h2>
+
+<tt>\CSVtolongtable{</tt><em>filename</em><tt>}{</tt><em>col-align</em><tt>}{</tt><em>first</em><tt>}{</tt><em>middle</em><tt>}{</tt><em>last</em><tt>}</tt>
+<p>
+The command <tt>\CSVtolongtable</tt> works in the same way as <tt>\CSVtotabular</tt> but
+ creates a <tt>longtable</tt> environment instead of a <tt>tabular</tt> environment.
+
+<h3><a name=ex:longtab>Example 7 (Using a longtable environment)</a></h3>
+<p>
+Suppose the CSV file in the previous example, contains, say, 100 entries.
+This will no longer fit onto one page, so it would be better to use
+<tt>\CSVtolongtable</tt> instead. For example:
+<pre>
+\CSVtolongtable{sample.csv}{|l|ccc|}{%
+\caption{Student Marks}\label{tab:students}\\
+\hline
+\bfseries Name &
+\bfseries Assignment 1 &
+\bfseries Assignment 2 &
+\bfseries Total\\\hline
+\endfirsthead
+\caption[]{Student Marks}\\
+\hline
+\bfseries Name &
+\bfseries Assignment 1 &
+\bfseries Assignment 2 &
+\bfseries Total\\\hline
+\endhead
+\hline
+\multicolumn{3}{r}{\em Continued on next page}
+\endfoot
+\hline
+\endlastfoot}{%
+\insertName &
+\insertbyname{Assignment 1} &
+\insertbyname{Assignment 2} &
+\insertTotal
+\ifnextrowlast{\\\hline\hline}{\\}}{%
+ & \insertbyname{Assignment 1} &
+ \insertbyname{Assignment 2} &
+\insertTotal\\}
+</pre>
+
+<h2><a name=counters>Associated Counters</a></h2>
+
+ Within the <tt>\CSVtotabular</tt>, <tt>\CSVtolongtable</tt> and <tt>\applyCSVfile</tt> commands, there are two
+ counters, <tt>csvlinenum</tt> and <tt>csvrownumber</tt>.
+ The former, <tt>csvlinenum</tt>, is the current line number in the CSV
+ file, whereas the latter, <tt>csvrownumber</tt>, is the current
+ data row. Of the two counters, <tt>csvrownumber</tt> is likely to be
+ the most useful.
+
+<h3><a name=ex:stripy>Example 8 (Stripy Table)</a></h3>
+
+ The package <tt>colortbl</tt> defines the command <tt>\rowcolor</tt>
+ which enables you to specify the row colour. Suppose
+ you want a stripy table this can be achieved as follows (this is designed as an example
+ of how to use the package, not incouragement to produce garish tables):
+
+<pre>
+\CSVtotabular{sample2.csv}{lccc}{%
+\rowcolor{green}\bfseries Name &
+\bfseries Assignment 1 &
+\bfseries Assignment 2 &
+\bfseries Total\\\rowcolor{blue}
+}{%
+\insertName &
+\insertbyname{Assignment 1} &
+\insertbyname{Assignment 2} &
+\insertTotal
+\ifthenelse{\isodd{\value{csvrownumber}}}{%
+\\\rowcolor{blue}}{\\\rowcolor{green}}
+}{%
+ &
+\insertbyname{Assignment 1} &
+\insertbyname{Assignment 2} &
+\insertTotal
+}
+</pre>
+
+<h3><a name=ex:mail2>Example 9 (More Mail Merging)</a></h3>
+
+ This is an example of mail merging where the letter reference
+ is generated from <tt>csvrownumber</tt>. The CSV file is
+ as used in the <a href=#ex:mail>earlier example</a>.
+<pre>
+\applyCSVfile{details.csv}{%
+\begin{letter}{\insertName\\\insertAddress}
+\opening{Dear \insertName}
+
+\textbf{Ref : } interview.\thecsvrownumber
+
+You are invited to an interview at \insertTime\ on the \insertDate.
+
+\closing{Yours Sincerely}
+\end{letter}}
+</pre>
+
+ <h2><a name=crossref>Cross-Referencing</a></h2>
+
+ Labels can be generated using the standard
+ <tt>\label</tt> command, but you will need some way
+ to make each label unique. <a href=#ex:ref1>Example 10</a>
+ does this by using <tt>\thecsvrownumber</tt>,
+ whereas <a href=#ex:ref2>Example 11</a> uses <tt>\insert</tt><em>identifier</em>.
+
+<h3><a name=ex:ref1>Example 10 (Labelling within <tt>\applyCSVfile</tt>)</a></h3>
+
+ <a href=#ex:ps>Example 2</a> can be modified to
+ label each figure:
+<pre>
+\applyCSVfile{sample3.csv}{
+\begin{figure}
+\centerline{\includegraphics{\insertFile}}
+\caption{\insertCaption}
+\label{fig:pic\thecsvrownumber}
+\end{figure}}
+</pre>
+ This example uses
+ <tt>\label{fig:pic\thecsvrownumber}</tt>, so the first figure generated
+ by this <tt>\applyCSVfile</tt> command will have the label <tt>fig:pic1</tt>,
+ the second <tt>fig:pic2</tt> etc.
+
+<h3><a name=ex:ref2>Example 11 (Labelling within <tt>\applyCSVfile</tt>)</a></h3>
+
+ Modifying the previous example, we now have:
+<pre>
+\applyCSVfile{sample3.csv}{
+\begin{figure}
+\centerline{\includegraphics{\insertFile}}
+\caption{\insertCaption}
+\label{fig:\insertFile}
+\end{figure}}
+</pre>
+ The labels for each figure are now:
+ <tt>fig:circle.ps</tt>, <tt>fig:rectangle.ps</tt>
+ and <tt>fig:triangle.ps</tt>, respectively.
+
+<h3><a name=ex:timetogrowth>Example 12 (Labelling within <tt>\CSVtotabular</tt>)</a></h3>
+
+ This example is slightly more complicated.
+ The CSV file, <tt>data.csv</tt> looks like:
+<pre>
+Incubation Temperature,Incubation Time,Time to Growth
+40,120,40
+40,90,60
+35,180,20
+</pre>
+The following code generates a table using the data
+ with an additional column that generates the experiment
+ number. (See <a href=#itm:csvrownumber>Note 9</a>.)
+<pre>
+\begin{table}
+\caption{Time to Growth Experiments}
+\label{tab:exp}
+\vspace{10pt}
+\centering
+\CSVtotabular{data.csv}{cccc}{%
+% Header Row
+\bfseries Experiment &
+\bfseries \begin{tabular}{c}Incubation\\Temperature\end{tabular} &
+\bfseries \begin{tabular}{c}Incubation\\Time\end{tabular} &
+\bfseries \begin{tabular}{c}Time\\to\\Growth\end{tabular}\\}{%
+% Middle Rows
+\label{exp:\insertbyname{Incubation Temperature}:\insertbyname{Incubation Time}}
+\thecsvrownumber &
+\insertbyname{Incubation Temperature} &
+\insertbyname{Incubation Time} &
+\insertbyname{Time to Growth} \\}{%
+% Final Row
+\label{exp:\insertbyname{Incubation Temperature}:\insertbyname{Incubation Time}}
+\thecsvrownumber &
+\insertbyname{Incubation Temperature} &
+\insertbyname{Incubation Time} &
+\insertbyname{Time to Growth}}
+\par
+\end{table}
+
+It can be seen from Table~\ref{tab:exp}, that
+Experiment~\ref{exp:35:180} had the shortest time to growth.
+</pre>
+
+ In this example, each experiment has the corresponding label
+ <tt>exp:</tt><em>Incubation Temperature</em><tt>:</tt><em>Incubation Time</em>
+ so the first experiment has label <tt>exp:40:120</tt>, the
+ second experiment has the label <tt>exp:40:90</tt> and the
+ third experiment has the label <tt>exp:35:180</tt>.
+
+ <a href=#tab:t2g>Table 2</a> shows the resulting table for
+ this example.
+<p>
+<table>
+<caption align=top><a name=tab:t2g>Time to Growth Experiments</a></caption>
+<tr><th align=center>Experiment </th>
+<th align=center>Incubation<br> Temperature </th>
+<th align=center>Incubation<br> Time </th>
+<th align=center>Time<br> to<br> Growth</th></tr>
+<tr><td align=center> 1 </td><td align=center> 40 </td><td align=center> 120 </td><td align=center> 40 </td></tr>
+<tr><td align=center> 2 </td><td align=center> 40 </td><td align=center> 90 </td><td align=center> 60 </td></tr>
+<tr><td align=center> 3 </td><td align=center> 35 </td><td align=center> 180 </td><td align=center> 20 </td></tr>
+</table>
+
+<p>
+ The following example is more refined in that it
+ takes advantage of the fact that the time to growth data consists
+ of integers only, so the experiment with the maximum growth can be
+ determined by LaTeX.
+
+<h3><a name=ex:t2g2>Example 13 (Labelling within <tt>\CSVtotabular</tt>)</a></h3>
+
+<pre>
+\newcounter{maxgrowth}
+\newcounter{incT} % incubation temperature
+\newcounter{inct} % incubation time
+
+\begin{table}
+\caption{Time to Growth Experiments}
+\label{tab:exp}
+\vspace{10pt}
+\centering
+\CSVtotabular{data.csv}{cccc}{%
+% Header row
+\bfseries Experiment &
+\bfseries \begin{tabular}{c}Incubation\\Temperature\end{tabular} &
+\bfseries \begin{tabular}{c}Incubation\\Time\end{tabular} &
+\bfseries \begin{tabular}{c}Time\\to\\Growth\end{tabular}\\}{%
+% Middle rows
+\label{exp:\insertbyname{Incubation Temperature}:\insertbyname{Incubation Time}}
+\thecsvrownumber &
+\insertbyname{Incubation Temperature} &
+\insertbyname{Incubation Time} &
+\insertbyname{Time to Growth}%
+\ifthenelse{\value{maxgrowth}<\insertbyname{Time to Growth}}{%
+\setcounter{maxgrowth}{\insertbyname{Time to Growth}}%
+\setcounter{incT}{\insertbyname{Incubation Temperature}}%
+\setcounter{inct}{\insertbyname{Incubation Time}}}{}%
+\\}{%
+% Last row
+\label{exp:\insertbyname{Incubation Temperature}:\insertbyname{Incubation Time}}
+\thecsvrownumber &
+\insertbyname{Incubation Temperature} &
+\insertbyname{Incubation Time} &
+\insertbyname{Time to Growth}%
+\ifthenelse{\value{maxgrowth}<\insertbyname{Time to Growth}}{%
+\setcounter{maxgrowth}{\insertbyname{Time to Growth}}%
+\setcounter{incT}{\insertbyname{Incubation Temperature}}%
+\setcounter{inct}{\insertbyname{Incubation Time}}}{}%
+}
+\par
+\end{table}
+
+As can be seen from Table~\ref{tab:exp},
+Experiment~\ref{exp:\theincT:\theinct}
+had the maximum time to growth, with
+incubation time \theinct,
+incubation temperature \theincT\ and
+time to growth, \themaxgrowth.
+</pre>
+
+<h2><a name=save>Saving Entries</a></h2>
+
+ Entries can be saved using the command:
+<p>
+ <tt>\csvSaveEntry[</tt><em>counter</em><tt>]{</tt><em>identifier</em><tt>}</tt>
+<p>
+ where <em>counter</em> is a LaTeX counter, by default <tt>csvrownumber</tt>,
+ and <em>identifier</em> is the header entry. The entry
+ can then be used with the command:<p>
+ <tt>\csvGetEntry{</tt><em>counter</em><tt>}{</tt><em>identifier</em><tt>}</tt><p>
+ The following example illustrates the use of these commands.
+
+<h3><a name=ex:index>Example 14 (Saving Entries)</a></h3>
+
+ This example illustrates how you can use one CSV
+ file to access data in other CSV files.
+ This example has several CSV files:
+<p>
+ File <tt>index.csv</tt>:
+<pre>
+File,Temperature,NaCl,pH
+exp25a.csv,25,4.7,0.5
+exp25b.csv,25,4.8,1.5
+exp30a.csv,30,5.12,4.5
+</pre>
+ File <tt>exp25a.csv</tt>:
+<pre>
+Time,Logcount
+0,3.75
+23,3.9
+45,4.0
+</pre>
+ File <tt>exp25b.csv</tt>:
+<pre>
+Time,Logcount
+0,3.6
+60,3.8
+120,4.0
+</pre>
+ File <tt>exp30a.csv</tt>:
+<pre>
+Time,Logcount
+0,3.73
+23,3.67
+60,4.9
+</pre>
+
+ It is not possible to nest <tt>\CSVtotabular</tt>, <tt>\CSVtolongtable</tt> and <tt>\applyCSVfile</tt>,
+ so if you need to go through <tt>index.csv</tt> and use each file
+ named in there, you can first go through <tt>index.csv</tt> storing
+ the information using <tt>\csvSaveEntry</tt> as follows:
+<pre>
+\newcounter{maxexperiments}
+\applyCSVfile{sample5.csv}{%
+\stepcounter{maxexperiments}
+\csvSaveEntry{File}
+\csvSaveEntry{Temperature}
+\csvSaveEntry{NaCl}
+\csvSaveEntry{pH}
+}
+</pre>
+ The counter <tt>maxexperiments</tt> simply counts the number of
+ entries in <tt>index.csv</tt>.
+ The entries can now be used to generate a table for each
+ file listed in <tt>index.csv</tt> (the <tt>\whiledo</tt> command is
+ defined in the <tt>ifthen</tt> package):
+<pre>
+\newcounter{experiment}
+
+\whiledo{\value{experiment}<\value{maxexperiments}}{%
+\stepcounter{experiment}
+\begin{table}
+\caption{Temperature = \protect\csvGetEntry{experiment}{Temperature},
+NaCl = \protect\csvGetEntry{experiment}{NaCl},
+pH = \protect\csvGetEntry{experiment}{pH}}
+\vspace{10pt}
+\centering
+\CSVtotabular{\csvGetEntry{experiment}{File}}{ll}{%
+Time & Log Count\\}{%
+\insertTime & \insertLogcount\\}{%
+\insertTime & \insertLogcount}
+
+\end{table}
+}
+</pre>
+ Note that <tt>\csvGetEntry</tt> needs to be <tt>\protect</tt>ed within
+ the <tt>\caption</tt> command.
+
+ This example can be modified if, say, you only want the
+ tables where the temperature is 25:
+<pre>
+\setcounter{experiment}{0}
+\whiledo{\value{experiment}<\value{maxexperiments}}{%
+\stepcounter{experiment}
+\ifthenelse{\equal{\csvGetEntry{experiment}{Temperature}}{25}}{%
+\begin{table}
+\caption{Temperature = \protect\csvGetEntry{experiment}{Temperature},
+NaCl = \protect\csvGetEntry{experiment}{NaCl},
+pH = \protect\csvGetEntry{experiment}{pH}}
+\vspace{10pt}
+\centering
+\CSVtotabular{\csvGetEntry{experiment}{File}}{ll}{%
+Time & Log Count\\}{%
+\insertTime & \insertLogcount\\}{%
+\insertTime & \insertLogcount}\par
+\end{table}}{}
+}
+</pre>
+
+<h2><a name=perl>The csvtools.pl Perl Script</a></h2>
+
+ Suppose you have several large CSV files, and you have included the information into
+ your document using <tt>\applyCSVfile</tt>, <tt>\CSVtolongtable</tt> or <tt>\CSVtotabular</tt>, which has made life so much easier for
+ you, but you are now required by a journal to submit your source code in a single <tt>.tex</tt> file.
+ They don't want all your CSV files, so what do you do? If you have Perl installed on your system
+ you can use the <tt>csvtools.pl</tt> Perl script. This has the following syntax:<p>
+ <tt>csvtools.pl</tt> <em>in-file</em> <em>out-file</em><p>
+ where <em>in-file</em> is the name of your file that contains the <tt>\applyCSVfile</tt>, <tt>\CSVtotabular</tt> etc
+ commands, and <em>out-file</em> is a new file which will be created by <tt>csvtools.pl</tt>. This new
+ file will be the same as <em>in-file</em> except that all occurances of <tt>\applyCSVfile</tt>, <tt>\CSVtolongtable</tt> and
+ <tt>\CSVtotabular</tt> will be replaced by the relevant data extracted from the named CSV files.
+
+<h3><a name=ex:perl>Example 15 (csvtools.pl - Aligning Data)</a></h3>
+
+ Suppose the file <tt>mydoc.tex</tt> contains the code given in <a href=#ex:tab1>Example 4</a>, with the associated
+ CSV file <tt>sample.csv</tt> also given in that example. Then if you do:
+<pre>
+csvtools.pl mydoc.tex mydocnew.tex
+</pre>
+the file <tt>mydocnew.tex</tt> will be created which will be identical to <tt>mydoc.tex</tt> except the lines
+ containing the code <tt>\CSVtotabular{sample.csv}{lccc}{</tt>...<tt>}{</tt>...<tt>}{</tt>...<tt>}</tt> will be replaced
+with the lines:
+<pre>
+ % \CSVtotabular{sample.csv}... converted using csvtools.pl
+ %>> START INSERT
+ \begin{tabular}{lccc}
+ \bfseries Name &
+ \bfseries Assignment 1 &
+ \bfseries Assignment 2 &
+ \bfseries Total\\
+ A. Smith&80&70&150\\
+ B. Jones&60&80&140\\
+ J. Doe&85&75&160\\
+ &75&75&150
+ \end{tabular}%<< END INSERT
+</pre>
+
+Similarly, <tt>csvtools.pl</tt> will substitute all occurrances of <tt>\CSVtolongtable</tt> and <tt>\applyCSVfile</tt>.
+
+<h3>Notes</h3>
+<ol>
+<li> The <tt>csvtools.pl</tt> file is bundled up with the code and documentation in the file
+ <tt>csvtools.dtx</tt>. It will be extracted along with the code when you LaTeX the
+ installation script <tt>csvtools.ins</tt>. If you are using UNIX or Linux etc, you will need
+ to set the permissions so that the file can be executed:
+<pre>
+chmod u+x csvtools.pl
+</pre>
+If perl is located in a directory other than <tt>/usr/bin/</tt> you will need to edit the
+first line of <tt>csvtools.pl</tt> as appropriate. You can find the location using the command:
+<pre>
+which perl
+</pre>
+
+<li>If you can't directly execute a Perl script,
+ you can do:<p>
+ <tt>perl csvtools.pl</tt> <em>in-file</em> <em>out-file</em>
+<p>
+<li> You must first LaTeX your document before using <tt>csvtools.pl</tt> as it checks the
+ log file for any counters that have been defined.
+<p>
+<li> <tt>csvtools.pl</tt> only knows about a very limited set of LaTeX commands. It should
+ be able to understand:
+<pre>
+\CSVtotabular{\csvGetEntry{experiment}{File}}{ll}{...
+</pre>
+(see <a href=#ex:index>Example 14</a>), but it won't be able to understand, say,
+<pre>
+\newcommand{\filename}{\csvGetEntry{experiment}{File}}
+\CSVtotabular{\filename}{ll}{...
+</pre>
+It can pick up on <tt>\addtocounter</tt>, <tt>\stepcounter</tt>, <tt>\refstepcounter</tt> and <tt>\setcounter</tt>
+ but only if they are used explicitly in the named <tt>.tex</tt> file. (It ignores any files
+ that have been included using <tt>\input</tt>, <tt>\include</tt> etc.)
+<p>
+<li> This Perl script has only been tested under Linux, but it ought to work under other
+ systems.
+</ol>
+
+<h2><a name=drawbacks>Bugs/Drawbacks/``Features''</a></h2>
+
+<ol>
+<li><a name=itm:insert></a>
+ The package doesn't check to see whether <tt>\insert</tt><em>identifier</em>
+ exists, otherwise you would not be able to use multiple CSV
+ files with the same headers, as in <a href=#ex:index>Example 14</a>. Therefore it is recommended that
+ you check to make sure that the command does not already exist.
+ For example, the TeX commands <tt>\insert</tt> and <tt>\insertpenalties</tt>
+ already exist, so a blank header or a header named <tt>penalties</tt>
+ would cause problems. (These two will now cause an error as from version 1.1, but it's something bear in mind.)
+<p>
+ <li> Note also that <tt>\insertbyname</tt> doesn't check
+ if you've given a valid label, so if no text appears,
+ check you've spelt it correctly, checking punctuation, spaces and case.
+<p>
+ <li><a name=itm:psbyname></a>
+ Note that in <a href=#ex:ps>Example 2</a>, replacing line 3 with:
+<pre>
+\centerline{\includegraphics{\insertbyname{File}}}
+</pre>
+ will cause an error, as <tt>\insertbyname{File}</tt> doesn't get
+ fully expanded by the time it gets passed to
+ <tt>\includegraphics</tt>, and will prevent <tt>\includegraphics</tt> from
+ finding the file. It is possible to get around this using
+ TeX's <tt>\edef</tt> command:
+<pre>
+\edef\psfilename{\insertbyname{File}}
+\centerline{\includegraphics{\psfilename}}
+</pre>
+
+ <li><a name=itm:noalign></a> You can't have commands like <tt>\hline</tt>, <tt>\cline</tt>
+ and <tt>\multicolumn</tt> in the first column of the
+ <em>middle</em> or <em>last</em> code of <tt>\CSVtotabular</tt> or <tt>\CSVtolongtable</tt>. If you do, it will generate
+ a <tt>misplaced \noalign</tt> error, instead you need to put it
+ at the end of the <em>first</em> or <em>middle</em> code.
+ (See <a href=#ex:tab3>Example 6</a>.)
+<p>
+ <li>You can't have nested <tt>\applyCSVfile</tt>, <tt>\CSVtolongtable</tt> and <tt>\CSVtotabular</tt>
+ commands. (See <a href=#ex:index>Example 14</a>)
+<p>
+ <li> If the CSV file has a header row, it must be on the first line.
+<p>
+ <li> It is possible for TeX to run out of memory if you use
+ <tt>\csvSaveEntry</tt> on a large file.
+<p>
+<li> Commas within an entry in a CSV file may cause problems. You will need to
+enclose the entry in braces, e.g. <code>{Joe Smith, Jr}</code>.
+<p>
+<li><a name=itm:csvrownumber</a> In version 1.0, there was an inconsistency
+with <tt>csvrownumber</tt> within <code>\applyCSVfile</code> and <code>\CSVtotabular</code>. In the former it excluded the header row, whereas the latter included it. This has been changed in version 1.1 so that with <code>\applyCSVfile</code>, <code>\CSVtotabular</code> and <code>\CSVtolongtable</code>, <tt>csvrownumber</tt> refers to the data row (excluding header row.) I hope this doesn't cause problems, but it makes more sense that they should be consistent. So if you have no blank lines in your CSV file, <tt>csvrownumber</tt> should always be 1 more than <tt>csvlinenumber</tt>.
+</ol>
+
+<hr>
+<h2>Contents</h2>
+<ul>
+<li><a href=#intro>Introduction</a>
+<li><a href=#mailmerge>Mail Merging and Similar Applications</a>
+<li><a href=#csv2tab>Converting CSV file into a tabular environment</a>
+<li><a href=#longtable>Converting CSV file into a longtable environment</a>
+<li><a href=#counters>Associated Counters</a>
+<li><a href=#crossref>Cross-Referencing</a>
+<li><a href=#save>Saving Entries</a>
+<li><a href=#perl>The csvtools.pl Perl Script</a>
+<li><a href=#drawbacks>Bugs/Drawbacks/``Features''</a>
+</ul>
+
+<h2>Examples</h2>
+<ul>
+<li><a href=#ex:mail>Example 1 (Mail Merging)</a>
+<li><a href=#ex:ps>Example 2 (Multiple Figures)</a>
+<li><a href=#ex:field>Example 3 (Mail Merging using <tt>\field</tt>)</a>
+<li><a href=#ex:tab1>Example 4 (Aligning Data from a CSV file)</a>
+<li><a href=#ex:tab2>Example 5 (Adding Lines)</a>
+<li><a href=#ex:tab3>Example 6 (Added Complexity)</a>
+<li><a href=#ex:longtab>Example 7</a>
+<li><a href=#ex:stripy>Example 8 (Stripy Table)</a>
+<li><a href=#ex:mail2>Example 9 (More Mail Merging)</a>
+<li><a href=#ex:ref1>Example 10 (Labelling within <tt>\applyCSVfile</tt>)</a>
+<li><a href=#ex:ref2>Example 11 (Labelling within <tt>\applyCSVfile</tt>)</a>
+<li><a href=#ex:timetogrowth>Example 12 (Labelling within <tt>\CSVtotabular</tt>)</a>
+<li><a href=#ex:t2g2>Example 13 (Labelling within <tt>\CSVtotabular</tt>)</a>
+<li><a href=#ex:index>Example 14 (Saving Entries)</a>
+<li><a href=#ex:perl>Example 15 (csvtools.pl - Aligning Data)</a>
+</ul>
+<hr>
+
+<a href=http://theoval.cmp.uea.ac.uk/~nlct>Dr Nicola Talbot</a> |
+<a href=http://www.cmp.uea.ac.uk/>School of Computing Sciences</a> |
+<a href=http://www.uea.ac.uk/>University of East Anglia</a>
+
+<h5>N.L.C. Talbot. School of Computing Sciences. University of East Anglia. Last Modified: 19 Oct 2004.</h5>
+</html>