From cff9bd20679420af3e56b43d035f08c03f6a257e Mon Sep 17 00:00:00 2001 From: Philipp Gesang <phg42.2a@gmail.com> Date: Sat, 12 Jul 2014 22:21:21 +0200 Subject: [doc] describe configuration options --- doc/luaotfload.conf.rst | 176 +++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 174 insertions(+), 2 deletions(-) (limited to 'doc') diff --git a/doc/luaotfload.conf.rst b/doc/luaotfload.conf.rst index eb7788e..9c8153a 100644 --- a/doc/luaotfload.conf.rst +++ b/doc/luaotfload.conf.rst @@ -40,8 +40,180 @@ SYNTAX VARIABLES ======================================================================= +Variables in belong into a configuration section and their values must +be of a certain type. Some of them have further constraints. For +example, the “color callback” must be a string of one of the values +``pre_linebreak_filter`` or ``pre_output_filter``, defined in the +section *run*. -* TODO, list variables +Currently, the configuration is organized into four sections: + +db + Options relating to the font index. + +misc + Options without a clearly defined category. + +paths + Path and file name settings. + +run + Options controlling runtime behavior of Luaotfload. + +The list of valid variables, the sections they are part of and their +type is given below. Types represent Lua types that the values must be +convertible to; they are abbreviated as follows: ``s`` for the *string* +type, ``n`` for *number*, ``b`` for *boolean*. A value of ``nil`` means +the variable is unset. + + +Section ``db`` +----------------------------------------------------------------------- + ++---------------+--------+---------------------------+ +| variable | type | default | ++---------------+--------+---------------------------+ +| compress | b | ``true`` | ++---------------+--------+---------------------------+ +| formats | s | ``"otf,ttf,ttc,dfont"`` | ++---------------+--------+---------------------------+ +| max_fonts | n | ``2^51`` | ++---------------+--------+---------------------------+ +| scan_local | b | ``false`` | ++---------------+--------+---------------------------+ +| skip_read | b | ``false`` | ++---------------+--------+---------------------------+ +| strip | b | ``true`` | ++---------------+--------+---------------------------+ +| update_live | b | ``true`` | ++---------------+--------+---------------------------+ + +The flag ``compress`` determines whether the font index (usually +``luaotfload-names.lua[.gz]`` will be stored in compressed forms. +If unset it is equivalent of passing ``--no-compress`` to +**luaotfload-tool**. Since the file is only created for convenience +and has no effect on the runtime behavior of Luaotfload, the flag +should remain set. Most editors come with zlib support anyways. + +The list of ``formats`` must be a comma separated sequence of strings +containing one or more of these elements: + +* ``otf`` (OpenType format), +* ``ttf`` and ``ttc`` (TrueType format), +* ``dfont`` (Macintosh TrueType format), +* ``afm`` (Adobe Font Metrics), +* ``pfb`` and ``pfa`` (PostScript format). + +It corresponds loosely to the ``--formats`` option to +**luaotfload-tool**. Invalid or duplicate members are ignored; if the +list does not contain any useful identifiers, the default list +``"otf,ttf,ttc,dfont"`` will be used. + +The variable ``max_fonts`` determines after processing how many font +files the font scanner will terminate the search. This is useful for +debugging issues with the font index and has the same effect as the +option ``--max-fonts`` to **luaotfload-tools**. + +The ``scan_local`` flag, if set, will incorporate the current working +directory as a font search location. NB: This will potentially slow +down document processing because a font index with local fonts will not +be saved to disk, so these fonts will have to be re-indexed whenever +the document is built. + +The ``skip_read`` flag is only useful for debugging: It makes +Luaotfload skip reading fonts. The font information for rebuilding the +index is taken from the presently existing one. + +Unsetting the ``strip`` flag prevents Luaotfload from removing data +from the index that is only useful when processing font files. NB: this +can increase the size of the index files significantly and has no +effect on the runtime behavior. + +If ``update_live`` is set, Luaotfload will reload the database if it +cannot find a requested font. Those who prefer to update manually using +**luaotfload-tool** should unset this flag. + + +Section ``misc`` +----------------------------------------------------------------------- + ++---------------+--------+-------------------------+ +| variable | type | default | ++---------------+--------+-------------------------+ +| statistics | b | ``false`` | ++---------------+--------+-------------------------+ +| termwidth | n | ``nil`` | ++---------------+--------+-------------------------+ +| version | s | ``luaotfload.version`` | ++---------------+--------+-------------------------+ + +With ``statistics`` enabled, extra statistics will be collected during +index creation and appended to the index file. It may then be queried +at the Lua end or inspected by reading the file itself. + +The value of ``termwidth``, if set, overrides the value retrieved by +querying the properties of the terminal in which Luatex runs. This is +useful if the engine runs with ``shell_escape`` disabled and the actual +terminal dimensions cannot be retrieved. + +The value of ``version`` is derived from the version string hard-coded +in the Luaotfload source. Override at your own risk. + + +Section ``paths`` +----------------------------------------------------------------------- + ++------------------+--------+------------------------------------+ +| variable | type | default | ++------------------+--------+------------------------------------+ +| cache_dir | s | ``"fonts"`` | ++------------------+--------+------------------------------------+ +| names_dir | s | ``"names"`` | ++------------------+--------+------------------------------------+ +| index_file | s | ``"luaotfload-names.lua"`` | ++------------------+--------+------------------------------------+ +| lookups_file | s | ``"luaotfload-lookup-cache.lua"`` | ++------------------+--------+------------------------------------+ + +The paths ``cache_dir`` and ``names_dir`` determine the subdirectory +inside the Luaotfload subtree of the ``luatex-cache`` directory where +the font cache and the font index will be stored, respectively. + +Inside the index directory, the names of the index file and the font +lookup cache will be derived from the respective values of +``index_file`` and ``lookups_file``. This is the filename base for the +bytecode compiled version as well as -- for the index -- the gzipped +version. + + +Section ``run`` +----------------------------------------------------------------------- + ++------------------+--------+------------------------------+ +| variable | type | default | ++------------------+--------+------------------------------+ +| color_callback | s | ``"pre_linebreak_filter"`` | ++------------------+--------+------------------------------+ +| definer | s | ``"patch"`` | ++------------------+--------+------------------------------+ +| log_level | n | ``0`` | ++------------------+--------+------------------------------+ +| resolver | s | ``"cached"`` | ++------------------+--------+------------------------------+ + +The ``color_callback`` option determines the stage at which fonts that +defined with a ``color=xxyyzz`` feature will be colorized. By default +this happens in a ``pre_linebreak_filter`` but alternatively the +``pre_output_filter`` may be chosen, which is faster but might produce +inconsistent output. The latter also was the default in the 1.x series +of Luaotfload. + +The value of ``log_level`` set the default verbosity of messages +printed by Luaotfload. Only messages defined with a verbosity of less +than or equal to the supplied value will be output on the terminal. +At a log level of five Luaotfload can be very noisy. Also, printing too +many messages will slow down the interpreter due to line buffering +being disabled (see **setbuf**\(3)). FILES @@ -66,7 +238,7 @@ iv. The *TEXMF* (using kpathsea). SEE ALSO ======================================================================= -**luaotfload-tool** (1), **luatex** (1), **lua** (1) +**luaotfload-tool**\(1), **luatex**\(1), **lua**\(1) * ``texdoc luaotfload`` to display the PDF manual for the *Luaotfload* package -- cgit v1.2.3