Merge pull request #228 from phi-gamma/master

merge version 2.5 (texlive2014) into master

1 files changed, 347 insertions, 0 deletions

diff --git a/doc/luaotfload.conf.rst b/doc/luaotfload.conf.rst
new file mode 100644
index 0000000..774095b
--- /dev/null
+++ b/doc/luaotfload.conf.rst
@@ -0,0 +1,347 @@
+=======================================================================
+                            luaotfload.conf
+=======================================================================
+
+-----------------------------------------------------------------------
+                     Luaotfload configuration file
+-----------------------------------------------------------------------
+
+:Date:                  2014-06-09
+:Copyright:             GPL v2.0
+:Version:               2.5
+: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, pfa, pfb
+        compress = false
+    
+    [misc]
+        termwidth = 60
+    
+    [run]
+        log-level = 6
+
+This will make Luaotfload ignore all font files except for PostScript
+formats. NB: With a default Tex Live install the PS fonts will take
+much longer to index than OpenType or TrueType ones. Also, an
+uncompressed index file will be dumped which is going to be much larger
+due to the huge amount of PostScript fonts indexed. 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 --update --force
+
+
+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
+``pre_linebreak_filter`` or ``pre_output_filter``, defined in the
+section *run*.
+
+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 ``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                     |
++------------------+--------+------------------------------+
+|  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 ``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 Fontspect that rely on the ``patch_font`` callback
+provided by Luaotfload to perform important corrections on font data.
+
+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
+<philipp.gesang@alumni.uni-heidelberg.de>.
+