path: root/support/bib2gls/src/bib2gls.pod

=head1 SYNOPSIS

B<bib2gls> [I<option>]+ I<auxfile>

=head1 DESCRIPTION

B<bib2gls> is designed to work with the B<glossaries-extra> LaTeX
package. (The B<record> package option is required.) The application
performs two functions in one: (1) selects entries from .bib files
according to information found in the I<auxfile> (similar to
B<bibtex>); (2) hierarchically sorts entries and collates location
lists (similar to B<makeindex> and B<xindy>). The .aux extension may
be omitted from I<auxfile>.

=head1 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<--debug> [I<level>]

Switch on the debug mode (optionally at the given I<level>, which
should be a non-negative integer). If I<level> is B<0> then the
debug mode is switched off.

=item B<--no-debug> (or B<--nodebug>)

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

=item B<--verbose>

Switch on verbose mode.

=item B<--no-verbose> (or B<--noverbose>)

Switch off verbose mode. (Some messages will still be written to
STDOUT.)

=item B<--silent>

Only display error messages. All other messages are just written to
the transcript file.

=item B<--locale> I<lang> (or B<-l> I<lang>)

Use language resource file for I<lang> (which should be an IETF
locale tag). 

=item B<--log-file> I<file> (or B<-t> <file>)

Set the transcript file.

=item B<--dir> I<directory> (or B<-d> <directory>)

Files are relative to I<directory>. (This doesn't change the current
working directory.)

=item B<--tex-encoding> I<name>

Set the character encoding for the output files. This overrides the
setting given in I<auxfile>.

=item B<--interpret>

Use the TeX parser library to interpret known (La)TeX commands
(default).

=item B<--no-interpret>

Don't try interpreting (La)TeX commands.

=item B<--break-space>

Interpret tilde character and \nobreakspace as a normal space.

=item B<--no-break-space>

Interpret tilde and \nobreakspace as a non-breaking space (default).

=item B<--cite-as-record>

Treat B<\citation> as an ignored record.

=item B<--no-cite-as-record>

Don't check for instances of B<\citation> in the B<.aux> file (default).

=item B<--warn-non-bib-fields>

Warn if internal non-bib fields are found in the .bib file.

=item B<--no-warn-non-bib-fields>

Don't warn if internal non-bib fields are found in the .bib file.
The use of these internal fields can cause unexpected results, so
only use this option if you have taken appropriate precautions.

=item B<--warn-unknown-entry-types>

Warn if any unknown entry types are found in the .bib file.

=item B<--no-warn-unknown-entry-types>

Don't warn if any unknown entry types are found in the .bib file.

=item B<--merge-wrglossary-records>

Merge an entry's B<wrglossary> records for the same page locations.
(For use with the B<indexcounter> package option.)

=item B<--no-merge-wrglossary-records>

Don't merge an entry's B<wrglossary> records.

=item B<--merge-nameref-on> I<rule>

Rule for merging locations created with the record=nameref package option
(requires glossaries-extra.sty version 1.37+). The I<rule> may be
one of: B<hcounter>, B<href>, B<title> or B<location>.

=item B<--force-cross-resource-refs> or B<-x>

Force cross-resource referencing mode on.

=item B<--no-force-cross-resource-refs>

Don't force cross-resource referencing mode on (default).

=item B<--support-unicode-script>

Text superscript (\textsuperscript) or subscripts (\textsubscript)
will use Unicode superscript/subscript characters if available.
For example, \textsuperscript{2} will be converted to U+00B2
(superscript two).

=item B<--no-support-unicode-script>

Text superscript (\textsuperscript) or subscripts (\textsubscript)
won't be converted to Unicode superscript/subscript characters.
For example, \textsuperscript{2} will be converted to <sup>2</sup>
and the markup will be stripped leaving just the character 2.

=item B<--packages> I<list> (or B<-p> I<list>)

Instruct the TeX parser library to pretend the packages listed 
in I<list> have been used by the document. Note that there's only a
limited number of packages supported by the TeX parser library.
This option has a cumulative action so B<--packages wasysym,pifont>
is the same as B<--packages wasysym --packages pifont>.

You can find out the list of supported packages with
B<--list-known-packages>.

=item B<--custom-packages> I<list>

Instruct the TeX parser library to attempt to parse the 
packages listed in I<list>. This is intended for simple custom
packages that don't contain complex code.

=item B<--ignore-packages> I<list> (or B<-k> I<list>)

Don't parse the log file for the packages listed in I<list>. Note
that B<--packages> overrides this option, so if the same package is
listed in both B<--ignore-packages> and B<--packages> then the
interpreter will check if it's supported. This option has a
cumulative action. Only known packages may be included in
I<list>.

=item B<--list-known-packages>

Lists all the packages that have are known to the TeX parser
library and then exits (with exit code 0). Any of the listed
packages may be used in B<--packages> or B<--ignore-packages>.

=item B<--mfirstuc-protection> I<fields>|B<all> (or B<-u> I<fields>|B<all>)

Insert an empty group if fields start with certain problematic
commands to protect against case-changing commands like \Gls.

The default is to do this for all fields.  To do this for only a
subset of fields, set I<fields> to a comma-separated list of fields
(e.g. B<name,short,long>).  The keyword B<all> indicates all fields.

=item B<--no-mfirstuc-protection>

Switch off the auto-insertion of an empty group for all fields.

=item B<--mfirstuc-math-protection>

Switch on the auto-insertion of an empty group for math-shift ($).
This option will be overridden by B<--no-mfirstuc-protection>.

=item B<--no-mfirstuc-math-protection>

Switch off the auto-insertion of an empty group for math-shift ($).

=item B<--nested-link-check> I<list>|B<none>

Check each field listed in I<list> for potentially problematic
nested link text. (Default list: name, text, plural, first,
firstplural, short, shortplural, long, longplural, symbol).

If B<none>, disable check.

=item B<--no-nested-link-check>

Don't check for potentially problematic nested link text.
(Equivalent to B<--nested-link-check> B<none>)

=item B<--shortcuts> I<option>

Check for the shortcut commands when searching for dependencies.
Permitted values of I<option>: B<acronyms> (or B<acro>), B<ac>,
B<abbreviations> (or B<abbr>), B<all> (or B<true>), B<none> (or
B<false>). This overrides the setting given in I<auxfile>.

=item B<--map-format> I<key>B<:>I<value>[B<,>I<key>B<:>I<value>]* (or 
B<-m> I<key>B<:>I<value>[B<,>I<key>B<:>I<value>]*)

Set location format mappings.

=item B<--group> or B<-g>

Add 'group' field to entries.

=item B<--no-group>

Don't add 'group' field to entries (default).

=item B<--record-count> or B<-c>

Add record count fields to entries.

=item B<--no-record-count>

Don't add record count field to entries (default).
This option automatically implements B<--no-record-count-unit>.

=item B<--record-count-unit> or B<-n>

Add unit record count fields to entries.
This option automatically implements B<--record-count>.

=item B<--no-record-count-unit>

Don't add unit record count field to entries (default).

=item B<--trim-fields>

Trim leading and trailing spaces from all fields.
This option cancels B<--trim-only-fields> and B<--no-trim-fields>.

=item B<--trim-only-fields> I<list>

Trim leading and trailing spaces from only the listed fields.
This option is cumulative but is cancelled by B<--trim-fields>
and B<--no-trim-fields>. This option may not be used with
B<--trim-except-fields>.

=item B<--trim-except-fields> I<list>

Trim leading and trailing spaces from all fields except those listed.
This option is cumulative but is cancelled by B<--trim-fields>
and B<--no-trim-fields>. This option may not be used with
B<--trim-only-fields>.

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

Don't trim leading and trailing spaces from fields (default).
This option cancels B<--trim-only-fields> and B<--trim-fields>.

=item B<--expand-fields>

Don't write B<\glsnoexpandfields> to the B<.glstex> file.

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

Write B<\glsnoexpandfields> to the B<.glstex> file (default).

=back

=head1 REQUIRES

Java 7 or later 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

=head1 AUTHOR

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

=cut