Debian Codegraph @

texmf-dist/doc/man/man5/luaotfload.conf.5

raw
1 .\" Man page generated from reStructuredText.
2 .
3 .
4 .nr rst2man-indent-level 0
5 .
6 .de1 rstReportMargin
7 \\$1 \\n[an-margin]
8 level \\n[rst2man-indent-level]
9 level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
10 -
11 \\n[rst2man-indent0]
12 \\n[rst2man-indent1]
13 \\n[rst2man-indent2]
14 ..
15 .de1 INDENT
16 .\" .rstReportMargin pre:
17 . RS \\$1
18 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
19 . nr rst2man-indent-level +1
20 .\" .rstReportMargin post:
21 ..
22 .de UNINDENT
23 . RE
24 .\" indent \\n[an-margin]
25 .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
26 .nr rst2man-indent-level -1
27 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
28 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
29 ..
30 .TH "LUAOTFLOAD.CONF" 5 "2024-12-03" "3.29" "text processing"
31 .SH NAME
32 luaotfload.conf \- Luaotfload configuration file
33 .SH SYNOPSIS
34 .INDENT 0.0
35 .IP \(bu 2
36 \fB\&./luaotfload{.conf,rc}\fP
37 .IP \(bu 2
38 \fBXDG_CONFIG_HOME/luaotfload/luaotfload{.conf,rc}\fP
39 .IP \(bu 2
40 \fB~/.luaotfloadrc\fP
41 .UNINDENT
42 .SH DESCRIPTION
43 .sp
44 The file \fBluaotfload.conf\fP contains configuration options for
45 \fILuaotfload\fP, a font loading and font management component for LuaTeX.
46 .SH EXAMPLE
47 .sp
48 A small Luaotfload configuration file with few customizations could
49 look as follows:
50 .INDENT 0.0
51 .INDENT 3.5
52 .sp
53 .nf
54 .ft C
55 [db]
56 formats = afm,ttf
57 compress = false
58
59 [misc]
60 termwidth = 60
61
62 [run]
63 log\-level = 6
64 .ft P
65 .fi
66 .UNINDENT
67 .UNINDENT
68 .sp
69 This will make Luaotfload ignore all font files except for PostScript
70 binary fonts with a matching AFM file, and Truetype fonts. Also, an
71 uncompressed index file will be dumped which is going to be much larger
72 than the default gzip’ed index. The terminal width
73 is truncated to 60 characters which influences the verbose output
74 during indexing. Finally, the verbosity is increased greatly: each font
75 file being processed will be printed to the stdout on a separate line,
76 along with lots of other information.
77 .sp
78 To observe the difference in behavior, save above snippet to
79 \fB\&./luaotfload.conf\fP and update the font index:
80 .INDENT 0.0
81 .INDENT 3.5
82 .sp
83 .nf
84 .ft C
85 luaotfload\-tool \-\-update \-\-force
86 .ft P
87 .fi
88 .UNINDENT
89 .UNINDENT
90 .sp
91 The current configuration can be written to disk using
92 \fBluaotfload\-tool\fP:
93 .INDENT 0.0
94 .INDENT 3.5
95 .sp
96 .nf
97 .ft C
98 luaotfload\-tool \-\-dumpconf > luaotfload.conf
99 .ft P
100 .fi
101 .UNINDENT
102 .UNINDENT
103 .sp
104 The result can itself be used as a configuration file.
105 .SH SYNTAX
106 .sp
107 The configuration file syntax follows the common INI format. For a more
108 detailed description please refer to the section “CONFIGURATION FILE”
109 of \fBgit\-config\fP(1). A brief list of rules is given below:
110 .INDENT 0.0
111 .INDENT 3.5
112 .INDENT 0.0
113 .IP \(bu 2
114 Blank lines and lines starting with a semicolon (\fB;\fP) are ignored.
115 .IP \(bu 2
116 A configuration file is partitioned into sections that are declared
117 by specifying the section title in brackets on a separate line:
118 .INDENT 2.0
119 .INDENT 3.5
120 .sp
121 .nf
122 .ft C
123 [some\-section]
124 \&... section content ...
125 .ft P
126 .fi
127 .UNINDENT
128 .UNINDENT
129 .IP \(bu 2
130 Sections consist of one or more variable assignments of the form
131 \fBvariable\-name = value\fP E. g.:
132 .INDENT 2.0
133 .INDENT 3.5
134 .sp
135 .nf
136 .ft C
137 [foo]
138 bar = baz
139 quux = xyzzy
140 ...
141 .ft P
142 .fi
143 .UNINDENT
144 .UNINDENT
145 .IP \(bu 2
146 Section and variable names may contain only uppercase and lowercase
147 letters as well as dashes (\fB\-\fP).
148 .UNINDENT
149 .UNINDENT
150 .UNINDENT
151 .SH VARIABLES
152 .sp
153 Variables in belong into a configuration section and their values must
154 be of a certain type. Some of them have further constraints. For
155 example, the “color callback” must be a string of one of the values
156 \fBpost_linebreak_filter\fP, \fBpre_linebreak_filter\fP, or
157 \fBpre_output_filter\fP, defined in the section \fIrun\fP of the
158 configuration file.
159 .sp
160 Currently, the configuration is organized into four sections:
161 .INDENT 0.0
162 .TP
163 .B db
164 Options relating to the font index.
165 .TP
166 .B misc
167 Options without a clearly defined category.
168 .TP
169 .B paths
170 Path and file name settings.
171 .TP
172 .B run
173 Options controlling runtime behavior of Luaotfload.
174 .UNINDENT
175 .sp
176 The list of valid variables, the sections they are part of and their
177 type is given below. Types represent Lua types that the values must be
178 convertible to; they are abbreviated as follows: \fBs\fP for the \fIstring\fP
179 type, \fBn\fP for \fInumber\fP, \fBb\fP for \fIboolean\fP\&. A value of \fBnil\fP means
180 the variable is unset.
181 .SS Section \fBdb\fP
182 .TS
183 center;
184 |l|l|l|.
185 _
186 T{
187 variable
188 T} T{
189 type
190 T} T{
191 default
192 T}
193 _
194 T{
195 compress
196 T} T{
197 b
198 T} T{
199 \fBtrue\fP
200 T}
201 _
202 T{
203 designsize\-dimen
204 T} T{
205 b
206 T} T{
207 \fBbp\fP
208 T}
209 _
210 T{
211 formats
212 T} T{
213 s
214 T} T{
215 \fB"otf,ttf,ttc"\fP
216 T}
217 _
218 T{
219 location\-precedence
220 T} T{
221 s
222 T} T{
223 \fB"system,texmf,local\fP
224 T}
225 _
226 T{
227 max\-fonts
228 T} T{
229 n
230 T} T{
231 \fB2^51\fP
232 T}
233 _
234 T{
235 scan\-local
236 T} T{
237 b
238 T} T{
239 \fBfalse\fP
240 T}
241 _
242 T{
243 skip\-read
244 T} T{
245 b
246 T} T{
247 \fBfalse\fP
248 T}
249 _
250 T{
251 strip
252 T} T{
253 b
254 T} T{
255 \fBtrue\fP
256 T}
257 _
258 T{
259 update\-live
260 T} T{
261 b
262 T} T{
263 \fBtrue\fP
264 T}
265 _
266 .TE
267 .sp
268 The flag \fBcompress\fP determines whether the font index (usually
269 \fBluaotfload\-names.lua[.gz]\fP will be stored in compressed forms.
270 If unset it is equivalent of passing \fB\-\-no\-compress\fP to
271 \fBluaotfload\-tool\fP\&. Since the file is only created for convenience
272 and has no effect on the runtime behavior of Luaotfload, the flag
273 should remain set. Most editors come with zlib support anyways.
274 .sp
275 The setting \fBdesignsize\-dimen\fP applies when looking up fonts from
276 families with design sizes. In Opentype, these are specified as
277 “decipoints” where one decipoint equals ten DTP style “big points”.
278 When indexing fonts these values are converted to \fBsp\fP\&. In order to
279 treat the values as though they were specified in TeX points or Didot
280 points, set \fBdesignsize\-dimen\fP to \fBpt\fP or \fBdd\fP\&.
281 .sp
282 The list of \fBformats\fP must be a comma separated sequence of strings
283 containing one or more of these elements:
284 .INDENT 0.0
285 .IP \(bu 2
286 \fBotf\fP (OpenType format),
287 .IP \(bu 2
288 \fBttf\fP and \fBttc\fP (TrueType format),
289 .IP \(bu 2
290 \fBafm\fP (Adobe Font Metrics),
291 .UNINDENT
292 .sp
293 It corresponds loosely to the \fB\-\-formats\fP option to
294 \fBluaotfload\-tool\fP\&. Invalid or duplicate members are ignored; if the
295 list does not contain any useful identifiers, the default list
296 \fB"otf,ttf,ttc"\fP will be used.
297 .sp
298 The variable \fBlocation\-precedence\fP selects where and in which order
299 luaotfload searches for fonts. Fonts in earlier locations are preferred.
300 The three supported locations are \fBsystem\fP for system specific font
301 directories, \fBtexmf\fP for fonts which are part of the TeX{} distribution
302 and \fBlocal\fP for local fonts.
303 .sp
304 The variable \fBmax\-fonts\fP determines after processing how many font
305 files the font scanner will terminate the search. This is useful for
306 debugging issues with the font index and has the same effect as the
307 option \fB\-\-max\-fonts\fP to \fBluaotfload\-tools\fP\&.
308 .sp
309 The \fBscan\-local\fP flag, if set, will incorporate the current working
310 directory as a font search location. NB: This will potentially slow
311 down document processing because a font index with local fonts will not
312 be saved to disk, so these fonts will have to be re\-indexed whenever
313 the document is built. Setting \fBscan_local\fP to \fBfalse\fP is the same
314 as removing \fBlocal\fP from \fBlocation\-precedence\fP\&.
315 .sp
316 The \fBskip\-read\fP flag is only useful for debugging: It makes
317 Luaotfload skip reading fonts. The font information for rebuilding the
318 index is taken from the presently existing one.
319 .sp
320 Unsetting the \fBstrip\fP flag prevents Luaotfload from removing data
321 from the index that is only useful when processing font files. NB: this
322 can increase the size of the index files significantly and has no
323 effect on the runtime behavior.
324 .sp
325 If \fBupdate\-live\fP is set, Luaotfload will reload the database if it
326 cannot find a requested font. Those who prefer to update manually using
327 \fBluaotfload\-tool\fP should unset this flag. This option does not affect
328 rebuilds due to version mismatch.
329 .SS Section \fBdefault\-features\fP
330 .sp
331 By default Luaotfload enables \fBnode\fP mode and picks the default font
332 features that are prescribed in the OpenType standard. This behavior
333 may be overridden in the \fBdefault\-features\fP section. Global defaults
334 that will be applied for all scripts can be set via the \fBglobal\fP
335 option, others by the script they are to be applied to. For example,
336 a setting of
337 .INDENT 0.0
338 .INDENT 3.5
339 .sp
340 .nf
341 .ft C
342 [default\-features]
343 global = mode=base,color=0000FF
344 dflt = smcp,onum
345 .ft P
346 .fi
347 .UNINDENT
348 .UNINDENT
349 .sp
350 would force \fIbase\fP mode, tint all fonts blue and activate small
351 capitals and text figures globally. Features are specified as a comma
352 separated list of variables or variable\-value pairs. Variables without
353 an explicit value are set to \fBtrue\fP\&.
354 .SS Section \fBmisc\fP
355 .TS
356 center;
357 |l|l|l|.
358 _
359 T{
360 variable
361 T} T{
362 type
363 T} T{
364 default
365 T}
366 _
367 T{
368 statistics
369 T} T{
370 b
371 T} T{
372 \fBfalse\fP
373 T}
374 _
375 T{
376 termwidth
377 T} T{
378 n
379 T} T{
380 \fBnil\fP
381 T}
382 _
383 T{
384 version
385 T} T{
386 s
387 T} T{
388 <Luaotfload version>
389 T}
390 _
391 T{
392 keepnames
393 T} T{
394 b
395 T} T{
396 \fBtrue\fP
397 T}
398 _
399 .TE
400 .sp
401 With \fBstatistics\fP enabled, extra statistics will be collected during
402 index creation and appended to the index file. It may then be queried
403 at the Lua end or inspected by reading the file itself.
404 .sp
405 The value of \fBtermwidth\fP, if set, overrides the value retrieved by
406 querying the properties of the terminal in which Luatex runs. This is
407 useful if the engine runs with \fBshell_escape\fP disabled and the actual
408 terminal dimensions cannot be retrieved.
409 .sp
410 The value of \fBversion\fP is derived from the version string hard\-coded
411 in the Luaotfload source. Override at your own risk.
412 .sp
413 The \fBkeepnames\fP option decides if the ConTeXt fontloader should keep
414 names it considers useless or if they should be discarded. This option
415 only takes effect after font caches are regenererated.
416 .SS Section \fBpaths\fP
417 .TS
418 center;
419 |l|l|l|.
420 _
421 T{
422 variable
423 T} T{
424 type
425 T} T{
426 default
427 T}
428 _
429 T{
430 cache\-dir
431 T} T{
432 s
433 T} T{
434 \fB"fonts"\fP
435 T}
436 _
437 T{
438 names\-dir
439 T} T{
440 s
441 T} T{
442 \fB"names"\fP
443 T}
444 _
445 T{
446 index\-file
447 T} T{
448 s
449 T} T{
450 \fB"luaotfload\-names.lua"\fP
451 T}
452 _
453 T{
454 lookups\-file
455 T} T{
456 s
457 T} T{
458 \fB"luaotfload\-lookup\-cache.lua"\fP
459 T}
460 _
461 .TE
462 .sp
463 The paths \fBcache\-dir\fP and \fBnames\-dir\fP determine the subdirectory
464 inside the Luaotfload subtree of the \fBluatex\-cache\fP directory where
465 the font cache and the font index will be stored, respectively.
466 .sp
467 Inside the index directory, the names of the index file and the font
468 lookup cache will be derived from the respective values of
469 \fBindex\-file\fP and \fBlookups\-file\fP\&. This is the filename base for the
470 bytecode compiled version as well as \-\- for the index \-\- the gzipped
471 version.
472 .SS Section \fBrun\fP
473 .TS
474 center;
475 |l|l|l|.
476 _
477 T{
478 variable
479 T} T{
480 type
481 T} T{
482 default
483 T}
484 _
485 T{
486 anon\-sequence
487 T} T{
488 s
489 T} T{
490 \fB"tex,path,name"\fP
491 T}
492 _
493 T{
494 color\-callback
495 T} T{
496 s
497 T} T{
498 \fB"post_linebreak_filter"\fP
499 T}
500 _
501 T{
502 definer
503 T} T{
504 s
505 T} T{
506 \fB"patch"\fP
507 T}
508 _
509 T{
510 log\-level
511 T} T{
512 n
513 T} T{
514 \fB0\fP
515 T}
516 _
517 T{
518 resolver
519 T} T{
520 s
521 T} T{
522 \fB"cached"\fP
523 T}
524 _
525 T{
526 fontloader
527 T} T{
528 s
529 T} T{
530 \fB"default"\fP
531 T}
532 _
533 T{
534 default_dvi_driver
535 T} T{
536 s
537 T} T{
538 \fB"dvisvgm"\fP
539 T}
540 _
541 .TE
542 .sp
543 Unqualified font lookups are treated with the flexible “anonymous”
544 mechanism. This involves a chain of lookups applied successively until
545 the first one yields a match. By default, the lookup will first search
546 for TFM fonts using the Kpathsea library. If this wasn’t successful, an
547 attempt is made at interpreting the request as an absolute path (like
548 the \fB[/path/to/font/foo.ttf]\fP syntax) or a file name
549 (\fBfile:foo.ttf\fP). Finally, the request is interpreted as a font name
550 and retrieved from the index (\fBname:Foo Regular\fP). This behavior can
551 be configured by specifying a list as the value to \fBanon\-sequence\fP\&.
552 Available items are \fBtex\fP, \fBpath\fP, \fBname\fP \-\- representing the
553 lookups described above, respectively \-\-, and \fBfile\fP for searching a
554 filename but not an absolute path. Also, \fBmy\fP lookups are valid
555 values but they should only be used from within TeX documents, because
556 there is no means of customizing a \fBmy\fP lookups on the command line.
557 .sp
558 The \fBcolor\-callback\fP option determines the stage at which fonts that
559 defined with a \fBcolor=xxyyzz\fP feature will be colorized. By default
560 this happens in a \fBpost_linebreak_filter\fP but alternatively the
561 \fBpre_linebreak_filter\fP or \fBpre_output_filter\fP may be chosen, which
562 is faster but might produce inconsistent output. The
563 \fBpre_output_filter\fP used to be the default in the 1.x series of
564 Luaotfload, whilst later versions up to and including 2.5 hooked into
565 the \fBpre_linebreak_filter\fP which naturally didn’t affect any glyphs
566 inserting during hyphenation. Both are kept around as options to
567 restore the previous behavior if necessary.
568 .sp
569 The \fBdefiner\fP allows for switching the \fBdefine_font\fP callback.
570 Apart from the default \fBpatch\fP one may also choose the \fBgeneric\fP
571 one that comes with the vanilla fontloader. Beware that this might
572 break tools like Fontspec that rely on the \fBpatch_font\fP callback
573 provided by Luaotfload to perform important corrections on font data.
574 .sp
575 The fontloader backend can be selected by setting the value of
576 \fBfontloader\fP\&. The most important choices are \fBdefault\fP, which will
577 load the dedicated Luaotfload fontloader, and \fBreference\fP, the
578 upstream package as shipped with Luaotfload. Other than those, a file
579 name accessible via kpathsea can be specified.
580 .sp
581 Alternatively, the individual files that constitute the fontloader can
582 be loaded directly. While less efficient, this greatly aids debugging
583 since error messages will reference the actual line numbers of the
584 source files and explanatory comments are not stripped. Currently,
585 three distinct loading strategies are available: \fBunpackaged\fP will
586 load the batch that is part of Luaotfload. These contain the identical
587 source code that the reference fontloader has been compiled from.
588 Another option, \fBcontext\fP will attempt to load the same files by
589 their names in the Context format from the search path. Consequently
590 this option allows to use the version of Context that comes with the
591 TeX distribution. Distros tend to prefer the stable version (“current”
592 in Context jargon) of those files so certain bugs encountered in the
593 more bleeding edge Luaotfload can be avoided this way. A third option
594 is to use \fBcontext\fP with a colon to specify a directory prefix where
595 the \fITEXMF\fP is located that the files should be loaded from, e. g.
596 \fBcontext:~/context/tex/texmf\-context\fP\&. This can be used when
597 referencing another distribution like the Context minimals that is
598 installed under a different path not indexed by kpathsea.
599 .sp
600 The value of \fBlog\-level\fP sets the default verbosity of messages
601 printed by Luaotfload. Only messages defined with a verbosity of less
602 than or equal to the supplied value will be output on the terminal.
603 At a log level of five Luaotfload can be very noisy. Also, printing too
604 many messages will slow down the interpreter due to line buffering
605 being disabled (see \fBsetbuf\fP(3)).
606 .sp
607 The \fBresolver\fP setting allows choosing the font name resolution
608 function: With the default value \fBcached\fP Luaotfload saves the result
609 of a successful font name request to a cache file to speed up
610 subsequent lookups. The alternative, \fBnormal\fP circumvents the cache
611 and resolves every request individually. (Since to the restructuring of
612 the font name index in Luaotfload 2.4 the performance difference
613 between the cached and uncached lookups should be marginal.)
614 .sp
615 When luaotfload is used in \fBDVI\fP mode, the \fBdefault_dvi_driver\fP option
616 determines how OpenType fonts are represented in the DVI output. In most
617 cases the default value \fBdvisvgm\fP should be set, it uses a format
618 supported by multiple backends including \fBdvipdfmx\fP and \fBdvisvgm\fP
619 which uses GIDs to identify characters.
620 Setting this to \fBxdvipsk\fP uses an unstable internal format instead
621 which will change depending on the luaotfload, engine, or font version.
622 No one should rely on the mapping between DVI character codes and font glyphs
623 in this mode unless they tightly control all involved versions and are deeply
624 familiar with the implementation.
625 .SH FILES
626 .sp
627 Luaotfload only processes the first configuration file it encounters at
628 one of the search locations. The file name may be either
629 \fBluaotfload.conf\fP or \fBluaotfloadrc\fP, except for the dotfile in the
630 user’s home directory which is expected at \fB~/.luaotfloadrc\fP\&.
631 .sp
632 Configuration files are located following a series of steps. The search
633 terminates as soon as a suitable file is encountered. The sequence of
634 locations that Luaotfload looks at is
635 .INDENT 0.0
636 .IP i. 5
637 The current working directory of the LuaTeX process.
638 .IP ii. 5
639 The subdirectory \fBluaotfload/\fP inside the XDG configuration
640 tree, e. g. \fB/home/oenothea/config/luaotfload/\fP\&.
641 .IP iii. 5
642 The dotfile.
643 .IP iv. 5
644 The \fITEXMF\fP (using kpathsea).
645 .UNINDENT
646 .SH SEE ALSO
647 .sp
648 \fBluaotfload\-tool\fP(1), \fBluatex\fP(1), \fBlua\fP(1)
649 .INDENT 0.0
650 .IP \(bu 2
651 \fBtexdoc luaotfload\fP to display the PDF manual for the \fILuaotfload\fP
652 package
653 .IP \(bu 2
654 Luaotfload development \fI\%https://github.com/latex3/luaotfload\fP
655 .IP \(bu 2
656 LuaLaTeX mailing list \fI\%http://tug.org/pipermail/lualatex\-dev/\fP
657 .IP \(bu 2
658 LuaTeX \fI\%http://luatex.org/\fP
659 .IP \(bu 2
660 Luaotfload on CTAN \fI\%http://ctan.org/pkg/luaotfload\fP
661 .UNINDENT
662 .SH REFERENCES
663 .INDENT 0.0
664 .IP \(bu 2
665 The XDG base specification
666 \fI\%http://standards.freedesktop.org/basedir\-spec/basedir\-spec\-latest.html\fP\&.
667 .UNINDENT
668 .SH AUTHORS
669 .sp
670 \fILuaotfload\fP was developed by the LuaLaTeX dev team
671 (\fI\%https://github.com/lualatex/\fP). It is currently maintained by the
672 LaTeX Project Team at \fI\%https://github.com/latex3/luaotfload\fP
673 .sp
674 This manual page was written by Philipp Gesang <\fI\%phg@phi\-gamma.net\fP>.
675 .SH COPYRIGHT
676 GPL v2.0
677 .\" Generated by docutils manpage writer.
678 .