From 66715ea0131082efdca3267d3ab663153b0372e9 Mon Sep 17 00:00:00 2001
From: Philipp Gesang <phg@phi-gamma.net>
Date: Thu, 19 Nov 2015 00:00:43 +0100
Subject: [man] document fontloader switch

---
 doc/luaotfload.conf.rst | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/doc/luaotfload.conf.rst b/doc/luaotfload.conf.rst
index 2a339ce..12dd887 100644
--- a/doc/luaotfload.conf.rst
+++ b/doc/luaotfload.conf.rst
@@ -276,6 +276,8 @@ Section ``run``
 +------------------+--------+------------------------------+
 |  resolver        |   s    |  ``"cached"``                |
 +------------------+--------+------------------------------+
+|  fontloader      |   s    |  ``"default"``               |
++------------------+--------+------------------------------+
 
 The ``color-callback`` option determines the stage at which fonts that
 defined with a ``color=xxyyzz`` feature will be colorized. By default
@@ -294,6 +296,29 @@ 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 fontloader backend can be selected by setting the value of
+``fontloader``. Other than the default, which selects the packaged
+``reference`` loader as shipped with Luaotfload, a file name accessible
+by 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.
-- 
cgit v1.2.3