Debian Codegraph @

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

raw
1 =head1 SYNOPSIS
2
3 B<datatool2bib> [I<option>]+ I<in-file> I<bibfile>
4
5 =head1 DESCRIPTION
6
7 Converts a F<.tex> file containing F<datatool.sty> databases to
8 a F<.bib> file in the format required for B<bib2gls>.
9 Distributed with F<bib2gls>.
10
11 The TeX Parser Library is used to parse the input, which may be
12 a DTLTEX or DBTEX file or a file that contains
13 database construction commands, such as
14 C<\DTLnewdb> or C<\DTLaction>. The input file may also be a CSV file
15 if used with B<--read>.
16
17 The B<datatool> and B<datagidx> are automatically implemented so the
18 input file does not need to include either them with C<\usepackage>.
19 In general, it's best not to include the entire document but instead
20 input a file that just contains the database construction commands,
21 as the TeX Parser Library only has a limited set of commands that it
22 recognises.
23
24 =head1 OPTIONS
25
26 =head2 GENERAL OPTIONS
27
28 =over 4
29
30 =item B<--help> or B<-h>
31
32 Display help message and exit.
33
34 =item B<--version> or B<-v>
35
36 Display version information and exit.
37
38 =item B<--silent> or B<--quiet> or B<-q>
39
40 Suppress all messages except for errors.
41
42 =item B<--verbose>
43
44 Switch on verbose mode.
45
46 =item B<--no-verbose>
47
48 Switch off verbose mode.
49
50 =item B<--debug> [I<n>]
51
52 Display debugging messages.
53
54 =item B<--debug-mode> I<setting>
55
56 May be used instead of B<--debug> where the level number is
57 difficult to remember. Value same as for B<bib2gls>'s
58 B<--debug-mode> option.
59
60 =item B<--no-debug>
61
62 Switch off debugging mode. Equivalent to B<--debug> B<0>.
63
64 =item B<--log-file> I<filename>
65
66 Log messages to given file. Intended primarily for debugging messages so
67 enabling debug mode will automatically create a transcript file, but otherwise
68 a file won't be created unless this option is used.
69
70 =back
71
72 =head2 ENCOSING AND LOCALISATION OPTIONS
73
74 =over 4
75
76 =item B<--texenc> I<name>
77
78 Set the character encoding to I<name> for the input B<.tex> files.
79
80 =item B<--bibenc> I<name>
81
82 Set the character encoding to I<name> for the output B<.bib> files.
83
84 =item B<--locale> I<lang tag>
85
86 Use the language resource files associated with the given language
87 tag I<lang tag>. If there isn't an appropriate file, the B<en>
88 (English) file will be used.
89
90 =back
91
92 =head2 FILTERING OPTIONS
93
94 =over 4
95
96 =item B<--preamble-only> or B<-p>
97
98 Only parse the document preamble. That is, stop parsing if
99 C<\begin{document}> encountered.
100
101 =item B<--no-preamble-only>
102
103 Parse the entire document (default).
104
105 =item B<--ignore-fields> I<list> or B<-f> I<list>
106
107 Ignore all the fields in the comma-separated I<list>.
108 Each item in the list should identify
109 the field by its original case-sensitive column key.
110
111 This option is cumulative.
112
113 =item B<--no-ignore-fields>
114
115 Cancels the effect of B<--ignore-fields>.
116
117 =item B<--skip-datagidx>
118
119 Skip the special B<datagidx> internal database.
120 (Default.)
121
122 =item B<--no-skip-datagidx>
123
124 Don't skip the special B<datagidx> internal database.
125
126 =back
127
128 =head2 OUTPUT FILE OPTIONS
129
130 =over 4
131
132 =item B<--overwrite>
133
134 Overwrite existing .bib files.
135
136 =item B<--no-overwrite>
137
138 Don't overwrite existing .bib files.
139
140 =item B<--split>
141
142 Split the entries into separate files according to the database.
143
144 =item B<--no-split>
145
146 Don't split the entries into separate files (default).
147
148 =back
149
150 =head2 ADJUSTMENT OPTIONS
151
152 =over 4
153
154 =item B<--space-sub> I<value> or B<-s> I<value>
155
156 Substitute spaces in labels with I<value>.
157
158 =item B<--field-map> I<mappings> or B<-m> I<mappings>
159
160 Add source column key to destination field label mappings. The argument
161 should be a comma-separated list of I<col-key>=I<bib-field>
162 pairs. This option is cumulative.
163
164 =item B<--no-field-map>
165
166 Cancels all mappings applied with B<--field-map>.
167
168 =item B<--index-conversion> or B<-i>
169
170 Any entries that would normally be converted to C<@entry> that don't
171 have a B<description> field will be converted to C<@index>.
172
173 =item B<--no-index-conversion>
174
175 Don't replace C<@entry> with C<@index> if the description is missing (default).
176
177 =item B<--detect-symbols>
178
179 Attempt to detect entries that should be C<@symbol> or C<@number>
180 based on the value of the B<name> field.
181
182 =item B<--no-detect-symbols>
183
184 Don't attempt symbol detection (default).
185
186
187 =item B<--label> I<col-key> or B<-L>
188
189 Use column identified by I<col-key> for the entry label. The default
190 column key is B<Label> so if the database doesn't have a column with
191 this key, you will either need to specify a column with B<--label>
192 or use B<--auto-label>. This option is ignored with B<--auto-label>.
193
194 =item B<--auto-label> or B<-a>
195
196 Auto-generate entry labels instead of using a column value.
197
198 =item B<--no-auto-label>
199
200 Don't auto-generate entry labels. Use the column identified by
201 B<--label> for the entry label. (Default.)
202
203 =item B<--auto-label-prefix> I<prefix>
204
205 Use I<prefix> when auto-generating entry labels. Ignored with
206 B<--no-auto-label>.
207
208 =item B<--adjust-gls>
209
210 Adjust labels in commands like C<\gls> in field values. (Default.)
211 This will also replace the F<datagidx.sty> commands like C<\glsnl>
212 with the closest F<glossaries.sty> equivalent.
213
214 =item B<--no-adjust-gls>
215
216 Don't adjust labels in commands like C<\gls> in field values.
217
218 =item B<--dependency-field> I<field-name>
219
220 Sets the name of the dependency field. Has no effect with
221 B<--no-strip-glsadd>. With B<--strip-glsadd>, the label from the
222 stripped C<\glsadd> argument will be added to the field identified
223 by I<field-name>. The default is B<dependency> which will be ignored
224 by B<bib2gls> unless instructed otherwise (via field aliasing etc).
225
226 =item B<--no-dependency-field>
227
228 Don't save labels from any stripped C<\glsadd> instances.
229
230 =item B<--strip>
231
232 Switch on all strip options.
233
234 =item B<--no-strip>
235
236 Switch off all strip options.
237
238 =item B<--strip-glsadd>
239
240 Strip C<\glsadd> and its argument from field values. (Default.)
241
242 =item B<--no-strip-glsadd>
243
244 Don't strip C<\glsadd> from field values.
245
246 =item B<--strip-acronym-font>
247
248 Strip C<\acronymfont> from field values. (Default.)
249
250 =item B<--no-strip-acronym-font>
251
252 Don't strip C<\acronymfont> from field values.
253
254 =item B<--strip-acronym-text>
255
256 Strip B<text> field for acronyms identified by C<\newacro>.
257 (Default.)
258
259 =item B<--no-strip-acronym-text>
260
261 Don't strip B<text> field for acronyms.
262
263 =item B<--strip-acronym-name>
264
265 Strip B<name> field for acronyms identified by C<\newacro>.
266 (Default.)
267
268 =item B<--no-strip-acronym-name>
269
270 Don't strip B<name> field for acronyms.
271
272 =item B<--strip-case-change>
273
274 Strip known case-changing commands (such as C<\makefirstuc> or C<\capitalisewords>)
275 from field values.
276
277 =item B<--nostrip-case-change>
278
279 Don't strip case-changing commands. (Default.)
280
281 =back
282
283 =head2 OTHER OPTIONS
284
285 These options correspond to features introduced to F<datatool.sty>
286 version 3.0, which has a setting that stores the numeric value and
287 currency symbol (where applicable) when parsing data. The original
288 string (formatted number), numeric value and currency symbol are
289 stored in a special datum format, which ordinarily expands to its
290 original formatted text but also allows the previously parsed
291 information to be easily extracted without having to reparse the
292 data.
293
294 =over 4
295
296 =item B<--setup> I<options>
297
298 Implement C<\DTLsetup{>I<options>C<}> at the start. This can include
299 options such as C<store-datum>, C<new-value-expand>,
300 C<new-value-trim> and C<default-name>.
301
302 =item B<--read> I<options>
303
304 Instead of simply parsing the input file as a normal F<.tex> file,
305 the source is presented to the TeX parser as
306 C<\DTLread[>I<options>C<]{>I<in-file>C<}> where the options can be
307 used to specify the file format (for example, C<format=tsv>).
308
309 If the I<options> list is empty (after trimming white space) then
310 this becomes equivalent to B<--no-read>.
311
312 =item B<--no-read>
313
314 The input file is parsed as a normal F<.tex> file, which may be the
315 complete document or a file that can be C<\input> into a document.
316 (Default.)
317
318 =item B<--save-value> I<suffix>
319
320 If a field value is parsed and identified as numeric, the
321 unformatted numeric value will be saved in a field whose name is
322 constructed from the original field name followed by the given
323 I<suffix>.
324
325 =item B<--no-save-value>
326
327 Don't save numeric value in a separate field. (Default.)
328
329 =item B<--save-currency> I<suffix>
330
331 If a field value is parsed and identified as currency data, the
332 currency symbol will be saved in a field whose name is
333 constructed from the original field name followed by the given
334 I<suffix>.
335
336 =item B<--no-save-currency>
337
338 Don't save currency symbol in a separate field. (Default.)
339
340 =item B<--save-datum>
341
342 Equivalent to:
343
344 --save-value '-value' --save-currency '-currency'
345
346 =item B<--no-save-datum>
347
348 Equivalent to B<--no-save-value> B<--no-save-currency>.
349
350 =back
351
352 =head1 REQUIRES
353
354 Java 8 and a TeX distribution.
355
356 =head1 LICENSE
357
358 License GPLv3+: GNU GPL version 3 or later
359 <http://gnu.org/licenses/gpl.html>
360 This is free software: you are free to change and redistribute it.
361 There is NO WARRANTY, to the extent permitted by law.
362
363 =head1 RECOMMENDED READING
364
365 The bib2gls manual:
366
367 texdoc bib2gls
368
369 The glossaries-extra manual:
370
371 texdoc glossaries-extra
372
373 The glossaries manual:
374
375 texdoc glossaries
376
377 The datatool manual:
378
379 texdoc datatool
380
381 =head1 AUTHOR
382
383 Nicola L. C. Talbot,
384 L<https://www.dickimaw-books.com/>
385
386 =cut
387