path: root/support/datatooltk/datatooltk.1

.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.29)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "DATATOOLTK 1"
.TH DATATOOLTK 1 "2018-01-21" "perl v5.18.4" "datatooltk"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fBdatatooltk\fR [\fIoption\fR]+
.PP
or
.PP
\&\fBdatatooltk-gui\fR [\fIoption\fR]+
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Reads and writes \fB.dbtex\fR files for use with the \fBdatatool\fR LaTeX
package. This application can also import data from \s-1CSV\s0 files,
spreadsheets (\fB.ods\fR or \fB.xls\fR), \s-1SQL \s0(only MySQL supported) or
\&\fB.tex\fR files that define problems using the \fBprobsoln\fR package.
The use of this application as a helper for the \fBdatatool\fR package
can significantly speed document build time.
.PP
The \fBdatatooltk\fR application can be run in either batch mode or \s-1GUI\s0
mode.
.SH "OPTIONS"
.IX Header "OPTIONS"
Some of the options may have the default settings change through the
\&\s-1GUI\s0 interface. You can't combine any of the load/import options:
\&\fB\-\-in\fR, \fB\-\-csv\fR, \fB\-\-xls\fR, \fB\-\-ods\fR, \fB\-\-sql\fR, \fB\-\-probsoln\fR. You
also can't combine any of the merge options: \fB\-\-merge\fR,
\&\fB\-\-merge\-csv\fR, \fB\-\-merge\-xls\fR, \fB\-\-merge\-ods\fR, \fB\-\-merge\-sql\fR, 
\&\fB\-\-merge\-probsoln\fR. The merge import options use the same settings
as the import options. See the \fBdatatooltk\fR user manual for further
details.
.IP "\fB\-\-gui\fR (or \fB\-g\fR)" 4
.IX Item "--gui (or -g)"
Invoke \fBdatatooltk\fR in \s-1GUI\s0 mode. The command line invocation
.Sp
\&\fBdatatooltk-gui\fR [\fIoption\fR]+
.Sp
is equivalent to
.Sp
\&\fBdatatooltk\fR \fB\-\-gui\fR [\fIoption\fR]+
.Sp
but additionally has a splash screen.
.IP "\fB\-\-batch\fR (or \fB\-b\fR)" 4
.IX Item "--batch (or -b)"
Invoke \fBdatatooltk\fR in batch mode.
.IP "\fB\-\-output\fR \fIfilename\fR (or \fB\-o\fR \fIfilename\fR)" 4
.IX Item "--output filename (or -o filename)"
Save the database to \fIfilename\fR (batch mode only).
.IP "\fB\-\-in\fR \fIfilename\fR (or \fB\-i\fR \fIfilename\fR)" 4
.IX Item "--in filename (or -i filename)"
Load \fIfilename\fR which must be a file that can be loaded in a
document using \fB\einput\fR or \fB\eDTLloaddbtex\fR.
.IP "\fB\-\-tex\-encoding\fR \fIencoding\fR" 4
.IX Item "--tex-encoding encoding"
Set the encoding for the TeX (\fB.tex\fR and \fB.dbtex\fR) files to 
\&\fIencoding\fR. The \fIencoding\fR may be the keyword \fBdefault\fR
or an empty string to indicate the default file encoding (as
understood by the Java Virtual Machine). Make sure that your LaTeX
document matches the given encoding.
.IP "\fB\-\-name\fR \fIname\fR" 4
.IX Item "--name name"
If used with \fB\-\-in\fR, \fB\-\-csv\fR, \fB\-\-sql\fR, \fB\-\-xls\fR, \fB\-\-ods\fR
or \fB\-\-probsoln\fR this sets the database label to \fIname\fR.
.IP "\fB\-\-version\fR (or \fB\-v\fR)" 4
.IX Item "--version (or -v)"
Print the version details to \s-1STDOUT\s0 and exit.
.IP "\fB\-\-help\fR (or \fB\-h\fR)" 4
.IX Item "--help (or -h)"
Print a brief summary of available options to \s-1STDOUT\s0 and exit.
.IP "\fB\-\-debug\fR" 4
.IX Item "--debug"
Enable debug mode.
.IP "\fB\-\-nodebug\fR" 4
.IX Item "--nodebug"
Disable debug mode.
.IP "\fB\-\-compat\fR \fIlevel\fR" 4
.IX Item "--compat level"
Set the compatibility level. The argument \fIlevel\fR may be \fBlatest\fR
or \fB1.6\fR. The \fB1.6\fR setting only affects \fB\-\-shuffle\fR and is
provided for old documents.
.IP "\fB\-\-owner\-only\fR" 4
.IX Item "--owner-only"
Set read/write permissions when saving \fB.dbtex\fR files to owner
only. (Has no effect on some operating systems.)
.IP "\fB\-\-noowner\-only\fR" 4
.IX Item "--noowner-only"
Don't change read/write permissions when saving \fB.dbtex\fR files.
.IP "\fB\-\-map\-tex\-specials\fR" 4
.IX Item "--map-tex-specials"
Map TeX special characters when importing data from \s-1CSV\s0 or \s-1SQL.\s0
.IP "\fB\-\-nomap\-tex\-specials\fR" 4
.IX Item "--nomap-tex-specials"
Don't map TeX special characters when importing data from \s-1CSV\s0 or
\&\s-1SQL.\s0
.IP "\fB\-\-seed\fR \fInumber\fR" 4
.IX Item "--seed number"
Set the random generator seed to \fInumber\fR or clear if if \fInumber\fR
is the empty string.
.IP "\fB\-\-shuffle\fR" 4
.IX Item "--shuffle"
Shuffle the database. (Always performed after \fB\-\-sort\fR regardless
of the option order.)
.IP "\fB\-\-noshuffle\fR" 4
.IX Item "--noshuffle"
Don't shuffle the database.
.IP "\fB\-\-sort\fR [\fIprefix\fR]\fIfield\fR" 4
.IX Item "--sort [prefix]field"
Sort the database according to the column whose label is \fIfield\fR.
Optionally, \fIprefix\fR may be \fB+\fR (ascending order) or \fB\-\fR (descending
order). If \fIprefix\fR is omitted, ascending is assumed.
.IP "\fB\-\-sort\-locale\fR \fIvalue\fR" 4
.IX Item "--sort-locale value"
If the \fIvalue\fR is \fBnone\fR then use letter-sorting for strings.
(That is, compare the Unicode values for each character.) Otherwise
\&\fIvalue\fR should be a valid \s-1IETF\s0 language tag that identifies the
locale to sort by.
.IP "\fB\-\-sort\-case\-sensitive\fR" 4
.IX Item "--sort-case-sensitive"
Use case-sensitive comparison when letter-sorting strings. (Ignored
with locale-sensitive comparisons.)
.IP "\fB\-\-sort\-case\-insensitive\fR" 4
.IX Item "--sort-case-insensitive"
Use case-insensitive comparison when letter-sorting strings. (Ignored
with locale-sensitive comparisons.)
.IP "\fB\-\-truncate\fR \fIn\fR" 4
.IX Item "--truncate n"
Truncate the database to the first \fIn\fR rows. Truncation is always 
performed last (after any sorting, shuffling and filtering).
.IP "\fB\-\-filter\fR \fIkey\fR \fIoperator\fR \fIvalue\fR" 4
.IX Item "--filter key operator value"
Adds the given filter. This filter returns true if the value in the
column whose label is given by \fIkey\fR matches the operation 
\&\fIoperator\fR \fIvalue\fR where \fIoperator\fR may be one of: \fBeq\fR (equals), 
\&\fBne\fR (does not equal), \fBle\fR (less than or equal to), \fBlt\fR (less
than), \fBge\fR (greater than or equal to), \fBgt\fR (greater than) or
\&\fBregex\fR (matches the regular expression given by \fIvalue\fR).
.Sp
Filtering is always performed after sorting and shuffling (when
those actions are specified). Numerical comparisons are used for
columns identified as containing numerical data otherwise string
comparisons are used, except in the case of \fBregex\fR where the data
type is disregarded and all values are assumed to be strings.
.Sp
This option may be used multiple times.
.IP "\fB\-\-filter\-or\fR" 4
.IX Item "--filter-or"
Use \s-1OR\s0 operator when filtering. (Has no effect with only one
instance of \fB\-\-filter\fR.)
.IP "\fB\-\-filter\-and\fR" 4
.IX Item "--filter-and"
Use \s-1AND\s0 operator when filtering. (Has no effect with only one
instance of \fB\-\-filter\fR.)
.IP "\fB\-\-filter\-include\fR" 4
.IX Item "--filter-include"
When filtering, only retain rows that match the filter. Non-matching
rows are discarded.
.IP "\fB\-\-filter\-exclude\fR" 4
.IX Item "--filter-exclude"
When filtering, only retain rows that don't match the filter.
Matching rows are discarded.
.IP "\fB\-\-merge\fR \fIkey\fR \fIdb file\fR" 4
.IX Item "--merge key db file"
Merges the input or imported database with the database stored in
the given \fBdb file\fR. Each row in \fBdb file\fR is merged with the row
that has a matching value in the column whose label is given by
\&\fIkey\fR. Both databases must contain a column with that label.
If both databases share additional columns, the values in \fIdb file\fR
override those in the original database. This options is always
implemented before any sorting, shuffling, filtering or truncating.
Only one of the merge options is permitted.
.IP "\fB\-\-csv\fR \fIcsv file\fR" 4
.IX Item "--csv csv file"
Import data from the given \s-1CSV\s0 file.
.IP "\fB\-\-merge\-csv\fR \fIkey\fR \fIcsv file\fR" 4
.IX Item "--merge-csv key csv file"
As \fB\-\-merge\fR but the data to be merged is imported from the given
\&\s-1CSV\s0 file.
.IP "\fB\-\-csv\-sep\fR \fIcharacter\fR" 4
.IX Item "--csv-sep character"
Specify the character used to separate values in the \s-1CSV\s0 file.
.IP "\fB\-\-csv\-delim\fR \fIcharacter\fR" 4
.IX Item "--csv-delim character"
Specify the character used to delimit values in the \s-1CSV\s0 file.
.IP "\fB\-\-csv\-skiplines\fR \fIn\fR" 4
.IX Item "--csv-skiplines n"
Skip the first \fIn\fR rows from the start of the \s-1CSV\s0 file.
The \fIn\fR may be 0 (don't skip any rows) or a positive
integer indicating the number of rows to skip.
.IP "\fB\-\-csv\-strictquotes\fR" 4
.IX Item "--csv-strictquotes"
Ignore any data that hasn't been delimited (by the character
identified with \fB\-\-csv\-delim\fR).
.IP "\fB\-\-nocsv\-strictquotes\fR" 4
.IX Item "--nocsv-strictquotes"
Allow undelimited values.
.IP "\fB\-\-csv\-encoding\fR \fIencoding\fR" 4
.IX Item "--csv-encoding encoding"
Set the encoding for the \s-1CSV\s0 files to \fIencoding\fR. The value may
be \fBdefault\fR or the empty string to indicate the default (as
recognised by the Java Virtual Machine). This setting is independent
of the TeX file encoding.
.IP "\fB\-\-csv\-header\fR" 4
.IX Item "--csv-header"
The \s-1CSV\s0 file has a header row.
.IP "\fB\-\-nocsv\-header\fR" 4
.IX Item "--nocsv-header"
The \s-1CSV\s0 file doesn't have a header row.
.IP "\fB\-\-csv\-escape\fR \fIcharacter\fR" 4
.IX Item "--csv-escape character"
Set the \s-1CSV\s0 file escape character to \fIcharacter\fR.
.IP "\fB\-\-nocsv\-escape\fR" 4
.IX Item "--nocsv-escape"
Don't have an escape character for the \s-1CSV\s0 file.
.IP "\fB\-\-xls\fR \fIxls file\fR" 4
.IX Item "--xls xls file"
Import data from the given Excel \fB.xls\fR file.
.IP "\fB\-\-merge\-xls\fR \fIkey\fR \fIxls file\fR" 4
.IX Item "--merge-xls key xls file"
As \fB\-\-merge\fR but the data to be merged is imported from the given
Excel file.
.IP "\fB\-\-ods\fR \fIods file\fR" 4
.IX Item "--ods ods file"
Import data from the given Open Document Spreadsheet \fB.ods\fR file.
.IP "\fB\-\-merge\-ods\fR \fIkey\fR \fIods file\fR" 4
.IX Item "--merge-ods key ods file"
As \fB\-\-merge\fR but the data to be merged is imported from the given
Open Document Spreadsheet \fB.ods\fR file.
.IP "\fB\-\-sheet\fR \fIsheet id\fR" 4
.IX Item "--sheet sheet id"
The sheet to select from the Excel workbook or Open Document
Spreadsheet. The \fIsheet id\fR may be either an index (starting from 0) 
or the name of the sheet. If this option is omitted, the first sheet
is assumed.
.IP "\fB\-\-sql\fR \fIstatement\fR" 4
.IX Item "--sql statement"
Import data from an \s-1SQL\s0 database where \fIstatement\fR is a \s-1SELECT\s0
statement.
.IP "\fB\-\-merge\-sql\fR \fIkey\fR \fIstatement\fR" 4
.IX Item "--merge-sql key statement"
As \fB\-\-merge\fR but the data to be merged is imported using the given
\&\s-1SQL\s0 statement.
.IP "\fB\-\-sqldb\fR \fIname\fR" 4
.IX Item "--sqldb name"
The \s-1SQL\s0 database name.
.IP "\fB\-\-sqlprefix\fR \fIprefix\fR" 4
.IX Item "--sqlprefix prefix"
The Java \s-1SQL\s0 prefix. Currently only MySQL is supported.
.IP "\fB\-\-sqlport\fR \fIport\fR" 4
.IX Item "--sqlport port"
The \s-1SQL\s0 port number.
.IP "\fB\-\-sqlhost\fR \fIhost\fR" 4
.IX Item "--sqlhost host"
The \s-1SQL\s0 host.
.IP "\fB\-\-sqluser\fR  \fIuser name\fR" 4
.IX Item "--sqluser user name"
The \s-1SQL\s0 user name.
.IP "\fB\-\-sqlpassword\fR \fIpassword\fR" 4
.IX Item "--sqlpassword password"
(Insecure!) The \s-1SQL\s0 password. If omitted, you will be prompted for
the password if you try to import data from an \s-1SQL\s0 database.
.IP "\fB\-\-wipepassword\fR" 4
.IX Item "--wipepassword"
For extra security, wipe the password from memory as soon as it has
been connected to an \s-1SQL\s0 database.
.IP "\fB\-\-nowipepassword\fR" 4
.IX Item "--nowipepassword"
Don't wipe the password from memory as soon as it has been used to
connect to an \s-1SQL\s0 database.
.IP "\fB\-\-noconsole\-action\fR \fIaction\fR" 4
.IX Item "--noconsole-action action"
If in batch mode and an \s-1SQL\s0 password is required and \fB\-\-sqlpassword\fR
hasn't been used, the default action is for \fBdatatooltk\fR to request
a password via the console. If there is no console available the
action is determined by \fIaction\fR which may be one of:
.RS 4
.IP "\fBerror\fR" 4
.IX Item "error"
Issue an error;
.IP "\fBstdin\fR" 4
.IX Item "stdin"
Request the password via \s-1STDIN \s0(less secure than a console and can 
produce an annoying flicker);
.IP "\fBgui\fR" 4
.IX Item "gui"
Display a dialog box in which to enter the password.
.RE
.RS 4
.RE
.IP "\fB\-\-probsoln\fR \fIfilename\fR" 4
.IX Item "--probsoln filename"
Import \fBprobsoln.sty\fR data from \fIfilename\fR.
.IP "\fB\-\-merge\-probsoln\fR \fIkey\fR \fIfilename\fR" 4
.IX Item "--merge-probsoln key filename"
As \fB\-\-merge\fR but the data to be merged is imported from the given
\&\fBprobsoln.sty\fR file.
.SH "REQUIRES"
.IX Header "REQUIRES"
Java 7 and also Perl if plugins are required.
.SH "LICENSE"
.IX Header "LICENSE"
License GPLv3+: \s-1GNU GPL\s0 version 3 or later
<http://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it.
There is \s-1NO WARRANTY,\s0 to the extent permitted by law.
.SH "RECOMMENDED READING"
.IX Header "RECOMMENDED READING"
The datatooltk manual (available as a \s-1PDF\s0 or through the \s-1GUI\s0).
.PP
The datatool manual:
.PP
.Vb 1
\&        texdoc datatool
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
Nicola L. C. Talbot,
<http://www.dickimaw\-books.com/>