1LUAOTFLOAD.CONF(5)              text processing             LUAOTFLOAD.CONF(5)
2
3
4

NAME

6       luaotfload.conf - Luaotfload configuration file
7

SYNOPSIS

9       · ./luaotfload{.conf,rc}
10
11       · XDG_CONFIG_HOME/luaotfload/luaotfload{.conf,rc}
12
13       · ~/.luaotfloadrc
14

DESCRIPTION

16       The file luaotfload.conf contains configuration options for Luaotfload,
17       a font loading and font management component for LuaTeX.
18

EXAMPLE

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

SYNTAX

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

VARIABLES

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

FILES

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

SEE ALSO

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

REFERENCES

358       · The                XDG               base               specification
359         http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html.
360

AUTHORS

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)
Impressum