Debian Codegraph @

texmf-dist/doc/luatex/luaotfload/luaotfload-tool.rst

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