=head1 SYNOPSIS

B<datatool2bib> [I<option>]+ I<in-file> I<bibfile>

=head1 DESCRIPTION

Converts a F<.tex> file containing F<datatool.sty> databases to 
a F<.bib> file in the format required for B<bib2gls>. 
Distributed with F<bib2gls>.

The TeX Parser Library is used to parse the input, which may be 
a DTLTEX or DBTEX file or a file that contains
database construction commands, such as 
C<\DTLnewdb> or C<\DTLaction>. The input file may also be a CSV file
if used with B<--read>.

The B<datatool> and B<datagidx> are automatically implemented so the
input file does not need to include either them with C<\usepackage>.
In general, it's best not to include the entire document but instead
input a file that just contains the database construction commands,
as the TeX Parser Library only has a limited set of commands that it
recognises.

=head1 OPTIONS

=head2 GENERAL OPTIONS

=over 4

=item B<--help> or B<-h>

Display help message and exit.

=item B<--version> or B<-v>

Display version information and exit.

=item B<--silent> or B<--quiet> or B<-q>

Suppress all messages except for errors.

=item B<--verbose>

Switch on verbose mode.

=item B<--no-verbose>

Switch off verbose mode.

=item B<--debug> [I<n>]

Display debugging messages.

=item B<--debug-mode> I<setting>

May be used instead of B<--debug> where the level number is
difficult to remember. Value same as for B<bib2gls>'s
B<--debug-mode> option.

=item B<--no-debug>

Switch off debugging mode. Equivalent to B<--debug> B<0>.

=item B<--log-file> I<filename>

Log messages to given file. Intended primarily for debugging messages so
enabling debug mode will automatically create a transcript file, but otherwise
a file won't be created unless this option is used.

=back

=head2 ENCOSING AND LOCALISATION OPTIONS

=over 4

=item B<--texenc> I<name>

Set the character encoding to I<name> for the input B<.tex> files.

=item B<--bibenc> I<name>

Set the character encoding to I<name> for the output B<.bib> files.

=item B<--locale> I<lang tag>

Use the language resource files associated with the given language
tag I<lang tag>. If there isn't an appropriate file, the B<en>
(English) file will be used.

=back

=head2 FILTERING OPTIONS

=over 4

=item B<--preamble-only> or B<-p>

Only parse the document preamble. That is, stop parsing if
C<\begin{document}> encountered.

=item B<--no-preamble-only>

Parse the entire document (default).

=item B<--ignore-fields> I<list> or B<-f> I<list>

Ignore all the fields in the comma-separated I<list>. 
Each item in the list should identify
the field by its original case-sensitive column key.

This option is cumulative.

=item B<--no-ignore-fields>

Cancels the effect of B<--ignore-fields>.

=item B<--skip-datagidx>

Skip the special B<datagidx> internal database.
(Default.)

=item B<--no-skip-datagidx>

Don't skip the special B<datagidx> internal database.

=back

=head2 OUTPUT FILE OPTIONS

=over 4

=item B<--overwrite>

Overwrite existing .bib files.

=item B<--no-overwrite>

Don't overwrite existing .bib files.

=item B<--split>

Split the entries into separate files according to the database.

=item B<--no-split>

Don't split the entries into separate files (default).

=back

=head2 ADJUSTMENT OPTIONS

=over 4

=item B<--space-sub> I<value> or B<-s> I<value>

Substitute spaces in labels with I<value>.

=item B<--field-map> I<mappings> or B<-m> I<mappings>

Add source column key to destination field label mappings. The argument
should be a comma-separated list of I<col-key>=I<bib-field>
pairs. This option is cumulative.

=item B<--no-field-map>

Cancels all mappings applied with B<--field-map>.

=item B<--index-conversion> or B<-i>

Any entries that would normally be converted to C<@entry> that don't
have a B<description> field will be converted to C<@index>.

=item B<--no-index-conversion> 

Don't replace C<@entry> with C<@index> if the description is missing (default).

=item B<--detect-symbols>

Attempt to detect entries that should be C<@symbol> or C<@number>
based on the value of the B<name> field.

=item B<--no-detect-symbols>

Don't attempt symbol detection (default).


=item B<--label> I<col-key> or B<-L>

Use column identified by I<col-key> for the entry label. The default
column key is B<Label> so if the database doesn't have a column with
this key, you will either need to specify a column with B<--label>
or use B<--auto-label>. This option is ignored with B<--auto-label>.

=item B<--auto-label> or B<-a>

Auto-generate entry labels instead of using a column value.

=item B<--no-auto-label>

Don't auto-generate entry labels. Use the column identified by
B<--label> for the entry label. (Default.)

=item B<--auto-label-prefix> I<prefix>

Use I<prefix> when auto-generating entry labels. Ignored with
B<--no-auto-label>.

=item B<--adjust-gls>

Adjust labels in commands like C<\gls> in field values. (Default.)
This will also replace the F<datagidx.sty> commands like C<\glsnl>
with the closest F<glossaries.sty> equivalent.

=item B<--no-adjust-gls>

Don't adjust labels in commands like C<\gls> in field values.

=item B<--dependency-field> I<field-name>

Sets the name of the dependency field. Has no effect with
B<--no-strip-glsadd>. With B<--strip-glsadd>, the label from the
stripped C<\glsadd> argument will be added to the field identified
by I<field-name>. The default is B<dependency> which will be ignored
by B<bib2gls> unless instructed otherwise (via field aliasing etc).

=item B<--no-dependency-field>

Don't save labels from any stripped C<\glsadd> instances.

=item B<--strip>

Switch on all strip options.

=item B<--no-strip>

Switch off all strip options.

=item B<--strip-glsadd>

Strip C<\glsadd> and its argument from field values. (Default.)

=item B<--no-strip-glsadd>

Don't strip C<\glsadd> from field values.

=item B<--strip-acronym-font>

Strip C<\acronymfont> from field values. (Default.)

=item B<--no-strip-acronym-font>

Don't strip C<\acronymfont> from field values.

=item B<--strip-acronym-text>

Strip B<text> field for acronyms identified by C<\newacro>.
(Default.)

=item B<--no-strip-acronym-text>

Don't strip B<text> field for acronyms.

=item B<--strip-acronym-name>

Strip B<name> field for acronyms identified by C<\newacro>.
(Default.)

=item B<--no-strip-acronym-name>

Don't strip B<name> field for acronyms.

=item B<--strip-case-change>

Strip known case-changing commands (such as C<\makefirstuc> or C<\capitalisewords>)
from field values.

=item B<--nostrip-case-change>

Don't strip case-changing commands.  (Default.)

=back

=head2 OTHER OPTIONS

These options correspond to features introduced to F<datatool.sty>
version 3.0, which has a setting that stores the numeric value and
currency symbol (where applicable) when parsing data. The original
string (formatted number), numeric value and currency symbol are
stored in a special datum format, which ordinarily expands to its
original formatted text but also allows the previously parsed
information to be easily extracted without having to reparse the
data.

=over 4

=item B<--setup> I<options>

Implement C<\DTLsetup{>I<options>C<}> at the start. This can include
options such as C<store-datum>, C<new-value-expand>,
C<new-value-trim> and C<default-name>.

=item B<--read> I<options>

Instead of simply parsing the input file as a normal F<.tex> file,
the source is presented to the TeX parser as 
C<\DTLread[>I<options>C<]{>I<in-file>C<}> where the options can be
used to specify the file format (for example, C<format=tsv>).

If the I<options> list is empty (after trimming white space) then
this becomes equivalent to B<--no-read>.

=item B<--no-read>

The input file is parsed as a normal F<.tex> file, which may be the
complete document or a file that can be C<\input> into a document.
(Default.)

=item B<--save-value> I<suffix>

If a field value is parsed and identified as numeric, the
unformatted numeric value will be saved in a field whose name is
constructed from the original field name followed by the given
I<suffix>.

=item B<--no-save-value>

Don't save numeric value in a separate field. (Default.)

=item B<--save-currency> I<suffix>

If a field value is parsed and identified as currency data, the
currency symbol will be saved in a field whose name is
constructed from the original field name followed by the given
I<suffix>.

=item B<--no-save-currency>

Don't save currency symbol in a separate field. (Default.)

=item B<--save-datum>

Equivalent to:

	--save-value '-value' --save-currency '-currency'

=item B<--no-save-datum>

Equivalent to B<--no-save-value> B<--no-save-currency>.

=back

=head1 REQUIRES

Java 8 and a TeX distribution.

=head1 LICENSE

License GPLv3+: GNU GPL version 3 or later
<http://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.

=head1 RECOMMENDED READING

The bib2gls manual:

        texdoc bib2gls

The glossaries-extra manual:

        texdoc glossaries-extra

The glossaries manual:

        texdoc glossaries

The datatool manual:

        texdoc datatool

=head1 AUTHOR

Nicola L. C. Talbot,
L<https://www.dickimaw-books.com/>

=cut

