summaryrefslogtreecommitdiff
path: root/support/datatooltk/datatooltk.1
diff options
context:
space:
mode:
Diffstat (limited to 'support/datatooltk/datatooltk.1')
-rw-r--r--support/datatooltk/datatooltk.1454
1 files changed, 454 insertions, 0 deletions
diff --git a/support/datatooltk/datatooltk.1 b/support/datatooltk/datatooltk.1
new file mode 100644
index 0000000000..c92471337a
--- /dev/null
+++ b/support/datatooltk/datatooltk.1
@@ -0,0 +1,454 @@
+.\" 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/>