summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorPhilipp Gesang <phg42.2a@gmail.com>2014-07-12 22:21:21 +0200
committerPhilipp Gesang <phg42.2a@gmail.com>2014-07-12 22:21:21 +0200
commitcff9bd20679420af3e56b43d035f08c03f6a257e (patch)
tree0459a551efcb950f730dc35d86c0b81d1e34af46 /doc
parent6a2df3f25e05f6a30c4789bd2c2daed999617784 (diff)
downloadluaotfload-cff9bd20679420af3e56b43d035f08c03f6a257e.tar.gz
[doc] describe configuration options
Diffstat (limited to 'doc')
-rw-r--r--doc/luaotfload.conf.rst176
1 files changed, 174 insertions, 2 deletions
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