Debian Codegraph @

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

raw
1 =======================================================================
2 luaotfload.conf
3 =======================================================================
4
5 -----------------------------------------------------------------------
6 Luaotfload configuration file
7 -----------------------------------------------------------------------
8
9 :Date: 2024-12-03
10 :Copyright: GPL v2.0
11 :Version: 3.29
12 :Manual section: 5
13 :Manual group: text processing
14
15 SYNOPSIS
16 =======================================================================
17
18 - **./luaotfload{.conf,rc}**
19 - **XDG_CONFIG_HOME/luaotfload/luaotfload{.conf,rc}**
20 - **~/.luaotfloadrc**
21
22 DESCRIPTION
23 =======================================================================
24
25 The file ``luaotfload.conf`` contains configuration options for
26 *Luaotfload*, a font loading and font management component for LuaTeX.
27
28
29 EXAMPLE
30 =======================================================================
31
32 A small Luaotfload configuration file with few customizations could
33 look as follows: ::
34
35 [db]
36 formats = afm,ttf
37 compress = false
38
39 [misc]
40 termwidth = 60
41
42 [run]
43 log-level = 6
44
45 This will make Luaotfload ignore all font files except for PostScript
46 binary fonts with a matching AFM file, and Truetype fonts. Also, an
47 uncompressed index file will be dumped which is going to be much larger
48 than the default gzip’ed index. The terminal width
49 is truncated to 60 characters which influences the verbose output
50 during indexing. Finally, the verbosity is increased greatly: each font
51 file being processed will be printed to the stdout on a separate line,
52 along with lots of other information.
53
54 To observe the difference in behavior, save above snippet to
55 ``./luaotfload.conf`` and update the font index: ::
56
57 luaotfload-tool --update --force
58
59 The current configuration can be written to disk using
60 **luaotfload-tool**: ::
61
62 luaotfload-tool --dumpconf > luaotfload.conf
63
64 The result can itself be used as a configuration file.
65
66
67 SYNTAX
68 =======================================================================
69
70 The configuration file syntax follows the common INI format. For a more
71 detailed description please refer to the section “CONFIGURATION FILE”
72 of **git-config**\(1). A brief list of rules is given below:
73
74 * Blank lines and lines starting with a semicolon (``;``) are ignored.
75
76 * A configuration file is partitioned into sections that are declared
77 by specifying the section title in brackets on a separate line: ::
78
79 [some-section]
80 ... section content ...
81
82 * Sections consist of one or more variable assignments of the form
83 ``variable-name = value`` E. g.::
84
85 [foo]
86 bar = baz
87 quux = xyzzy
88 ...
89
90 * Section and variable names may contain only uppercase and lowercase
91 letters as well as dashes (``-``).
92
93
94 VARIABLES
95 =======================================================================
96
97 Variables in belong into a configuration section and their values must
98 be of a certain type. Some of them have further constraints. For
99 example, the “color callback” must be a string of one of the values
100 ``post_linebreak_filter``, ``pre_linebreak_filter``, or
101 ``pre_output_filter``, defined in the section *run* of the
102 configuration file.
103
104 Currently, the configuration is organized into four sections:
105
106 db
107 Options relating to the font index.
108
109 misc
110 Options without a clearly defined category.
111
112 paths
113 Path and file name settings.
114
115 run
116 Options controlling runtime behavior of Luaotfload.
117
118 The list of valid variables, the sections they are part of and their
119 type is given below. Types represent Lua types that the values must be
120 convertible to; they are abbreviated as follows: ``s`` for the *string*
121 type, ``n`` for *number*, ``b`` for *boolean*. A value of ``nil`` means
122 the variable is unset.
123
124
125 Section ``db``
126 -----------------------------------------------------------------------
127
128 +----------------------+--------+---------------------------+
129 | variable | type | default |
130 +----------------------+--------+---------------------------+
131 | compress | b | ``true`` |
132 +----------------------+--------+---------------------------+
133 | designsize-dimen | b | ``bp`` |
134 +----------------------+--------+---------------------------+
135 | formats | s | ``"otf,ttf,ttc"`` |
136 +----------------------+--------+---------------------------+
137 | location-precedence | s | ``"system,texmf,local`` |
138 +----------------------+--------+---------------------------+
139 | max-fonts | n | ``2^51`` |
140 +----------------------+--------+---------------------------+
141 | scan-local | b | ``false`` |
142 +----------------------+--------+---------------------------+
143 | skip-read | b | ``false`` |
144 +----------------------+--------+---------------------------+
145 | strip | b | ``true`` |
146 +----------------------+--------+---------------------------+
147 | update-live | b | ``true`` |
148 +----------------------+--------+---------------------------+
149
150 The flag ``compress`` determines whether the font index (usually
151 ``luaotfload-names.lua[.gz]`` will be stored in compressed forms.
152 If unset it is equivalent of passing ``--no-compress`` to
153 **luaotfload-tool**. Since the file is only created for convenience
154 and has no effect on the runtime behavior of Luaotfload, the flag
155 should remain set. Most editors come with zlib support anyways.
156
157 The setting ``designsize-dimen`` applies when looking up fonts from
158 families with design sizes. In Opentype, these are specified as
159 “decipoints” where one decipoint equals ten DTP style “big points”.
160 When indexing fonts these values are converted to ``sp``. In order to
161 treat the values as though they were specified in TeX points or Didot
162 points, set ``designsize-dimen`` to ``pt`` or ``dd``.
163
164 The list of ``formats`` must be a comma separated sequence of strings
165 containing one or more of these elements:
166
167 * ``otf`` (OpenType format),
168 * ``ttf`` and ``ttc`` (TrueType format),
169 * ``afm`` (Adobe Font Metrics),
170
171 It corresponds loosely to the ``--formats`` option to
172 **luaotfload-tool**. Invalid or duplicate members are ignored; if the
173 list does not contain any useful identifiers, the default list
174 ``"otf,ttf,ttc"`` will be used.
175
176 The variable ``location-precedence`` selects where and in which order
177 luaotfload searches for fonts. Fonts in earlier locations are preferred.
178 The three supported locations are ``system`` for system specific font
179 directories, ``texmf`` for fonts which are part of the \TeX{} distribution
180 and ``local`` for local fonts.
181
182 The variable ``max-fonts`` determines after processing how many font
183 files the font scanner will terminate the search. This is useful for
184 debugging issues with the font index and has the same effect as the
185 option ``--max-fonts`` to **luaotfload-tools**.
186
187 The ``scan-local`` flag, if set, will incorporate the current working
188 directory as a font search location. NB: This will potentially slow
189 down document processing because a font index with local fonts will not
190 be saved to disk, so these fonts will have to be re-indexed whenever
191 the document is built. Setting ``scan_local`` to ``false`` is the same
192 as removing ``local`` from ``location-precedence``.
193
194 The ``skip-read`` flag is only useful for debugging: It makes
195 Luaotfload skip reading fonts. The font information for rebuilding the
196 index is taken from the presently existing one.
197
198 Unsetting the ``strip`` flag prevents Luaotfload from removing data
199 from the index that is only useful when processing font files. NB: this
200 can increase the size of the index files significantly and has no
201 effect on the runtime behavior.
202
203 If ``update-live`` is set, Luaotfload will reload the database if it
204 cannot find a requested font. Those who prefer to update manually using
205 **luaotfload-tool** should unset this flag. This option does not affect
206 rebuilds due to version mismatch.
207
208 Section ``default-features``
209 -----------------------------------------------------------------------
210
211 By default Luaotfload enables ``node`` mode and picks the default font
212 features that are prescribed in the OpenType standard. This behavior
213 may be overridden in the ``default-features`` section. Global defaults
214 that will be applied for all scripts can be set via the ``global``
215 option, others by the script they are to be applied to. For example,
216 a setting of ::
217
218 [default-features]
219 global = mode=base,color=0000FF
220 dflt = smcp,onum
221
222 would force *base* mode, tint all fonts blue and activate small
223 capitals and text figures globally. Features are specified as a comma
224 separated list of variables or variable-value pairs. Variables without
225 an explicit value are set to ``true``.
226
227
228 Section ``misc``
229 -----------------------------------------------------------------------
230
231 +---------------+--------+-------------------------+
232 | variable | type | default |
233 +---------------+--------+-------------------------+
234 | statistics | b | ``false`` |
235 +---------------+--------+-------------------------+
236 | termwidth | n | ``nil`` |
237 +---------------+--------+-------------------------+
238 | version | s | <Luaotfload version> |
239 +---------------+--------+-------------------------+
240 | keepnames | b | ``true`` |
241 +---------------+--------+-------------------------+
242
243 With ``statistics`` enabled, extra statistics will be collected during
244 index creation and appended to the index file. It may then be queried
245 at the Lua end or inspected by reading the file itself.
246
247 The value of ``termwidth``, if set, overrides the value retrieved by
248 querying the properties of the terminal in which Luatex runs. This is
249 useful if the engine runs with ``shell_escape`` disabled and the actual
250 terminal dimensions cannot be retrieved.
251
252 The value of ``version`` is derived from the version string hard-coded
253 in the Luaotfload source. Override at your own risk.
254
255 The ``keepnames`` option decides if the ConTeXt fontloader should keep
256 names it considers useless or if they should be discarded. This option
257 only takes effect after font caches are regenererated.
258
259
260 Section ``paths``
261 -----------------------------------------------------------------------
262
263 +------------------+--------+------------------------------------+
264 | variable | type | default |
265 +------------------+--------+------------------------------------+
266 | cache-dir | s | ``"fonts"`` |
267 +------------------+--------+------------------------------------+
268 | names-dir | s | ``"names"`` |
269 +------------------+--------+------------------------------------+
270 | index-file | s | ``"luaotfload-names.lua"`` |
271 +------------------+--------+------------------------------------+
272 | lookups-file | s | ``"luaotfload-lookup-cache.lua"`` |
273 +------------------+--------+------------------------------------+
274
275 The paths ``cache-dir`` and ``names-dir`` determine the subdirectory
276 inside the Luaotfload subtree of the ``luatex-cache`` directory where
277 the font cache and the font index will be stored, respectively.
278
279 Inside the index directory, the names of the index file and the font
280 lookup cache will be derived from the respective values of
281 ``index-file`` and ``lookups-file``. This is the filename base for the
282 bytecode compiled version as well as -- for the index -- the gzipped
283 version.
284
285
286 Section ``run``
287 -----------------------------------------------------------------------
288
289 +---------------------+--------+------------------------------+
290 | variable | type | default |
291 +---------------------+--------+------------------------------+
292 | anon-sequence | s | ``"tex,path,name"`` |
293 +---------------------+--------+------------------------------+
294 | color-callback | s | ``"post_linebreak_filter"`` |
295 +---------------------+--------+------------------------------+
296 | definer | s | ``"patch"`` |
297 +---------------------+--------+------------------------------+
298 | log-level | n | ``0`` |
299 +---------------------+--------+------------------------------+
300 | resolver | s | ``"cached"`` |
301 +---------------------+--------+------------------------------+
302 | fontloader | s | ``"default"`` |
303 +---------------------+--------+------------------------------+
304 | default_dvi_driver | s | ``"dvisvgm"`` |
305 +---------------------+--------+------------------------------+
306
307 Unqualified font lookups are treated with the flexible “anonymous”
308 mechanism. This involves a chain of lookups applied successively until
309 the first one yields a match. By default, the lookup will first search
310 for TFM fonts using the Kpathsea library. If this wasn’t successful, an
311 attempt is made at interpreting the request as an absolute path (like
312 the ``[/path/to/font/foo.ttf]`` syntax) or a file name
313 (``file:foo.ttf``). Finally, the request is interpreted as a font name
314 and retrieved from the index (``name:Foo Regular``). This behavior can
315 be configured by specifying a list as the value to ``anon-sequence``.
316 Available items are ``tex``, ``path``, ``name`` -- representing the
317 lookups described above, respectively --, and ``file`` for searching a
318 filename but not an absolute path. Also, ``my`` lookups are valid
319 values but they should only be used from within TeX documents, because
320 there is no means of customizing a ``my`` lookups on the command line.
321
322 The ``color-callback`` option determines the stage at which fonts that
323 defined with a ``color=xxyyzz`` feature will be colorized. By default
324 this happens in a ``post_linebreak_filter`` but alternatively the
325 ``pre_linebreak_filter`` or ``pre_output_filter`` may be chosen, which
326 is faster but might produce inconsistent output. The
327 ``pre_output_filter`` used to be the default in the 1.x series of
328 Luaotfload, whilst later versions up to and including 2.5 hooked into
329 the ``pre_linebreak_filter`` which naturally didn’t affect any glyphs
330 inserting during hyphenation. Both are kept around as options to
331 restore the previous behavior if necessary.
332
333 The ``definer`` allows for switching the ``define_font`` callback.
334 Apart from the default ``patch`` one may also choose the ``generic``
335 one that comes with the vanilla fontloader. Beware that this might
336 break tools like Fontspec that rely on the ``patch_font`` callback
337 provided by Luaotfload to perform important corrections on font data.
338
339 The fontloader backend can be selected by setting the value of
340 ``fontloader``. The most important choices are ``default``, which will
341 load the dedicated Luaotfload fontloader, and ``reference``, the
342 upstream package as shipped with Luaotfload. Other than those, a file
343 name accessible via kpathsea can be specified.
344
345 Alternatively, the individual files that constitute the fontloader can
346 be loaded directly. While less efficient, this greatly aids debugging
347 since error messages will reference the actual line numbers of the
348 source files and explanatory comments are not stripped. Currently,
349 three distinct loading strategies are available: ``unpackaged`` will
350 load the batch that is part of Luaotfload. These contain the identical
351 source code that the reference fontloader has been compiled from.
352 Another option, ``context`` will attempt to load the same files by
353 their names in the Context format from the search path. Consequently
354 this option allows to use the version of Context that comes with the
355 TeX distribution. Distros tend to prefer the stable version (“current”
356 in Context jargon) of those files so certain bugs encountered in the
357 more bleeding edge Luaotfload can be avoided this way. A third option
358 is to use ``context`` with a colon to specify a directory prefix where
359 the *TEXMF* is located that the files should be loaded from, e. g.
360 ``context:~/context/tex/texmf-context``. This can be used when
361 referencing another distribution like the Context minimals that is
362 installed under a different path not indexed by kpathsea.
363
364 The value of ``log-level`` sets the default verbosity of messages
365 printed by Luaotfload. Only messages defined with a verbosity of less
366 than or equal to the supplied value will be output on the terminal.
367 At a log level of five Luaotfload can be very noisy. Also, printing too
368 many messages will slow down the interpreter due to line buffering
369 being disabled (see **setbuf**\(3)).
370
371 The ``resolver`` setting allows choosing the font name resolution
372 function: With the default value ``cached`` Luaotfload saves the result
373 of a successful font name request to a cache file to speed up
374 subsequent lookups. The alternative, ``normal`` circumvents the cache
375 and resolves every request individually. (Since to the restructuring of
376 the font name index in Luaotfload 2.4 the performance difference
377 between the cached and uncached lookups should be marginal.)
378
379 When luaotfload is used in ``DVI`` mode, the ``default_dvi_driver`` option
380 determines how OpenType fonts are represented in the DVI output. In most
381 cases the default value ``dvisvgm`` should be set, it uses a format
382 supported by multiple backends including ``dvipdfmx`` and ``dvisvgm``
383 which uses GIDs to identify characters.
384 Setting this to ``xdvipsk`` uses an unstable internal format instead
385 which will change depending on the luaotfload, engine, or font version.
386 No one should rely on the mapping between DVI character codes and font glyphs
387 in this mode unless they tightly control all involved versions and are deeply
388 familiar with the implementation.
389
390 FILES
391 =======================================================================
392
393 Luaotfload only processes the first configuration file it encounters at
394 one of the search locations. The file name may be either
395 ``luaotfload.conf`` or ``luaotfloadrc``, except for the dotfile in the
396 user’s home directory which is expected at ``~/.luaotfloadrc``.
397
398 Configuration files are located following a series of steps. The search
399 terminates as soon as a suitable file is encountered. The sequence of
400 locations that Luaotfload looks at is
401
402 i. The current working directory of the LuaTeX process.
403 ii. The subdirectory ``luaotfload/`` inside the XDG configuration
404 tree, e. g. ``/home/oenothea/config/luaotfload/``.
405 iii. The dotfile.
406 iv. The *TEXMF* (using kpathsea).
407
408
409 SEE ALSO
410 =======================================================================
411
412 **luaotfload-tool**\(1), **luatex**\(1), **lua**\(1)
413
414 * ``texdoc luaotfload`` to display the PDF manual for the *Luaotfload*
415 package
416 * Luaotfload development `<https://github.com/latex3/luaotfload>`_
417 * LuaLaTeX mailing list `<http://tug.org/pipermail/lualatex-dev/>`_
418 * LuaTeX `<http://luatex.org/>`_
419 * Luaotfload on CTAN `<http://ctan.org/pkg/luaotfload>`_
420
421
422 REFERENCES
423 =======================================================================
424
425 * The XDG base specification
426 `<http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html>`_.
427
428 AUTHORS
429 =======================================================================
430
431 *Luaotfload* was developed by the LuaLaTeX dev team
432 (`<https://github.com/lualatex/>`_). It is currently maintained by the
433 LaTeX Project Team at `<https://github.com/latex3/luaotfload>`_
434
435 This manual page was written by Philipp Gesang <[email protected]>.
436