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
40       · update:  update the database or rebuild it entirely;
41
42       · query:   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
96              unsuccessful (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.
122
123              For  example,  in  order  to output file names and corresponding
124              versions, sorted by the font format:
125
126                 ./luaotfload-tool.lua --list="format" --fields="file->base,version"
127
128              This prints:
129
130                 otf latinmodern-math.otf  Version 1.958
131                 otf lmromancaps10-oblique.otf 2.004
132                 otf lmmono8-regular.otf 2.004
133                 otf lmmonoproplt10-bold.otf 2.004
134                 otf lmsans10-oblique.otf  2.004
135                 otf lmromanslant8-regular.otf 2.004
136                 otf lmroman12-italic.otf  2.004
137                 otf lmsansdemicond10-oblique.otf  2.004
138                 ...
139
140       --fields=FIELDS
141              Comma-separated list of fields that should be printed.  Informa‐
142              tion in an unstripped database (see the option --no-strip above)
143              is nested: Subfields of a record can be addressed using  the  ->
144              separator,   e.   g.   file->location,  style->units_per_em,  or
145              names->sanitized->english->subfamily.   The  default  is  plain‐
146              name,version*.  (Only meaningful with --list.)
147
148   font and lookup caches
149       --flush-lookups
150              Clear font name lookup cache (experimental).
151
152       --cache=DIRECTIVE
153              Cache control, where DIRECTIVE is one of the following:
154
155              1. purge -> delete Lua files from cache;
156
157              2. erase -> delete Lua and Luc files from cache;
158
159              3. show  -> print stats.
160
161   debugging methods
162       --show-blacklist, -b
163              Show blacklisted files (not directories).
164
165       --dry-run, -D
166              Don’t  load  fonts  when updating the database; scan directories
167              only.  (For debugging file system related issues.)
168
169       --no-strip
170              Do not strip redundant information after building the  database.
171              Warning: this will inflate the index to about two to three times
172              the normal size.
173
174       --max-fonts=N
175              Process at most N font files, including fonts already indexed in
176              the count.
177
178       --bisect=DIRECTIVE
179              Bisection of the font database.  This mode is intended as assis‐
180              tance in debugging the Luatex engine, especially  when  tracking
181              memleaks or buggy fonts.
182
183              DIRECTIVE can be one of the following:
184
185              1. run  ->  Make  luaotfload-tool respect the bisection progress
186                 when running.  Combined with --update  and  possibly  --force
187                 this  will only process the files from the start up until the
188                 pivot and ignore the rest.
189
190              2. start -> Start bisection: create a bisection state  file  and
191                 initialize the low, high, and pivot indices.
192
193              3. stop  ->  Terminate the current bisection session by deleting
194                 the state file.
195
196              4. good | bad -> Mark the section processed last  as  “good”  or
197                 “bad”,  respectively.  The  next bisection step will continue
198                 with the bad section.
199
200              5. status -> Print status information about the  current  bisec‐
201                 tion  session.  Hint:  Use with higher verbosity settings for
202                 more output.
203
204              A bisection session is initiated by issuing the start directive.
205              This  sets the pivot to the middle of the list of available font
206              files.  Now run luaotfload-tool with the --update  flag  set  as
207              well  as  --bisect=run:  only  the fonts up to the pivot will be
208              considered. If that task exhibited the issue you  are  tracking,
209              then  tell  Luaotfload  using  --bisect=bad.   The  next step of
210              --bisect=run will continue bisection with the part of the  files
211              below the pivot.  Likewise, issue --bisect=good in order to con‐
212              tinue with the fonts above the pivot, assuming the  tested  part
213              of the list did not trigger the bug.
214
215              Once  the culprit font is tracked down, good or bad will have no
216              effect anymore. run will always end  up  processing  the  single
217              font  file that was left.  Use --bisect=stop to clear the bisec‐
218              tion state.
219
220   miscellaneous
221       --verbose=N, -v
222              Set verbosity level to n or the number of repetitions of -v.
223
224       --quiet
225              No verbose output (log level set to zero).
226
227       --log=CHANNEL
228              Redirect log output (for database troubleshooting), where  CHAN‐
229              NEL can be
230
231              1. stdout   ->  all  output  will  be  dumped  to  the  terminal
232                 (default); or
233
234              2. file -> write to a file to the temporary directory (the  name
235                 will be chosen automatically.
236
237       --version, -V
238              Show  version numbers of components as well as some basic infor‐
239              mation and exit.
240
241       --help, -h
242              Show help message and exit.
243
244       --diagnose=CHECK
245              Run the diagnostic procedure CHECK. Available procedures are:
246
247              1. files -> check Luaotfload files for modifications;
248
249              2. permissions -> check permissions  of  cache  directories  and
250                 files;
251
252              3.
253
254                 environment -> print relevant
255                        environment and kpse variables;
256
257              4. repository -> check the git repository for new releases,
258
259              5. index -> check database, display information about it.
260
261              Procedures  can  be  chained  by concatenating with commas, e.g.
262              --diagnose=files,permissions.   Specify  thorough  to  run   all
263              checks.
264
265       --conf=FILE
266              Read  the  configuration  from  FILE. See luaotfload.conf(%) for
267              documentation concerning the format and available options.
268
269       --dumpconf
270              Print the currently active  configuration;  the  output  can  be
271              saved  to  a file and used for bootstrapping a custom configura‐
272              tion files.
273

FILES

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

SEE ALSO

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

BUGS

303       Tons, probably.
304

AUTHORS

306       Luaotfload   was   developed   by   the   LuaLaTeX    dev    team    (‐
307       https://github.com/lualatex/).  It  is  currently  maintained by Ulrike
308       Fischer and Marcel  Krüger  at  https://github.com/u-fischer/luaotfload
309       The fontloader code is provided by Hans Hagen of Pragma ADE, Hasselt NL
310       (http://pragma-ade.com/).
311
312       This manual page was written by Philipp Gesang <phg@phi-gamma.net>.
313
315       GPL v2.0
316
317
318
319
3202.97                              2019-05-18                LUAOTFLOAD-TOOL(1)
Impressum