1LUAOTFLOAD-TOOL(1)              text processing             LUAOTFLOAD-TOOL(1)
2
3
4

NAME

6       luaotfload-tool - generate and query the Luaotfload font names database
7

SYNOPSIS

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

DESCRIPTION

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
40update:  update the database or rebuild it entirely;
41
42query:   resolve a font name or display close matches.
43

OPTIONS

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
275       --aliases
276              Dump the font name database as a kpathsea aliases file. This op‐
277              tion is experimental and might go away.
278

FILES

280       The  font  name  database  is  usually   located   in   the   directory
281       texmf-var/luatex-cache/generic/names/ ($TEXMFCACHE as set in texmf.cnf)
282       of  your  TeX  Live  distribution  as  a  zlib-compressed  file  luaot‐
283       fload-names.lua.gz.   The  experimental lookup cache will be created as
284       luaotfload-lookup-cache.lua in the same directory.   These  Lua  tables
285       are  not  used  directly by Luaotfload, though.  Instead, they are com‐
286       piled to Lua bytecode which is written to corresponding files with  the
287       extension .luc in the same directory.  When modifying the files by hand
288       keep in mind that only if the bytecode files are  missing  will  Luaot‐
289       fload  use  the plain version instead.  Both kinds of files are safe to
290       delete, at the cost of regenerating them with the next run of LuaTeX.
291

SEE ALSO

293       luaotfload.conf(5), luatex(1), lua(1)
294
295texdoc luaotfload to display the manual for the Luaotfload package
296
297       • Luaotfload development https://github.com/latex3/luaotfload
298
299       • LuaLaTeX mailing list  http://tug.org/pipermail/lualatex-dev/
300
301       • LuaTeX                 http://luatex.org/
302
303       • ConTeXt                http://wiki.contextgarden.net
304
305       • Luaotfload on CTAN     http://ctan.org/pkg/luaotfload
306

BUGS

308       Tons, probably.
309

AUTHORS

311       Luaotfload   was   developed   by   the   LuaLaTeX    dev    team    (‐
312       https://github.com/lualatex/).  It is currently maintained by the LaTeX
313       Project Team  at  https://github.com/latex3/luaotfload  The  fontloader
314       code   is  provided  by  Hans  Hagen  of  Pragma  ADE,  Hasselt  NL  (‐
315       http://pragma-ade.com/).
316
317       This manual page was written by Philipp Gesang <phg@phi-gamma.net>.
318
320       GPL v2.0
321
322
323
324
3253.23                              2022-10-03                LUAOTFLOAD-TOOL(1)
Impressum