summaryrefslogtreecommitdiff
path: root/support/bib2gls/src/bib2gls.pod
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2023-08-26 03:00:52 +0000
committerNorbert Preining <norbert@preining.info>2023-08-26 03:00:52 +0000
commit2c6f7db39402a9980f7423ed3266ad1d18936bcc (patch)
treeb998126ee1c53cfee553777049066ea4b50244f4 /support/bib2gls/src/bib2gls.pod
parentba73c7edc85ac1310d82920c5f432993f8a9af23 (diff)
CTAN sync 202308260300
Diffstat (limited to 'support/bib2gls/src/bib2gls.pod')
-rw-r--r--support/bib2gls/src/bib2gls.pod459
1 files changed, 279 insertions, 180 deletions
diff --git a/support/bib2gls/src/bib2gls.pod b/support/bib2gls/src/bib2gls.pod
index a470b73fc9..e9645adb65 100644
--- a/support/bib2gls/src/bib2gls.pod
+++ b/support/bib2gls/src/bib2gls.pod
@@ -21,196 +21,192 @@ or in a location that can be found by kpsewhich.
=over 4
-=item B<--help> or B<-h>
+=item B<--break-space>
-Display help message and exit.
+Interpret C<~> (tilde) character and C<\nobreakspace> as a normal space.
-=item B<--version> or B<-v>
+=item B<--cite-as-record>
-Display version information and exit.
+Treat C<\citation> as an ignored record.
-=item B<--debug> [I<level>]
+=item B<--collapse-same-location-range>
-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.
+Collapse an explicit range that has a duplicate start and end
+location into a normal record (default).
-=item B<--no-debug> (or B<--nodebug>)
+=item B<--custom-packages> I<list>
-Switch off debug mode. (Equivalent to B<--debug> B<0>)
+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<--verbose>
+=item B<--debug> [I<n>]
-Switch on verbose mode.
+Switch on the debug mode at the given setting I<n>, which
+should be a non-negative integer. If I<n> is B<0> then the
+debug mode is switched off. If omitted, I<n> is set to 1, which
+corresponds to B<--debug-mode> B<io>. Any positive number will
+enable all of B<bib2gls>'s debugging messages. The amount of
+TeX Parser Library debugging messages depends on bitwise operation of I<n>.
-=item B<--no-verbose> (or B<--noverbose>)
+=item B<--debug-mode> I<setting>
-Switch off verbose mode. (Some messages will still be written to
-STDOUT.)
+May be used instead of B<--debug> where the level number is
+difficult to remember. The I<setting> may be a comma-separated list
+of any of the keywords:
-=item B<--silent>
+=over 4
-Only display error messages. All other messages are just written to
-the transcript file.
+=item B<all>
-=item B<--locale> I<lang> (or B<-l> I<lang>)
+Highest level (likely to result in a large transcript file). Equivalent to
+switching on all settings.
-Use language resource file for I<lang> (which should be an IETF
-locale tag).
+=item B<catcode>
-=item B<--log-file> I<file> (or B<-t> <file>)
+TeX Parser category code changes.
-Set the transcript file.
+=item B<cs>
-=item B<--dir> I<directory> (or B<-d> <directory>)
+TeX Parser command definitions.
-Files are relative to I<directory>. (This doesn't change the current
-working directory.)
+=item B<decl>
-=item B<--tex-encoding> I<name>
+TeX Parser declarations.
-Set the character encoding for the output files. This overrides the
-setting given in I<auxfile>.
+=item B<expansion>
-=item B<--interpret>
+TeX Parser expansions (may result in a large transcript file).
-Use the TeX parser library to interpret known (La)TeX commands
-(default).
+=item B<expansion-list>
-=item B<--no-interpret>
+TeX Parser stack expansions (may result in a large transcript file).
-Don't try interpreting (La)TeX commands.
+=item B<expansion-once>
-=item B<--break-space>
+TeX Parser one-level expansions.
-Interpret C<~> (tilde) character and C<\nobreakspace> as a normal space.
+=item B<expansion-once-list>
-=item B<--no-break-space>
+TeX Parser one-level list expansions.
-Interpret C<~> (tilde) and C<\nobreakspace> as a non-breaking space (default).
+=item B<io>
-=item B<--obey-aux-catcode>
+TeX Parser I/O operations (open, close and fetch token).
-Obey known category code changing commands encountered in the aux
-file.
+=item B<popped>
-=item B<--no-obey-aux-catcode>
+TeX Parser stack popping.
-Ignore category code changing commands encountered in the aux file.
+=item B<process>
-=item B<--cite-as-record>
+TeX Parser macro process (may result in a large transcript file).
-Treat C<\citation> as an ignored record.
+=item B<process-generic-cs>
-=item B<--no-cite-as-record>
+TeX Parser generic command process.
-Don't check for instances of C<\citation> in the F<.aux> file (default).
+=item B<process-stack>
-=item B<--warn-non-bib-fields>
+TeX Parser stack process (may result in a large transcript file).
-Warn if internal non-bib fields are found in the F<.bib> file.
+=item B<process-stack-list>
-=item B<--no-warn-non-bib-fields>
+TeX Parser detailed stack process (may result in a large transcript file).
-Don't warn if internal non-bib fields are found in the F<.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<read>
-=item B<--warn-unknown-entry-types>
+TeX Parser codepoint read from file (likely to result in a large
+transcript file).
-Warn if any unknown entry types are found in the F<.bib> file.
+=item B<sty-data>
-=item B<--no-warn-unknown-entry-types>
+TeX Parser data (typically relates to internal objects that don't
+have an analogous TeX macro). This includes data gathered from the
+aux file.
-Don't warn if any unknown entry types are found in the F<.bib> file.
+=back
-=item B<--merge-wrglossary-records>
+For example: C<bib2gls --debug-mode io,catcode,sty-data mydoc>
-Merge an entry's B<wrglossary> records for the same page locations.
-(For use with the B<indexcounter> package option.)
+=item B<--default-encoding> I<name>
-=item B<--no-merge-wrglossary-records>
+Set the default character encoding for input and output files.
+If omitted, the JVM default encoding is assumed.
-Don't merge an entry's B<wrglossary> records.
+=item B<--dir> I<directory> (or B<-d> <directory>)
-=item B<--collapse-same-location-range>
+Files are relative to I<directory>. (This doesn't change the current
+working directory.)
-Collapse an explicit range that has a duplicate start and end
-location into a normal record (default).
+=item B<--expand-fields>
-=item B<--no-collapse-same-location-range>
+Don't write C<\glsnoexpandfields> to the F<.glstex> file.
-Don't collapse an explicit range that has a duplicate start and end
-location into a normal record.
+=item B<--force-cross-resource-refs> or B<-x>
-=item B<--retain-formats> I<list>
+Force cross-resource referencing mode on.
-Indicates which location formats should always be retained even if
-it causes a partial duplicate. Only exact duplicates will be merged.
+=item B<--group> or B<-g>
-=item B<--no-retain-formats>
+Add B<group> field to entries.
-Normal location merging rules apply (default).
+=item B<--help> or B<-h>
-=item B<--merge-nameref-on> I<rule>
+Display help message and exit.
-Rule for merging locations created with the B<record=nameref> package option
-(requires F<glossaries-extra.sty> version 1.37+). The I<rule> may be
-one of: B<hcounter>, B<href>, B<title> or B<location>.
+=item B<--ignore-packages> I<list> (or B<-k> I<list>)
-=item B<--force-cross-resource-refs> or B<-x>
+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>.
-Force cross-resource referencing mode on.
+=item B<--interpret>
-=item B<--no-force-cross-resource-refs>
+Use the TeX Parser Library to interpret known (La)TeX commands
+(default).
-Don't force cross-resource referencing mode on (default).
+=item B<--list-known-packages>
-=item B<--support-unicode-script>
+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>.
-Text superscript (C<\textsuperscript>) or subscripts (C<\textsubscript>)
-will use Unicode superscript/subscript characters if available.
-For example, C<\textsuperscript{2}> will be converted to U+00B2
-(superscript two).
+=item B<--locale> I<lang> (or B<-l> I<lang>)
-=item B<--no-support-unicode-script>
+Use language resource file for I<lang> (which should be an IETF
+locale tag).
-Text superscript (C<\textsuperscript>) or subscripts (C<\textsubscript>)
-won't be converted to Unicode superscript/subscript characters.
-For example, C<\textsuperscript{2}> will be converted to C<E<lt>supE<gt>2E<lt>/supE<gt>>
-and the markup will be stripped leaving just the character 2.
+=item B<--log-encoding> I<name>
-=item B<--packages> I<list> (or B<-p> I<list>)
+Set the character encoding for the F<log> files (which may not be
+the same as the encoding for the document LaTeX files).
-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>.
+=item B<--log-file> I<file> (or B<-t> <file>)
-You can find out the list of supported packages with
-B<--list-known-packages>.
+Set the transcript file.
-=item B<--custom-packages> I<list>
+=item B<--merge-nameref-on> I<rule>
-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.
+Rule for merging locations created with the B<record=nameref> package option
+(requires F<glossaries-extra.sty> version 1.37+). The I<rule> may be
+one of: B<hcounter>, B<href>, B<title> or B<location>.
-=item B<--ignore-packages> I<list> (or B<-k> I<list>)
+=item B<--merge-wrglossary-records>
-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>.
+Merge an entry's B<wrglossary> records for the same page locations.
+(For use with the B<indexcounter> package option.)
-=item B<--list-known-packages>
+=item B<--mfirstuc-math-protection>
-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>.
+Switch on the auto-insertion of an empty group for math-shift (C<$>).
+
+If F<mfirstuc> v2.08+, F<glossaries> v4.50+ and F<glossaries-extra> v1.49+
+are detected, the default will be B<--no-mfirstuc-math-protection>
+as there should no longer be any need for this protection.
=item B<--mfirstuc-protection> I<fields>|B<all> (or B<-u> I<fields>|B<all>)
@@ -225,54 +221,149 @@ If F<mfirstuc> v2.08+, F<glossaries> v4.50+ and F<glossaries-extra> v1.49+
are detected, the default will be B<--no-mfirstuc-protection>
as there should no longer be any need for this protection.
-=item B<--no-mfirstuc-protection>
+=item B<--nested-link-check> I<list>|B<none>
-Switch off the auto-insertion of an empty group for all fields.
+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).
-=item B<--mfirstuc-math-protection>
+If B<none>, disable check.
-Switch on the auto-insertion of an empty group for math-shift (C<$>).
+=item B<--no-break-space>
-If F<mfirstuc> v2.08+, F<glossaries> v4.50+ and F<glossaries-extra> v1.49+
-are detected, the default will be B<--no-mfirstuc-math-protection>
-as there should no longer be any need for this protection.
+Interpret C<~> (tilde) and C<\nobreakspace> as a non-breaking space (default).
+
+=item B<--no-cite-as-record>
+
+Don't check for instances of C<\citation> in the F<.aux> file (default).
+
+=item B<--no-collapse-same-location-range>
+
+Don't collapse an explicit range that has a duplicate start and end
+location into a normal record.
+
+=item B<--no-debug> (or B<--nodebug>)
+
+Switch off debug mode. (Equivalent to B<--debug> B<0>)
+
+=item B<--no-expand-fields>
+
+Write C<\glsnoexpandfields> to the F<.glstex> file (default).
+
+=item B<--no-force-cross-resource-refs>
+
+Don't force cross-resource referencing mode on (default).
+
+=item B<--no-group>
+
+Don't add B<group> field to entries (default).
+
+=item B<--no-interpret>
+
+Don't try interpreting (La)TeX commands. The TeX Parser Library will
+still be used to parse the F<aux> and F<bib> files.
+
+=item B<--no-merge-wrglossary-records>
+
+Don't merge an entry's B<wrglossary> records.
=item B<--no-mfirstuc-math-protection>
Switch off the auto-insertion of an empty group for math-shift (C<$>).
-=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).
+=item B<--no-mfirstuc-protection>
-If B<none>, disable check.
+Switch off the auto-insertion of an empty group for all fields.
=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>
+=item B<--no-obey-aux-catcode>
-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>.
+Ignore category code changing commands encountered in the aux file.
-=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>]*)
+=item B<--no-provide-glossaries>
-Set location format mappings.
+Don't write C<\provideignoredglossary*> to the F<.glstex> file to
+provide unknown glossaries except in documented situations
+(B<master>, B<secondary> and B<trigger-type> resource options).
+This setting is the default.
-=item B<--group> or B<-g>
+=item B<--no-record-count>
-Add B<group> field to entries.
+Don't add record count field to entries (default).
+This option automatically implements B<--no-record-count-unit>.
-=item B<--no-group>
+=item B<--no-record-count-unit>
-Don't add B<group> field to entries (default).
+Don't add unit record count field to entries (default).
+
+=item B<--no-replace-quotes>
+
+Don't replace quote characters (default).
+
+=item B<--no-retain-formats>
+
+Normal location merging rules apply (default).
+
+=item B<--no-support-unicode-script>
+
+Text superscript (C<\textsuperscript>) or subscripts (C<\textsubscript>)
+won't be converted to Unicode superscript/subscript characters.
+For example, C<\textsuperscript{2}> will be converted to C<E<lt>supE<gt>2E<lt>/supE<gt>>
+and the markup will be stripped leaving just the character 2.
+
+=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<--no-verbose> (or B<--noverbose>)
+
+Switch off verbose mode. (Some messages will still be written to
+STDOUT.)
+
+=item B<--no-warn-non-bib-fields>
+
+Don't warn if internal non-bib fields are found in the F<.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<--no-warn-unknown-entry-types>
+
+Don't warn if any unknown entry types are found in the F<.bib> file.
+
+=item B<--obey-aux-catcode>
+
+Obey known category code changing commands encountered in the aux
+file.
+
+=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<--provide-glossaries>
+
+Write C<\provideignoredglossary*> to the F<.glstex> file to provide
+unknown glossaries.
+
+=item B<--quiet> (or B<-q>)
+
+Only display error messages. All other messages are just written to
+the transcript file.
+
+=item B<--record-count> or B<-c>
+
+Add record count fields to entries.
=item B<--record-count-rule> I<rule> or B<-r> I<rule>
@@ -292,35 +383,50 @@ optional. If present it may be one of: C<and> (format AND counter
must match), C<or> (format OR counter must match). If I<op> is
omitted, AND is assumed.
-=item B<--record-count> or B<-c>
+=item B<--record-count-unit> or B<-n>
-Add record count fields to entries.
+Add unit record count fields to entries.
+This option automatically implements B<--record-count>.
-=item B<--no-record-count>
+=item B<--replace-quotes>
-Don't add record count field to entries (default).
-This option automatically implements B<--no-record-count-unit>.
+Replace single and double quote characters (C<'> and C<">) with
+C<\bibglsaposchar> and C<\bibglsdoublequotechar> in field values
+and group information written to the F<.glstex> file.
-=item B<--record-count-unit> or B<-n>
+=item B<--retain-formats> I<list>
-Add unit record count fields to entries.
-This option automatically implements B<--record-count>.
+Indicates which location formats should always be retained even if
+it causes a partial duplicate. Only exact duplicates will be merged.
-=item B<--no-record-count-unit>
+=item B<--shortcuts> I<option>
-Don't add unit record count field to entries (default).
+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<--trim-fields>
+=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>]*)
-Trim leading and trailing spaces from all fields.
-This option cancels B<--trim-only-fields> and B<--no-trim-fields>.
+Set location format mappings.
-=item B<--trim-only-fields> I<list>
+=item B<--silent>
-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>.
+Only display error messages. All other messages are just written to
+the transcript file. (Synonym of B<--quiet>.)
+
+=item B<--support-unicode-script>
+
+Text superscript (C<\textsuperscript>) or subscripts (C<\textsubscript>)
+will use Unicode superscript/subscript characters if available.
+For example, C<\textsuperscript{2}> will be converted to U+00B2
+(superscript two).
+
+=item B<--tex-encoding> I<name>
+
+Set the character encoding for the F<glstex> files. This overrides the
+setting given in I<auxfile>.
=item B<--trim-except-fields> I<list>
@@ -329,40 +435,33 @@ 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>
+=item B<--trim-fields>
-Don't write C<\glsnoexpandfields> to the F<.glstex> file.
+Trim leading and trailing spaces from all fields.
+This option cancels B<--trim-only-fields> and B<--no-trim-fields>.
-=item B<--no-expand-fields>
+=item B<--trim-only-fields> I<list>
-Write C<\glsnoexpandfields> to the F<.glstex> file (default).
+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<--provide-glossaries>
+=item B<--verbose>
-Write C<\provideignoredglossary*> to the F<.glstex> file to provide
-unknown glossaries.
+Switch on verbose mode.
-=item B<--no-provide-glossaries>
+=item B<--version> or B<-v>
-Don't write C<\provideignoredglossary*> to the F<.glstex> file to
-provide unknown glossaries except in documented situations
-(B<master>, B<secondary> and B<trigger-type> resource options).
-This setting is the default.
+Display version information and exit.
-=item B<--replace-quotes>
+=item B<--warn-non-bib-fields>
-Replace single and double quote characters (C<'> and C<">) with
-C<\bibglsaposchar> and C<\bibglsdoublequotechar> in field values
-and group information written to the F<.glstex> file.
+Warn if internal non-bib fields are found in the F<.bib> file.
-=item B<--no-replace-quotes>
+=item B<--warn-unknown-entry-types>
-Don't replace quote characters (default).
+Warn if any unknown entry types are found in the F<.bib> file.
=back