1LUAOTFLOAD-TOOL(1) text processing LUAOTFLOAD-TOOL(1)
2
3
4
6 luaotfload-tool - generate and query the Luaotfload font names database
7
9 luaotfload-tool [ -bcDfFiIlLnpqRSuvVhw ]
10
11 luaotfload-tool --update [ --force ] [ --quiet ] [ --verbose ]
12 [ --prefer-texmf ] [ --dry-run ] [ --formats=[+|-]EXTENSIONS ] [
13 --no-compress ] [ --no-strip ] [ --local ] [ --max-fonts=N ]
14
15 luaotfload-tool --find=FONTNAME [ --fuzzy ] [ --info ] [ --inspect ]
16 [ --no-reload ]
17
18 luaotfload-tool --flush-lookups
19
20 luaotfload-tool --cache=DIRECTIVE
21
22 luaotfload-tool --list=CRITERION[:VALUE] [ --fields=F1,F2,...,Fn ]
23
24 luaotfload-tool --bisect=DIRECTIVE
25
26 luaotfload-tool --help
27
28 luaotfload-tool --version
29
30 luaotfload-tool --show-blacklist
31
32 luaotfload-tool --diagnose=CHECK
33
34 luaotfload-tool --conf=FILE --dumpconf
35
37 luaotfload-tool accesses the font names database that is required by
38 the Luaotfload package. There are two general modes: update and query.
39
40 • update: update the database or rebuild it entirely;
41
42 • query: resolve a font name or display close matches.
43
45 update mode
46 --update, -u
47 Update the database; indexes new fonts.
48
49 --force, -f
50 Force rebuilding of the database; re-indexes all fonts.
51
52 --local, -L
53 Include font files in $PWD. This option will cause large parts
54 of the database to be rebuilt. Thus it is quite inefficient.
55 Additionally, if local font files are found, the database is
56 prevented from being saved to disk, so the local fonts need to
57 be parsed with every invocation of luaotfload-tool.
58
59 --no-reload, -n
60 Suppress auto-updates to the database (e.g. when --find is
61 passed an unknown name).
62
63 --no-compress, -c
64 Do not filter the plain text version of the font index through
65 gzip. Useful for debugging if your editor is built without zlib.
66
67 --prefer-texmf, -p
68 Organize the file name database in a way so that it prefer fonts
69 in the TEXMF tree over system fonts if they are installed in
70 both.
71
72 --formats=EXTENSIONS
73 Extensions of the font files to index. Where EXTENSIONS is a
74 comma-separated list of supported file extensions (otf, ttf,
75 ttc). If the list is prefixed with a + sign, the given list is
76 added to the currently active one; - subtracts. Default:
77 otf,ttf,ttc. Examples:
78
79 1. --formats=-ttc,ttf would skip TrueType fonts and font collec‐
80 tions;
81
82 2. --formats=otf would scan only OpenType files;
83
84 3. --formats=+afm includes binary Postscript files accompanied
85 by an AFM file.
86
87 query mode
88 --find=NAME
89 Resolve a font name; this looks up <name> in the database and
90 prints the file name it is mapped to. --find also understands
91 request syntax, i.e. --find=file:foo.otf checks whether foo.otf
92 is indexed.
93
94 --fuzzy, -F
95 Show approximate matches to the file name if the lookup was un‐
96 successful (requires --find).
97
98 --info, -i
99 Display basic information to a resolved font file (requires
100 --find).
101
102 --inspect, -I
103 Display detailed information by loading the font and analyzing
104 the font table; very slow! For the meaning of the returned
105 fields see the LuaTeX documentation. (requires --find).
106
107 --list=CRITERION
108 Show entries, where CRITERION is one of the following:
109
110 1. the character *, selecting all entries;
111
112 2. a field of a database entry, for instance version or format*,
113 according to which the output will be sorted. Information in
114 an unstripped database (see the option --no-strip above) is
115 nested: Subfields of a record can be addressed using the ->
116 separator, e. g. file->location, style->units_per_em, or
117 names->sanitized->english->prefmodifiers. NB: shell syntax
118 requires that arguments containing -> be properly quoted!
119
120 3. an expression of the form field:value to limit the output to
121 entries whose field matches value. The value can contain * to
122 match an arbitrary number of characters.
123
124 For example, in order to output file names and corresponding
125 versions, sorted by the font format:
126
127 ./luaotfload-tool.lua --list="format" --fields="file->base,version"
128
129 This prints:
130
131 otf latinmodern-math.otf Version 1.958
132 otf lmromancaps10-oblique.otf 2.004
133 otf lmmono8-regular.otf 2.004
134 otf lmmonoproplt10-bold.otf 2.004
135 otf lmsans10-oblique.otf 2.004
136 otf lmromanslant8-regular.otf 2.004
137 otf lmroman12-italic.otf 2.004
138 otf lmsansdemicond10-oblique.otf 2.004
139 ...
140
141 --fields=FIELDS
142 Comma-separated list of fields that should be printed. Informa‐
143 tion in an unstripped database (see the option --no-strip above)
144 is nested: Subfields of a record can be addressed using the ->
145 separator, e. g. file->location, style->units_per_em, or
146 names->sanitized->english->subfamily. The default is plain‐
147 name,version*. (Only meaningful with --list.)
148
149 font and lookup caches
150 --flush-lookups
151 Clear font name lookup cache (experimental).
152
153 --cache=DIRECTIVE
154 Cache control, where DIRECTIVE is one of the following:
155
156 1. purge -> delete Lua files from cache;
157
158 2. erase -> delete Lua and Luc files from cache;
159
160 3. show -> print stats.
161
162 debugging methods
163 --show-blacklist, -b
164 Show blacklisted files (not directories).
165
166 --dry-run, -D
167 Don’t load fonts when updating the database; scan directories
168 only. (For debugging file system related issues.)
169
170 --no-strip
171 Do not strip redundant information after building the database.
172 Warning: this will inflate the index to about two to three times
173 the normal size.
174
175 --max-fonts=N
176 Process at most N font files, including fonts already indexed in
177 the count.
178
179 --bisect=DIRECTIVE
180 Bisection of the font database. This mode is intended as as‐
181 sistance in debugging the Luatex engine, especially when track‐
182 ing memleaks or buggy fonts.
183
184 DIRECTIVE can be one of the following:
185
186 1. run -> Make luaotfload-tool respect the bisection progress
187 when running. Combined with --update and possibly --force
188 this will only process the files from the start up until the
189 pivot and ignore the rest.
190
191 2. start -> Start bisection: create a bisection state file and
192 initialize the low, high, and pivot indices.
193
194 3. stop -> Terminate the current bisection session by deleting
195 the state file.
196
197 4. good | bad -> Mark the section processed last as “good” or
198 “bad”, respectively. The next bisection step will continue
199 with the bad section.
200
201 5. status -> Print status information about the current bisec‐
202 tion session. Hint: Use with higher verbosity settings for
203 more output.
204
205 A bisection session is initiated by issuing the start directive.
206 This sets the pivot to the middle of the list of available font
207 files. Now run luaotfload-tool with the --update flag set as
208 well as --bisect=run: only the fonts up to the pivot will be
209 considered. If that task exhibited the issue you are tracking,
210 then tell Luaotfload using --bisect=bad. The next step of --bi‐
211 sect=run will continue bisection with the part of the files be‐
212 low the pivot. Likewise, issue --bisect=good in order to con‐
213 tinue with the fonts above the pivot, assuming the tested part
214 of the list did not trigger the bug.
215
216 Once the culprit font is tracked down, good or bad will have no
217 effect anymore. run will always end up processing the single
218 font file that was left. Use --bisect=stop to clear the bisec‐
219 tion state.
220
221 miscellaneous
222 --verbose=N, -v
223 Set verbosity level to n or the number of repetitions of -v.
224
225 --quiet
226 No verbose output (log level set to zero).
227
228 --log=CHANNEL
229 Redirect log output (for database troubleshooting), where CHAN‐
230 NEL can be
231
232 1. stdout -> all output will be dumped to the terminal (de‐
233 fault); or
234
235 2. file -> write to a file to the temporary directory (the name
236 will be chosen automatically.
237
238 --version, -V
239 Show version numbers of components as well as some basic infor‐
240 mation and exit.
241
242 --help, -h
243 Show help message and exit.
244
245 --diagnose=CHECK
246 Run the diagnostic procedure CHECK. Available procedures are:
247
248 1. files -> check Luaotfload files for modifications;
249
250 2. permissions -> check permissions of cache directories and
251 files;
252
253 3.
254
255 environment -> print relevant
256 environment and kpse variables;
257
258 4. repository -> check the git repository for new releases,
259
260 5. index -> check database, display information about it.
261
262 Procedures can be chained by concatenating with commas, e.g.
263 --diagnose=files,permissions. Specify thorough to run all
264 checks.
265
266 --conf=FILE
267 Read the configuration from FILE. See luaotfload.conf(%) for
268 documentation concerning the format and available options.
269
270 --dumpconf
271 Print the currently active configuration; the output can be
272 saved to a file and used for bootstrapping a custom configura‐
273 tion files.
274
276 The font name database is usually located in the directory
277 texmf-var/luatex-cache/generic/names/ ($TEXMFCACHE as set in texmf.cnf)
278 of your TeX Live distribution as a zlib-compressed file luaot‐
279 fload-names.lua.gz. The experimental lookup cache will be created as
280 luaotfload-lookup-cache.lua in the same directory. These Lua tables
281 are not used directly by Luaotfload, though. Instead, they are com‐
282 piled to Lua bytecode which is written to corresponding files with the
283 extension .luc in the same directory. When modifying the files by hand
284 keep in mind that only if the bytecode files are missing will Luaot‐
285 fload use the plain version instead. Both kinds of files are safe to
286 delete, at the cost of regenerating them with the next run of LuaTeX.
287
289 luaotfload.conf(5), luatex(1), lua(1)
290
291 • texdoc luaotfload to display the manual for the Luaotfload package
292
293 • Luaotfload development https://github.com/latex3/luaotfload
294
295 • LuaLaTeX mailing list http://tug.org/pipermail/lualatex-dev/
296
297 • LuaTeX http://luatex.org/
298
299 • ConTeXt http://wiki.contextgarden.net
300
301 • Luaotfload on CTAN http://ctan.org/pkg/luaotfload
302
304 Tons, probably.
305
307 Luaotfload was developed by the LuaLaTeX dev team (‐
308 https://github.com/lualatex/). It is currently maintained by the LaTeX
309 Project Team at https://github.com/latex3/luaotfload The fontloader
310 code is provided by Hans Hagen of Pragma ADE, Hasselt NL (‐
311 http://pragma-ade.com/).
312
313 This manual page was written by Philipp Gesang <phg@phi-gamma.net>.
314
316 GPL v2.0
317
318
319
320
3213.17 2021-01-08 LUAOTFLOAD-TOOL(1)