1LUAOTFLOAD.CONF(5) text processing LUAOTFLOAD.CONF(5)
2
6 luaotfload.conf - Luaotfload configuration file
7
9 • ./luaotfload{.conf,rc}
10 • XDG_CONFIG_HOME/luaotfload/luaotfload{.conf,rc}
12 • ~/.luaotfloadrc
14
16 The file luaotfload.conf contains configuration options for Luaotfload,
17 a font loading and font management component for LuaTeX.
18
20 A small Luaotfload configuration file with few customizations could
21 look as follows:
22 [db]
24 formats = afm,ttf
25 compress = false
26 [misc]
28 termwidth = 60
29 [run]
31 log-level = 6
32 This will make Luaotfload ignore all font files except for PostScript
34 binary fonts with a matching AFM file, and Truetype fonts. Also, an un‐
35 compressed index file will be dumped which is going to be much larger
36 than the default gzip’ed index. The terminal width is truncated to 60
37 characters which influences the verbose output during indexing. Fi‐
38 nally, the verbosity is increased greatly: each font file being pro‐
39 cessed will be printed to the stdout on a separate line, along with
40 lots of other information.
41 To observe the difference in behavior, save above snippet to ./luaot‐
43 fload.conf and update the font index:
44 luaotfload-tool --update --force
46 The current configuration can be written to disk using luaotfload-tool:
48 luaotfload-tool --dumpconf > luaotfload.conf
50 The result can itself be used as a configuration file.
52
54 The configuration file syntax follows the common INI format. For a more
55 detailed description please refer to the section “CONFIGURATION FILE”
56 of git-config(1). A brief list of rules is given below:
57 • Blank lines and lines starting with a semicolon (;) are ignored.
59 • A configuration file is partitioned into sections that are de‐
61 clared by specifying the section title in brackets on a separate
62 line:
63 [some-section]
65 ... section content ...
66 • Sections consist of one or more variable assignments of the form
68 variable-name = value E. g.:
69 [foo]
71 bar = baz
72 quux = xyzzy
73 ...
74 • Section and variable names may contain only uppercase and lower‐
76 case letters as well as dashes (-).
77
79 Variables in belong into a configuration section and their values must
80 be of a certain type. Some of them have further constraints. For exam‐
81 ple, the “color callback” must be a string of one of the values
82 post_linebreak_filter, pre_linebreak_filter, or pre_output_filter, de‐
83 fined in the section run of the configuration file.
84 Currently, the configuration is organized into four sections:
86 db Options relating to the font index.
88 misc Options without a clearly defined category.
90 paths Path and file name settings.
92 run Options controlling runtime behavior of Luaotfload.
94 The list of valid variables, the sections they are part of and their
96 type is given below. Types represent Lua types that the values must be
97 convertible to; they are abbreviated as follows: s for the string type,
98 n for number, b for boolean. A value of nil means the variable is un‐
99 set.
100 Section db
102 ┌─────────────────┬──────┬───────────────┐
103 │variable │ type │ default │
104 ├─────────────────┼──────┼───────────────┤
105 │compress │ b │ true │
106 ├─────────────────┼──────┼───────────────┤
107 │designsize-dimen │ b │ bp │
108 ├─────────────────┼──────┼───────────────┤
109 │formats │ s │ "otf,ttf,ttc" │
110 ├─────────────────┼──────┼───────────────┤
111 │max-fonts │ n │ 2^51 │
112 ├─────────────────┼──────┼───────────────┤
113 │scan-local │ b │ false │
114 ├─────────────────┼──────┼───────────────┤
115 │skip-read │ b │ false │
116 ├─────────────────┼──────┼───────────────┤
117 │strip │ b │ true │
118 ├─────────────────┼──────┼───────────────┤
119 │update-live │ b │ true │
120 └─────────────────┴──────┴───────────────┘
121 The flag compress determines whether the font index (usually luaot‐
123 fload-names.lua[.gz] will be stored in compressed forms. If unset it
124 is equivalent of passing --no-compress to luaotfload-tool. Since the
125 file is only created for convenience and has no effect on the runtime
126 behavior of Luaotfload, the flag should remain set. Most editors come
127 with zlib support anyways.
128 The setting designsize-dimen applies when looking up fonts from fami‐
130 lies with design sizes. In Opentype, these are specified as “deci‐
131 points” where one decipoint equals ten DTP style “big points”. When
132 indexing fonts these values are converted to sp. In order to treat the
133 values as though they were specified in TeX points or Didot points, set
134 designsize-dimen to pt or dd.
135 The list of formats must be a comma separated sequence of strings con‐
137 taining one or more of these elements:
138 • otf (OpenType format),
140 • ttf and ttc (TrueType format),
142 • afm (Adobe Font Metrics),
144 It corresponds loosely to the --formats option to luaotfload-tool. In‐
146 valid or duplicate members are ignored; if the list does not contain
147 any useful identifiers, the default list "otf,ttf,ttc" will be used.
148 The variable max-fonts determines after processing how many font files
150 the font scanner will terminate the search. This is useful for debug‐
151 ging issues with the font index and has the same effect as the option
152 --max-fonts to luaotfload-tools.
153 The scan-local flag, if set, will incorporate the current working di‐
155 rectory as a font search location. NB: This will potentially slow down
156 document processing because a font index with local fonts will not be
157 saved to disk, so these fonts will have to be re-indexed whenever the
158 document is built.
159 The skip-read flag is only useful for debugging: It makes Luaotfload
161 skip reading fonts. The font information for rebuilding the index is
162 taken from the presently existing one.
163 Unsetting the strip flag prevents Luaotfload from removing data from
165 the index that is only useful when processing font files. NB: this can
166 increase the size of the index files significantly and has no effect on
167 the runtime behavior.
168 If update-live is set, Luaotfload will reload the database if it cannot
170 find a requested font. Those who prefer to update manually using luaot‐
171 fload-tool should unset this flag. This option does not affect rebuilds
172 due to version mismatch.
173 Section default-features
175 By default Luaotfload enables node mode and picks the default font fea‐
176 tures that are prescribed in the OpenType standard. This behavior may
177 be overridden in the default-features section. Global defaults that
178 will be applied for all scripts can be set via the global option, oth‐
179 ers by the script they are to be applied to. For example, a setting of
180 [default-features]
182 global = mode=base,color=0000FF
183 dflt = smcp,onum
184 would force base mode, tint all fonts blue and activate small capitals
186 and text figures globally. Features are specified as a comma separated
187 list of variables or variable-value pairs. Variables without an ex‐
188 plicit value are set to true.
189 Section misc
191 ┌───────────┬──────┬─────────────────────┐
192 │variable │ type │ default │
193 ├───────────┼──────┼─────────────────────┤
194 │statistics │ b │ false │
195 ├───────────┼──────┼─────────────────────┤
196 │termwidth │ n │ nil │
197 └───────────┴──────┴─────────────────────┘
198 │version │ s │ <Luaotfload ver‐ │
200 │ │ │ sion> │
201 ├───────────┼──────┼─────────────────────┤
202 │keepnames │ b │ true │
203 └───────────┴──────┴─────────────────────┘
204 With statistics enabled, extra statistics will be collected during in‐
206 dex creation and appended to the index file. It may then be queried at
207 the Lua end or inspected by reading the file itself.
208 The value of termwidth, if set, overrides the value retrieved by query‐
210 ing the properties of the terminal in which Luatex runs. This is useful
211 if the engine runs with shell_escape disabled and the actual terminal
212 dimensions cannot be retrieved.
213 The value of version is derived from the version string hard-coded in
215 the Luaotfload source. Override at your own risk.
216 The keepnames option decides if the ConTeXt fontloader should keep
218 names it considers useless or if they should be discarded. This option
219 only takes effect after font caches are regenererated.
220 Section paths
222 ┌─────────────┬──────┬─────────────────────────┐
223 │variable │ type │ default │
224 ├─────────────┼──────┼─────────────────────────┤
225 │cache-dir │ s │ "fonts" │
226 ├─────────────┼──────┼─────────────────────────┤
227 │names-dir │ s │ "names" │
228 ├─────────────┼──────┼─────────────────────────┤
229 │index-file │ s │ "luaot‐ │
230 │ │ │ fload-names.lua" │
231 ├─────────────┼──────┼─────────────────────────┤
232 │lookups-file │ s │ "luaot‐ │
233 │ │ │ fload-lookup-cache.lua" │
234 └─────────────┴──────┴─────────────────────────┘
235 The paths cache-dir and names-dir determine the subdirectory inside the
237 Luaotfload subtree of the luatex-cache directory where the font cache
238 and the font index will be stored, respectively.
239 Inside the index directory, the names of the index file and the font
241 lookup cache will be derived from the respective values of index-file
242 and lookups-file. This is the filename base for the bytecode compiled
243 version as well as -- for the index -- the gzipped version.
244 Section run
246 ┌───────────────┬──────┬─────────────────┐
247 │variable │ type │ default │
248 ├───────────────┼──────┼─────────────────┤
249 │anon-sequence │ s │ "tex,path,name" │
250 ├───────────────┼──────┼─────────────────┤
251 │color-callback │ s │ "post_line‐ │
252 │ │ │ break_filter" │
253 ├───────────────┼──────┼─────────────────┤
254 │definer │ s │ "patch" │
255 ├───────────────┼──────┼─────────────────┤
256 │log-level │ n │ 0 │
257 ├───────────────┼──────┼─────────────────┤
258 │resolver │ s │ "cached" │
259 ├───────────────┼──────┼─────────────────┤
260 │fontloader │ s │ "default" │
261 └───────────────┴──────┴─────────────────┘
262 Unqualified font lookups are treated with the flexible “anonymous”
264 mechanism. This involves a chain of lookups applied successively until
265 the first one yields a match. By default, the lookup will first search
266 for TFM fonts using the Kpathsea library. If this wasn’t successful, an
267 attempt is made at interpreting the request as an absolute path (like
268 the [/path/to/font/foo.ttf] syntax) or a file name (file:foo.ttf). Fi‐
269 nally, the request is interpreted as a font name and retrieved from the
270 index (name:Foo Regular). This behavior can be configured by specifying
271 a list as the value to anon-sequence. Available items are tex, path,
272 name -- representing the lookups described above, respectively --, and
273 file for searching a filename but not an absolute path. Also, my
274 lookups are valid values but they should only be used from within TeX
275 documents, because there is no means of customizing a my lookups on the
276 command line.
277 The color-callback option determines the stage at which fonts that de‐
279 fined with a color=xxyyzz feature will be colorized. By default this
280 happens in a post_linebreak_filter but alternatively the pre_line‐
281 break_filter or pre_output_filter may be chosen, which is faster but
282 might produce inconsistent output. The pre_output_filter used to be the
283 default in the 1.x series of Luaotfload, whilst later versions up to
284 and including 2.5 hooked into the pre_linebreak_filter which naturally
285 didn’t affect any glyphs inserting during hyphenation. Both are kept
286 around as options to restore the previous behavior if necessary.
287 The definer allows for switching the define_font callback. Apart from
289 the default patch one may also choose the generic one that comes with
290 the vanilla fontloader. Beware that this might break tools like
291 Fontspec that rely on the patch_font callback provided by Luaotfload to
292 perform important corrections on font data.
293 The fontloader backend can be selected by setting the value of font‐
295 loader. The most important choices are default, which will load the
296 dedicated Luaotfload fontloader, and reference, the upstream package as
297 shipped with Luaotfload. Other than those, a file name accessible via
298 kpathsea can be specified.
299 Alternatively, the individual files that constitute the fontloader can
301 be loaded directly. While less efficient, this greatly aids debugging
302 since error messages will reference the actual line numbers of the
303 source files and explanatory comments are not stripped. Currently,
304 three distinct loading strategies are available: unpackaged will load
305 the batch that is part of Luaotfload. These contain the identical
306 source code that the reference fontloader has been compiled from. An‐
307 other option, context will attempt to load the same files by their
308 names in the Context format from the search path. Consequently this op‐
309 tion allows to use the version of Context that comes with the TeX dis‐
310 tribution. Distros tend to prefer the stable version (“current” in Con‐
311 text jargon) of those files so certain bugs encountered in the more
312 bleeding edge Luaotfload can be avoided this way. A third option is to
313 use context with a colon to specify a directory prefix where the TEXMF
314 is located that the files should be loaded from, e. g. context:~/con‐
315 text/tex/texmf-context. This can be used when referencing another dis‐
316 tribution like the Context minimals that is installed under a different
317 path not indexed by kpathsea.
318 The value of log-level sets the default verbosity of messages printed
320 by Luaotfload. Only messages defined with a verbosity of less than or
321 equal to the supplied value will be output on the terminal. At a log
322 level of five Luaotfload can be very noisy. Also, printing too many
323 messages will slow down the interpreter due to line buffering being
324 disabled (see setbuf(3)).
325 The resolver setting allows choosing the font name resolution function:
327 With the default value cached Luaotfload saves the result of a success‐
328 ful font name request to a cache file to speed up subsequent lookups.
329 The alternative, normal circumvents the cache and resolves every re‐
330 quest individually. (Since to the restructuring of the font name index
331 in Luaotfload 2.4 the performance difference between the cached and un‐
332 cached lookups should be marginal.)
333
335 Luaotfload only processes the first configuration file it encounters at
336 one of the search locations. The file name may be either luaot‐
337 fload.conf or luaotfloadrc, except for the dotfile in the user’s home
338 directory which is expected at ~/.luaotfloadrc.
339 Configuration files are located following a series of steps. The search
341 terminates as soon as a suitable file is encountered. The sequence of
342 locations that Luaotfload looks at is
343 i. The current working directory of the LuaTeX process.
345 ii. The subdirectory luaotfload/ inside the XDG configuration tree, e.
347 g. /home/oenothea/config/luaotfload/.
348 iii. The dotfile.
350 iv. The TEXMF (using kpathsea).
352
354 luaotfload-tool(1), luatex(1), lua(1)
355 • texdoc luaotfload to display the PDF manual for the Luaotfload pack‐
357 age
358 • Luaotfload development https://github.com/latex3/luaotfload
360 • LuaLaTeX mailing list http://tug.org/pipermail/lualatex-dev/
362 • LuaTeX http://luatex.org/
364 • Luaotfload on CTAN http://ctan.org/pkg/luaotfload
366
368 • The XDG base specification
369 http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html.
370
372 Luaotfload was developed by the LuaLaTeX dev team (‐
373 https://github.com/lualatex/). It is currently maintained by the LaTeX
374 Project Team at https://github.com/latex3/luaotfload
375 This manual page was written by Philipp Gesang <phg@phi-gamma.net>.
377
379 GPL v2.0
3803.23 2022-10-03 LUAOTFLOAD.CONF(5)