Debian Codegraph @

texmf-dist/source/support/bib2gls/bib2gls.pod

raw
1 =head1 SYNOPSIS
2
3 B<bib2gls> [I<option>]+ I<auxfile>
4
5 =head1 DESCRIPTION
6
7 B<bib2gls> is designed to work with the B<glossaries-extra> LaTeX
8 package. (The B<record> package option is required.) The application
9 performs two functions in one: (1) selects entries from .bib files
10 according to information found in the I<auxfile> (similar to
11 B<bibtex>); (2) hierarchically sorts entries and collates location
12 lists (similar to B<makeindex> and B<xindy>). The .aux extension may
13 be omitted from I<auxfile>.
14
15 The I<auxfile> (and corresponding .log file) should either be in the
16 current directory or in the directory specified by B<--dir>. Bib files can
17 either be relative to the directory the I<auxfile> is in
18 or in a location that can be found by kpsewhich.
19
20 =head1 OPTIONS
21
22 =over 4
23
24 =item B<--aux-input-action> I<setting>
25
26 Determines what to do when B<bib2gls> encounters C<\@input> in the
27 F<aux> file. The I<setting> may be one of:
28
29 =over 4
30
31 =item B<follow>
32
33 Follow the reference (that is, input the file as usual).
34
35 =item B<skip-after-bibglsaux> (or B<skip after bibglsaux>)
36
37 Follow the reference for each C<\@input> encountered until
38 C<\@bibgls@input> is encountered, after which skip all remaining
39 instances of C<\@input> (default).
40
41 =item B<skip>
42
43 Skip all instances of C<\@input> (but not C<\@bibgls@input>
44 which is always followed).
45
46 =back
47
48 The C<\@bibgls@input> command will be in the F<aux> file if the package
49 option C<bibglsaux> has been used.
50
51 =item B<--break-space>
52
53 Interpret C<~> (tilde) character and C<\nobreakspace> as a normal space.
54
55 =item B<--cite-as-record>
56
57 Treat C<\citation> as an ignored record.
58
59 =item B<--collapse-same-location-range>
60
61 Collapse an explicit range that has a duplicate start and end
62 location into a normal record (default).
63
64 =item B<--custom-packages> I<list>
65
66 Instruct the TeX parser library to attempt to parse the
67 packages listed in I<list>. This is intended for simple custom
68 packages that don't contain complex code.
69
70 =item B<--datatool-sort-markers>
71
72 The interpreter will use the F<datatool-base.sty> marker commands to match their
73 localised definitions within C<\DTLsortwordlist> (F<datatool> v3.0+).
74 You will need a sort method that doesn't ignore the control
75 characters used by those commands.
76
77 =item B<--date-in-header> (or B<-D>)
78
79 The header comment at the start of the F<.glstex> file will include
80 the file modification date.
81
82 =item B<--debug> [I<n>]
83
84 Switch on the debug mode at the given setting I<n>, which
85 should be a non-negative integer. If I<n> is B<0> then the
86 debug mode is switched off. If omitted, I<n> is set to 1, which
87 corresponds to B<--debug-mode> B<io>. Any positive number will
88 enable all of B<bib2gls>'s debugging messages. The amount of
89 TeX Parser Library debugging messages depends on bitwise operation of I<n>.
90
91 =item B<--debug-mode> I<setting>
92
93 May be used instead of B<--debug> where the level number is
94 difficult to remember. The I<setting> may be a comma-separated list
95 of any of the keywords:
96
97 =over 4
98
99 =item B<all>
100
101 Highest level (likely to result in a large transcript file). Equivalent to
102 switching on all settings.
103
104 =item B<catcode>
105
106 TeX Parser category code changes.
107
108 =item B<cs>
109
110 TeX Parser command definitions.
111
112 =item B<decl>
113
114 TeX Parser declarations.
115
116 =item B<expansion>
117
118 TeX Parser expansions (may result in a large transcript file).
119
120 =item B<expansion-list>
121
122 TeX Parser stack expansions (may result in a large transcript file).
123
124 =item B<expansion-once>
125
126 TeX Parser one-level expansions.
127
128 =item B<expansion-once-list>
129
130 TeX Parser one-level list expansions.
131
132 =item B<io>
133
134 TeX Parser I/O operations (open, close and fetch token).
135
136 =item B<popped>
137
138 TeX Parser stack popping.
139
140 =item B<process>
141
142 TeX Parser macro process (may result in a large transcript file).
143
144 =item B<process-generic-cs>
145
146 TeX Parser generic command process.
147
148 =item B<process-stack>
149
150 TeX Parser stack process (may result in a large transcript file).
151
152 =item B<process-stack-list>
153
154 TeX Parser detailed stack process (may result in a large transcript file).
155
156 =item B<read>
157
158 TeX Parser codepoint read from file (likely to result in a large
159 transcript file).
160
161 =item B<sty-data>
162
163 TeX Parser data (typically relates to internal objects that don't
164 have an analogous TeX macro). This includes data gathered from the
165 aux file.
166
167 =back
168
169 For example: C<bib2gls --debug-mode io,catcode,sty-data mydoc>
170
171 =item B<--default-encoding> I<name>
172
173 Set the default character encoding for input and output files.
174 If omitted, the JVM default encoding is assumed.
175
176 =item B<--dir> I<directory> (or B<-d> <directory>)
177
178 Files are relative to I<directory>. (This doesn't change the current
179 working directory.)
180
181 =item B<--expand-fields>
182
183 Don't write C<\glsnoexpandfields> to the F<.glstex> file.
184
185 =item B<--force-cross-resource-refs> or B<-x>
186
187 Force cross-resource referencing mode on.
188
189 =item B<--group> or B<-g>
190
191 Add B<group> field to entries.
192
193 =item B<--help> or B<-h>
194
195 Display help message and exit.
196
197 =item B<--ignore-packages> I<list> (or B<-k> I<list>)
198
199 Don't parse the log file for the packages listed in I<list>. Note
200 that B<--packages> overrides this option, so if the same package is
201 listed in both B<--ignore-packages> and B<--packages> then the
202 interpreter will check if it's supported. This option has a
203 cumulative action. Only known packages may be included in
204 I<list>.
205
206 =item B<--interpret>
207
208 Use the TeX Parser Library to interpret known (La)TeX commands
209 (default).
210
211 =item B<--list-known-packages>
212
213 Lists all the packages that have are known to the TeX parser
214 library and then exits (with exit code 0). Any of the listed
215 packages may be used in B<--packages> or B<--ignore-packages>.
216
217 =item B<--locale> I<lang> (or B<-l> I<lang>)
218
219 Use language resource file for I<lang> (which should be an IETF
220 locale tag).
221
222 =item B<--log-encoding> I<name>
223
224 Set the character encoding for the F<log> files (which may not be
225 the same as the encoding for the document LaTeX files).
226
227 =item B<--log-file> I<file> (or B<-t> <file>)
228
229 Set the transcript file.
230
231 =item B<--merge-nameref-on> I<rule>
232
233 Rule for merging locations created with the B<record=nameref> package option
234 (requires F<glossaries-extra.sty> version 1.37+). The I<rule> may be
235 one of: B<hcounter>, B<href>, B<title> or B<location>.
236
237 =item B<--merge-wrglossary-records>
238
239 Merge an entry's B<wrglossary> records for the same page locations.
240 (For use with the B<indexcounter> package option.)
241
242 =item B<--mfirstuc-math-protection>
243
244 Switch on the auto-insertion of an empty group for math-shift (C<$>).
245
246 If F<mfirstuc> v2.08+, F<glossaries> v4.50+ and F<glossaries-extra> v1.49+
247 are detected, the default will be B<--no-mfirstuc-math-protection>
248 as there should no longer be any need for this protection.
249
250 =item B<--mfirstuc-protection> I<fields>|B<all> (or B<-u> I<fields>|B<all>)
251
252 Insert an empty group if fields start with certain problematic
253 commands to protect against case-changing commands like C<\Gls>.
254
255 The default is to do this for all fields. To do this for only a
256 subset of fields, set I<fields> to a comma-separated list of fields
257 (e.g. B<name,short,long>). The keyword B<all> indicates all fields.
258
259 If F<mfirstuc> v2.08+, F<glossaries> v4.50+ and F<glossaries-extra> v1.49+
260 are detected, the default will be B<--no-mfirstuc-protection>
261 as there should no longer be any need for this protection.
262
263 =item B<--nested-link-check> I<list>|B<none>
264
265 Check each field listed in I<list> for potentially problematic
266 nested link text. (Default list: name, text, plural, first,
267 firstplural, short, shortplural, long, longplural, symbol).
268
269 If B<none>, disable check.
270
271 =item B<--no-break-space>
272
273 Interpret C<~> (tilde) and C<\nobreakspace> as a non-breaking space (default).
274
275 =item B<--no-cite-as-record>
276
277 Don't check for instances of C<\citation> in the F<.aux> file (default).
278
279 =item B<--no-collapse-same-location-range>
280
281 Don't collapse an explicit range that has a duplicate start and end
282 location into a normal record.
283
284 =item B<--no-datatool-sort-markers>
285
286 The interpreter will use the normal definition of the
287 F<datatool-base.sty> sort marker commands.
288
289 =item B<--no-date-in-header>
290
291 The header comment at the start of the F<.glstex> file will not include
292 the file modification date (default).
293
294 =item B<--no-debug> (or B<--nodebug>)
295
296 Switch off debug mode. (Equivalent to B<--debug> B<0>)
297
298 =item B<--no-expand-fields>
299
300 Write C<\glsnoexpandfields> to the F<.glstex> file (default).
301
302 =item B<--no-force-cross-resource-refs>
303
304 Don't force cross-resource referencing mode on (default).
305
306 =item B<--no-group>
307
308 Don't add B<group> field to entries (default).
309
310 =item B<--no-interpret>
311
312 Don't try interpreting (La)TeX commands. The TeX Parser Library will
313 still be used to parse the F<aux> and F<bib> files.
314
315 =item B<--no-merge-wrglossary-records>
316
317 Don't merge an entry's B<wrglossary> records.
318
319 =item B<--no-mfirstuc-math-protection>
320
321 Switch off the auto-insertion of an empty group for math-shift (C<$>).
322
323 =item B<--no-mfirstuc-protection>
324
325 Switch off the auto-insertion of an empty group for all fields.
326
327 =item B<--no-nested-link-check>
328
329 Don't check for potentially problematic nested link text.
330 (Equivalent to B<--nested-link-check> B<none>)
331
332 =item B<--no-obey-aux-catcode>
333
334 Ignore category code changing commands encountered in the aux file.
335
336 =item B<--no-provide-glossaries>
337
338 Don't write C<\provideignoredglossary*> to the F<.glstex> file to
339 provide unknown glossaries except in documented situations
340 (B<master>, B<secondary> and B<trigger-type> resource options).
341 This setting is the default.
342
343 =item B<--no-record-count>
344
345 Don't add record count field to entries (default).
346 This option automatically implements B<--no-record-count-unit>.
347
348 =item B<--no-record-count-unit>
349
350 Don't add unit record count field to entries (default).
351
352 =item B<--no-replace-quotes>
353
354 Don't replace quote characters (default).
355
356 =item B<--no-retain-formats>
357
358 Normal location merging rules apply (default).
359
360 =item B<--no-shift-zero-sections>
361
362 Don't check for locations ending with ".0" (default).
363
364 =item B<--no-support-unicode-script>
365
366 Text superscript (C<\textsuperscript>) or subscripts (C<\textsubscript>)
367 won't be converted to Unicode superscript/subscript characters.
368 For example, C<\textsuperscript{2}> will be converted to C<E<lt>supE<gt>2E<lt>/supE<gt>>
369 and the markup will be stripped leaving just the character 2.
370
371 =item B<--no-trim-fields>
372
373 Don't trim leading and trailing spaces from fields (default).
374 This option cancels B<--trim-only-fields> and B<--trim-fields>.
375
376 =item B<--no-verbose> (or B<--noverbose>)
377
378 Switch off verbose mode. (Some messages will still be written to
379 STDOUT.)
380
381 =item B<--no-warn-non-bib-fields>
382
383 Don't warn if internal non-bib fields are found in the F<.bib> file.
384 The use of these internal fields can cause unexpected results, so
385 only use this option if you have taken appropriate precautions.
386
387 =item B<--no-warn-unknown-entry-types>
388
389 Don't warn if any unknown entry types are found in the F<.bib> file.
390
391 =item B<--obey-aux-catcode>
392
393 Obey known category code changing commands encountered in the aux
394 file.
395
396 =item B<--packages> I<list> (or B<-p> I<list>)
397
398 Instruct the TeX parser library to pretend the packages listed
399 in I<list> have been used by the document. Note that there's only a
400 limited number of packages supported by the TeX parser library.
401 This option has a cumulative action so B<--packages wasysym,pifont>
402 is the same as B<--packages wasysym --packages pifont>.
403
404 You can find out the list of supported packages with
405 B<--list-known-packages>.
406
407 =item B<--provide-glossaries>
408
409 Write C<\provideignoredglossary*> to the F<.glstex> file to provide
410 unknown glossaries.
411
412 =item B<--quiet> (or B<-q>)
413
414 Only display error messages. All other messages are just written to
415 the transcript file.
416
417 =item B<--record-count> or B<-c>
418
419 Add record count fields to entries.
420
421 =item B<--record-count-rule> I<rule> or B<-r> I<rule>
422
423 Sets the rule used by B<--record-count> and B<--record-count-unit>.
424 This option automatically implements B<--record-count>.
425
426 The I<rule> may be: C<all> or C<a> (count all records),
427 C<non-ignored> or C<n> (count all non-ignored records),
428 C<f/>I<regex>C</> (only count records where the format
429 matches the regular expression I<regex>),
430 C<c/>I<regex>C</> (only count records where the counter name
431 matches the regular expression I<regex>),
432 or C<f/>I<regex1>C</c/>I<regex2>C</>I<op> (only count records where the format
433 matches the regular expression I<regex1> and/or the counter name
434 matches the regular expression I<regex2>). The I<op> part is
435 optional. If present it may be one of: C<and> (format AND counter
436 must match), C<or> (format OR counter must match). If I<op> is
437 omitted, AND is assumed.
438
439 =item B<--record-count-unit> or B<-n>
440
441 Add unit record count fields to entries.
442 This option automatically implements B<--record-count>.
443
444 =item B<--replace-quotes>
445
446 Replace single and double quote characters (C<'> and C<">) with
447 C<\bibglsaposchar> and C<\bibglsdoublequotechar> in field values
448 and group information written to the F<.glstex> file.
449
450 =item B<--retain-formats> I<list>
451
452 Indicates which location formats should always be retained even if
453 it causes a partial duplicate. Only exact duplicates will be merged.
454
455 =item B<--shift-zero-sections>
456
457 Shift up section locations ending with ".0" (for sections deeper
458 than chapter). This action is applied recursively.
459
460 For example, if a record has counter C<subsection> and location
461 C<2.0.0> then this will first be replaced with counter C<section>
462 and location C<2.0> but since this still has a section location
463 ending with ".0" the function will be applied again and the counter
464 will be changed to C<chapter> and the location will be changed to
465 C<2> (so the location subsection 2.0.0 ends up as chapter 2).
466 The log file (and verbose mode) will have a line for each change in the
467 recursion.
468
469 =item B<--shortcuts> I<option>
470
471 Check for the shortcut commands when searching for dependencies.
472 Permitted values of I<option>: B<acronyms> (or B<acro>), B<ac>,
473 B<abbreviations> (or B<abbr>), B<all> (or B<true>), B<none> (or
474 B<false>). This overrides the setting given in I<auxfile>.
475
476 =item B<--map-format> I<key>B<:>I<value>[B<,>I<key>B<:>I<value>]* (or
477 B<-m> I<key>B<:>I<value>[B<,>I<key>B<:>I<value>]*)
478
479 Set location format mappings.
480
481 =item B<--silent>
482
483 Only display error messages. All other messages are just written to
484 the transcript file. (Synonym of B<--quiet>.)
485
486 =item B<--support-unicode-script>
487
488 Text superscript (C<\textsuperscript>) or subscripts (C<\textsubscript>)
489 will use Unicode superscript/subscript characters if available.
490 For example, C<\textsuperscript{2}> will be converted to U+00B2
491 (superscript two).
492
493 =item B<--tex-encoding> I<name>
494
495 Set the character encoding for the F<glstex> files. This overrides the
496 setting given in I<auxfile>.
497
498 =item B<--trim-except-fields> I<list>
499
500 Trim leading and trailing spaces from all fields except those listed.
501 This option is cumulative but is cancelled by B<--trim-fields>
502 and B<--no-trim-fields>. This option may not be used with
503 B<--trim-only-fields>.
504
505 =item B<--trim-fields>
506
507 Trim leading and trailing spaces from all fields.
508 This option cancels B<--trim-only-fields> and B<--no-trim-fields>.
509
510 =item B<--trim-only-fields> I<list>
511
512 Trim leading and trailing spaces from only the listed fields.
513 This option is cumulative but is cancelled by B<--trim-fields>
514 and B<--no-trim-fields>. This option may not be used with
515 B<--trim-except-fields>.
516
517 =item B<--verbose>
518
519 Switch on verbose mode.
520
521 =item B<--version> or B<-v>
522
523 Display version information and exit.
524
525 =item B<--warn-non-bib-fields>
526
527 Warn if internal non-bib fields are found in the F<.bib> file.
528
529 =item B<--warn-unknown-entry-types>
530
531 Warn if any unknown entry types are found in the F<.bib> file.
532
533 =back
534
535 =head1 REQUIRES
536
537 Java 8 or later and a TeX distribution.
538
539 =head1 LICENSE
540
541 License GPLv3+: GNU GPL version 3 or later
542 L<http://gnu.org/licenses/gpl.html>
543 This is free software: you are free to change and redistribute it.
544 There is NO WARRANTY, to the extent permitted by law.
545
546 =head1 RECOMMENDED READING
547
548 The bib2gls manual:
549
550 texdoc bib2gls
551
552 The glossaries-extra manual:
553
554 texdoc glossaries-extra
555
556 The glossaries manual:
557
558 texdoc glossaries
559
560 =head1 AUTHOR
561
562 Nicola L. C. Talbot,
563 L<https://www.dickimaw-books.com/>
564
565 =cut
566