Debian Codegraph @

texmf-dist/doc/man/man1/datatool2bib.1

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\"
56 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "DATATOOL2BIB 1"
61 .TH DATATOOL2BIB 1 2024-12-21 "perl v5.40.0" datatool2bib
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH SYNOPSIS
67 .IX Header "SYNOPSIS"
68 \&\fBdatatool2bib\fR [\fIoption\fR]+ \fIin\-file\fR \fIbibfile\fR
69 .SH DESCRIPTION
70 .IX Header "DESCRIPTION"
71 Converts a \fI.tex\fR file containing \fIdatatool.sty\fR databases to
72 a \fI.bib\fR file in the format required for \fBbib2gls\fR.
73 Distributed with \fIbib2gls\fR.
74 .PP
75 The TeX Parser Library is used to parse the input, which may be
76 a DTLTEX or DBTEX file or a file that contains
77 database construction commands, such as
78 \&\f(CW\*(C`\eDTLnewdb\*(C'\fR or \f(CW\*(C`\eDTLaction\*(C'\fR. The input file may also be a CSV file
79 if used with \fB\-\-read\fR.
80 .PP
81 The \fBdatatool\fR and \fBdatagidx\fR are automatically implemented so the
82 input file does not need to include either them with \f(CW\*(C`\eusepackage\*(C'\fR.
83 In general, it\*(Aqs best not to include the entire document but instead
84 input a file that just contains the database construction commands,
85 as the TeX Parser Library only has a limited set of commands that it
86 recognises.
87 .SH OPTIONS
88 .IX Header "OPTIONS"
89 .SS "GENERAL OPTIONS"
90 .IX Subsection "GENERAL OPTIONS"
91 .IP "\fB\-\-help\fR or \fB\-h\fR" 4
92 .IX Item "--help or -h"
93 Display help message and exit.
94 .IP "\fB\-\-version\fR or \fB\-v\fR" 4
95 .IX Item "--version or -v"
96 Display version information and exit.
97 .IP "\fB\-\-silent\fR or \fB\-\-quiet\fR or \fB\-q\fR" 4
98 .IX Item "--silent or --quiet or -q"
99 Suppress all messages except for errors.
100 .IP \fB\-\-verbose\fR 4
101 .IX Item "--verbose"
102 Switch on verbose mode.
103 .IP \fB\-\-no\-verbose\fR 4
104 .IX Item "--no-verbose"
105 Switch off verbose mode.
106 .IP "\fB\-\-debug\fR [\fIn\fR]" 4
107 .IX Item "--debug [n]"
108 Display debugging messages.
109 .IP "\fB\-\-debug\-mode\fR \fIsetting\fR" 4
110 .IX Item "--debug-mode setting"
111 May be used instead of \fB\-\-debug\fR where the level number is
112 difficult to remember. Value same as for \fBbib2gls\fR\*(Aqs
113 \&\fB\-\-debug\-mode\fR option.
114 .IP \fB\-\-no\-debug\fR 4
115 .IX Item "--no-debug"
116 Switch off debugging mode. Equivalent to \fB\-\-debug\fR \fB0\fR.
117 .IP "\fB\-\-log\-file\fR \fIfilename\fR" 4
118 .IX Item "--log-file filename"
119 Log messages to given file. Intended primarily for debugging messages so
120 enabling debug mode will automatically create a transcript file, but otherwise
121 a file won\*(Aqt be created unless this option is used.
122 .SS "ENCOSING AND LOCALISATION OPTIONS"
123 .IX Subsection "ENCOSING AND LOCALISATION OPTIONS"
124 .IP "\fB\-\-texenc\fR \fIname\fR" 4
125 .IX Item "--texenc name"
126 Set the character encoding to \fIname\fR for the input \fB.tex\fR files.
127 .IP "\fB\-\-bibenc\fR \fIname\fR" 4
128 .IX Item "--bibenc name"
129 Set the character encoding to \fIname\fR for the output \fB.bib\fR files.
130 .IP "\fB\-\-locale\fR \fIlang tag\fR" 4
131 .IX Item "--locale lang tag"
132 Use the language resource files associated with the given language
133 tag \fIlang tag\fR. If there isn\*(Aqt an appropriate file, the \fBen\fR
134 (English) file will be used.
135 .SS "FILTERING OPTIONS"
136 .IX Subsection "FILTERING OPTIONS"
137 .IP "\fB\-\-preamble\-only\fR or \fB\-p\fR" 4
138 .IX Item "--preamble-only or -p"
139 Only parse the document preamble. That is, stop parsing if
140 \&\f(CW\*(C`\ebegin{document}\*(C'\fR encountered.
141 .IP \fB\-\-no\-preamble\-only\fR 4
142 .IX Item "--no-preamble-only"
143 Parse the entire document (default).
144 .IP "\fB\-\-ignore\-fields\fR \fIlist\fR or \fB\-f\fR \fIlist\fR" 4
145 .IX Item "--ignore-fields list or -f list"
146 Ignore all the fields in the comma\-separated \fIlist\fR.
147 Each item in the list should identify
148 the field by its original case\-sensitive column key.
149 .Sp
150 This option is cumulative.
151 .IP \fB\-\-no\-ignore\-fields\fR 4
152 .IX Item "--no-ignore-fields"
153 Cancels the effect of \fB\-\-ignore\-fields\fR.
154 .IP \fB\-\-skip\-datagidx\fR 4
155 .IX Item "--skip-datagidx"
156 Skip the special \fBdatagidx\fR internal database.
157 (Default.)
158 .IP \fB\-\-no\-skip\-datagidx\fR 4
159 .IX Item "--no-skip-datagidx"
160 Don\*(Aqt skip the special \fBdatagidx\fR internal database.
161 .SS "OUTPUT FILE OPTIONS"
162 .IX Subsection "OUTPUT FILE OPTIONS"
163 .IP \fB\-\-overwrite\fR 4
164 .IX Item "--overwrite"
165 Overwrite existing .bib files.
166 .IP \fB\-\-no\-overwrite\fR 4
167 .IX Item "--no-overwrite"
168 Don\*(Aqt overwrite existing .bib files.
169 .IP \fB\-\-split\fR 4
170 .IX Item "--split"
171 Split the entries into separate files according to the database.
172 .IP \fB\-\-no\-split\fR 4
173 .IX Item "--no-split"
174 Don\*(Aqt split the entries into separate files (default).
175 .SS "ADJUSTMENT OPTIONS"
176 .IX Subsection "ADJUSTMENT OPTIONS"
177 .IP "\fB\-\-space\-sub\fR \fIvalue\fR or \fB\-s\fR \fIvalue\fR" 4
178 .IX Item "--space-sub value or -s value"
179 Substitute spaces in labels with \fIvalue\fR.
180 .IP "\fB\-\-field\-map\fR \fImappings\fR or \fB\-m\fR \fImappings\fR" 4
181 .IX Item "--field-map mappings or -m mappings"
182 Add source column key to destination field label mappings. The argument
183 should be a comma\-separated list of \fIcol\-key\fR=\fIbib\-field\fR
184 pairs. This option is cumulative.
185 .IP \fB\-\-no\-field\-map\fR 4
186 .IX Item "--no-field-map"
187 Cancels all mappings applied with \fB\-\-field\-map\fR.
188 .IP "\fB\-\-index\-conversion\fR or \fB\-i\fR" 4
189 .IX Item "--index-conversion or -i"
190 Any entries that would normally be converted to \f(CW@entry\fR that don\*(Aqt
191 have a \fBdescription\fR field will be converted to \f(CW@index\fR.
192 .IP \fB\-\-no\-index\-conversion\fR 4
193 .IX Item "--no-index-conversion"
194 Don\*(Aqt replace \f(CW@entry\fR with \f(CW@index\fR if the description is missing (default).
195 .IP \fB\-\-detect\-symbols\fR 4
196 .IX Item "--detect-symbols"
197 Attempt to detect entries that should be \f(CW@symbol\fR or \f(CW@number\fR
198 based on the value of the \fBname\fR field.
199 .IP \fB\-\-no\-detect\-symbols\fR 4
200 .IX Item "--no-detect-symbols"
201 Don\*(Aqt attempt symbol detection (default).
202 .IP "\fB\-\-label\fR \fIcol\-key\fR or \fB\-L\fR" 4
203 .IX Item "--label col-key or -L"
204 Use column identified by \fIcol\-key\fR for the entry label. The default
205 column key is \fBLabel\fR so if the database doesn\*(Aqt have a column with
206 this key, you will either need to specify a column with \fB\-\-label\fR
207 or use \fB\-\-auto\-label\fR. This option is ignored with \fB\-\-auto\-label\fR.
208 .IP "\fB\-\-auto\-label\fR or \fB\-a\fR" 4
209 .IX Item "--auto-label or -a"
210 Auto\-generate entry labels instead of using a column value.
211 .IP \fB\-\-no\-auto\-label\fR 4
212 .IX Item "--no-auto-label"
213 Don\*(Aqt auto\-generate entry labels. Use the column identified by
214 \&\fB\-\-label\fR for the entry label. (Default.)
215 .IP "\fB\-\-auto\-label\-prefix\fR \fIprefix\fR" 4
216 .IX Item "--auto-label-prefix prefix"
217 Use \fIprefix\fR when auto\-generating entry labels. Ignored with
218 \&\fB\-\-no\-auto\-label\fR.
219 .IP \fB\-\-adjust\-gls\fR 4
220 .IX Item "--adjust-gls"
221 Adjust labels in commands like \f(CW\*(C`\egls\*(C'\fR in field values. (Default.)
222 This will also replace the \fIdatagidx.sty\fR commands like \f(CW\*(C`\eglsnl\*(C'\fR
223 with the closest \fIglossaries.sty\fR equivalent.
224 .IP \fB\-\-no\-adjust\-gls\fR 4
225 .IX Item "--no-adjust-gls"
226 Don\*(Aqt adjust labels in commands like \f(CW\*(C`\egls\*(C'\fR in field values.
227 .IP "\fB\-\-dependency\-field\fR \fIfield\-name\fR" 4
228 .IX Item "--dependency-field field-name"
229 Sets the name of the dependency field. Has no effect with
230 \&\fB\-\-no\-strip\-glsadd\fR. With \fB\-\-strip\-glsadd\fR, the label from the
231 stripped \f(CW\*(C`\eglsadd\*(C'\fR argument will be added to the field identified
232 by \fIfield\-name\fR. The default is \fBdependency\fR which will be ignored
233 by \fBbib2gls\fR unless instructed otherwise (via field aliasing etc).
234 .IP \fB\-\-no\-dependency\-field\fR 4
235 .IX Item "--no-dependency-field"
236 Don\*(Aqt save labels from any stripped \f(CW\*(C`\eglsadd\*(C'\fR instances.
237 .IP \fB\-\-strip\fR 4
238 .IX Item "--strip"
239 Switch on all strip options.
240 .IP \fB\-\-no\-strip\fR 4
241 .IX Item "--no-strip"
242 Switch off all strip options.
243 .IP \fB\-\-strip\-glsadd\fR 4
244 .IX Item "--strip-glsadd"
245 Strip \f(CW\*(C`\eglsadd\*(C'\fR and its argument from field values. (Default.)
246 .IP \fB\-\-no\-strip\-glsadd\fR 4
247 .IX Item "--no-strip-glsadd"
248 Don\*(Aqt strip \f(CW\*(C`\eglsadd\*(C'\fR from field values.
249 .IP \fB\-\-strip\-acronym\-font\fR 4
250 .IX Item "--strip-acronym-font"
251 Strip \f(CW\*(C`\eacronymfont\*(C'\fR from field values. (Default.)
252 .IP \fB\-\-no\-strip\-acronym\-font\fR 4
253 .IX Item "--no-strip-acronym-font"
254 Don\*(Aqt strip \f(CW\*(C`\eacronymfont\*(C'\fR from field values.
255 .IP \fB\-\-strip\-acronym\-text\fR 4
256 .IX Item "--strip-acronym-text"
257 Strip \fBtext\fR field for acronyms identified by \f(CW\*(C`\enewacro\*(C'\fR.
258 (Default.)
259 .IP \fB\-\-no\-strip\-acronym\-text\fR 4
260 .IX Item "--no-strip-acronym-text"
261 Don\*(Aqt strip \fBtext\fR field for acronyms.
262 .IP \fB\-\-strip\-acronym\-name\fR 4
263 .IX Item "--strip-acronym-name"
264 Strip \fBname\fR field for acronyms identified by \f(CW\*(C`\enewacro\*(C'\fR.
265 (Default.)
266 .IP \fB\-\-no\-strip\-acronym\-name\fR 4
267 .IX Item "--no-strip-acronym-name"
268 Don\*(Aqt strip \fBname\fR field for acronyms.
269 .IP \fB\-\-strip\-case\-change\fR 4
270 .IX Item "--strip-case-change"
271 Strip known case\-changing commands (such as \f(CW\*(C`\emakefirstuc\*(C'\fR or \f(CW\*(C`\ecapitalisewords\*(C'\fR)
272 from field values.
273 .IP \fB\-\-nostrip\-case\-change\fR 4
274 .IX Item "--nostrip-case-change"
275 Don\*(Aqt strip case\-changing commands. (Default.)
276 .SS "OTHER OPTIONS"
277 .IX Subsection "OTHER OPTIONS"
278 These options correspond to features introduced to \fIdatatool.sty\fR
279 version 3.0, which has a setting that stores the numeric value and
280 currency symbol (where applicable) when parsing data. The original
281 string (formatted number), numeric value and currency symbol are
282 stored in a special datum format, which ordinarily expands to its
283 original formatted text but also allows the previously parsed
284 information to be easily extracted without having to reparse the
285 data.
286 .IP "\fB\-\-setup\fR \fIoptions\fR" 4
287 .IX Item "--setup options"
288 Implement \f(CW\*(C`\eDTLsetup{\*(C'\fR\fIoptions\fR\f(CW\*(C`}\*(C'\fR at the start. This can include
289 options such as \f(CW\*(C`store\-datum\*(C'\fR, \f(CW\*(C`new\-value\-expand\*(C'\fR,
290 \&\f(CW\*(C`new\-value\-trim\*(C'\fR and \f(CW\*(C`default\-name\*(C'\fR.
291 .IP "\fB\-\-read\fR \fIoptions\fR" 4
292 .IX Item "--read options"
293 Instead of simply parsing the input file as a normal \fI.tex\fR file,
294 the source is presented to the TeX parser as
295 \&\f(CW\*(C`\eDTLread[\*(C'\fR\fIoptions\fR\f(CW\*(C`]{\*(C'\fR\fIin\-file\fR\f(CW\*(C`}\*(C'\fR where the options can be
296 used to specify the file format (for example, \f(CW\*(C`format=tsv\*(C'\fR).
297 .Sp
298 If the \fIoptions\fR list is empty (after trimming white space) then
299 this becomes equivalent to \fB\-\-no\-read\fR.
300 .IP \fB\-\-no\-read\fR 4
301 .IX Item "--no-read"
302 The input file is parsed as a normal \fI.tex\fR file, which may be the
303 complete document or a file that can be \f(CW\*(C`\einput\*(C'\fR into a document.
304 (Default.)
305 .IP "\fB\-\-save\-value\fR \fIsuffix\fR" 4
306 .IX Item "--save-value suffix"
307 If a field value is parsed and identified as numeric, the
308 unformatted numeric value will be saved in a field whose name is
309 constructed from the original field name followed by the given
310 \&\fIsuffix\fR.
311 .IP \fB\-\-no\-save\-value\fR 4
312 .IX Item "--no-save-value"
313 Don\*(Aqt save numeric value in a separate field. (Default.)
314 .IP "\fB\-\-save\-currency\fR \fIsuffix\fR" 4
315 .IX Item "--save-currency suffix"
316 If a field value is parsed and identified as currency data, the
317 currency symbol will be saved in a field whose name is
318 constructed from the original field name followed by the given
319 \&\fIsuffix\fR.
320 .IP \fB\-\-no\-save\-currency\fR 4
321 .IX Item "--no-save-currency"
322 Don\*(Aqt save currency symbol in a separate field. (Default.)
323 .IP \fB\-\-save\-datum\fR 4
324 .IX Item "--save-datum"
325 Equivalent to:
326 .Sp
327 .Vb 1
328 \& \-\-save\-value \*(Aq\-value\*(Aq \-\-save\-currency \*(Aq\-currency\*(Aq
329 .Ve
330 .IP \fB\-\-no\-save\-datum\fR 4
331 .IX Item "--no-save-datum"
332 Equivalent to \fB\-\-no\-save\-value\fR \fB\-\-no\-save\-currency\fR.
333 .SH REQUIRES
334 .IX Header "REQUIRES"
335 Java 8 and a TeX distribution.
336 .SH LICENSE
337 .IX Header "LICENSE"
338 License GPLv3+: GNU GPL version 3 or later
339 <http://gnu.org/licenses/gpl.html>
340 This is free software: you are free to change and redistribute it.
341 There is NO WARRANTY, to the extent permitted by law.
342 .SH "RECOMMENDED READING"
343 .IX Header "RECOMMENDED READING"
344 The bib2gls manual:
345 .PP
346 .Vb 1
347 \& texdoc bib2gls
348 .Ve
349 .PP
350 The glossaries\-extra manual:
351 .PP
352 .Vb 1
353 \& texdoc glossaries\-extra
354 .Ve
355 .PP
356 The glossaries manual:
357 .PP
358 .Vb 1
359 \& texdoc glossaries
360 .Ve
361 .PP
362 The datatool manual:
363 .PP
364 .Vb 1
365 \& texdoc datatool
366 .Ve
367 .SH AUTHOR
368 .IX Header "AUTHOR"
369 Nicola L. C. Talbot,
370 <https://www.dickimaw\-books.com/>