summaryrefslogtreecommitdiff
path: root/support/bib2gls/src/bib2gls.pod
blob: de6da0038b6bde3ba5197533f48380447afe1a28 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
=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 C<~> (tilde) character and C<\nobreakspace> as a normal space.

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

Interpret C<~> (tilde) and C<\nobreakspace> as a non-breaking space (default).

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

Treat C<\citation> as an ignored record.

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

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

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

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

=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<--warn-unknown-entry-types>

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

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

Don't warn if any unknown entry types are found in the F<.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<--collapse-same-location-range>

Collapse an explicit range that has a duplicate start and end
location into a normal record (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<--retain-formats> I<list>

Indicates which location formats should always be retained even if
it causes a partial duplicate. Only exact duplicates will be merged.

=item B<--no-retain-formats>

Normal location merging rules apply (default).

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

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<--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 (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<--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<--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 C<\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 (C<$>).
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 (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).

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 B<group> field to entries.

=item B<--no-group>

Don't add B<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 C<\glsnoexpandfields> to the F<.glstex> file.

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

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

=item B<--provide-glossaries>

Write C<\provideignoredglossary*> to the F<.glstex> file to provide
unknown glossaries.

=item B<--no-provide-glossaries>

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.


=back

=head1 REQUIRES

Java 7 or later and a TeX distribution.

=head1 LICENSE

License GPLv3+: GNU GPL version 3 or later
L<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<https://www.dickimaw-books.com/>

=cut