1LUAOTFLOAD.CONF(5) text processing LUAOTFLOAD.CONF(5)
2
3
4
6 luaotfload.conf - Luaotfload configuration file
7
9 · ./luaotfload{.conf,rc}
10
11 · XDG_CONFIG_HOME/luaotfload/luaotfload{.conf,rc}
12
13 · ~/.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
23 [db]
24 formats = afm,ttf
25 compress = false
26
27 [misc]
28 termwidth = 60
29
30 [run]
31 log-level = 6
32
33 This will make Luaotfload ignore all font files except for PostScript
34 binary fonts with a matching AFM file, and Truetype fonts. Also, an
35 uncompressed 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.
38 Finally, 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
42 To observe the difference in behavior, save above snippet to ./luaot‐
43 fload.conf and update the font index:
44
45 luaotfload-tool --update --force
46
47 The current configuration can be written to disk using luaotfload-tool:
48
49 luaotfload-tool --dumpconf > luaotfload.conf
50
51 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
58 · Blank lines and lines starting with a semicolon (;) are ignored.
59
60 · A configuration file is partitioned into sections that are
61 declared by specifying the section title in brackets on a separate
62 line:
63
64 [some-section]
65 ... section content ...
66
67 · Sections consist of one or more variable assignments of the form
68 variable-name = value E. g.:
69
70 [foo]
71 bar = baz
72 quux = xyzzy
73 ...
74
75 · 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,
83 defined in the section run of the configuration file.
84
85 Currently, the configuration is organized into four sections:
86
87 db Options relating to the font index.
88
89 misc Options without a clearly defined category.
90
91 paths Path and file name settings.
92
93 run Options controlling runtime behavior of Luaotfload.
94
95 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
99 unset.
100
101 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
122 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
129 The setting designsize-dimen applies when looking up fonts from fami‐
130 lies with design sizes. The default of DTP-style “big points” can be
131 changed for pt or even dd.
132
133 The list of formats must be a comma separated sequence of strings con‐
134 taining one or more of these elements:
135
136 · otf (OpenType format),
137
138 · ttf and ttc (TrueType format),
139
140 · afm (Adobe Font Metrics),
141
142 It corresponds loosely to the --formats option to luaotfload-tool.
143 Invalid or duplicate members are ignored; if the list does not contain
144 any useful identifiers, the default list "otf,ttf,ttc" will be used.
145
146 The variable max-fonts determines after processing how many font files
147 the font scanner will terminate the search. This is useful for debug‐
148 ging issues with the font index and has the same effect as the option
149 --max-fonts to luaotfload-tools.
150
151 The scan-local flag, if set, will incorporate the current working
152 directory as a font search location. NB: This will potentially slow
153 down document processing because a font index with local fonts will not
154 be saved to disk, so these fonts will have to be re-indexed whenever
155 the document is built.
156
157 The skip-read flag is only useful for debugging: It makes Luaotfload
158 skip reading fonts. The font information for rebuilding the index is
159 taken from the presently existing one.
160
161 Unsetting the strip flag prevents Luaotfload from removing data from
162 the index that is only useful when processing font files. NB: this can
163 increase the size of the index files significantly and has no effect on
164 the runtime behavior.
165
166 If update-live is set, Luaotfload will reload the database if it cannot
167 find a requested font. Those who prefer to update manually using luaot‐
168 fload-tool should unset this flag. This option does not affect rebuilds
169 due to version mismatch.
170
171 Section default-features
172 By default Luaotfload enables node mode and picks the default font fea‐
173 tures that are prescribed in the OpenType standard. This behavior may
174 be overridden in the default-features section. Global defaults that
175 will be applied for all scripts can be set via the global option, oth‐
176 ers by the script they are to be applied to. For example, a setting of
177
178 [default-features]
179 global = mode=base,color=0000FF
180 dflt = smcp,onum
181
182 would force base mode, tint all fonts blue and activate small capitals
183 and text figures globally. Features are specified as a comma separated
184 list of variables or variable-value pairs. Variables without an
185 explicit value are set to true.
186
187 Section misc
188 ┌───────────┬──────┬─────────────────────┐
189 │variable │ type │ default │
190 ├───────────┼──────┼─────────────────────┤
191 │statistics │ b │ false │
192 ├───────────┼──────┼─────────────────────┤
193 │termwidth │ n │ nil │
194 ├───────────┼──────┼─────────────────────┤
195 │version │ s │ <Luaotfload ver‐ │
196 │ │ │ sion> │
197 └───────────┴──────┴─────────────────────┘
198
199 With statistics enabled, extra statistics will be collected during
200 index creation and appended to the index file. It may then be queried
201 at the Lua end or inspected by reading the file itself.
202
203 The value of termwidth, if set, overrides the value retrieved by query‐
204 ing the properties of the terminal in which Luatex runs. This is useful
205 if the engine runs with shell_escape disabled and the actual terminal
206 dimensions cannot be retrieved.
207
208 The value of version is derived from the version string hard-coded in
209 the Luaotfload source. Override at your own risk.
210
211 Section paths
212 ┌─────────────┬──────┬─────────────────────────┐
213 │variable │ type │ default │
214 ├─────────────┼──────┼─────────────────────────┤
215 │cache-dir │ s │ "fonts" │
216 ├─────────────┼──────┼─────────────────────────┤
217 │names-dir │ s │ "names" │
218 ├─────────────┼──────┼─────────────────────────┤
219 │index-file │ s │ "luaot‐ │
220 │ │ │ fload-names.lua" │
221 ├─────────────┼──────┼─────────────────────────┤
222 │lookups-file │ s │ "luaot‐ │
223 │ │ │ fload-lookup-cache.lua" │
224 └─────────────┴──────┴─────────────────────────┘
225
226 The paths cache-dir and names-dir determine the subdirectory inside the
227 Luaotfload subtree of the luatex-cache directory where the font cache
228 and the font index will be stored, respectively.
229
230 Inside the index directory, the names of the index file and the font
231 lookup cache will be derived from the respective values of index-file
232 and lookups-file. This is the filename base for the bytecode compiled
233 version as well as -- for the index -- the gzipped version.
234
235 Section run
236 ┌───────────────┬──────┬─────────────────┐
237 │variable │ type │ default │
238 ├───────────────┼──────┼─────────────────┤
239 │anon-sequence │ s │ "tex,path,name" │
240 ├───────────────┼──────┼─────────────────┤
241 │color-callback │ s │ "post_line‐ │
242 │ │ │ break_filter" │
243 ├───────────────┼──────┼─────────────────┤
244 │definer │ s │ "patch" │
245 ├───────────────┼──────┼─────────────────┤
246 │log-level │ n │ 0 │
247 ├───────────────┼──────┼─────────────────┤
248 │resolver │ s │ "cached" │
249 ├───────────────┼──────┼─────────────────┤
250 │fontloader │ s │ "default" │
251 └───────────────┴──────┴─────────────────┘
252
253 Unqualified font lookups are treated with the flexible “anonymous”
254 mechanism. This involves a chain of lookups applied successively until
255 the first one yields a match. By default, the lookup will first search
256 for TFM fonts using the Kpathsea library. If this wasn’t successful, an
257 attempt is made at interpreting the request as an absolute path (like
258 the [/path/to/font/foo.ttf] syntax) or a file name (file:foo.ttf).
259 Finally, the request is interpreted as a font name and retrieved from
260 the index (name:Foo Regular). This behavior can be configured by speci‐
261 fying a list as the value to anon-sequence. Available items are tex,
262 path, name -- representing the lookups described above, respectively
263 --, and file for searching a filename but not an absolute path. Also,
264 my lookups are valid values but they should only be used from within
265 TeX documents, because there is no means of customizing a my lookups on
266 the command line.
267
268 The color-callback option determines the stage at which fonts that
269 defined with a color=xxyyzz feature will be colorized. By default this
270 happens in a post_linebreak_filter but alternatively the pre_line‐
271 break_filter or pre_output_filter may be chosen, which is faster but
272 might produce inconsistent output. The pre_output_filter used to be the
273 default in the 1.x series of Luaotfload, whilst later versions up to
274 and including 2.5 hooked into the pre_linebreak_filter which naturally
275 didn’t affect any glyphs inserting during hyphenation. Both are kept
276 around as options to restore the previous behavior if necessary.
277
278 The definer allows for switching the define_font callback. Apart from
279 the default patch one may also choose the generic one that comes with
280 the vanilla fontloader. Beware that this might break tools like
281 Fontspec that rely on the patch_font callback provided by Luaotfload to
282 perform important corrections on font data.
283
284 The fontloader backend can be selected by setting the value of font‐
285 loader. The most important choices are default, which will load the
286 dedicated Luaotfload fontloader, and reference, the upstream package as
287 shipped with Luaotfload. Other than those, a file name accessible via
288 kpathsea can be specified.
289
290 Alternatively, the individual files that constitute the fontloader can
291 be loaded directly. While less efficient, this greatly aids debugging
292 since error messages will reference the actual line numbers of the
293 source files and explanatory comments are not stripped. Currently,
294 three distinct loading strategies are available: unpackaged will load
295 the batch that is part of Luaotfload. These contain the identical
296 source code that the reference fontloader has been compiled from.
297 Another option, context will attempt to load the same files by their
298 names in the Context format from the search path. Consequently this
299 option allows to use the version of Context that comes with the TeX
300 distribution. Distros tend to prefer the stable version (“current” in
301 Context jargon) of those files so certain bugs encountered in the more
302 bleeding edge Luaotfload can be avoided this way. A third option is to
303 use context with a colon to specify a directory prefix where the TEXMF
304 is located that the files should be loaded from, e. g. context:~/con‐
305 text/tex/texmf-context. This can be used when referencing another dis‐
306 tribution like the Context minimals that is installed under a different
307 path not indexed by kpathsea.
308
309 The value of log-level sets the default verbosity of messages printed
310 by Luaotfload. Only messages defined with a verbosity of less than or
311 equal to the supplied value will be output on the terminal. At a log
312 level of five Luaotfload can be very noisy. Also, printing too many
313 messages will slow down the interpreter due to line buffering being
314 disabled (see setbuf(3)).
315
316 The resolver setting allows choosing the font name resolution function:
317 With the default value cached Luaotfload saves the result of a success‐
318 ful font name request to a cache file to speed up subsequent lookups.
319 The alternative, normal circumvents the cache and resolves every
320 request individually. (Since to the restructuring of the font name
321 index in Luaotfload 2.4 the performance difference between the cached
322 and uncached lookups should be marginal.)
323
325 Luaotfload only processes the first configuration file it encounters at
326 one of the search locations. The file name may be either luaot‐
327 fload.conf or luaotfloadrc, except for the dotfile in the user’s home
328 directory which is expected at ~/.luaotfloadrc.
329
330 Configuration files are located following a series of steps. The search
331 terminates as soon as a suitable file is encountered. The sequence of
332 locations that Luaotfload looks at is
333
334 i. The current working directory of the LuaTeX process.
335
336 ii. The subdirectory luaotfload/ inside the XDG configuration tree, e.
337 g. /home/oenothea/config/luaotfload/.
338
339 iii. The dotfile.
340
341 iv. The TEXMF (using kpathsea).
342
344 luaotfload-tool(1), luatex(1), lua(1)
345
346 · texdoc luaotfload to display the PDF manual for the Luaotfload pack‐
347 age
348
349 · Luaotfload development https://github.com/lualatex/luaotfload
350
351 · LuaLaTeX mailing list http://tug.org/pipermail/lualatex-dev/
352
353 · LuaTeX http://luatex.org/
354
355 · Luaotfload on CTAN http://ctan.org/pkg/luaotfload
356
358 · The XDG base specification
359 http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html.
360
362 Luaotfload is maintained by the LuaLaTeX dev team (‐
363 https://github.com/lualatex/).
364
365 This manual page was written by Philipp Gesang <phg@phi-gamma.net>.
366
368 GPL v2.0
369
370
371
372
3732.8 2017-01-29 LUAOTFLOAD.CONF(5)