From 2c6f7db39402a9980f7423ed3266ad1d18936bcc Mon Sep 17 00:00:00 2001 From: Norbert Preining Date: Sat, 26 Aug 2023 03:00:52 +0000 Subject: CTAN sync 202308260300 --- support/bib2gls/src/bib2gls.pod | 459 ++++++++++++++++++++++++---------------- 1 file changed, 279 insertions(+), 180 deletions(-) (limited to 'support/bib2gls/src/bib2gls.pod') 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] +=item B<--collapse-same-location-range> -Switch on the debug mode (optionally at the given I, which -should be a non-negative integer). If I 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 -Switch off debug mode. (Equivalent to B<--debug> B<0>) +Instruct the TeX parser library to attempt to parse the +packages listed in I. This is intended for simple custom +packages that don't contain complex code. -=item B<--verbose> +=item B<--debug> [I] -Switch on verbose mode. +Switch on the debug mode at the given setting I, which +should be a non-negative integer. If I is B<0> then the +debug mode is switched off. If omitted, I is set to 1, which +corresponds to B<--debug-mode> B. Any positive number will +enable all of B's debugging messages. The amount of +TeX Parser Library debugging messages depends on bitwise operation of I. -=item B<--no-verbose> (or B<--noverbose>) +=item B<--debug-mode> I -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 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 -=item B<--locale> I (or B<-l> I) +Highest level (likely to result in a large transcript file). Equivalent to +switching on all settings. -Use language resource file for I (which should be an IETF -locale tag). +=item B -=item B<--log-file> I (or B<-t> ) +TeX Parser category code changes. -Set the transcript file. +=item B -=item B<--dir> I (or B<-d> ) +TeX Parser command definitions. -Files are relative to I. (This doesn't change the current -working directory.) +=item B -=item B<--tex-encoding> I +TeX Parser declarations. -Set the character encoding for the output files. This overrides the -setting given in I. +=item B -=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 -=item B<--no-interpret> +TeX Parser stack expansions (may result in a large transcript file). -Don't try interpreting (La)TeX commands. +=item B -=item B<--break-space> +TeX Parser one-level expansions. -Interpret C<~> (tilde) character and C<\nobreakspace> as a normal space. +=item B -=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 -=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 -=item B<--no-obey-aux-catcode> +TeX Parser stack popping. -Ignore category code changing commands encountered in the aux file. +=item B -=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 -=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 -=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 -=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 -=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 -=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 -Merge an entry's B records for the same page locations. -(For use with the B package option.) +=item B<--default-encoding> I -=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 records. +=item B<--dir> I (or B<-d> ) -=item B<--collapse-same-location-range> +Files are relative to I. (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 +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 field to entries. -Normal location merging rules apply (default). +=item B<--help> or B<-h> -=item B<--merge-nameref-on> I +Display help message and exit. -Rule for merging locations created with the B package option -(requires F version 1.37+). The I may be -one of: B, B, B 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 -- cgit v1.2.3