<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE manual SYSTEM "datatooltk.dtd">
<manual fontenc="T1">
  <preamble>
    <!-- Document Info -->
    <title>User Manual for <dict tag="appname"/> version 
      <dict tag="appversion" /></title>
    <author>Nicola L. C. Talbot<br/><url www="www.dickimaw-books.com" /></author>
<!--
    <author>Another Author<br />Affliation or URL</author>
    <author>Translated by Some One<br />Affliation or URL</author>
-->
    <date><dict tag="appdate" /></date>
    <!-- Define Acronyms -->
    <newacro short="GUI" long="graphical user interface" tag="gui" />
    <newacro short="CSV" long="comma-separated values" tag="csv" />
    <newacro short="SQL" long="structured query language" tag="sql"/>
    <!-- Define Terms. If a description is included it's a glossary
         term otherwise it goes in the index -->
    <newterm tag="mysql" text="MySQL" description="An open source SQL database" />
    <newterm tag="database" text="database" />
    <newterm tag="cwd" text="current working directory" 
      description="The directory in which the application was started"/>
  </preamble>
  <document>
   <node tag="introduction" type="chapter" title="Introduction">
     <p>
     The <LaTeX /> <sty>datatool</sty> package is able to save databases 
     in its own internal format to allow for rapid loading (using
     <cs tag="DTLsaverawdb"/> or <cs tag="DTLprotectedsaverawdb"/>).
     Files in this format are difficult to 
     edit and only a<nbsp /><TeX />pert should attempt it, but they are 
     by far the fastest way of loading a <sty>datatool</sty> 
     <term tag="database" /> in <LaTeX />. This application provides 
     a<nbsp /><acr tag="gui" /> making it easier to edit these files. 
     It can also import data from <acr tag="csv" /> files, from
     Excel <tt>.xls</tt> or Open Document <tt>.ods</tt> spreadsheets, from 
     <acr tag="sql" /> databases and from <sty>probsoln</sty> databases.
     This manual assumes the user has some knowledge of the
     <sty>datatool</sty> package. Please ensure you have at least version
     2.15 of <sty>datatool</sty> installed in your <TeX/> distribution.
     </p>
     <p>The <app/> 
     application can run in either 
     batch mode (default) or <acr tag="gui" /> mode (see <ref tag="gui" />).
     Command line invocation:
     </p>
     <p align="center">
      <app/> [<meta>options</meta>]
     </p>
     <p noindent="true">
     Available options:
     <dl>
       <dt><opt tag="gui"/> (or <tt>-g</tt>)</dt>
       <dd>
       Invoke <app/> in <acr tag="gui" /> mode. The command line invocation
       <p align="center">
       <app/><tt>-gui</tt> [<meta>options</meta>] 
       </p>
       <p noindent="true">
       is equivalent to
       </p>
       <p align="center">
       <app/> <opt tag="gui"/> [<meta>options</meta>] 
       </p>
       <p noindent="true">
       but additionally has a<nbsp/>splash screen.
       </p>
       </dd>
       <dt><opt tag="batch"/> (or <tt>-b</tt>)</dt>
       <dd>
       Invoke <app/> in batch mode (default).
       </dd>
       <dt><opt tag="output"/> <meta>filename</meta>
         (or <tt>-o</tt> <meta>filename</meta>)</dt>
       <dd>
       Save the database to <meta>filename</meta> (batch mode only).
       </dd>
       <dt><opt tag="in"/> (or <tt>-i</tt>) <meta>datatool file</meta></dt>
       <dd>Load <meta>datatool file</meta>. The switch <opt tag="in"/>
       (or <tt>-i</tt>) is optional, so <app/><nbsp/><meta>file</meta>
       is equivalent to <app/><nbsp/><opt tag="in"/> <meta>file</meta>.</dd>
       <dt><opt tag="name"/> <meta>name</meta></dt>
       <dd>If used with <opt tag="in"/>, <opt tag="csv"/>, <opt tag="sql"/>, <opt tag="xls"/>, <opt tag="ods"/>
       or <opt tag="probsoln"/>, sets the database label to 
       <meta>name</meta>. (See <ref tag="fileext"/>.)</dd>
       <dt><opt tag="version"/> (or <tt>-v</tt>)</dt>
       <dd>Print the version details to STDOUT and exit.</dd>
       <dt><opt tag="help"/> (or <tt>-h</tt>)</dt>
       <dd>Print a brief summary of available options to STDOUT and exit.</dd>
       <dt><opt tag="debug"/></dt>
       <dd>Enable debug mode.</dd>
       <dt><opt tag="nodebug"/></dt>
       <dd>Disable debug mode. (Default.)</dd>
       <dt><opt tag="delete-tmp-files"/></dt>
       <dd>Delete temporary files on exit. (Default.)</dd>
       <dt><opt tag="nodelete-tmp-files"/></dt>
       <dd>Don't delete temporary files on exit.</dd>
       <dt><opt tag="owner-only"/></dt>
       <dd>Set read/write permissions when saving .dbtex files to owner only.
       (Has no effect on some operating systems.)</dd>
       <dt><opt tag="noowner-only"/></dt>
       <dd>Don't change read/write permissions when saving .dbtex files.</dd>
       <dt><opt tag="map-tex-specials"/></dt>
       <dd>Map <TeX/> special characters when importing data from 
       <acr tag="csv"/> or <acr tag="sql"/>.</dd>
       <dt><opt tag="nomap-tex-specials"/></dt>
       <dd>Don't map <TeX/> special characters when importing data from
       <acr tag="csv"/> or <acr tag="sql"/>. (Default.)</dd>
       <dt><opt tag="seed"/> <meta>number</meta></dt>
       <dd>Set the random generator seed to <meta>number</meta> or clear it
       if <meta>number</meta> is <tt>""</tt>. (See <ref tag="shuffle"/>.)</dd>
       <dt><opt tag="shuffle-iterations"/> <meta>number</meta></dt>
       <dd>Set the number of iterations to perform in a<nbsp/>shuffle to 
       <meta>number</meta>. (See <ref tag="shuffle"/>.)</dd>
       <dt><opt tag="shuffle"/></dt>
       <dd>Shuffle the database. (Shuffle is always performed after sort,
       regardless of the option order.)</dd>
       <dt><opt tag="noshuffle"/></dt>
       <dd>Don't shuffle the database. (Default.)</dd>
       <dt><opt tag="sort"/> [<meta>prefix</meta>]<meta>field</meta></dt>
       <dd>Sort the database according to the column whose label is
       <meta>field</meta>. Optionally, <meta>prefix</meta> may be
       <tt>+</tt> (ascending order) or <tt>-</tt> (descending order).
       If <meta>prefix</meta> is omitted, ascending is assumed.
       (See <ref tag="sort"/>.)</dd>
       <dt><opt tag="sort-case-sensitive"/></dt>
       <dd>Use case-sensitive comparison when sorting strings.</dd>
       <dt><opt tag="sort-case-insensitive"/></dt>
       <dd>Use case-insensitive comparison when sorting strings. (Default.)</dd>
       <dt><opt tag="truncate"/> <meta>n</meta></dt>
       <dd>Truncate the database to the first <meta>n</meta> rows.
       (Has no effect if <meta>n</meta> is greater than or equal
       to the total number of rows.) Truncation is always performed
       last. (After any sorting, shuffling and filtering.)</dd>
       <dt><opt tag="filter"/> <meta>key</meta> <meta>operator</meta> <meta>value</meta></dt>
       <dd>Adds the filter. This filter returns true if the value in
       the column whose label is given by <meta>key</meta>
       matches the operation <meta>operator</meta> <meta>value</meta>
       where <meta>operator</meta> may be one of:
       <tt>eq</tt> (equals <meta>value</meta>),
       <tt>ne</tt> (does not equal <meta>value</meta>),
       <tt>le</tt> (less than or equal to <meta>value</meta>),
       <tt>lt</tt> (less than <meta>value</meta>),
       <tt>ge</tt> (greater than or equal to <meta>value</meta>),
       <tt>gt</tt> (greater than <meta>value</meta>),
       <tt>regex</tt> (matches the regular expression <meta>value</meta>). Multiple filters may be used. The regular expression
       should be in the format used by <url www="http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html" text="java.util.regex.Pattern"/>.
       Filtering is always performed after sorting and shuffling.
       Numerical comparisons are used for columns that are identified 
       as either integer or real data types otherwise string
       comparisons are used, except in the case of 
       <tt>regex</tt> where the data type is disregarded
       and all values are assumed to be strings. (If the column type
       is identified as having an integer or real data type but
       <meta>value</meta> is not a number, a string comparison will be used.)
       For example: <opt tag="filter"/> <tt>Level eq 3</tt>
       means that the filter should return true if the value in the column
       whose label is <tt>Level</tt> is equal to 3.
       If there isn't a<nbsp/>column with the label <meta>key</meta>, 
       a<nbsp/>warning is printed on the standard error stream and the
       filter is ignored.
       </dd>
       <dt><opt tag="filter-or"/></dt>
       <dd>Use OR operator when filtering. (Default.)
       This has no effect if you only supply one filter.</dd>
       <dt><opt tag="filter-and"/></dt>
       <dd>Use AND operator when filtering. 
       This has no effect if you only supply one filter.</dd>
       <dt><opt tag="filter-include"/></dt>
       <dd>When filtering, discard rows that don't match the filter (and keep those that do match). This is the default action.</dd>
       <dt><opt tag="filter-exclude"/></dt>
       <dd>When filtering, discard rows that match the filter (and keep those that don't match).</dd>
       <dt><opt tag="merge"/> <meta>key</meta> <meta>db file</meta></dt>
       <dd>Merges the input or imported database with the database stored
       in the given <meta>db file</meta>. Each row
       in <meta>db file</meta> is merged with the row that has a matching
       value in the column whose label is given by <meta>key</meta>.
       Both databases must contain a column with that label. (Each entry
       in that column should ideally be unique.)
       If no matching row is found, a new row is added. If both databases
       share additional columns, the values in <meta>db file</meta>
       override those in the original database. If <meta>db file</meta>
       doesn't exist, a warning is issued and the option is ignored.
       This option is always implemented before any sorting, shuffling,
       filtering or truncating. Only one of the merge options is permitted.
       </dd>
       <dt><opt tag="csv" /> <meta>csv file</meta></dt>
       <dd>Import data from the given <acr tag="csv"/> file.
       (See <ref tag="importcsv"/>.)</dd>
       <dt><opt tag="merge-csv"/> <meta>key</meta> <meta>csv file</meta></dt>
       <dd>As <opt tag="merge"/> but the data to be merged is imported from the given <acr tag="csv"/> file.
       </dd>
       <dt><opt tag="sep" /> <meta>character</meta></dt>
       <dd>Specify the character used to separate values in the 
       <acr tag="csv" /> file. (Defaults to a<nbsp />comma.)</dd>
       <dt><opt tag="delim" /> <meta>character</meta></dt>
       <dd>Specify the character used to delimit values in the 
       <acr tag="csv" /> file. (Defaults to a<nbsp />double quote.)</dd>
       <dt><opt tag="csvheader" /></dt>
       <dd>The <acr tag="csv"/> file has a header row. (Default.)</dd>
       <dt><opt tag="nocsvheader" /></dt>
       <dd>The <acr tag="csv"/> file doesn't have a header row.</dd>
       <dt><opt tag="xls"/> <meta>xls file</meta></dt>
       <dd>Import data from the given Excel <tt>.xls</tt> file. 
       (See <ref tag="importspread"/>.)</dd>
       <dt><opt tag="merge-xls"/> <meta>key</meta> <meta>xls file</meta></dt>
       <dd>As <opt tag="merge"/> but the data to be merged is imported from the given Excel <tt>.xls</tt> file.
       </dd>
       <dt><opt tag="ods"/> <meta>ods file</meta></dt>
       <dd>Import data from the given Open Document Spreadsheet <tt>.ods</tt> file. 
       (See <ref tag="importspread"/>.)</dd>
       <dt><opt tag="merge-ods"/> <meta>key</meta> <meta>ods file</meta></dt>
       <dd>As <opt tag="merge"/> but the data to be merged is imported from the given Open Document Spreadsheet <tt>.ods</tt> file.
       </dd>
       <dt><opt tag="sheet"/></dt>
       <dd>The sheet to select from the Excel workbook or Open Document 
       Spreadsheet. This may either be an index (starting from 0) or 
       the name of the sheet. If omitted, the first sheet is assumed.</dd>
       <dt><opt tag="sql"/> <meta>statement</meta></dt>
       <dd>Import data from an <acr tag="sql"/> database where 
       <meta>statement</meta> is an <acr tag="sql"/> SELECT statement.
       (See <ref tag="importsql"/>)</dd>
       <dt><opt tag="merge-sql"/> <meta>key</meta> <meta>statement</meta></dt>
       <dd>As <opt tag="merge"/> but the data to be merged is imported using the given <acr tag="sql"/> SELECT statement.
       </dd>
       <dt><opt tag="sqldb"/> <meta>name</meta></dt>
       <dd>The <acr tag="sql"/> database name.</dd>
       <dt><opt tag="sqlprefix"/> <meta>prefix</meta></dt>
       <dd>The Java <acr tag="sql"/> prefix. (Default: <dq><tt>jdbc:mysql://</tt></dq>.) Currently, only <term tag="mysql"/> is supported. Additional libraries will be required for other <acr tag="sql"/> databases.</dd>
       <dt><opt tag="sqlport"/> <meta>port</meta></dt>
       <dd>The <acr tag="sql"/> port number. (Default: 3306.)</dd>
       <dt><opt tag="sqlhost"/> <meta>host</meta></dt>
       <dd>The <acr tag="sql"/> host. (Default: <dq><tt>localhost</tt></dq>.)</dd>
       <dt><opt tag="sqluser"/> <meta>user name</meta></dt>
       <dd>The <acr tag="sql"/> user name.</dd>
       <dt><opt tag="sqlpassword"/> <meta>password</meta></dt>
       <dd>The <acr tag="sql"/> password (insecure). If omitted, you will be prompted 
       for<nbsp />a password if you try to import data from an <acr tag="sql"/> 
       database.</dd>
       <dt><opt tag="wipepassword"/></dt>
       <dd>For extra security, wipe the password from memory as soon as it 
       has been used to connect to an <acr tag="sql"/> database. (Default.)</dd>
       <dt><opt tag="nowipepassword"/></dt>
       <dd>Don't wipe the password from memory as soon as it 
       has been used to connect to an <acr tag="sql"/> database.</dd>
       <dt><opt tag="noconsole-action" /> <meta>action</meta></dt>
       <dd>If in batch mode and a SQL password is required
       and <opt tag="sqlpassword"/> hasn't been used, the
       default action is for <app/> to request a password
       via the console. If there is no console available
       the action is determined by <meta>action</meta>
       which may be one of:
       <ul>
        <li><tt>error</tt> <emdash/> issue an error;</li>
        <li><tt>stdin</tt> <emdash/> request the password via the standard
        input stream (less secure than using a console, and can produce 
        an annoying flicker);</li>
        <li><tt>gui</tt> <emdash/> display a dialog box in which to enter the password (default).</li>
       </ul>
       </dd>
       <dt><opt tag="probsoln"/> <meta>filename</meta></dt>
       <dd>Import <sty>probsoln</sty> data from <meta>filename</meta>.
       (See <ref tag="importprobsoln"/>.)</dd>
       <dt><opt tag="merge-probsoln"/> <meta>key</meta> <meta>filename</meta></dt>
       <dd>As <opt tag="merge"/> but the data to be merged is imported from the given <sty>probsoln</sty> data set file.
       </dd>
     </dl>
     You can't combine any of the load/import options: <opt tag="in"/>, 
     <opt tag="csv"/>, <opt tag="xls"/>, <opt tag="ods"/>, <opt tag="sql"/>, <opt tag="probsoln"/>. You also can't combine any of the merge options:
     <opt tag="merge"/>, 
     <opt tag="merge-csv"/>, 
     <opt tag="merge-xls"/>, 
     <opt tag="merge-ods"/>, 
     <opt tag="merge-sql"/>, 
     <opt tag="merge-probsoln"/>. 
     The merge import options use the same settings as the import options. If you want to merge, for example, sheet<nbsp/>1 and sheet<nbsp/>2
    from the same spreadsheet, you will have to first import one or both of them to a <tt>.dbtex</tt> file and then perform the merge. 
     With the exception of <opt tag="merge-sql"/>, all the merge options will ignore a missing file and just print a warning to STDERR.
     </p>
   </node>
   <node tag="notaspreadsheet" type="section" title="What it isn't">
   <p>
   The <app/> application isn't intended to have the full functionality of
   a<nbsp/>spreadsheet. Its purpose is to allow you to edit 
   <sty>datatool</sty> databases with multilined entries. If your data 
   just consists of numbers or short single-lined text, then you'll probably 
   be better off just using a<nbsp/>spreadsheet to input the data and 
   use <app/> in batch mode to convert from <acr tag="csv"/> to 
   a<nbsp/><sty>datatool</sty> file.
   </p>
   </node>
   <node tag="fileext" type="section" title="File Extensions">
   <p>
   The <sty>datatool</sty> database files loaded and saved by <app/>
   are just <LaTeX/> files, so they could simply have the standard
   <tt>.tex</tt> extension, but to help differentiate the database files
   from other files containing <TeX/>/<LaTeX/> code (such as picture-drawing
   code), <app/> assumes a<nbsp/>default extension of <tt>.dbtex</tt>.
   If you use this extension, remember to include it in the argument of
   <cs tag="input"/> or <cs tag="DTLloaddbtex"/>. Note that the database label 
   (as used in commands like <cs tag="DTLnewdb"/>) is independent of the file 
   name (although when importing data, it defaults to the file base name). 
   The database label can be changed using <menu tag="edit.edit_dbname"/> in 
   <acr tag="gui"/> mode or via the command line option 
   <opt tag="name"/> <meta>label</meta>.
   </p>
     <float type="figure" tag="setnamedialog" 
      caption="Setting the Database Name" pos="htb">
      <image scale="0.75" alt="Image of dialog box"
         src="images/setnamedialog.png" />
     </float>
   <example>
   <p>
   Suppose you have a<nbsp/>database file called <tt>my-data.dbtex</tt>
   and you have set the database label to just <dq><tt>data</tt></dq>
   (as shown in <ref tag="setnamedialog"/>).
   Then you can load and display the data using:
   </p>
   <pre>
\documentclass{article}
\usepackage{datatool}% remember to load the datatool package

\input{my-data.dbtex}% load the database from file `my-data.dbtex'

\begin{document}

\DTLdisplaydb{data}% Display the database identified by the name `data'

\end{document}
   </pre>
   <p>
   If you can't remember the name you assigned to the database, you can 
   access it using <cs tag="dtllastloadeddb"/>.
   </p>
   <pre>
\documentclass{article}
\usepackage{datatool}% remember to load the datatool package

\input{my-data.dbtex}% load the database from file `my-data.dbtex'

\begin{document}

\DTLdisplaydb{\dtllastloadeddb}% Display the last loaded database

\end{document}
   </pre>
   <p>
   Alternatively, as from <sty>datatool</sty> version 2.20, use 
   <cs tag="DTLloaddbtex"/> instead of <cs tag="input"/>.
   </p>
   <pre>
\documentclass{article}
\usepackage{datatool}% remember to load the datatool package

\DTLloaddbtex{\mydata}{my-data.dbtex}% load the database from file `my-data.dbtex'

\begin{document}

\DTLdisplaydb{\mydata}% Display the database

\end{document}
   </pre>
   </example>
   </node>
   <node tag="verbatim" type="section" title="Verbatim">
   <p>
   Since the contents of the database are stored in a<nbsp/><TeX/> token
   register, and assigned to control sequences via commands like
   <cs tag="DTLforeach"/>, verbatim text is not permitted. This is 
   a<nbsp/>common problem when attempting to use verbatim text within
   a<nbsp/>command and is covered in the UK List of <TeX/> Frequently
   Asked Questions (<url www="http://www.tex.ac.uk/cgi-bin/texfaq2html?label=verbwithin" text="Why doesn't verbatim work within...?"/>).
   The <app/> application checks for verbatim text<footnote>More
   specifically, it checks for any occurrences of <cs tag="verb"/>, 
   <cs tag="lstinline"/> or the beginning of the <env tag="verbatim"/>,
   <env tag="lstlisting"/> or <env tag="alltt"/> environments.</footnote> when you load a<nbsp/>database or import
   data (unless the <dq>map <TeX/> special characters</dq> property is set for
   <acr tag="csv"/> or <acr tag="sql"/> imports). Also, <app/> checks for
   verbatim text when you edit the contents of a<nbsp/>cell. If it
   detects any, it will give a<nbsp/>warning. If you ignore the warning, 
   <TeX/> will give an error if you then attempt to load the database into
   a<nbsp/>document.
   </p>
   <p>
   If you just have a<nbsp/>short fragment of inline verbatim text, consider
   one of the alternatives listed in <url www="http://www.tex.ac.uk/cgi-bin/texfaq2html?label=verbwithin" text="the FAQ"/>.
   If on the other hand you have a<nbsp/>block of verbatim text you'll have 
   to put the verbatim text in a<nbsp/>separate file
   and load it using <cs tag="verbatiminput"/> (from the 
   <sty>verbatim</sty> package) or <cs tag="lstinputlisting"/> (from the
   <sty>listings</sty> package). For example, in <ref tag="ex.verb"/> 
   I<nbsp/>have used <cs tag="lstinputlisting"/>.
   </p>
     <float type="figure" tag="ex.verb" caption="Verbatim Blocks Need to be in Separate Files" pos="htb">
      <image scale="0.75" alt="Image of main window showing cells with listing input" src="images/verb.png" />
     </float>
   <p>
   That database requires two files: <tt>HelloWorld.java</tt>
   </p>
   <verbinput src="../tests/HelloWorld.java"/>
   <p noindent="true">
   and <tt>HelloUser.java</tt>:
   </p>
   <verbinput src="../tests/HelloUser.java"/>
   <p>
   Assuming that I've saved my database in a<nbsp/>file called
   <tt>prob-verb.dbtex</tt> with database label <dq><tt>problems</tt></dq>,
   here's a<nbsp/>sample document:
   </p>
   <verbinput src="../tests/test-probsoln-doc.tex"/>
   <seealso tags="shuffle,sortshuffle,importprobsoln"/>
   </node>
   <node tag="null" type="section" title="Null Values">
   <p>
   Empty entries aren't the same as null entries. If you want 
   a<nbsp/>null entry, set the entry to <cs tag="@dtlnovalue"/>. 
   A<nbsp/>convenient way to do this is to select the cell and use
   <menu tag="edit.cell_to_null"/>. Alternatively, you can set all entries in 
   a<nbsp/>selected column to null with <menu tag="edit.column.column_to_null"/>
   and similiarly for a<nbsp/>selected row with <menu tag="edit.row.row_to_null"/>.
   </p>
   <p>
   In your <LaTeX/> document, you can check for null values using 
   <sty>datatool</sty>'s <cs tag="DTLifnull"/> command. To check for empty 
   values you can use one of <sty>etoolbox</sty>'s commands, such as 
   <cs tag="ifdefempty"/>.
   </p>
   </node>
   <node tag="gui" type="chapter" title="Graphical Mode">
     <p>
       To run <app/> in graphical mode you must invoke it with either 
       <app/><tt>-gui</tt> or <app/><nbsp/><opt tag="gui"/>. The main window
       is shown in <ref tag="mainwindow"/>. Each database is
       in a<nbsp/>tabbed pane, with the name of the database in the
       tab. Note that the name corresponds to the database's identifying
       label, as used in commands like <cs tag="DTLnewdb"/>. This is 
       not necessarily the same as the filename (see <ref tag="fileext"/>). 
       Since this name is used as a label, it shouldn't contain any of 
       <TeX/>'s special characters or any other active characters that could 
       cause problems.  An asterisk <tt>*</tt> following the label in the tab 
       indicates that the database has been modified. If you move the mouse
       over the tab, you will see the filename appear in a<nbsp/>tooltip,
       if the database has been saved to a<nbsp/><sty>datatool</sty> file.
     </p>
     <float type="figure" tag="mainwindow" caption="Main Window" pos="htb">
      <image scale="0.75" alt="Image of main window" src="images/mainwindow.png" />
     </float>
     <p>
      You can use the <menu tag="file" /> menu to create a<nbsp />new 
      database, load an existing database or import data (see 
      <ref tag="import"/>). To load an existing database, use
      <menu tag="file.open" />. These database files contain <LaTeX/> code
      in a<nbsp/>specific format. The <app/> application assumes 
      a<nbsp/><tt>.dbtex</tt> file extension (see <ref tag="fileext"/>).
      You can load these files into a<nbsp/><LaTeX/> document using 
      <cs tag="input"/> or <cs tag="DTLloaddbtex"/>, but remember to specify 
      the <tt>.dbtex</tt> extension. (Also remember to load the 
      <sty>datatool</sty> package.)
     </p>
     <p>
     Each column has a corresponding data type: string, integer, real
     or currency. The type is automatically detected from the column data,
     but can be changed, as described in <ref tag="editheader"/>.
     </p>
     <p>
     Non-string entries can be edited by double-clicking on the relevant cell, 
     or you can select the relevant cell and use <menu tag="edit.edit_cell"/>.
     In the first case, a cursor will appear in the cell and you 
     can edit the numerical value and press <dq>Enter</dq> to finish 
     editing. In the second case, the cell editor dialog box will 
     open, see <ref tag="celleditor"/>.
     </p>
     <p>
     <b>Only the first few lines of a string entry are visible in the main 
     window. If an entry has more than that number of lines, you will need to 
     use the cell editor dialog box to view the entire contents of that 
     cell.</b> The default row height can be changed in the
     <dict tag="preferences.title"/> dialog box (see <ref tag="preferences"/>).
     Columns set to integer or real data types have single-lined cells with no
     line wrap. Columns set to currency data type may wrap, but using 
     <dq>Enter</dq> will finish editing the cell (unless you're using the cell
     editor dialog box). If you insert a<nbsp/>newline character in the cell
     edit dialog box (for any data type), the type for that column will 
     be converted to <dq>string</dq>.
     </p>
     <p>
     To edit or view an entry in a column
     with the <dq>string</dq> data type, double-click on the relevant cell or 
     select the cell and use <menu tag="edit.edit_cell"/> to open the cell editor 
     dialog box (see <ref tag="celleditor" />). You can now scroll through
     the cell contents.
     </p>
   </node>
   <node tag="celleditor" type="section" title="Cell Editor">
   <p>
   To open the cell editor dialog box (see <ref tag="fig.celleditor" />)
   double-click on the required cell, which must be in a column with a 
   string data type. Alternatively, select the cell (of any type) and use 
   <menu tag="edit.edit_cell"/>.
   </p>
   <float type="figure" tag="fig.celleditor" caption="Cell Editor Dialog" pos="htbp">
     <image scale="0.75" alt="Image of cell editor dialog" src="images/celleditor.png" />
   </float>
   <p>
   Remember that the contents of the cell should be <LaTeX/> code, so be
   careful if you use any of <TeX/>'s special characters. Also, see the
   section on verbatim text (<ref tag="verbatim"/>) if you haven't 
   already read it.
   Once you have made your edits, click on <button tag="button.okay" />
   to update the database. To discard the edits, click 
   <button tag="button.cancel" />.
   </p>
   <p>
   If you've used <sty>datatool</sty>, you will probably know that 
   if you want a paragraph break in your cell entries you need to use 
   <cs tag="DTLpar"/>, but with <app/> you don't need to worry about it 
   as blank lines in an entry will automatically be converted behind 
   the scenes. Note that redundant blank lines will be removed.
   </p>
   <p>
   <b>Important:</b> if you use <sty>datatool</sty>'s <cs tag="DTLsaverawdb"/> 
   or <cs tag="DTLprotectedsaverawdb"/> commands to overwrite your file, you 
   will lose any pretty-printing spaces or comments in your code.
   </p>
   </node>
   <node tag="editheader" type="section" title="Header Dialog">
     <p>
     Each column has a<nbsp/>title, a<nbsp/>uniquely identifying label
     and an associated type. The type can be one of:
     <button tag="header.type.string"/>, 
     <button tag="header.type.int"/>, 
     <button tag="header.type.real"/> or 
     <button tag="header.type.currency"/>.
     The type is automatically detected from the column data,
     but can be changed using the <menu tag="edit.column.edit_header"/>
     menu item or by double-clicking on the column header which opens the 
     header dialog box (see <ref tag="headerdialog"/>). The label corresponds 
     to the label used to identify the column in commands such
     as <cs tag="DTLforeach"/>. The title is used in commands like
     <cs tag="DTLdisplaydb"/>. See <ref tag="preferences"/> for 
     currency mappings.
     </p>
     <float type="figure" tag="headerdialog" caption="Header Dialog" pos="htbp">
      <image scale="0.75" alt="Image of header dialog box" src="images/headerdialog.png" />
     </float>
     <p>
     In <acr tag="gui"/> mode, column headers show the
     title. If you move the mouse over the column header, you will see the
     label and type displayed in a<nbsp/>tooltip (see 
     <ref tag="headerdetails"/>).
     </p>
     <float type="figure" tag="headerdetails" caption="Header Details Shown in Tooltip" pos="htbp">
      <image scale="0.75" alt="Image of main window showing header tooltip"
         src="images/headerdetails.png" />
     </float>
   </node>
   <node tag="tools" type="chapter" title="Tools">
   <p>
   There are currently two tools available: sort (see <ref tag="sort"/>)
   and shuffle (see <ref tag="shuffle"/>). These both reorder the rows of the
   database and can be invoked either from the <menu tag="tools"/> menu
   or from the command line (as long as
   you have also loaded a<nbsp/>database using <opt tag="in"/> or one of the
   import options). If you use both <opt tag="sort"/> and <opt tag="shuffle"/>
   in the command line invocation, sort will always be performed first, 
   regardless of the option order.
   </p>
   </node>
   <node tag="sort" type="section" title="Sorting the Data">
   <p>
   Although you can sort data in <sty>datatool</sty> using <cs tag="DTLsort"/>, 
   it's far more efficient to sort it in <app/>.<footnote>If the original 
   data is in an <acr tag="sql"/> database, it's even more efficient to 
   do the sorting in the SELECT statement when you import the data (see 
   <ref tag="importsql"/>).</footnote> So instead of doing, say,
   <pre>
\input{mydata.dbtex}% loads database <dict tag="manual.labelled"/> `data' from file `mydata.dbtex'
\DTLsortdb{Surname}{data}% sort data on `Title' field
% Later in the document:
\DTLdisplaydb{data}% display data in tabular environment
   </pre>
It's better to run, say,
<pre>
<dict tag="appname"/> --in mydata.dbtex --sort Surname --output mydata-sorted.dbtex
</pre>
   Then in the document, just load <tt>mydata-sorted.dbtex</tt>:
<pre>
\input{mydata-sorted.dbtex}
% Later in the document:
\DTLdisplaydb{data}% display data in tabular environment
</pre>
   or, if you have shell escape enabled you can used <TeX/>'s 
<cs tag="write18"/> mechanism:
   </p>
<pre>
\immediate\write18{<dict tag="appname"/> --in mydata.dbtex --sort Surname 
--output mydata-sorted.dbtex}

\input{mydata-sorted.dbtex}
% Later in the document:
\DTLdisplaydb{data}% display data in tabular environment
</pre>
   <p>
   A<nbsp/>database can be sorted according to a<nbsp/>particular column
   in either ascending or descending order. In batch mode, this is done
   with the <opt tag="sort"/> option, as shown above, where the sort column is identified
   by the column's unique label. If the label is preceded by <tt>-</tt> then
   descending order is used (for example, <opt tag="sort"/><nbsp/><tt>-Surname</tt>). If the label is preceded by <tt>+</tt> (or has
   no prefix) then ascending order is used.  For alphabetical comparisons you 
   can also use <opt tag="sort-case-sensitive"/> for case-sensitive comparisons
   and <opt tag="sort-case-insensitive"/> for case-insensitive comparisons.
   The default is case-insensitive.
   </p>
   <p>In <acr tag="gui"/> mode, sorting is
   done using the <menu tag="tools.sort"/> menu item which opens
   the <button tag="sort.title"/> dialog box (see <ref tag="sortdialog"/>).
   </p>
   <float type="figure" tag="sortdialog" caption="Sort Dialog" pos="htb">
      <image scale="0.75" alt="Image of sort dialog box" src="images/sortdialog.png" />
   </float>
   <p>
   Select the column you wish to sort by from the drop-down list of column
   titles, and check the appropriate radio button for ascending or descending
   sort. If the column has the string data type, you also need to specify
   whether or not you want to use case-sensitive comparisons by checking or
   unchecking the <button tag="sort.case_sensitive"/> box.  If the 
   column type has a<nbsp/>numerical type, the entries will be sorted via 
   a<nbsp/>numerical comparison (10 is greater than 2) and the case-sensitive
   option is ignored. If the column type is a string type,
   the entries will be sorted via an alphabetical comparison (<dq>10</dq>
   comes before <dq>2</dq>).
   </p>
   <example>
   <p>
   Consider the data shown in <ref tag="sortex1"/> and reproduced in 
   <ref tag="tabsortex1"/>.
   <float type="table" tag="tabsortex1" caption="Original Data" pos="htbp">
    <tabular spec="ll" >
     <tr>
      <td><tt>Book</tt></td>
      <td><cs tag="pounds"/><tt>5.99</tt></td>
     </tr>
     <tr>
      <td><tt>Video Game</tt></td>
      <td><cs tag="euro"/><tt>20.00</tt></td>
     </tr>
     <tr>
      <td><tt>Pen</tt></td>
      <td><cs tag="pounds"/><tt>3.00</tt></td>
     </tr>
    </tabular>
   </float>
   The first column has a<nbsp/>string data type and the second has 
   a<nbsp/>currency data type. Sorting in ascending order on the second column,
   will sort numerically on just the number. The currency symbol is ignored
   (see <ref tag="tabsortex2"/>).
   If the type of the second column is changed from currency to string, and the
   sort is redone, the order is now based on a<nbsp/>string comparison that
   includes the currency symbol (see <ref tag="tabsortex3"/>).
   </p>
   <float type="figure" tag="sortex1" caption="Original Data" pos="htbp">
      <image scale="0.75" alt="Image of example database" src="images/sortex1.png" />
   </float>
   <float type="table" tag="tabsortex2" caption="Data Sorted on Second Column (Currency Comparison)" pos="htbp">
    <tabular spec="ll" >
     <tr>
      <td><tt>Pen</tt></td>
      <td><cs tag="pounds"/><tt>3.00</tt></td>
     </tr>
     <tr>
      <td><tt>Book</tt></td>
      <td><cs tag="pounds"/><tt>5.99</tt></td>
     </tr>
     <tr>
      <td><tt>Video Game</tt></td>
      <td><cs tag="euro"/><tt>20.00</tt></td>
     </tr>
    </tabular>
   </float>
   <float type="table" tag="tabsortex3" caption="Data Sorted on Second Column (String Comparison)" pos="htbp">
    <tabular spec="ll" >
     <tr>
      <td><tt>Video Game</tt></td>
      <td><cs tag="euro"/><tt>20.00</tt></td>
     </tr>
     <tr>
      <td><tt>Pen</tt></td>
      <td><cs tag="pounds"/><tt>3.00</tt></td>
     </tr>
     <tr>
      <td><tt>Book</tt></td>
      <td><cs tag="pounds"/><tt>5.99</tt></td>
     </tr>
    </tabular>
   </float>
   </example>
   </node>
   <node tag="shuffle" type="section" title="Shuffling the Data">
   <p>
   Data can be reordered by randomly swapping pairs of rows. By default, 
   this random row swapping is done 100 times, but this number can be
   changed via the <opt tag="shuffle-iterations"/> command line option 
   or the <button tag="preferences.shuffle.iter"/> field in the 
   <dict tag="preferences.title"/> dialog box. Data shuffling can be
   performed either by the <opt tag="shuffle"/> command line option or
   the <menu tag="tools.shuffle"/> menu item.
   </p>
   <example>
   <p>
   Consider the database shown in <ref tag="shuffleex1"/>. This database
   has three columns. The first is a<nbsp/>question, the second is the 
   corresponding answer (optional) and the third is a<nbsp/>number indicating 
   the question level.  For example, 1 could correspond to easy and 2 could 
   correspond to medium difficulty.
   </p>
   <float type="figure" tag="shuffleex1" caption="Shuffle Example" pos="htbp">
      <image scale="0.75" alt="Image of example database" src="images/shuffleex1.png" />
   </float>
   <p>
   Now suppose I<nbsp/>want to write an assignment sheet that has one randomly
   selected question of level<nbsp/>1 and two randomly selected questions of
   level<nbsp/>2. Let's suppose the file name is <tt>data.dbtex</tt>
   and the database label is <dq><tt>problems</tt></dq>. Then I<nbsp/>can run <app/>
   in batch mode using:
   <pre>
<dict tag="appname"/> --shuffle --in data.dbtex --output data-shuffled.dbtex
   </pre>
   Remember to use <opt tag="seed"/> if you don't want a<nbsp/>different
   ordering every time you run that command. For example:
   <pre>
<dict tag="appname"/> --seed 2013 --shuffle --in data.dbtex --output data-shuffled.dbtex
   </pre>
   This shuffled database can now be loaded in my document:
   </p>
<verbinput src="../tests/test-shuffle.tex"/>
   <p>
   What if I<nbsp/>want all the easy questions listed first? This requires 
   some modifications to the code as shown below:
   </p>
<verbinput src="../tests/test-shuffle-level.tex"/>
   <p>
   Now, the <cs tag="DTLforeach"/> loop just stores the row numbers of the
   required questions in two lists, corresponding to the two different levels.
   Then each list is iterated through and the corresponding row is fetched
   using <cs tag="dtlgetrow"/>. Extending this example to accommodate an
   arbitrary number of levels is left as an exercise for the reader.
   </p>
   <p>
   Remember that if you have shell escape enabled when you run <LaTeX/> you
   can invoke <app/> in your document <em>before</em> you load the database:
   </p>
   <pre>
\immediate\write18{datatooltk --in data.dbtex --seed 2013 --shuffle 
--output data-shuffled.dbtex}

\input{data-shuffled.dbtex}
   </pre>
   </example>
   </node>
   <node tag="sortshuffle" type="section" title="Sorting and Shuffling">
   <p>
   As mentioned earlier, if you specify both <opt tag="sort"/> and
   <opt tag="shuffle"/>, the sorting will always be performed first, 
   regardless of the option order, but why would you want to sort the data
   if you're going to shuffle it? Consider the command invocation:
<alltt>
<dict tag="appname"/> <opt tag="shuffle"/> <opt tag="in"/> <meta>in-file</meta> <opt tag="output"/> <meta>out-file</meta>
</alltt>
   Every time you run this command, you will get a<nbsp/>different ordering.
If, however, you set a<nbsp/>seed for the random generator, for example:
<alltt>
<dict tag="appname"/> <opt tag="seed"/> 2013 <opt tag="shuffle"/> <opt tag="in"/> <meta>in-file</meta> <opt tag="output"/> <meta>out-file</meta>
</alltt>
   You will always get the same random ordering <em>provided the original 
   data in <meta>in-file</meta> has remained unchanged</em>. If you want to 
   modify the shuffled data in your document and save it to the original 
   file <meta>in-file</meta> using <cs tag="DTLsaverawdb"/>, the ordering in 
   that file will change, so the next time you shuffle it, you'll get 
   a<nbsp/>different ordering, even if you use the same seed. If you sort
   first on a unique label, that will ensure the shuffle has the same 
   starting point (unless you add or remove rows).
   </p>
   <example>
   <p>
   Suppose you have a<nbsp/>database of exam questions and you want to keep
   track of the year in which each question was last used. (To make life
   easier, let's identify the academic year <dq>2012/13</dq> as 2013, the
   academic year <dq>2013/14</dq> as 2014, etc.) Let's further suppose the
   database of questions is in a<nbsp/>file called <tt>mth-101.dbtex</tt>
   and the database label is <dq><tt>problems</tt></dq> (see 
   <ref tag="sortshuffleex"/>). The database 
   contains a<nbsp/>column with the label <dq><tt>Label</tt></dq>, which
   uniquely identifies an exam question, a<nbsp/>column with the label
   <dq><tt>Question</tt></dq> that contains the exam question, a<nbsp/>column
   with the label <dq><tt>Answer</tt></dq> that contains the answer and
   an integer column with the label <dq><tt>Year</tt></dq> that contains the
   exam year in which that question was last used. (A zero entry means the
   question hasn't been used.)
   </p>
   <float type="figure" tag="sortshuffleex" caption="Sort and Shuffle Example" pos="htbp">
      <image scale="0.75" alt="Image of example database" src="images/sortshuffleex1.png" />
   </float>
   <p>
   Now suppose the exam requires five questions to be randomly selected from 
   this database, but must not include any question used in the past three 
   years. So the exam <LaTeX/> document needs to load in a<nbsp/>shuffled
   version of <tt>mth-101.dbtex</tt>, use the first five questions that don't
   have a<nbsp/>year set in the past three year range, set the year for the
   selected questions to the current exam year, display the questions (and
   optionally the answers for the solution sheet), and at the end of the
   document, overwrite <tt>mth-101.dbtex</tt> so that it now has 
   a<nbsp/>record of this year's exam questions.
   </p>
   <p>
   There are two problems. Firstly, if the process is to be automated
   with a<nbsp/>call to <app/> <opt tag="shuffle"/> followed by 
   a<nbsp/><LaTeX/> call, a<nbsp/>different set of problems will be selected
   on each run, even with the same seed. To overcome this, a<nbsp/>sort on 
   the <tt>Label</tt> column needs to be done before the shuffle:
<alltt>
<dict tag="appname"/> <opt tag="sort"/> Label <opt tag="seed"/> 2013 <opt tag="shuffle"/> <opt tag="in"/> mth-101.dbtex <cont/><opt tag="output"/> mth-101-shuffled.dbtex
</alltt>
   <contexplan/>
   This way the shuffle always starts from the same ordering.
   </p>
   <p>
   The second problem occurs if you edit the database such that you add or
   remove rows. This will change the initial conditions, even with the sort.
   If you add or remove rows, you need to accept that the document may well
   end up with a<nbsp/>different selection of questions, which is okay if
   you haven't finalised the exam, but it means that some of the questions
   will be identified as having been used in that exam year from 
   a<nbsp/>previous run but are now no longer selected. In order to make them
   available for the next year, if they haven't been selected but have had the
   year set to this year, the year needs to be cleared.
   </p>
   <p>
   To solve this, once you have selected the maximum required number of
   questions, don't break out of the loop, as was done earlier (see
   <ref tag="shuffle"/>). Instead, for the rest of the loop, if the exam
   year is set to the current year, clear it.
   </p>
   <verbinput src="../tests/test-exam.tex" />
   <p>
   <b>Note:</b> since this overwrites the <sty>datatool</sty> file, you will
   lose any pretty-printing spaces or comments you may have done in 
   <app/>'s cell editor dialog.
   </p>
   </example>
   </node>
   <node tag="plugins" type="section" title="Plugins">
   <p>
   Plugins are usually associated with a<nbsp/>particular template 
   (see <ref tag="templates"/>) and provide a<nbsp/>convenient way of
   adding a<nbsp/>row of data to the currently selected database.
   Typically when a<nbsp/>plugin is run it will add a<nbsp/>new row of data 
   if no row is selected, otherwise it will allow you to edit the selected row.
   <b>Note:</b> you must have Perl installed to use the plugins (see 
   <ref tag="preferences"/>). <b>Really Important Note:</b> the plugin is
   sent the database information when you start each instance of the plugin, 
   so if you change the database in <app/> while a<nbsp/>plugin is running 
   there may be unexpected results. Wait until the plugin has finished 
   (usually by clicking on <button tag="button.okay"/> or 
   <button tag="button.cancel"/>) before you make any further edits to the 
   database.
   </p>
   </node>
   <node tag="peopleplugin" type="subsection" title="The people Plugin">
   <p>
   The <tt>people</tt> plugin is designed for use with databases created
   using the <tt>people</tt> template.
   </p>
   <example>
   <p>
   Suppose you create a<nbsp/>new database using the <tt>people</tt>
   template. This creates a<nbsp/>database with the following fields:
   ID, Title, Surname, Forename, Address, Telephone and Email, as
   illustrated in <ref tag="ex.people"/>.
   </p>
     <float type="figure" tag="ex.people" caption="Database Created From people Template">
      <image scale="0.75" alt="Image of main window" src="images/peopletemplate.png" />
     </float>
   <p>
   Having created this database, I<nbsp/>can just use the 
   <menu tag="edit.row"/> menu to insert rows and then edit each entry,
   but suppose I<nbsp/>want to automatically increment the associated ID
   for each person. I<nbsp/>can do this using the <tt>people</tt> plugin 
   that corresponds to this template via the <menu tag="tools.plugins"/> menu.
   </p>
   <p>
   If a<nbsp/>row is currently selected, this plugin will allow you to edit
   the data for that row. Otherwise, it will allow you to insert a<nbsp/>new
   row. For a<nbsp/>new row of data, the <tt>people</tt> plugin will open
   the dialog box shown in <ref tag="ex.peopleplugin"/>.
   </p>
     <float type="figure" tag="ex.peopleplugin" caption="The people Plugin Dialog">
      <image scale="0.75" alt="Image of people dialog" src="images/peopleplugin.png" />
     </float>
   <p>
   After entering the data, I<nbsp/>can click on <button tag="button.okay"/>
   and a<nbsp/>new row of data is added to the database (see 
   <ref tag="peoplepluginex1"/>). Note that the plugin has converted newline
   characters in the address into <doublebackslash/>. The ID has automatically 
   been inserted.
   </p>
     <float type="figure" tag="peoplepluginex1" caption="A New Row of Data">
      <image scale="0.75" alt="Image of main window" src="images/peoplepluginex1.png" />
     </float>
   Since the <tt>people</tt> plugin only adds or modifies a<nbsp/>single
   row at a<nbsp/>time, if you no longer require an entry, you can delete the
   unwanted row using <menu tag="edit.row.remove_row"/>.
   </example>
   </node>
   <node tag="datagidxplugin" type="subsection" title="The datagidx Plugin">
   <p>
   The <sty>datagidx</sty> package creates its own custom database 
   to store terms, symbols and acronyms. The <tt>datagidx</tt> template
   will create a<nbsp/>database that contains <sty>datagidx</sty>'s required 
   fields. There are a<nbsp/>lot of fields, some of which are reserved for
   <sty>datagidx</sty>'s private use. The <tt>datagidx</tt> plugin, 
   available via the <menu tag="tools.plugins"/> menu, provides 
   a<nbsp/>convenient interface to add or edit entries. If no row is selected,
   the plugin will create a<nbsp/>new row. If a<nbsp/>row is selected,
   the plugin will allow you to edit or remove the row. Since the 
   <tt>datagidx</tt> plugin can modify other rows at the same time
   (for example, if you set a<nbsp/>parent entry or cross-reference)
   it's recommended that you use the <tt>datagidx</tt> plugin to remove an
   entry (via the <button tag="plugin.remove_entry"/> button) rather than 
   using <menu tag="edit.row.remove_row"/>.
   </p>
   <example>
   <p>
   The new database (created via <menu tag="file.new_from_template"/>) is
   shown in <ref tag="datagidxplugin1"/>. The default name of the database
   is <dq><dict tag="plugin.datagidx.default_name"/></dq>. You can change it 
   as required, but don't call it <dq>datagidx</dq> as the <sty>datagidx</sty> 
   package creates a<nbsp/>database with that name for its private use.
   Once this database has been created, the <tt>datagidx</tt> plugin will 
   open the dialog box shown in <ref tag="datagidxplugin2"/>.
   </p>
     <float type="figure" tag="datagidxplugin1" caption="A Database Created From the datagidx Template" pos="htbp">
      <image scale="0.75" alt="Image of main window" src="images/datagidxplugin1.png" />
     </float>
     <float type="figure" tag="datagidxplugin2" caption="The datagidx Plugin Dialog" pos="htbp">
      <image scale="0.75" alt="Image of datagidx plugin dialog" src="images/datagidxplugin2.png" />
     </float>
   <p>
   Since many of the fields are often duplicated (for example, the 
   <tt>Name</tt> field is often the same as the <tt>Text</tt> field)
   if you first enter the name in the <button tag="plugin.datagidx.Name"/>
   field, when you move the focus to another field, default entries will 
   be added to most of the empty fields. For example, in 
   <ref tag="datagidxplugin3"/> I<nbsp/>typed <dq>bird</dq> in the
   <button tag="plugin.datagidx.Name"/> field and then moved the cursor to
   the <button tag="plugin.datagidx.Description"/> field. This automatically
   filled in default values for the <button tag="plugin.datagidx.Label"/>,
   <button tag="plugin.datagidx.Sort"/>,
   <button tag="plugin.datagidx.Text"/>,
   <button tag="plugin.datagidx.Short"/>,
   <button tag="plugin.datagidx.Long"/>,
   <button tag="plugin.datagidx.Plural"/>,
   <button tag="plugin.datagidx.ShortPlural"/> and
   <button tag="plugin.datagidx.LongPlural"/> fields.
   Since this is the first entry, there are no options for the
   <button tag="plugin.datagidx.Parent"/>,
   <button tag="plugin.datagidx.See"/> and 
   <button tag="plugin.datagidx.SeeAlso"/> fields. (The last two are hidden in
   <ref tag="datagidxplugin3"/> as the <button tag="plugin.datagidx.crossref"/>
   button is unchecked.)
   </p>
     <float type="figure" tag="datagidxplugin3" caption="Most Fields Are Auto-Filled From the Name Field" pos="htbp">
      <image scale="0.75" alt="Image of datagidx plugin dialog" src="images/datagidxplugin3.png" />
     </float>
   <p>
   When I<nbsp/>click on <button tag="button.okay"/>, a<nbsp/>new row is
   added to the database (see <ref tag="datagidxplugin4"/>). Note that
   I<nbsp/>didn't specify a<nbsp/>parent for this entry so the parent has
   been given the value <cs tag="@dtlnovalue"/>, which ensures it will work
   correctly when the <sty>datagidx</sty> package tests if the parent entry
   is null.
   </p>
     <float type="figure" tag="datagidxplugin4" caption="New Row Added to the Database" pos="htbp">
      <image scale="0.75" alt="Image of main window" src="images/datagidxplugin4.png" />
     </float>
   <p>
   If I<nbsp/>use the <tt>datagidx</tt> plugin to create a<nbsp/>new row,
   there are now options available in the 
   <button tag="plugin.datagidx.Parent"/>, 
   <button tag="plugin.datagidx.See"/> and 
   <button tag="plugin.datagidx.SeeAlso"/> fields 
   (see <ref tag="datagidxplugin5"/>).
   </p>
     <float type="figure" tag="datagidxplugin5" caption="Parent Field Lists Other Entry Labels">
      <image scale="0.75" alt="Image of datagidx plugin dialog" src="images/datagidxplugin5.png" />
     </float>
   <p>
   In <ref tag="datagidxplugin5"/> I<nbsp/>have set the parent to 
   <tt>bird</tt>. When the new row is added, the plugin automatically adjusts
   the <tt>bird</tt> entry to include the new <tt>duck</tt> label as one of its
   children (see <ref tag="datagidxplugin6"/>).
   </p>
     <float type="figure" tag="datagidxplugin6" caption="Child Entry Automatically Adjusted For Parent Entry">
      <image scale="0.75" alt="Image of main window" src="images/datagidxplugin6.png" />
     </float>
   <p>
   It's also possible to cross-reference another entry. There are two ways
   of cross-referencing an entry: (1) using <button tag="plugin.datagidx.See"/>
   which redirects the reader to a<nbsp/>synonym that has the location list;
   (2) using <button tag="plugin.datagidx.SeeAlso"/> which in addition to the
   location list refers the reader to one or more related topics. (See the
   <sty>datagidx</sty> section of the <sty>datatool</sty> user manual
   for further details.) To enable
   either form of cross-referencing, make sure the
   <button tag="plugin.datagidx.crossref"/> button is selected. This will 
   display extra options, shown in <ref tag="datagidxplugin7"/>.
   </p>
     <float type="figure" tag="datagidxplugin7" caption="Cross-Referencing Entries">
      <image scale="0.6" alt="Image of datagidx plugin dialog" src="images/datagidxplugin7.png" />
     </float>
   <p>
   Either select the <button tag="plugin.datagidx.See"/> button and choose
   the synonym from the drop-down box next to it, or select the 
   <button tag="plugin.datagidx.SeeAlso"/> button and select the related 
   cross-reference from the drop-down box to the right and either click on
   <button tag="plugin.datagidx.add_seealso"/> to append it to the 
   <button tag="plugin.datagidx.SeeAlso"/> list or click on 
   <button tag="plugin.datagidx.remove_seealso"/> to remove it from the list.
   For example, in <ref tag="datagidxplugin7"/> I've added the <tt>chicken</tt>
   and <tt>turkey</tt> entries to the <button tag="plugin.datagidx.SeeAlso"/>
   list. (Assuming I've already added the <tt>chicken</tt> and <tt>turkey</tt>
   entries before defining this new entry.)
   </p>
   <p>
   Once I've enter all my terms, I<nbsp/>can sort the data according to 
   the <button tag="plugin.datagidx.Sort"/> column. (Recall <ref tag="sort"/>.)
   Now let's suppose I<nbsp/>save this sorted database to a<nbsp/>file
   called <tt>datagidx-test.dbtex</tt>. I<nbsp/>can now load it into 
   a<nbsp/><LaTeX/> document as follows<footnote>Ensure you have at least
   version 2.15 of the <sty>datatool</sty> bundle.</footnote>:
   </p>
<verbinput src="../tests/datagidx-doc.tex"/>
   </example>
   </node>
   <node tag="comparison" type="subsection" title="Comparison of glossaries and datagidx">
   <p>
   If you're interested in the comparitive efficiency between
   using <sty>glossaries</sty> and <sty>datagidx</sty>, I<nbsp/>performed
   a<nbsp/>test with 100 entries randomly selected from a<nbsp/>dictionary.
   The entries were listed in a<nbsp/>file called <tt>entries</tt> in
   the form:
   </p>
<alltt>
<cs tag="newterm"/><marg>minnow</marg>
<cs tag="newterm"/><marg>running board</marg>
<cs tag="newterm"/><marg>diamant<cs tag="'"/>e</marg>
</alltt>
   <p>
   First, let's look at a<nbsp/>document that uses <sty>datagidx</sty> with <cs tag="newgidx"/>:
   </p>
<verbinput src="../tests/datagidx/test-datagidx.tex"/>
   <p>
   In general you need three <LaTeX/> runs to compile a<nbsp/><sty>datagidx</sty>
   document. In this case, you actually only need to do it twice
   since there are no location lists.
   </p>
   <p>
   Now let's test a<nbsp/><sty>datagidx</sty> document where <app/> does the
   sorting. First, we need to generate a<nbsp/><tt>.dbtex</tt>
   file that corresponds the same set of entries. This can be done
   with the following document:
   </p>
<verbinput src="../tests/datagidx/test-savedbtex.tex"/>
   <p>
   This just converts the entries listed in <tt>entries.tex</tt>
   into the appropriate database file, simulating having entered
   the terms using <app/>'s datagidx plugin. The file is saved
   as <tt>index.dbtex</tt>. Remember that this data only needs
   to be sorted when you add a<nbsp/>term. This can either be done
   in <app/>'s <acr tag="gui"/> mode or it can be done in batch mode:
   </p>
<pre>
datatooltk --in index.dbtex --sort Sort --output index-sorted.dbtex
</pre>
   <p>
   This creates a<nbsp/>file called <tt>index-sorted.dbtex</tt>.
   This file can be loaded into a<nbsp/>document as follows (NB there's a bug in 
   <cs tag="glsaddall"/>, which is patched using the <cs tag="setkeys"/> line. This will be fixed in the next version of <sty>datagidx</sty>):
   </p>
<verbinput src="../tests/datagidx/test-loaddb.tex"/>
   <p>
   Now let's look at the <sty>glossaries</sty> package. Since the terms
   have been defined using <cs tag="newterm"/>, I've defined a<nbsp/>command
   that will convert this into an equivalent <cs tag="newglossaryentry"/>.
   Some of the entries have accents in their name, which
   <sty>datagidx</sty> automatically strips when generating the default 
   label, so I've added a<nbsp/>quick way of generating an
   analogous accent-free label and sort key that can be used with <cs tag="newglossaryentry"/>. Here's the document:
   </p>
<verbinput src="../tests/datagidx/test-glossaries.tex"/>
   <p>
   In order to compare them, I<nbsp/>used <tt>arara</tt> with 
   the Linux <tt>time</tt> command. In each case, the <tt>clean</tt>
   directive is used at the start to ensure the tests start without
   any auxiliary files. Since there are no location lists, only
   two <LaTeX/> calls are used on each example. If there were
   location lists, the <sty>datagidx</sty> examples would both
   need a<nbsp/>third <LaTeX/> call.<footnote>The <sty>datagidx</sty>
   package doesn't generate a<nbsp/>location with <cs tag="glsadd"/>
   or <cs tag="glsaddall"/>, whereas <sty>glossaries</sty> does.
   I've suppressed the location list in the <sty>glossaries</sty>
   example to produce an equivalent document.</footnote>
   Remember that with the example that uses <tt>index-sorted.dbtex</tt>,
   <app/> needs to sort the database whenever a<nbsp/>new entry is 
   added to the database. Assuming that all possible required
   entries have been added to the database, we just need one
   sort operation:
   </p>
<pre>
datatooltk --in index.dbtex --sort Sort --output index-sorted.dbtex
</pre>
   <p noindent="true">
   Invoking this with the Linux <tt>time</tt> command gives:
   </p>
<pre>
real	0m0.296s
user	0m0.466s
sys	0m0.033s
</pre>
   <p>
   Now <tt>arara</tt> can be run on each of the three test documents 
   (via the <tt>time</tt> command). The result from the first test
   that uses <sty>datagidx</sty> and <cs tag="newgidx"/>. The results are:
   </p>
<pre>
real	0m13.801s
user	0m13.925s
sys	0m0.076s
</pre>
  <p>
  <tt>arara</tt> records the total time taken as 13.39 seconds.
  </p>
  <p>
  The next test uses <sty>datagidx</sty> and <cs tag="loadgidx"/>. 
  The result is:
  </p>
<pre>
real	0m2.643s
user	0m2.775s
sys	0m0.065s
</pre>
  <p>
  <tt>arara</tt> records the total time taken as 2.23 seconds.
  </p>
  <p>
  The third test uses <sty>glossaries</sty>. The result is:
  </p>
<pre>
real	0m1.156s
user	0m1.307s
sys	0m0.069s
</pre>
   <p>
  <tt>arara</tt> records the total time taken as 0.75 seconds.
   </p>
   <p>
   Using <sty>glossaries</sty> is clearly faster than using
   <sty>datagidx</sty>. In the case of <cs tag="loadgidx"/>,
   <sty>glossaries</sty> is approximately three times faster. In the 
   case of <cs tag="newgidx"/>, <sty>glossaries</sty> is approximately 
  18 times faster. If a<nbsp/>third <LaTeX/> run was required
  for the location lists with <cs tag="newgidx"/>, using <sty>glossaries</sty> would be approximately 
  27 times faster (with only two <LaTeX/> runs and one <tt>makeglossaries</tt> run).
   </p>
   <p>
   If you're interested to know how this compares with <cs tag="makenoidxglossaries"/> instead of <cs tag="makeglossaries"/>, here's the revised 
   <sty>glossaries</sty> code:
   </p>
<verbinput src="../tests/datagidx/test-glossaries-noidx.tex"/>
   <p>
   The result is:
   </p>
<pre>
real	0m2.463s
user	0m2.596s
sys	0m0.065s
</pre>
  <p>
  <tt>arara</tt> records the total time taken as 2.06 seconds.
  This is slightly quicker than the second <sty>datagidx</sty> test.
  </p>
   </node>
   <node tag="import" type="chapter" title="Importing Data">
   <p>
   Data can be imported from <acr tag="csv"/> files (see 
   <ref tag="importcsv"/>), <acr tag="sql"/> databases (see 
   <ref tag="importsql"/>) or from files that can be imported with 
   the <sty>probsoln</sty> package's <cs tag="loadallproblems"/> command
   (see <ref tag="importprobsoln"/>). In the case of the first
   two, <app /> can automatically convert <TeX />'s special characters if the
   <opt tag="map-tex-specials"/> command line option is used or the
   <button tag="preferences.tex.map"/> option has been selected in the 
   <dict tag="preferences.title"/> dialog box (see <ref tag="preferences"/>).
   </p>
   </node>
   <node tag="importcsv" type="section" title="Import CSV Data">
   <p>
   Data can be imported from a<nbsp/><acr tag="csv"/> file using
   the <opt tag="csv"/> command line option or (in <acr tag="gui"/> mode)
   using the <menu tag="file.import.importcsv"/> menu item. The default
   separator is a<nbsp/>comma and the default delimiter is the double-quote
   character. These can be changed using the <opt tag="sep"/> and 
   <opt tag="delim"/> command line options or in the 
   <dict tag="preferences.title"/>
   dialog box (see <ref tag="preferences"/>). Unlike <sty>datatool</sty>'s
   <cs tag="DTLloaddb"/> command, <app/> can import data with multilined
   entries (via the Open<nbsp/>CSV library 
   <url www="http://opencsv.sourceforge.net/"/>).
   Multiple blank lines within entries are automatically converted to
   <cs tag="DTLpar"/> (although you won't see this in <acr tag="gui"/>
   mode).
   </p>
   <p>
   If the <acr tag="csv"/> file has a<nbsp/>header row, you must make sure 
   the <opt tag="csvheader"/> option is used or the 
   <button tag="preferences.csv.hasheader"/> option is checked in the
   <dict tag="preferences.title"/> dialog box.
   If the <acr tag="csv"/> file has no header row, you must make sure 
   the <opt tag="nocsvheader"/> option is used or the 
   <button tag="preferences.csv.hasheader"/> option is unchecked in the
   <dict tag="preferences.title"/> dialog box.
   </p>
   <example>
   <p>
   Consider the <acr tag="csv"/> file shown below:
   </p>
   <verbinput src="../tests/test-para.csv" />
   This has a cell with multiple lines. When it's imported into
   <app/>, the paragraph break is converted to <cs tag="DTLpar"/>.
   However, this isn't visible when you look at the file in 
   <acr tag="gui"/> mode (see <ref tag="ex.csvpara"/>).
     <float type="figure" tag="ex.csvpara" caption="Paragraph Breaks Appear as a Single Blank Line">
      <image scale="0.75" alt="Image of main window showing cell with paragraph break" src="images/csvpara.png" />
     </float>
   Note that the redundant second blank line in the <acr tag="csv"/> file
   has gone as multiple blank lines are replaced by a<nbsp/>single
   <cs tag="DTLpar"/>.
   </example>
   </node>
   <node tag="importspread" type="section" title="Import Spreadsheet Data">
   <p>
   Data can be imported from an Excel <tt>.xls</tt> file (via the 
   Apache POI library <url www="http://poi.apache.org/" />)
   or an Open Document Spreadsheet (via the jOpenDocument Library
   <url www="http://www.jopendocument.org/"/>) using the
   <opt tag="xls"/> or <opt tag="ods"/> command line options, respectively.
   Alternative, in <acr tag="gui"/> mode you can use the 
   <menu tag="file.import.importspread" /> menu item. When using the command line,
   you additionally need to specify the sheet index (starting from 0) or the 
   sheet name using the <opt tag="sheet"/> command line option. If you are 
   using the <acr tag="gui"/>, after you've selected the spreadsheet file 
   from the file selector dialog, you need to select the required sheet 
   name.</p>
   <p>Importing data from a spreadsheet uses the same header row option and 
   <TeX/> mapping settings as the import <acr tag="csv"/> function. 
   So if the sheet doesn't have a header row, you need to use
   <opt tag="nocsvheader"/> or uncheck the <button tag="preferences.csv.hasheader"/> button 
   in the <dict tag="preferences.title"/> dialog box. Note that 
   <tt>.xlsx</tt> files aren't supported.
   </p>
   <p>
   <b>Note:</b> no formatting information is read when importing
   data from an Excel spreadsheet. It's up to you to explicitly
   add <LaTeX/> font commands when you include the data in your
   document.
   </p>
   </node>
   <node tag="importsql" type="section" title="Import SQL Data">
   <p>
   Data can be imported from an<nbsp/><acr tag="sql"/> database using
   the <opt tag="sql"/> command line option or the 
   <menu tag="file.import.importsql"/> menu item. You additionally need to
   supply the database, port, prefix, host, user name and password. In batch 
   mode, you can use the command line options <opt tag="sqldb"/>,
   <opt tag="sqlport"/>, <opt tag="sqlprefix"/>, <opt tag="sqlhost"/> and
   <opt tag="sqluser"/>. You can specify the password with 
   <opt tag="sqlpassword"/>, but that isn't secure. If you don't use that, 
   you will be prompted for the password, where the text you enter 
   won't be visible. Note that in batch mode, the default action
   is to use the console to request the password. If there's no console available, you need to use the <opt tag="noconsole-action"/>
   to determine what action to perform. See <ref tag="introduction"/> for more details
   about command line options.
   </p>
   <p>
   In <acr tag="gui"/> mode, when you use <menu tag="file.import.importsql"/>
   the dialog box shown in <ref tag="sqlimportdialog"/> will be displayed,
   where you can enter the settings. In addition to the above named settings,
   you must also specify the <acr tag="sql"/> SELECT statement that identifies 
   the required data to import. (This manual assumes that if you have
   data in an <acr tag="sql"/> database, then you have a<nbsp/>basic
   knowledge of <acr tag="sql"/> syntax.)
   </p>
     <float type="figure" tag="sqlimportdialog" caption="SQL Import Dialog Box">
      <image scale="0.75" alt="Image of the SQL dialog box" src="images/sqlimportdialog.png" />
     </float>
   <p>
   For example, in <ref tag="sqlimportdialog"/> I<nbsp/>want to import all
   data from the table called <tt>customers</tt> in the <term tag="mysql"/>
   database called <tt>myshop</tt>. (I've created a<nbsp/>user called
   <tt>shopadmin</tt> with SELECT privileges for this database.) Once I've 
   entered this information,
   I<nbsp/>then click on <button tag="button.okay"/> and the password
   dialog box will appear (see <ref tag="sqlpassworddialog"/>).
   </p>
     <float type="figure" tag="sqlpassworddialog" caption="Password Dialog Box">
      <image scale="0.75" alt="Image of the password dialog box" src="images/sqlpassworddialog.png" />
     </float>
   <p>
   Alternatively, I<nbsp/>can use batch mode to import and save the data 
   from the command prompt:
   </p>
   <alltt>
datatooltk --output customers.dbtex --sql "SELECT * FROM customers" <cont />--sqldb myshop --sqluser shopadmin
Password:
   </alltt>
   <p>
   <contexplan/> The password should be entered at the <button tag="password.prompt"/>
   prompt. Remember that it's more efficient to get the <acr tag="sql"/>
   database to do any sorting. For example (assuming the table has 
   a<nbsp/>column called <tt>Surname</tt>):
   <alltt>
datatooltk --output customers.dbtex --sql "SELECT * FROM customers ORDER BY <cont />Surname" --sqldb myshop --sqluser shopadmin
Password:
   </alltt>
   </p>
   </node>
   <node tag="importprobsoln" type="section" title="Import probsoln Data">
   <p>
   The <sty>probsoln</sty> package allows you to define problems (and 
   optionally their solutions) using <cs tag="newproblem"/> or the
   <env tag="defproblem"/> environment. <app/> can load a<nbsp/>file
   containing these definitions and convert the <sty>probsoln</sty> data
   into a<nbsp/><sty>datatool</sty> database containing three columns
   with keys: <tt><dict tag="probsoln.label"/></tt>, 
   <tt><dict tag="probsoln.question"/></tt> and
   <tt><dict tag="probsoln.answer"/></tt>. You can import one of these
   files using the <opt tag="probsoln"/> command line option or (in
   <acr tag="gui"/> mode) using the <menu tag="file.import.importprobsoln"/>
   menu item.
   </p>
   <p>
   <TeX/> is a<nbsp/>difficult language to parse, so <app/> uses 
   <LaTeX/> to help gather the data from the imported file.
   The <app/> application creates a<nbsp/>temporary <LaTeX/> file and runs <LaTeX/>
   on it in the background. It assumes that the <tt>latex</tt> application
   is on your path. If this isn't the case, you will have to specify
   the location of the <tt>latex</tt> executable in the 
   <dict tag="preferences.title"/> dialog box (see <ref tag="preferences"/>).
   The temporary files are deleted when you quit <app/> unless you have
   used the <opt tag="nodelete-tmp-files"/> option.
   </p>
   <p>
   <b>Note:</b> <app/> doesn't support problems that require arguments. Any
   instance of <hash/><meta>n</meta> will be replaced with
   <hash/><hash/><meta>n</meta>, but you will have to replace those
   with something else. Also, recall from <ref tag="verbatim"/> that you
   can't have verbatim text in a<nbsp/><sty>datatool</sty> database, 
   but you can use <cs tag="verbatiminput"/> (from the 
   <sty>verbatim</sty> package) or <cs tag="lstinputlisting"/> (from the
   <sty>listings</sty> package). Since <LaTeX/> is used to gather the
   data, pretty-printing spaces and comments won't be imported.
   </p>
   <example>
   <p>
   Consider the file called <tt>prob-mixed.tex</tt> that contains the 
   following:
   </p>
   <verbinput src="../tests/prob-mixed.tex"/>
   <p>
   This contains a<nbsp/>mixture of <cs tag="newproblem"/> and
   <env tag="defproblem"/>. It also has comments and spaces to make
   the code more readable. As can be seen in <ref tag="importps"/>
   these have gone in the import.
   </p>
     <float type="figure" tag="importps" caption="Pretty Printing and Comments are Lost When Importing Data from probsoln" pos="hbt">
      <image scale="0.75" alt="Image of the main window" src="images/importps.png" />
     </float>
   </example>
   <seealso tags="shuffle,sortshuffle"/>
   </node>
   <node tag="templates" type="chapter" title="Templates">
   <p>
   Templates that come with <app/> are located in the <tt>resources/templates</tt>
   subdirectory of the <app/> installation directory. You can also write
   your own templates and store them in the user templates directory 
   (see <ref tag="writingtemplates"/>). Each template defines a<nbsp/>set
   of column headers. To create a<nbsp/>new database with a<nbsp/>particular
   set of column headers, use the <menu tag="file.new_from_template"/>
   menu item, which opens the dialog box shown in <ref tag="templatedialog"/>.
   </p>
   <float type="figure" tag="templatedialog" 
      caption="New From Template Dialog">
     <image scale="0.75" alt="Image of template dialog"
        src="images/templatedialog.png"/>
   </float>
   <p>
   The <app/> application comes with the following templates: 
   <tt>datagidx</tt> (creates a<nbsp/>database with the same structure as
   used by the <sty>datagidx</sty> package) and <tt>people</tt> (creates
   a<nbsp/>database suitable for storing records about people, including
   columns for forenames, a<nbsp/>surname, title and address.) For example,
   <ref tag="peopletemplate"/> shows a<nbsp/>database created from the 
   <tt>people</tt> template.
   </p>
   <float type="figure" tag="peopletemplate" 
      caption="New Database Created from people Template">
     <image scale="0.75" alt="Image of main window"
        src="images/peopletemplate.png"/>
   </float>
   <p>
   Rows can now be added to this database using the <menu tag="edit.row"/>
   menu or via corresponding plugins (see <ref tag="plugins"/>).
   </p>
   </node>
   <node tag="writingtemplates" type="section" title="Writing a Template File">
   <p>
   If you want to write your own template, you need to create an XML file
   and store it in a<nbsp/>subdirectory  of the <app/> 
   user properties directory (see <ref tag="preferences"/>) called 
   <tt>templates</tt>. You will need to create this directory, if it doesn't
   already exist. For example, on a<nbsp/>UNIX-like system, the user
   template directory will be <tt><tilde/>/.datatooltk/templates/</tt>.
   The template file must have the extension <tt>.xml</tt> for it to be
   listed in the <dq><dict tag="template.title"/></dq> dialog box. (The base
   name of the file is used in the list.)
   </p>
   <p>
   The template file must have one <element>datatooltktemplate</element> element. This
   element may contain one or more <element>header</element> elements. Each 
   <element>header</element> element must contain one <element>label</element> element and 
   optionally one <element>title</element> and/or one <element>type</element> element.
   </p>
   <p>
   The <element>label</element> element contains the uniquely identifying header label.
   The <element>title</element> element contains the header title. If omitted, the
   title is set to the label, unless there is an entry in the resource
   dictionary file that matches <tt>plugin.</tt><meta>template name</meta><tt>.</tt><meta>label</meta>, 
   in which case that property is used. The <element>type</element> element must be one of:
   <tt>-1</tt> (unknown type), <tt>0</tt> (string type), <tt>1</tt> (integer 
   type), <tt>2</tt> (real type) or <tt>3</tt> (currency type). If omitted the 
   type is set to <tt>-1</tt>.
   </p>
   <example>
   <p>
   Suppose I<nbsp/>want to write a<nbsp/>template to create a<nbsp/>database
   for a<nbsp/>list of products. The database needs three columns: one for
   the product name, one for the product code and one for the product price.
   The name should be a<nbsp/>string, the price column could either be set
   to <dq>real</dq> if you don't need to worry about the currency unit
   or <dq>currency</dq> if you need a<nbsp/>currency unit for each product.
   Let's suppose that the code must be an integer.
   Here's a<nbsp/>template file (the price column is set to <dq>real</dq>
   rather than <dq>currency</dq>):
   </p>
<alltt>
<element>datatooltktemplate</element>
  <element>header</element>
    <element>label</element>Name<element>/label</element>
    <element>type</element>0<element>/type</element>
  <element>/header</element>
  <element>header</element>
    <element>label</element>Code<element>/label</element>
    <element>type</element>1<element>/type</element>
  <element>/header</element>
  <element>header</element>
    <element>label</element>Price<element>/label</element>
    <element>type</element>2<element>/type</element>
  <element>/header</element>
<element>/datatooltktemplate</element>
</alltt>
   </example>
   </node>
   <node tag="preferences" type="chapter" title="Application Properties">
   <p>
   When <app/> is run, either in batch or <acr tag="gui"/> mode, 
   the application settings are read in from the user properties file, 
   if it exists. Any command line options override those settings.
   If <app/> is run in <acr tag="gui"/> mode, the application properties are saved on exit. They are not saved in batch mode.
   </p>
   <p>
   The user properties directory depends on the operating system.
   On Windows, it is a folder called <tt>datatooltk-settings</tt>
   in the folder given by the Java system property <tt>user.home</tt>.
   This is usually the user's home folder but in some versions of
   Java this can be <tt><percent/>userprofile<percent/></tt>.
   On other operating systems, the user properties directory is
   called <tt>.datatooltk</tt> and is in the user's home directory.
   </p>
   <p>
   In <acr tag="gui"/> mode, the settings can be changed using
   <menu tag="edit.preferences"/>. This opens the 
   <button tag="preferences.title"/> dialog box, which has the 
   following tabs:
   </p>
   <dl>
    <dt><button tag="preferences.general"/></dt>
    <dd>
     (<ref tag="prefgeneral"/>)
     <float type="figure" tag="prefgeneral" caption="General Tab" pos="htbp">
      <image scale="0.75" alt="Image of the general tab of the preferences dialog box" src="images/pref-general.png" />
     </float>
     <p>
     In this tab you can specify the start up directory. (The default 
     directory when you first load, save or import data via the 
     <menu tag="file"/> menu.) You can set this to your home directory,
     the <term tag="cwd"/>, the directory you last used on the previous run
     of <app/> or you can specify a<nbsp/>directory of your choice.
     </p>
     <p>
     In this tab you can also specify the number of iterations to use in
     a<nbsp/>shuffle operation (equivalent to <opt tag="shuffle-iterations"/>)
     and, optionally, a<nbsp/>seed for the random number generator 
     (equivalent to <opt tag="seed"/>).
     </p>
    </dd>
    <dt><button tag="preferences.csv"/></dt>
    <dd>
     (<ref tag="prefcsv"/>)
     <float type="figure" tag="prefcsv" caption="CSV Tab" pos="htbp">
      <image scale="0.75" alt="Image of the csv tab of the preferences dialog box" src="images/pref-csv.png" />
     </float>
     <p>
     In this tab you can specify the separator character. If the separator is
     a<nbsp/>tab character, select the 
     <button tag="preferences.csv.tabsep"/> radio button. Otherwise
     select the <button tag="preferences.csv.sepchar"/> radio button
     and enter the character in the neighbouring text box. Set the delimiter
     in the <button tag="preferences.csv.delim"/> field. Check the
     <button tag="preferences.csv.hasheader"/> button if your 
     <acr tag="csv"/> files have a<nbsp/>header row otherwise uncheck it.
     </p>
    </dd>
    <dt><button tag="preferences.sql"/></dt>
    <dd>
     (<ref tag="prefsql"/>)
     <float type="figure" tag="prefsql" caption="SQL Tab" pos="htbp">
      <image scale="0.75" alt="Image of the SQL tab of the preferences dialog box" src="images/pref-sql.png" />
     </float>
    <p>
    In this tab, you can specify the <acr tag="sql"/> connection information.
    Enter the host name and port number the <acr tag="sql"/> server is 
    running on in the <button tag="preferences.sql.host"/> and 
    <button tag="preferences.sql.port"/> fields. Currently, the only
    available prefix is <dq>jdbc:mysql://</dq>, which is the JDBC driver for
    <term tag="mysql"/>. If you are using another driver or <acr tag="sql"/> 
    database, you'll have to add the relevant library to the <tt>lib</tt>
    directory and add it to the class path used by <tt>datatooltk.jar</tt>.
    Enter the name of the database you want to connect to in the 
    <button tag="preferences.sql.database"/> field and the associated
    user name in the <button tag="preferences.sql.user"/> field.
    If you want the password wiped from memory as soon as a<nbsp/>connection
    has been made, make sure the <button tag="preferences.sql.wipe"/>
    box has been selected.
    </p>
    </dd>
    <dt><button tag="preferences.tex"/></dt>
    <dd>
     (<ref tag="preftex"/>)
     <float type="figure" tag="preftex" caption="TeX Tab" pos="htbp">
      <image scale="0.75" alt="Image of the tex tab of the preferences dialog box" src="images/pref-tex.png" />
     </float>
    <p>
    In this tab you can specify whether or not to map <TeX/> special 
    characters when you import data from <acr tag="csv"/> or <acr tag="sql"/>.
    If you want the mapping, make sure the <button tag="preferences.tex.map"/>
    box is checked. If it is checked, the performed mappings are listed
    in the table in the tab. To add another mapping, click on the
    <button tag="preferences.tex.add_map"/> button, which opens the 
    dialog box shown in <ref tag="addmap"/>.
    </p>
     <float type="figure" tag="addmap" caption="Add Mapping Dialog" pos="htbp">
      <image scale="0.75" alt="Image of the add mapping dialog box" src="images/addmap.png" />
     </float>
    <p>
    To remove a<nbsp/>mapping, select the unwanted mapping and click on 
    <button tag="preferences.tex.remove_map"/>. To edit a<nbsp/>mapping,
    select the mapping and click on <button tag="preferences.tex.edit_map"/>.
    </p>
    <p>
    <LaTeX/> is used to help <app/> import data from 
    a<nbsp/><sty>probsoln</sty> dataset. If the <tt>latex</tt> executable 
    isn't on the system path, you will have to specify its full location
    in the <button tag="preferences.tex.latexapp"/> field. You can use
    the ellipsis button next to the field to browse your filing system.
    </p>
    </dd>
    <dt><button tag="preferences.currencies"/></dt>
    <dd>
     (<ref tag="prefcurrencies"/>)
     <float type="figure" tag="prefcurrencies" caption="Currencies Tab" pos="htbp">
      <image scale="0.75" alt="Image of the currencies tab of the preferences dialog box" src="images/pref-currencies.png" />
     </float>
    <p>
    If you want to identify a<nbsp/>column as a<nbsp/>currency type, you 
    must make sure that <app/> recognises the <LaTeX/> command to typeset
    your currency. Known currency commands are listed in the 
    <button tag="preferences.currencies"/> tab. If you add any currencies
    to the list, remember to add them in your document as well with 
    <cs tag="DTLnewcurrencysymbol"/>.
    </p>
    </dd>
    <dt><button tag="preferences.display"/></dt>
    <dd>
     (<ref tag="prefdisplay"/>)
     <float type="figure" tag="prefdisplay" caption="Display Tab" pos="htbp">
      <image scale="0.75" alt="Image of the display tab of the preferences dialog box" src="images/pref-display.png" />
     </float>
    <p>
    The default font used in cell entries is a monospaced font. This can be
    changed using the <button tag="preferences.display.font"/> drop-down menu.
    You can also set the font size in the 
    <button tag="preferences.display.fontsize"/> field. By default, each
    string cell has a<nbsp/>maximum of four lines visible in the main window.
    (Real and integer columns only have a<nbsp/>single line visible.) This
    number can be changed in the <button tag="preferences.display.cellheight"/>
    field. Each column has a<nbsp/>default width that depends on the data type
    for that column. The values are listed in the 
    <button tag="preferences.display.cellwidths"/> area. These can be changed
    as required.
    </p>
    </dd>
    <dt><button tag="preferences.language"/></dt>
    <dd>
     (<ref tag="preflanguage"/>)
     <float type="figure" tag="preflanguage" caption="Language Tab" pos="htbp">
      <image scale="0.75" alt="Image of the language tab of the preferences dialog box" src="images/pref-language.png" />
     </float>
    <p>
    The language used by the manual accessed via <menu tag="help.manual"/>
    can be set from the <button tag="preferences.language.helpset"/> drop-down 
    list. The language used in the messages, menu items, buttons and 
    <acr tag="gui"/> labels can be set from the 
    <button tag="preferences.language.dictionary"/> drop-down 
    list. Note that you have to restart <app/> for these changes to take 
    effect.
    </p>
    </dd>
    <dt><button tag="preferences.plugins"/></dt>
    <dd>
     (<ref tag="prefplugins"/>)
     <float type="figure" tag="prefplugins" caption="Plugins Tab" pos="htbp">
      <image scale="0.75" alt="Image of the plugins tab of the preferences dialog box" src="images/pref-plugins.png" />
     </float>
    <p>
    In order to use <app/> plugins, you must have Perl installed (and the
    Perl Tk module). If the Perl executable is on your path, you can just
    specify it as <tt>perl</tt> in the <button tag="preferences.plugins.perl"/>
    field of the <dict tag="preferences.plugins"/> tab. If it's not on your
    path, you will have to specify the full path name in this tab. You can
    use the ellipsis button to browse your filing system.
    </p>
    </dd>
   </dl>
   </node>
   <node type="chapter" tag="licence" title="Licence" >
   <p>
   <app/> is licensed under the terms of the GNU General Public License.
   <app/> depends on the following third party libraries whose jar files are
   in the <tt>lib</tt> directory: Java Help 
   (<url www="https://javahelp.java.net/"/>),
   Open CSV (<url www="http://opencsv.sourceforge.net/"/>),
   MySQL connector (<url www="http://dev.mysql.com/downloads/connector/j/"/>)
   and the Java Look and Feel Graphics Repository
   (<url www="http://www.oracle.com/technetwork/java/index-138612.html"/>).
   </p>
     <verbtabinput src="LICENSE"/>
   </node>
   <printglossary />
   <printacronyms />
   <printindex />
  </document>
</manual>
