| 1 |
======================================================================= |
| 2 |
luaotfload.conf |
| 3 |
======================================================================= |
| 4 |
|
| 5 |
----------------------------------------------------------------------- |
| 6 |
Luaotfload configuration file |
| 7 |
----------------------------------------------------------------------- |
| 8 |
|
| 9 |
:Date: 2024-12-03 |
| 10 |
:Copyright: GPL v2.0 |
| 11 |
:Version: 3.29 |
| 12 |
:Manual section: 5 |
| 13 |
:Manual group: text processing |
| 14 |
|
| 15 |
SYNOPSIS |
| 16 |
======================================================================= |
| 17 |
|
| 18 |
- **./luaotfload{.conf,rc}** |
| 19 |
- **XDG_CONFIG_HOME/luaotfload/luaotfload{.conf,rc}** |
| 20 |
- **~/.luaotfloadrc** |
| 21 |
|
| 22 |
DESCRIPTION |
| 23 |
======================================================================= |
| 24 |
|
| 25 |
The file ``luaotfload.conf`` contains configuration options for |
| 26 |
*Luaotfload*, a font loading and font management component for LuaTeX. |
| 27 |
|
| 28 |
|
| 29 |
EXAMPLE |
| 30 |
======================================================================= |
| 31 |
|
| 32 |
A small Luaotfload configuration file with few customizations could |
| 33 |
look as follows: :: |
| 34 |
|
| 35 |
[db] |
| 36 |
formats = afm,ttf |
| 37 |
compress = false |
| 38 |
|
| 39 |
[misc] |
| 40 |
termwidth = 60 |
| 41 |
|
| 42 |
[run] |
| 43 |
log-level = 6 |
| 44 |
|
| 45 |
This will make Luaotfload ignore all font files except for PostScript |
| 46 |
binary fonts with a matching AFM file, and Truetype fonts. Also, an |
| 47 |
uncompressed index file will be dumped which is going to be much larger |
| 48 |
than the default gzip’ed index. The terminal width |
| 49 |
is truncated to 60 characters which influences the verbose output |
| 50 |
during indexing. Finally, the verbosity is increased greatly: each font |
| 51 |
file being processed will be printed to the stdout on a separate line, |
| 52 |
along with lots of other information. |
| 53 |
|
| 54 |
To observe the difference in behavior, save above snippet to |
| 55 |
``./luaotfload.conf`` and update the font index: :: |
| 56 |
|
| 57 |
luaotfload-tool --update --force |
| 58 |
|
| 59 |
The current configuration can be written to disk using |
| 60 |
**luaotfload-tool**: :: |
| 61 |
|
| 62 |
luaotfload-tool --dumpconf > luaotfload.conf |
| 63 |
|
| 64 |
The result can itself be used as a configuration file. |
| 65 |
|
| 66 |
|
| 67 |
SYNTAX |
| 68 |
======================================================================= |
| 69 |
|
| 70 |
The configuration file syntax follows the common INI format. For a more |
| 71 |
detailed description please refer to the section “CONFIGURATION FILE” |
| 72 |
of **git-config**\(1). A brief list of rules is given below: |
| 73 |
|
| 74 |
* Blank lines and lines starting with a semicolon (``;``) are ignored. |
| 75 |
|
| 76 |
* A configuration file is partitioned into sections that are declared |
| 77 |
by specifying the section title in brackets on a separate line: :: |
| 78 |
|
| 79 |
[some-section] |
| 80 |
... section content ... |
| 81 |
|
| 82 |
* Sections consist of one or more variable assignments of the form |
| 83 |
``variable-name = value`` E. g.:: |
| 84 |
|
| 85 |
[foo] |
| 86 |
bar = baz |
| 87 |
quux = xyzzy |
| 88 |
... |
| 89 |
|
| 90 |
* Section and variable names may contain only uppercase and lowercase |
| 91 |
letters as well as dashes (``-``). |
| 92 |
|
| 93 |
|
| 94 |
VARIABLES |
| 95 |
======================================================================= |
| 96 |
|
| 97 |
Variables in belong into a configuration section and their values must |
| 98 |
be of a certain type. Some of them have further constraints. For |
| 99 |
example, the “color callback” must be a string of one of the values |
| 100 |
``post_linebreak_filter``, ``pre_linebreak_filter``, or |
| 101 |
``pre_output_filter``, defined in the section *run* of the |
| 102 |
configuration file. |
| 103 |
|
| 104 |
Currently, the configuration is organized into four sections: |
| 105 |
|
| 106 |
db |
| 107 |
Options relating to the font index. |
| 108 |
|
| 109 |
misc |
| 110 |
Options without a clearly defined category. |
| 111 |
|
| 112 |
paths |
| 113 |
Path and file name settings. |
| 114 |
|
| 115 |
run |
| 116 |
Options controlling runtime behavior of Luaotfload. |
| 117 |
|
| 118 |
The list of valid variables, the sections they are part of and their |
| 119 |
type is given below. Types represent Lua types that the values must be |
| 120 |
convertible to; they are abbreviated as follows: ``s`` for the *string* |
| 121 |
type, ``n`` for *number*, ``b`` for *boolean*. A value of ``nil`` means |
| 122 |
the variable is unset. |
| 123 |
|
| 124 |
|
| 125 |
Section ``db`` |
| 126 |
----------------------------------------------------------------------- |
| 127 |
|
| 128 |
+----------------------+--------+---------------------------+ |
| 129 |
| variable | type | default | |
| 130 |
+----------------------+--------+---------------------------+ |
| 131 |
| compress | b | ``true`` | |
| 132 |
+----------------------+--------+---------------------------+ |
| 133 |
| designsize-dimen | b | ``bp`` | |
| 134 |
+----------------------+--------+---------------------------+ |
| 135 |
| formats | s | ``"otf,ttf,ttc"`` | |
| 136 |
+----------------------+--------+---------------------------+ |
| 137 |
| location-precedence | s | ``"system,texmf,local`` | |
| 138 |
+----------------------+--------+---------------------------+ |
| 139 |
| max-fonts | n | ``2^51`` | |
| 140 |
+----------------------+--------+---------------------------+ |
| 141 |
| scan-local | b | ``false`` | |
| 142 |
+----------------------+--------+---------------------------+ |
| 143 |
| skip-read | b | ``false`` | |
| 144 |
+----------------------+--------+---------------------------+ |
| 145 |
| strip | b | ``true`` | |
| 146 |
+----------------------+--------+---------------------------+ |
| 147 |
| update-live | b | ``true`` | |
| 148 |
+----------------------+--------+---------------------------+ |
| 149 |
|
| 150 |
The flag ``compress`` determines whether the font index (usually |
| 151 |
``luaotfload-names.lua[.gz]`` will be stored in compressed forms. |
| 152 |
If unset it is equivalent of passing ``--no-compress`` to |
| 153 |
**luaotfload-tool**. Since the file is only created for convenience |
| 154 |
and has no effect on the runtime behavior of Luaotfload, the flag |
| 155 |
should remain set. Most editors come with zlib support anyways. |
| 156 |
|
| 157 |
The setting ``designsize-dimen`` applies when looking up fonts from |
| 158 |
families with design sizes. In Opentype, these are specified as |
| 159 |
“decipoints” where one decipoint equals ten DTP style “big points”. |
| 160 |
When indexing fonts these values are converted to ``sp``. In order to |
| 161 |
treat the values as though they were specified in TeX points or Didot |
| 162 |
points, set ``designsize-dimen`` to ``pt`` or ``dd``. |
| 163 |
|
| 164 |
The list of ``formats`` must be a comma separated sequence of strings |
| 165 |
containing one or more of these elements: |
| 166 |
|
| 167 |
* ``otf`` (OpenType format), |
| 168 |
* ``ttf`` and ``ttc`` (TrueType format), |
| 169 |
* ``afm`` (Adobe Font Metrics), |
| 170 |
|
| 171 |
It corresponds loosely to the ``--formats`` option to |
| 172 |
**luaotfload-tool**. Invalid or duplicate members are ignored; if the |
| 173 |
list does not contain any useful identifiers, the default list |
| 174 |
``"otf,ttf,ttc"`` will be used. |
| 175 |
|
| 176 |
The variable ``location-precedence`` selects where and in which order |
| 177 |
luaotfload searches for fonts. Fonts in earlier locations are preferred. |
| 178 |
The three supported locations are ``system`` for system specific font |
| 179 |
directories, ``texmf`` for fonts which are part of the \TeX{} distribution |
| 180 |
and ``local`` for local fonts. |
| 181 |
|
| 182 |
The variable ``max-fonts`` determines after processing how many font |
| 183 |
files the font scanner will terminate the search. This is useful for |
| 184 |
debugging issues with the font index and has the same effect as the |
| 185 |
option ``--max-fonts`` to **luaotfload-tools**. |
| 186 |
|
| 187 |
The ``scan-local`` flag, if set, will incorporate the current working |
| 188 |
directory as a font search location. NB: This will potentially slow |
| 189 |
down document processing because a font index with local fonts will not |
| 190 |
be saved to disk, so these fonts will have to be re-indexed whenever |
| 191 |
the document is built. Setting ``scan_local`` to ``false`` is the same |
| 192 |
as removing ``local`` from ``location-precedence``. |
| 193 |
|
| 194 |
The ``skip-read`` flag is only useful for debugging: It makes |
| 195 |
Luaotfload skip reading fonts. The font information for rebuilding the |
| 196 |
index is taken from the presently existing one. |
| 197 |
|
| 198 |
Unsetting the ``strip`` flag prevents Luaotfload from removing data |
| 199 |
from the index that is only useful when processing font files. NB: this |
| 200 |
can increase the size of the index files significantly and has no |
| 201 |
effect on the runtime behavior. |
| 202 |
|
| 203 |
If ``update-live`` is set, Luaotfload will reload the database if it |
| 204 |
cannot find a requested font. Those who prefer to update manually using |
| 205 |
**luaotfload-tool** should unset this flag. This option does not affect |
| 206 |
rebuilds due to version mismatch. |
| 207 |
|
| 208 |
Section ``default-features`` |
| 209 |
----------------------------------------------------------------------- |
| 210 |
|
| 211 |
By default Luaotfload enables ``node`` mode and picks the default font |
| 212 |
features that are prescribed in the OpenType standard. This behavior |
| 213 |
may be overridden in the ``default-features`` section. Global defaults |
| 214 |
that will be applied for all scripts can be set via the ``global`` |
| 215 |
option, others by the script they are to be applied to. For example, |
| 216 |
a setting of :: |
| 217 |
|
| 218 |
[default-features] |
| 219 |
global = mode=base,color=0000FF |
| 220 |
dflt = smcp,onum |
| 221 |
|
| 222 |
would force *base* mode, tint all fonts blue and activate small |
| 223 |
capitals and text figures globally. Features are specified as a comma |
| 224 |
separated list of variables or variable-value pairs. Variables without |
| 225 |
an explicit value are set to ``true``. |
| 226 |
|
| 227 |
|
| 228 |
Section ``misc`` |
| 229 |
----------------------------------------------------------------------- |
| 230 |
|
| 231 |
+---------------+--------+-------------------------+ |
| 232 |
| variable | type | default | |
| 233 |
+---------------+--------+-------------------------+ |
| 234 |
| statistics | b | ``false`` | |
| 235 |
+---------------+--------+-------------------------+ |
| 236 |
| termwidth | n | ``nil`` | |
| 237 |
+---------------+--------+-------------------------+ |
| 238 |
| version | s | <Luaotfload version> | |
| 239 |
+---------------+--------+-------------------------+ |
| 240 |
| keepnames | b | ``true`` | |
| 241 |
+---------------+--------+-------------------------+ |
| 242 |
|
| 243 |
With ``statistics`` enabled, extra statistics will be collected during |
| 244 |
index creation and appended to the index file. It may then be queried |
| 245 |
at the Lua end or inspected by reading the file itself. |
| 246 |
|
| 247 |
The value of ``termwidth``, if set, overrides the value retrieved by |
| 248 |
querying the properties of the terminal in which Luatex runs. This is |
| 249 |
useful if the engine runs with ``shell_escape`` disabled and the actual |
| 250 |
terminal dimensions cannot be retrieved. |
| 251 |
|
| 252 |
The value of ``version`` is derived from the version string hard-coded |
| 253 |
in the Luaotfload source. Override at your own risk. |
| 254 |
|
| 255 |
The ``keepnames`` option decides if the ConTeXt fontloader should keep |
| 256 |
names it considers useless or if they should be discarded. This option |
| 257 |
only takes effect after font caches are regenererated. |
| 258 |
|
| 259 |
|
| 260 |
Section ``paths`` |
| 261 |
----------------------------------------------------------------------- |
| 262 |
|
| 263 |
+------------------+--------+------------------------------------+ |
| 264 |
| variable | type | default | |
| 265 |
+------------------+--------+------------------------------------+ |
| 266 |
| cache-dir | s | ``"fonts"`` | |
| 267 |
+------------------+--------+------------------------------------+ |
| 268 |
| names-dir | s | ``"names"`` | |
| 269 |
+------------------+--------+------------------------------------+ |
| 270 |
| index-file | s | ``"luaotfload-names.lua"`` | |
| 271 |
+------------------+--------+------------------------------------+ |
| 272 |
| lookups-file | s | ``"luaotfload-lookup-cache.lua"`` | |
| 273 |
+------------------+--------+------------------------------------+ |
| 274 |
|
| 275 |
The paths ``cache-dir`` and ``names-dir`` determine the subdirectory |
| 276 |
inside the Luaotfload subtree of the ``luatex-cache`` directory where |
| 277 |
the font cache and the font index will be stored, respectively. |
| 278 |
|
| 279 |
Inside the index directory, the names of the index file and the font |
| 280 |
lookup cache will be derived from the respective values of |
| 281 |
``index-file`` and ``lookups-file``. This is the filename base for the |
| 282 |
bytecode compiled version as well as -- for the index -- the gzipped |
| 283 |
version. |
| 284 |
|
| 285 |
|
| 286 |
Section ``run`` |
| 287 |
----------------------------------------------------------------------- |
| 288 |
|
| 289 |
+---------------------+--------+------------------------------+ |
| 290 |
| variable | type | default | |
| 291 |
+---------------------+--------+------------------------------+ |
| 292 |
| anon-sequence | s | ``"tex,path,name"`` | |
| 293 |
+---------------------+--------+------------------------------+ |
| 294 |
| color-callback | s | ``"post_linebreak_filter"`` | |
| 295 |
+---------------------+--------+------------------------------+ |
| 296 |
| definer | s | ``"patch"`` | |
| 297 |
+---------------------+--------+------------------------------+ |
| 298 |
| log-level | n | ``0`` | |
| 299 |
+---------------------+--------+------------------------------+ |
| 300 |
| resolver | s | ``"cached"`` | |
| 301 |
+---------------------+--------+------------------------------+ |
| 302 |
| fontloader | s | ``"default"`` | |
| 303 |
+---------------------+--------+------------------------------+ |
| 304 |
| default_dvi_driver | s | ``"dvisvgm"`` | |
| 305 |
+---------------------+--------+------------------------------+ |
| 306 |
|
| 307 |
Unqualified font lookups are treated with the flexible “anonymous” |
| 308 |
mechanism. This involves a chain of lookups applied successively until |
| 309 |
the first one yields a match. By default, the lookup will first search |
| 310 |
for TFM fonts using the Kpathsea library. If this wasn’t successful, an |
| 311 |
attempt is made at interpreting the request as an absolute path (like |
| 312 |
the ``[/path/to/font/foo.ttf]`` syntax) or a file name |
| 313 |
(``file:foo.ttf``). Finally, the request is interpreted as a font name |
| 314 |
and retrieved from the index (``name:Foo Regular``). This behavior can |
| 315 |
be configured by specifying a list as the value to ``anon-sequence``. |
| 316 |
Available items are ``tex``, ``path``, ``name`` -- representing the |
| 317 |
lookups described above, respectively --, and ``file`` for searching a |
| 318 |
filename but not an absolute path. Also, ``my`` lookups are valid |
| 319 |
values but they should only be used from within TeX documents, because |
| 320 |
there is no means of customizing a ``my`` lookups on the command line. |
| 321 |
|
| 322 |
The ``color-callback`` option determines the stage at which fonts that |
| 323 |
defined with a ``color=xxyyzz`` feature will be colorized. By default |
| 324 |
this happens in a ``post_linebreak_filter`` but alternatively the |
| 325 |
``pre_linebreak_filter`` or ``pre_output_filter`` may be chosen, which |
| 326 |
is faster but might produce inconsistent output. The |
| 327 |
``pre_output_filter`` used to be the default in the 1.x series of |
| 328 |
Luaotfload, whilst later versions up to and including 2.5 hooked into |
| 329 |
the ``pre_linebreak_filter`` which naturally didn’t affect any glyphs |
| 330 |
inserting during hyphenation. Both are kept around as options to |
| 331 |
restore the previous behavior if necessary. |
| 332 |
|
| 333 |
The ``definer`` allows for switching the ``define_font`` callback. |
| 334 |
Apart from the default ``patch`` one may also choose the ``generic`` |
| 335 |
one that comes with the vanilla fontloader. Beware that this might |
| 336 |
break tools like Fontspec that rely on the ``patch_font`` callback |
| 337 |
provided by Luaotfload to perform important corrections on font data. |
| 338 |
|
| 339 |
The fontloader backend can be selected by setting the value of |
| 340 |
``fontloader``. The most important choices are ``default``, which will |
| 341 |
load the dedicated Luaotfload fontloader, and ``reference``, the |
| 342 |
upstream package as shipped with Luaotfload. Other than those, a file |
| 343 |
name accessible via kpathsea can be specified. |
| 344 |
|
| 345 |
Alternatively, the individual files that constitute the fontloader can |
| 346 |
be loaded directly. While less efficient, this greatly aids debugging |
| 347 |
since error messages will reference the actual line numbers of the |
| 348 |
source files and explanatory comments are not stripped. Currently, |
| 349 |
three distinct loading strategies are available: ``unpackaged`` will |
| 350 |
load the batch that is part of Luaotfload. These contain the identical |
| 351 |
source code that the reference fontloader has been compiled from. |
| 352 |
Another option, ``context`` will attempt to load the same files by |
| 353 |
their names in the Context format from the search path. Consequently |
| 354 |
this option allows to use the version of Context that comes with the |
| 355 |
TeX distribution. Distros tend to prefer the stable version (“current” |
| 356 |
in Context jargon) of those files so certain bugs encountered in the |
| 357 |
more bleeding edge Luaotfload can be avoided this way. A third option |
| 358 |
is to use ``context`` with a colon to specify a directory prefix where |
| 359 |
the *TEXMF* is located that the files should be loaded from, e. g. |
| 360 |
``context:~/context/tex/texmf-context``. This can be used when |
| 361 |
referencing another distribution like the Context minimals that is |
| 362 |
installed under a different path not indexed by kpathsea. |
| 363 |
|
| 364 |
The value of ``log-level`` sets the default verbosity of messages |
| 365 |
printed by Luaotfload. Only messages defined with a verbosity of less |
| 366 |
than or equal to the supplied value will be output on the terminal. |
| 367 |
At a log level of five Luaotfload can be very noisy. Also, printing too |
| 368 |
many messages will slow down the interpreter due to line buffering |
| 369 |
being disabled (see **setbuf**\(3)). |
| 370 |
|
| 371 |
The ``resolver`` setting allows choosing the font name resolution |
| 372 |
function: With the default value ``cached`` Luaotfload saves the result |
| 373 |
of a successful font name request to a cache file to speed up |
| 374 |
subsequent lookups. The alternative, ``normal`` circumvents the cache |
| 375 |
and resolves every request individually. (Since to the restructuring of |
| 376 |
the font name index in Luaotfload 2.4 the performance difference |
| 377 |
between the cached and uncached lookups should be marginal.) |
| 378 |
|
| 379 |
When luaotfload is used in ``DVI`` mode, the ``default_dvi_driver`` option |
| 380 |
determines how OpenType fonts are represented in the DVI output. In most |
| 381 |
cases the default value ``dvisvgm`` should be set, it uses a format |
| 382 |
supported by multiple backends including ``dvipdfmx`` and ``dvisvgm`` |
| 383 |
which uses GIDs to identify characters. |
| 384 |
Setting this to ``xdvipsk`` uses an unstable internal format instead |
| 385 |
which will change depending on the luaotfload, engine, or font version. |
| 386 |
No one should rely on the mapping between DVI character codes and font glyphs |
| 387 |
in this mode unless they tightly control all involved versions and are deeply |
| 388 |
familiar with the implementation. |
| 389 |
|
| 390 |
FILES |
| 391 |
======================================================================= |
| 392 |
|
| 393 |
Luaotfload only processes the first configuration file it encounters at |
| 394 |
one of the search locations. The file name may be either |
| 395 |
``luaotfload.conf`` or ``luaotfloadrc``, except for the dotfile in the |
| 396 |
user’s home directory which is expected at ``~/.luaotfloadrc``. |
| 397 |
|
| 398 |
Configuration files are located following a series of steps. The search |
| 399 |
terminates as soon as a suitable file is encountered. The sequence of |
| 400 |
locations that Luaotfload looks at is |
| 401 |
|
| 402 |
i. The current working directory of the LuaTeX process. |
| 403 |
ii. The subdirectory ``luaotfload/`` inside the XDG configuration |
| 404 |
tree, e. g. ``/home/oenothea/config/luaotfload/``. |
| 405 |
iii. The dotfile. |
| 406 |
iv. The *TEXMF* (using kpathsea). |
| 407 |
|
| 408 |
|
| 409 |
SEE ALSO |
| 410 |
======================================================================= |
| 411 |
|
| 412 |
**luaotfload-tool**\(1), **luatex**\(1), **lua**\(1) |
| 413 |
|
| 414 |
* ``texdoc luaotfload`` to display the PDF manual for the *Luaotfload* |
| 415 |
package |
| 416 |
* Luaotfload development `<https://github.com/latex3/luaotfload>`_ |
| 417 |
* LuaLaTeX mailing list `<http://tug.org/pipermail/lualatex-dev/>`_ |
| 418 |
* LuaTeX `<http://luatex.org/>`_ |
| 419 |
* Luaotfload on CTAN `<http://ctan.org/pkg/luaotfload>`_ |
| 420 |
|
| 421 |
|
| 422 |
REFERENCES |
| 423 |
======================================================================= |
| 424 |
|
| 425 |
* The XDG base specification |
| 426 |
`<http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html>`_. |
| 427 |
|
| 428 |
AUTHORS |
| 429 |
======================================================================= |
| 430 |
|
| 431 |
*Luaotfload* was developed by the LuaLaTeX dev team |
| 432 |
(`<https://github.com/lualatex/>`_). It is currently maintained by the |
| 433 |
LaTeX Project Team at `<https://github.com/latex3/luaotfload>`_ |
| 434 |
|
| 435 |
This manual page was written by Philipp Gesang <[email protected]>. |
| 436 |
|