summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/luatex/luaotfload/luaotfload.conf.rst
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/luatex/luaotfload/luaotfload.conf.rst')
-rw-r--r--Master/texmf-dist/source/luatex/luaotfload/luaotfload.conf.rst408
1 files changed, 0 insertions, 408 deletions
diff --git a/Master/texmf-dist/source/luatex/luaotfload/luaotfload.conf.rst b/Master/texmf-dist/source/luatex/luaotfload/luaotfload.conf.rst
deleted file mode 100644
index 63472cff23b..00000000000
--- a/Master/texmf-dist/source/luatex/luaotfload/luaotfload.conf.rst
+++ /dev/null
@@ -1,408 +0,0 @@
-=======================================================================
- luaotfload.conf
-=======================================================================
-
------------------------------------------------------------------------
- Luaotfload configuration file
------------------------------------------------------------------------
-
-:Date: 2017-01-29
-:Copyright: GPL v2.0
-:Version: 2.8
-:Manual section: 5
-:Manual group: text processing
-
-SYNOPSIS
-=======================================================================
-
-- **./luaotfload{.conf,rc}**
-- **XDG_CONFIG_HOME/luaotfload/luaotfload{.conf,rc}**
-- **~/.luaotfloadrc**
-
-DESCRIPTION
-=======================================================================
-
-The file ``luaotfload.conf`` contains configuration options for
-*Luaotfload*, a font loading and font management component for LuaTeX.
-
-
-EXAMPLE
-=======================================================================
-
-A small Luaotfload configuration file with few customizations could
-look as follows: ::
-
- [db]
- formats = afm,ttf
- compress = false
-
- [misc]
- termwidth = 60
-
- [run]
- log-level = 6
-
-This will make Luaotfload ignore all font files except for PostScript
-binary fonts with a matching AFM file, and Truetype fonts. Also, an
-uncompressed index file will be dumped which is going to be much larger
-than the default gzip’ed index. The terminal width
-is truncated to 60 characters which influences the verbose output
-during indexing. Finally, the verbosity is increased greatly: each font
-file being processed will be printed to the stdout on a separate line,
-along with lots of other information.
-
-To observe the difference in behavior, save above snippet to
-``./luaotfload.conf`` and update the font index: ::
-
- luaotfload-tool --update --force
-
-The current configuration can be written to disk using
-**luaotfload-tool**: ::
-
- luaotfload-tool --dumpconf > luaotfload.conf
-
-The result can itself be used as a configuration file.
-
-
-SYNTAX
-=======================================================================
-
-The configuration file syntax follows the common INI format. For a more
-detailed description please refer to the section “CONFIGURATION FILE”
-of **git-config**\(1). A brief list of rules is given below:
-
- * Blank lines and lines starting with a semicolon (``;``) are ignored.
-
- * A configuration file is partitioned into sections that are declared
- by specifying the section title in brackets on a separate line: ::
-
- [some-section]
- ... section content ...
-
- * Sections consist of one or more variable assignments of the form
- ``variable-name = value`` E. g.::
-
- [foo]
- bar = baz
- quux = xyzzy
- ...
-
- * Section and variable names may contain only uppercase and lowercase
- letters as well as dashes (``-``).
-
-
-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
-``post_linebreak_filter``, ``pre_linebreak_filter``, or
-``pre_output_filter``, defined in the section *run* of the
-configuration file.
-
-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`` |
-+--------------------+--------+---------------------------+
-| designsize-dimen | b | ``bp`` |
-+--------------------+--------+---------------------------+
-| formats | s | ``"otf,ttf,ttc"`` |
-+--------------------+--------+---------------------------+
-| 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 setting ``designsize-dimen`` applies when looking up fonts from
-families with design sizes. In Opentype, these are specified as
-“decipoints” where one decipoint equals ten DTP style “big points”.
-When indexing fonts these values are converted to ``sp``. In order to
-treat the values as though they were specified in TeX points or Didot
-points, set ``designsize-dimen`` to ``pt`` or ``dd``.
-
-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),
-* ``afm`` (Adobe Font Metrics),
-
-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"`` 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. This option does not affect
-rebuilds due to version mismatch.
-
-Section ``default-features``
------------------------------------------------------------------------
-
-By default Luaotfload enables ``node`` mode and picks the default font
-features that are prescribed in the OpenType standard. This behavior
-may be overridden in the ``default-features`` section. Global defaults
-that will be applied for all scripts can be set via the ``global``
-option, others by the script they are to be applied to. For example,
-a setting of ::
-
- [default-features]
- global = mode=base,color=0000FF
- dflt = smcp,onum
-
-would force *base* mode, tint all fonts blue and activate small
-capitals and text figures globally. Features are specified as a comma
-separated list of variables or variable-value pairs. Variables without
-an explicit value are set to ``true``.
-
-
-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 |
-+------------------+--------+------------------------------+
-| anon-sequence | s | ``"tex,path,name"`` |
-+------------------+--------+------------------------------+
-| color-callback | s | ``"post_linebreak_filter"`` |
-+------------------+--------+------------------------------+
-| definer | s | ``"patch"`` |
-+------------------+--------+------------------------------+
-| log-level | n | ``0`` |
-+------------------+--------+------------------------------+
-| resolver | s | ``"cached"`` |
-+------------------+--------+------------------------------+
-| fontloader | s | ``"default"`` |
-+------------------+--------+------------------------------+
-
-Unqualified font lookups are treated with the flexible “anonymous”
-mechanism. This involves a chain of lookups applied successively until
-the first one yields a match. By default, the lookup will first search
-for TFM fonts using the Kpathsea library. If this wasn’t successful, an
-attempt is made at interpreting the request as an absolute path (like
-the ``[/path/to/font/foo.ttf]`` syntax) or a file name
-(``file:foo.ttf``). Finally, the request is interpreted as a font name
-and retrieved from the index (``name:Foo Regular``). This behavior can
-be configured by specifying a list as the value to ``anon-sequence``.
-Available items are ``tex``, ``path``, ``name`` -- representing the
-lookups described above, respectively --, and ``file`` for searching a
-filename but not an absolute path. Also, ``my`` lookups are valid
-values but they should only be used from within TeX documents, because
-there is no means of customizing a ``my`` lookups on the command line.
-
-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 ``post_linebreak_filter`` but alternatively the
-``pre_linebreak_filter`` or ``pre_output_filter`` may be chosen, which
-is faster but might produce inconsistent output. The
-``pre_output_filter`` used to be the default in the 1.x series of
-Luaotfload, whilst later versions up to and including 2.5 hooked into
-the ``pre_linebreak_filter`` which naturally didn’t affect any glyphs
-inserting during hyphenation. Both are kept around as options to
-restore the previous behavior if necessary.
-
-The ``definer`` allows for switching the ``define_font`` callback.
-Apart from the default ``patch`` one may also choose the ``generic``
-one that comes with the vanilla fontloader. Beware that this might
-break tools like Fontspec that rely on the ``patch_font`` callback
-provided by Luaotfload to perform important corrections on font data.
-
-The fontloader backend can be selected by setting the value of
-``fontloader``. The most important choices are ``default``, which will
-load the dedicated Luaotfload fontloader, and ``reference``, the
-upstream package as shipped with Luaotfload. Other than those, a file
-name accessible via kpathsea can be specified.
-
-Alternatively, the individual files that constitute the fontloader can
-be loaded directly. While less efficient, this greatly aids debugging
-since error messages will reference the actual line numbers of the
-source files and explanatory comments are not stripped. Currently,
-three distinct loading strategies are available: ``unpackaged`` will
-load the batch that is part of Luaotfload. These contain the identical
-source code that the reference fontloader has been compiled from.
-Another option, ``context`` will attempt to load the same files by
-their names in the Context format from the search path. Consequently
-this option allows to use the version of Context that comes with the
-TeX distribution. Distros tend to prefer the stable version (“current”
-in Context jargon) of those files so certain bugs encountered in the
-more bleeding edge Luaotfload can be avoided this way. A third option
-is to use ``context`` with a colon to specify a directory prefix where
-the *TEXMF* is located that the files should be loaded from, e. g.
-``context:~/context/tex/texmf-context``. This can be used when
-referencing another distribution like the Context minimals that is
-installed under a different path not indexed by kpathsea.
-
-The value of ``log-level`` sets 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)).
-
-The ``resolver`` setting allows choosing the font name resolution
-function: With the default value ``cached`` Luaotfload saves the result
-of a successful font name request to a cache file to speed up
-subsequent lookups. The alternative, ``normal`` circumvents the cache
-and resolves every request individually. (Since to the restructuring of
-the font name index in Luaotfload 2.4 the performance difference
-between the cached and uncached lookups should be marginal.)
-
-
-FILES
-=======================================================================
-
-Luaotfload only processes the first configuration file it encounters at
-one of the search locations. The file name may be either
-``luaotfload.conf`` or ``luaotfloadrc``, except for the dotfile in the
-user’s home directory which is expected at ``~/.luaotfloadrc``.
-
-Configuration files are located following a series of steps. The search
-terminates as soon as a suitable file is encountered. The sequence of
-locations that Luaotfload looks at is
-
-i. The current working directory of the LuaTeX process.
-ii. The subdirectory ``luaotfload/`` inside the XDG configuration
- tree, e. g. ``/home/oenothea/config/luaotfload/``.
-iii. The dotfile.
-iv. The *TEXMF* (using kpathsea).
-
-
-SEE ALSO
-=======================================================================
-
-**luaotfload-tool**\(1), **luatex**\(1), **lua**\(1)
-
-* ``texdoc luaotfload`` to display the PDF manual for the *Luaotfload*
- package
-* Luaotfload development `<https://github.com/lualatex/luaotfload>`_
-* LuaLaTeX mailing list `<http://tug.org/pipermail/lualatex-dev/>`_
-* LuaTeX `<http://luatex.org/>`_
-* Luaotfload on CTAN `<http://ctan.org/pkg/luaotfload>`_
-
-
-REFERENCES
-=======================================================================
-
-* The XDG base specification
- `<http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html>`_.
-
-AUTHORS
-=======================================================================
-
-*Luaotfload* is maintained by the LuaLaTeX dev team
-(`<https://github.com/lualatex/>`_).
-
-This manual page was written by Philipp Gesang <phg@phi-gamma.net>.
-