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.  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
136       The  list of formats must be a comma separated sequence of strings con‐
137       taining one or more of these elements:
138
139       · otf               (OpenType format),
140
141       · ttf and ttc       (TrueType format),
142
143       · afm               (Adobe Font Metrics),
144
145       It corresponds loosely to  the  --formats  option  to  luaotfload-tool.
146       Invalid  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
149       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
154       The  scan-local  flag,  if  set,  will  incorporate the current working
155       directory as a font search location. NB:  This  will  potentially  slow
156       down document processing because a font index with local fonts will not
157       be saved to disk, so these fonts will have to  be  re-indexed  whenever
158       the document is built.
159
160       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
164       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
169       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
174   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
181          [default-features]
182              global = mode=base,color=0000FF
183              dflt   = smcp,onum
184
185       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
188       explicit value are set to true.
189
190   Section misc
191                      ┌───────────┬──────┬─────────────────────┐
192                      │variable   │ type │ default             │
193                      ├───────────┼──────┼─────────────────────┤
194                      │statistics │ b    │ false               
195                      ├───────────┼──────┼─────────────────────┤
196                      │termwidth  │ n    │ nil                 
197                      └───────────┴──────┴─────────────────────┘
198
199                      │version    │ s    │ <Luaotfload    ver‐ │
200                      │           │      │ sion>               │
201                      └───────────┴──────┴─────────────────────┘
202
203       With  statistics  enabled,  extra  statistics  will be collected during
204       index creation and appended to the index file. It may then  be  queried
205       at the Lua end or inspected by reading the file itself.
206
207       The value of termwidth, if set, overrides the value retrieved by query‐
208       ing the properties of the terminal in which Luatex runs. This is useful
209       if  the  engine runs with shell_escape disabled and the actual terminal
210       dimensions cannot be retrieved.
211
212       The value of version is derived from the version string  hard-coded  in
213       the Luaotfload source. Override at your own risk.
214
215   Section paths
216                   ┌─────────────┬──────┬─────────────────────────┐
217                   │variable     │ type │ default                 │
218                   ├─────────────┼──────┼─────────────────────────┤
219                   │cache-dir    │ s    │ "fonts"                 
220                   ├─────────────┼──────┼─────────────────────────┤
221                   │names-dir    │ s    │ "names"                 
222                   ├─────────────┼──────┼─────────────────────────┤
223                   │index-file   │ s    │ "luaot‐                 
224                   │             │      │ fload-names.lua"        
225                   ├─────────────┼──────┼─────────────────────────┤
226                   │lookups-file │ s    │ "luaot‐                 
227                   │             │      │ fload-lookup-cache.lua" 
228                   └─────────────┴──────┴─────────────────────────┘
229
230       The paths cache-dir and names-dir determine the subdirectory inside the
231       Luaotfload  subtree  of the luatex-cache directory where the font cache
232       and the font index will be stored, respectively.
233
234       Inside the index directory, the names of the index file  and  the  font
235       lookup  cache  will be derived from the respective values of index-file
236       and lookups-file. This is the filename base for the  bytecode  compiled
237       version as well as -- for the index -- the gzipped version.
238
239   Section run
240                      ┌───────────────┬──────┬─────────────────┐
241                      │variable       │ type │ default         │
242                      ├───────────────┼──────┼─────────────────┤
243                      │anon-sequence  │ s    │ "tex,path,name" 
244                      ├───────────────┼──────┼─────────────────┤
245                      │color-callback │ s    │ "post_line‐     
246                      │               │      │ break_filter"   
247                      ├───────────────┼──────┼─────────────────┤
248                      │definer        │ s    │ "patch"         
249                      ├───────────────┼──────┼─────────────────┤
250                      │log-level      │ n    │ 0               
251                      ├───────────────┼──────┼─────────────────┤
252                      │resolver       │ s    │ "cached"        
253                      ├───────────────┼──────┼─────────────────┤
254                      │fontloader     │ s    │ "default"       
255                      └───────────────┴──────┴─────────────────┘
256
257       Unqualified font lookups are  treated  with  the  flexible  “anonymous”
258       mechanism.  This involves a chain of lookups applied successively until
259       the first one yields a match. By default, the lookup will first  search
260       for TFM fonts using the Kpathsea library. If this wasn’t successful, an
261       attempt is made at interpreting the request as an absolute  path  (like
262       the  [/path/to/font/foo.ttf]  syntax)  or  a  file name (file:foo.ttf).
263       Finally, the request is interpreted as a font name and  retrieved  from
264       the index (name:Foo Regular). This behavior can be configured by speci‐
265       fying a list as the value to anon-sequence.  Available items  are  tex,
266       path,  name  --  representing the lookups described above, respectively
267       --, and file for searching a filename but not an absolute  path.  Also,
268       my  lookups  are  valid values but they should only be used from within
269       TeX documents, because there is no means of customizing a my lookups on
270       the command line.
271
272       The  color-callback  option  determines  the  stage at which fonts that
273       defined with a color=xxyyzz feature will be colorized. By default  this
274       happens  in  a  post_linebreak_filter  but  alternatively the pre_line‐
275       break_filter or pre_output_filter may be chosen, which  is  faster  but
276       might produce inconsistent output. The pre_output_filter used to be the
277       default in the 1.x series of Luaotfload, whilst later  versions  up  to
278       and  including 2.5 hooked into the pre_linebreak_filter which naturally
279       didn’t affect any glyphs inserting during hyphenation.  Both  are  kept
280       around as options to restore the previous behavior if necessary.
281
282       The  definer allows for switching the define_font callback.  Apart from
283       the default patch one may also choose the generic one that  comes  with
284       the  vanilla  fontloader.  Beware  that  this  might  break  tools like
285       Fontspec that rely on the patch_font callback provided by Luaotfload to
286       perform important corrections on font data.
287
288       The  fontloader  backend  can be selected by setting the value of font‐
289       loader. The most important choices are default,  which  will  load  the
290       dedicated Luaotfload fontloader, and reference, the upstream package as
291       shipped with Luaotfload. Other than those, a file name  accessible  via
292       kpathsea can be specified.
293
294       Alternatively,  the individual files that constitute the fontloader can
295       be loaded directly. While less efficient, this greatly  aids  debugging
296       since  error  messages  will  reference  the actual line numbers of the
297       source files and explanatory  comments  are  not  stripped.  Currently,
298       three  distinct  loading strategies are available: unpackaged will load
299       the batch that is part  of  Luaotfload.  These  contain  the  identical
300       source  code  that  the  reference  fontloader  has been compiled from.
301       Another option, context will attempt to load the same  files  by  their
302       names  in  the  Context  format from the search path. Consequently this
303       option allows to use the version of Context that  comes  with  the  TeX
304       distribution.  Distros  tend to prefer the stable version (“current” in
305       Context jargon) of those files so certain bugs encountered in the  more
306       bleeding  edge Luaotfload can be avoided this way. A third option is to
307       use context with a colon to specify a directory prefix where the  TEXMF
308       is  located that the files should be loaded from, e. g.  context:~/con‐
309       text/tex/texmf-context. This can be used when referencing another  dis‐
310       tribution like the Context minimals that is installed under a different
311       path not indexed by kpathsea.
312
313       The value of log-level sets the default verbosity of  messages  printed
314       by  Luaotfload.  Only messages defined with a verbosity of less than or
315       equal to the supplied value will be output on the terminal.  At  a  log
316       level  of  five  Luaotfload  can be very noisy. Also, printing too many
317       messages will slow down the interpreter due  to  line  buffering  being
318       disabled (see setbuf(3)).
319
320       The resolver setting allows choosing the font name resolution function:
321       With the default value cached Luaotfload saves the result of a success‐
322       ful  font  name request to a cache file to speed up subsequent lookups.
323       The alternative,  normal  circumvents  the  cache  and  resolves  every
324       request  individually.  (Since  to  the  restructuring of the font name
325       index in Luaotfload 2.4 the performance difference between  the  cached
326       and uncached lookups should be marginal.)
327

FILES

329       Luaotfload only processes the first configuration file it encounters at
330       one of the search  locations.  The  file  name  may  be  either  luaot‐
331       fload.conf  or  luaotfloadrc, except for the dotfile in the user’s home
332       directory which is expected at ~/.luaotfloadrc.
333
334       Configuration files are located following a series of steps. The search
335       terminates  as  soon as a suitable file is encountered. The sequence of
336       locations that Luaotfload looks at is
337
338       i.   The current working directory of the LuaTeX process.
339
340       ii.  The subdirectory luaotfload/ inside the XDG configuration tree, e.
341            g. /home/oenothea/config/luaotfload/.
342
343       iii. The dotfile.
344
345       iv.  The TEXMF (using kpathsea).
346

SEE ALSO

348       luaotfload-tool(1), luatex(1), lua(1)
349
350       · texdoc  luaotfload to display the PDF manual for the Luaotfload pack‐
351         age
352
353       · Luaotfload development https://github.com/u-fischer/luaotfload
354
355       · LuaLaTeX mailing list  http://tug.org/pipermail/lualatex-dev/
356
357       · LuaTeX                 http://luatex.org/
358
359       · Luaotfload on CTAN     http://ctan.org/pkg/luaotfload
360

REFERENCES

362       · The               XDG               base                specification
363         http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html.
364

AUTHORS

366       Luaotfload   was   developed   by   the   LuaLaTeX    dev    team    (‐
367       https://github.com/lualatex/).  It  is  currently  maintained by Ulrike
368       Fischer and Marcel Krüger at https://github.com/u-fischer/luaotfload
369
370       This manual page was written by Philipp Gesang <phg@phi-gamma.net>.
371
373       GPL v2.0
374
375
376
377
3782.97                              2019-05-18                LUAOTFLOAD.CONF(5)
Impressum