Debian Codegraph @

texmf-dist/doc/man/man1/luaotfload-tool.1

raw
1 .\" Man page generated from reStructuredText.
2 .
3 .
4 .nr rst2man-indent-level 0
5 .
6 .de1 rstReportMargin
7 \\$1 \\n[an-margin]
8 level \\n[rst2man-indent-level]
9 level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
10 -
11 \\n[rst2man-indent0]
12 \\n[rst2man-indent1]
13 \\n[rst2man-indent2]
14 ..
15 .de1 INDENT
16 .\" .rstReportMargin pre:
17 . RS \\$1
18 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
19 . nr rst2man-indent-level +1
20 .\" .rstReportMargin post:
21 ..
22 .de UNINDENT
23 . RE
24 .\" indent \\n[an-margin]
25 .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
26 .nr rst2man-indent-level -1
27 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
28 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
29 ..
30 .TH "LUAOTFLOAD-TOOL" 1 "2024-12-03" "3.29" "text processing"
31 .SH NAME
32 luaotfload-tool \- generate and query the Luaotfload font names database
33 .SH SYNOPSIS
34 .sp
35 \fBluaotfload\-tool\fP [ \-bcDfFiIlLnpqRSuvVhw ]
36 .INDENT 0.0
37 .TP
38 .B \fBluaotfload\-tool\fP \-\-update [ \-\-force ] [ \-\-quiet ] [ \-\-verbose ]
39 [ \-\-prefer\-texmf ] [ \-\-dry\-run ]
40 [ \-\-formats=[+|\-]EXTENSIONS ]
41 [ \-\-no\-compress ] [ \-\-no\-strip ]
42 [ \-\-local ] [ \-\-max\-fonts=N ]
43 .TP
44 .B \fBluaotfload\-tool\fP \-\-find=FONTNAME [ \-\-fuzzy ] [ \-\-info ] [ \-\-inspect ]
45 [ \-\-no\-reload ]
46 .UNINDENT
47 .sp
48 \fBluaotfload\-tool\fP \-\-flush\-lookups
49 .sp
50 \fBluaotfload\-tool\fP \-\-cache=DIRECTIVE
51 .sp
52 \fBluaotfload\-tool\fP \-\-list=CRITERION[:VALUE] [ \-\-fields=F1,F2,...,Fn ]
53 .sp
54 \fBluaotfload\-tool\fP \-\-bisect=DIRECTIVE
55 .sp
56 \fBluaotfload\-tool\fP \-\-help
57 .sp
58 \fBluaotfload\-tool\fP \-\-version
59 .sp
60 \fBluaotfload\-tool\fP \-\-show\-blacklist
61 .sp
62 \fBluaotfload\-tool\fP \-\-diagnose=CHECK
63 .sp
64 \fBluaotfload\-tool\fP \-\-conf=FILE \-\-dumpconf
65 .SH DESCRIPTION
66 .sp
67 luaotfload\-tool accesses the font names database that is required by
68 the \fILuaotfload\fP package. There are two general modes: \fBupdate\fP and
69 \fBquery\fP\&.
70 .INDENT 0.0
71 .IP \(bu 2
72 \fBupdate\fP: update the database or rebuild it entirely;
73 .IP \(bu 2
74 \fBquery\fP: resolve a font name or display close matches.
75 .UNINDENT
76 .SH OPTIONS
77 .SS update mode
78 .INDENT 0.0
79 .TP
80 .B \-\-update\fP,\fB \-u
81 Update the database; indexes new fonts.
82 .TP
83 .B \-\-force\fP,\fB \-f
84 Force rebuilding of the database; re\-indexes
85 all fonts.
86 .TP
87 .B \-\-local\fP,\fB \-L
88 Include font files in \fB$PWD\fP\&. This option
89 will cause large parts of the database to be
90 rebuilt. Thus it is quite inefficient.
91 Additionally, if local font files are found,
92 the database is prevented from being saved
93 to disk, so the local fonts need to be parsed
94 with every invocation of \fBluaotfload\-tool\fP\&.
95 .TP
96 .B \-\-no\-reload\fP,\fB \-n
97 Suppress auto\-updates to the database (e.g.
98 when \fB\-\-find\fP is passed an unknown name).
99 .TP
100 .B \-\-no\-compress\fP,\fB \-c
101 Do not filter the plain text version of the
102 font index through gzip. Useful for debugging
103 if your editor is built without zlib.
104 .TP
105 .B \-\-prefer\-texmf\fP,\fB \-p
106 Organize the file name database in a way so
107 that it prefer fonts in the \fITEXMF\fP tree over
108 system fonts if they are installed in both.
109 .TP
110 .BI \-\-formats\fB= EXTENSIONS
111 Extensions of the font files to index.
112 Where \fIEXTENSIONS\fP is a comma\-separated list of
113 supported file extensions (otf, ttf, ttc).
114 If the list is prefixed
115 with a \fB+\fP sign, the given list is added to
116 the currently active one; \fB\-\fP subtracts.
117 Default: \fIotf,ttf,ttc\fP\&.
118 Examples:
119 .INDENT 7.0
120 .IP 1. 3
121 \fB\-\-formats=\-ttc,ttf\fP would skip
122 TrueType fonts and font collections;
123 .IP 2. 3
124 \fB\-\-formats=otf\fP would scan only OpenType
125 files;
126 .IP 3. 3
127 \fB\-\-formats=+afm\fP includes binary
128 Postscript files accompanied by an AFM file.
129 .UNINDENT
130 .UNINDENT
131 .SS query mode
132 .INDENT 0.0
133 .TP
134 .BI \-\-find\fB= NAME
135 Resolve a font name; this looks up <name> in
136 the database and prints the file name it is
137 mapped to.
138 \fB\-\-find\fP also understands request syntax,
139 i.e. \fB\-\-find=file:foo.otf\fP checks whether
140 \fBfoo.otf\fP is indexed.
141 .TP
142 .B \-\-fuzzy\fP,\fB \-F
143 Show approximate matches to the file name if
144 the lookup was unsuccessful (requires
145 \fB\-\-find\fP).
146 .TP
147 .B \-\-info\fP,\fB \-i
148 Display basic information to a resolved font
149 file (requires \fB\-\-find\fP).
150 .TP
151 .B \-\-inspect\fP,\fB \-I
152 Display detailed information by loading the
153 font and analyzing the font table; very slow!
154 For the meaning of the returned fields see
155 the LuaTeX documentation.
156 (requires \fB\-\-find\fP).
157 .TP
158 .BI \-\-list\fB= CRITERION
159 Show entries, where \fICRITERION\fP is one of the
160 following:
161 .INDENT 7.0
162 .IP 1. 3
163 the character \fB*\fP, selecting all entries;
164 .IP 2. 3
165 a field of a database entry, for instance
166 \fIversion\fP or \fIformat*\fP, according to which
167 the output will be sorted.
168 Information in an unstripped database (see
169 the option \fB\-\-no\-strip\fP above) is nested:
170 Subfields of a record can be addressed using
171 the \fB\->\fP separator, e. g.
172 \fBfile\->location\fP, \fBstyle\->units_per_em\fP,
173 or
174 \fBnames\->sanitized\->english\->prefmodifiers\fP\&.
175 NB: shell syntax requires that arguments
176 containing \fB\->\fP be properly quoted!
177 .IP 3. 3
178 an expression of the form \fBfield:value\fP to
179 limit the output to entries whose \fBfield\fP
180 matches \fBvalue\fP\&. The \fBvalue\fP can contain
181 \fB*\fP to match an arbitrary number of characters.
182 .UNINDENT
183 .sp
184 For example, in order to output file names and
185 corresponding versions, sorted by the font
186 format:
187 .INDENT 7.0
188 .INDENT 3.5
189 .sp
190 .nf
191 .ft C
192 \&./luaotfload\-tool.lua \-\-list="format" \-\-fields="file\->base,version"
193 .ft P
194 .fi
195 .UNINDENT
196 .UNINDENT
197 .sp
198 This prints:
199 .INDENT 7.0
200 .INDENT 3.5
201 .sp
202 .nf
203 .ft C
204 otf latinmodern\-math.otf Version 1.958
205 otf lmromancaps10\-oblique.otf 2.004
206 otf lmmono8\-regular.otf 2.004
207 otf lmmonoproplt10\-bold.otf 2.004
208 otf lmsans10\-oblique.otf 2.004
209 otf lmromanslant8\-regular.otf 2.004
210 otf lmroman12\-italic.otf 2.004
211 otf lmsansdemicond10\-oblique.otf 2.004
212 \&...
213 .ft P
214 .fi
215 .UNINDENT
216 .UNINDENT
217 .TP
218 .BI \-\-fields\fB= FIELDS
219 Comma\-separated list of fields that should be
220 printed.
221 Information in an unstripped database (see the
222 option \fB\-\-no\-strip\fP above) is nested:
223 Subfields of a record can be addressed using
224 the \fB\->\fP separator, e. g.
225 \fBfile\->location\fP, \fBstyle\->units_per_em\fP,
226 or \fBnames\->sanitized\->english\->subfamily\fP\&.
227 The default is plainname,version*.
228 (Only meaningful with \fB\-\-list\fP\&.)
229 .UNINDENT
230 .SS font and lookup caches
231 .INDENT 0.0
232 .TP
233 .B \-\-flush\-lookups
234 Clear font name lookup cache (experimental).
235 .TP
236 .BI \-\-cache\fB= DIRECTIVE
237 Cache control, where \fIDIRECTIVE\fP is one of the
238 following:
239 .INDENT 7.0
240 .IP 1. 3
241 \fBpurge\fP \-> delete Lua files from cache;
242 .IP 2. 3
243 \fBerase\fP \-> delete Lua and Luc files from
244 cache;
245 .IP 3. 3
246 \fBshow\fP \-> print stats.
247 .UNINDENT
248 .UNINDENT
249 .SS debugging methods
250 .INDENT 0.0
251 .TP
252 .B \-\-show\-blacklist\fP,\fB \-b
253 Show blacklisted files (not directories).
254 .TP
255 .B \-\-dry\-run\fP,\fB \-D
256 Don’t load fonts when updating the database;
257 scan directories only.
258 (For debugging file system related issues.)
259 .TP
260 .B \-\-no\-strip
261 Do not strip redundant information after
262 building the database. Warning: this will
263 inflate the index to about two to three times
264 the normal size.
265 .TP
266 .BI \-\-max\-fonts\fB= N
267 Process at most \fIN\fP font files, including fonts
268 already indexed in the count.
269 .TP
270 .BI \-\-bisect\fB= DIRECTIVE
271 Bisection of the font database.
272 This mode is intended as assistance in
273 debugging the Luatex engine, especially when
274 tracking memleaks or buggy fonts.
275 .sp
276 \fIDIRECTIVE\fP can be one of the following:
277 .INDENT 7.0
278 .IP 1. 3
279 \fBrun\fP \-> Make \fBluaotfload\-tool\fP respect
280 the bisection progress when running.
281 Combined with \fB\-\-update\fP and possibly
282 \fB\-\-force\fP this will only process the files
283 from the start up until the pivot and ignore
284 the rest.
285 .IP 2. 3
286 \fBstart\fP \-> Start bisection: create a
287 bisection state file and initialize the low,
288 high, and pivot indices.
289 .IP 3. 3
290 \fBstop\fP \-> Terminate the current bisection
291 session by deleting the state file.
292 .IP 4. 3
293 \fBgood\fP | \fBbad\fP \-> Mark the section
294 processed last as “good” or “bad”,
295 respectively. The next bisection step will
296 continue with the bad section.
297 .IP 5. 3
298 \fBstatus\fP \-> Print status information about
299 the current bisection session. Hint: Use
300 with higher verbosity settings for more
301 output.
302 .UNINDENT
303 .sp
304 A bisection session is initiated by issuing the
305 \fBstart\fP directive. This sets the pivot to the
306 middle of the list of available font files.
307 Now run \fIluaotfload\-tool\fP with the \fB\-\-update\fP
308 flag set as well as \fB\-\-bisect=run\fP: only the
309 fonts up to the pivot will be considered. If
310 that task exhibited the issue you are tracking,
311 then tell Luaotfload using \fB\-\-bisect=bad\fP\&.
312 The next step of \fB\-\-bisect=run\fP will continue
313 bisection with the part of the files below the
314 pivot.
315 Likewise, issue \fB\-\-bisect=good\fP in order to
316 continue with the fonts above the pivot,
317 assuming the tested part of the list did not
318 trigger the bug.
319 .sp
320 Once the culprit font is tracked down, \fBgood\fP
321 or \fBbad\fP will have no effect anymore. \fBrun\fP
322 will always end up processing the single font
323 file that was left.
324 Use \fB\-\-bisect=stop\fP to clear the bisection
325 state.
326 .UNINDENT
327 .SS miscellaneous
328 .INDENT 0.0
329 .TP
330 .BI \-\-verbose\fB= N\fR,\fB \ \-v
331 Set verbosity level to \fIn\fP or the number of
332 repetitions of \fB\-v\fP\&.
333 .TP
334 .B \-\-quiet
335 No verbose output (log level set to zero).
336 .TP
337 .BI \-\-log\fB= CHANNEL
338 Redirect log output (for database
339 troubleshooting), where \fICHANNEL\fP can be
340 .INDENT 7.0
341 .IP 1. 3
342 \fBstdout\fP \-> all output will be
343 dumped to the terminal (default); or
344 .IP 2. 3
345 \fBfile\fP \-> write to a file to the temporary
346 directory (the name will be chosen
347 automatically.
348 .UNINDENT
349 .TP
350 .B \-\-version\fP,\fB \-V
351 Show version numbers of components as well as
352 some basic information and exit.
353 .TP
354 .B \-\-help\fP,\fB \-h
355 Show help message and exit.
356 .TP
357 .BI \-\-diagnose\fB= CHECK
358 Run the diagnostic procedure \fICHECK\fP\&. Available
359 procedures are:
360 .INDENT 7.0
361 .IP 1. 3
362 \fBfiles\fP \-> check \fILuaotfload\fP files for
363 modifications;
364 .IP 2. 3
365 \fBpermissions\fP \-> check permissions of
366 cache directories and files;
367 .IP 3. 3
368 .INDENT 3.0
369 .TP
370 .B \fBenvironment\fP \-> print relevant
371 environment and kpse variables;
372 .UNINDENT
373 .IP 4. 3
374 \fBrepository\fP \-> check the git repository
375 for new releases,
376 .IP 5. 3
377 \fBindex\fP \-> check database, display
378 information about it.
379 .UNINDENT
380 .sp
381 Procedures can be chained by concatenating with
382 commas, e.g. \fB\-\-diagnose=files,permissions\fP\&.
383 Specify \fBthorough\fP to run all checks.
384 .TP
385 .BI \-\-conf\fB= FILE
386 Read the configuration from \fIFILE\fP\&. See
387 \fBluaotfload.conf\fP(%) for documentation
388 concerning the format and available options.
389 .TP
390 .B \-\-dumpconf
391 Print the currently active configuration; the
392 output can be saved to a file and used for
393 bootstrapping a custom configuration files.
394 .TP
395 .B \-\-aliases
396 Dump the font name database as a kpathsea
397 aliases file. This option is experimental and
398 might go away.
399 .UNINDENT
400 .SH FILES
401 .sp
402 The font name database is usually located in the directory
403 \fBtexmf\-var/luatex\-cache/generic/names/\fP (\fB$TEXMFCACHE\fP as set in
404 \fBtexmf.cnf\fP) of your \fITeX Live\fP distribution as a zlib\-compressed
405 file \fBluaotfload\-names.lua.gz\fP\&.
406 The experimental lookup cache will be created as
407 \fBluaotfload\-lookup\-cache.lua\fP in the same directory.
408 These Lua tables are not used directly by Luaotfload, though.
409 Instead, they are compiled to Lua bytecode which is written to
410 corresponding files with the extension \fB\&.luc\fP in the same directory.
411 When modifying the files by hand keep in mind that only if the bytecode
412 files are missing will Luaotfload use the plain version instead.
413 Both kinds of files are safe to delete, at the cost of regenerating
414 them with the next run of \fILuaTeX\fP\&.
415 .SH SEE ALSO
416 .sp
417 \fBluaotfload.conf\fP(5), \fBluatex\fP(1), \fBlua\fP(1)
418 .INDENT 0.0
419 .IP \(bu 2
420 \fBtexdoc luaotfload\fP to display the manual for the \fILuaotfload\fP
421 package
422 .IP \(bu 2
423 Luaotfload development \fI\%https://github.com/latex3/luaotfload\fP
424 .IP \(bu 2
425 LuaLaTeX mailing list \fI\%http://tug.org/pipermail/lualatex\-dev/\fP
426 .IP \(bu 2
427 LuaTeX \fI\%http://luatex.org/\fP
428 .IP \(bu 2
429 ConTeXt \fI\%http://wiki.contextgarden.net\fP
430 .IP \(bu 2
431 Luaotfload on CTAN \fI\%http://ctan.org/pkg/luaotfload\fP
432 .UNINDENT
433 .SH BUGS
434 .sp
435 Tons, probably.
436 .SH AUTHORS
437 .sp
438 \fILuaotfload\fP was developed by the LuaLaTeX dev team
439 (\fI\%https://github.com/lualatex/\fP). It is currently maintained by the LaTeX
440 Project Team at \fI\%https://github.com/latex3/luaotfload\fP
441 The fontloader code is provided by Hans Hagen of Pragma ADE, Hasselt
442 NL (\fI\%http://pragma\-ade.com/\fP).
443 .sp
444 This manual page was written by Philipp Gesang <\fI\%phg@phi\-gamma.net\fP>.
445 .SH COPYRIGHT
446 GPL v2.0
447 .\" Generated by docutils manpage writer.
448 .