From 4540a7d25d8a2dbbc3c773f2f27f2f1d7604b2ea Mon Sep 17 00:00:00 2001
From: Philipp Gesang <phg@phi-gamma.net>
Date: Thu, 5 Nov 2015 23:29:15 +0100
Subject: [doc] fix manual build
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

``\luafunction`` appears to now have some fragile semantics that we’d
rather avoid. Also the Latex folks finally got rid of the ``\luatex…``
namespace for primitives.
---
 doc/luaotfload-main.tex | 48 ++++++++++++++++++++++++------------------------
 1 file changed, 24 insertions(+), 24 deletions(-)

(limited to 'doc/luaotfload-main.tex')

diff --git a/doc/luaotfload-main.tex b/doc/luaotfload-main.tex
index c01beba..8f548fa 100644
--- a/doc/luaotfload-main.tex
+++ b/doc/luaotfload-main.tex
@@ -32,7 +32,7 @@
 \beginfrontmatter
 
   \setdocumenttitle  {The \identifier{luaotfload} package}
-  \setdocumentdate   {2015/03/29 v2.6}
+  \setdocumentdate   {2015/11/05 v2.6}
   \setdocumentauthor {Elie Roux · Khaled Hosny · Philipp Gesang\\
                       Home:    \hyperlink {https://github.com/lualatex/luaotfload}\\
                       Support: \email     {lualatex-dev@tug.org}}
@@ -233,7 +233,7 @@ where \meta{prefix} is either \inlinecode{file:} or \inlinecode {name:}.\footnot
   needed, for instance when supplying a customized tex distribution.
 
   The \inlinecode {my} lookup takes this a step further: it lets you define
-  a custom resolver function and hook it into the \luafunction{resolve_font}
+  a custom resolver function and hook it into the \luaident{resolve_font}
   callback.
   %
   This ensures full control over how a file is located.
@@ -664,7 +664,7 @@ obviously, \inlinecode{random}.
 
          Specific pairs of letters and ligatures may be exempt from
          letterspacing by defining the \LUA functions
-         \luafunction{keeptogether} and \luafunction{keepligature},
+         \luaident{keeptogether} and \luaident{keepligature},
          respectively, inside the namespace \inlinecode {luaotfload.letterspace}.
          %
          Both functions are called whenever the letterspacing callback
@@ -673,10 +673,10 @@ obviously, \inlinecode{random}.
          If they return a true-ish value, no extra kern is inserted at
          the current position.
          %
-         \luafunction{keeptogether} receives a pair of consecutive
+         \luaident{keeptogether} receives a pair of consecutive
          glyph nodes in order of their appearance in the node list.
          %
-         \luafunction{keepligature} receives a single node which can be
+         \luaident{keepligature} receives a single node which can be
          analyzed into components.
          %
          (For details refer to the \emphasis{glyph nodes} section in the
@@ -1254,7 +1254,7 @@ The purpose of this addition twofold.
 Firstly, \identifier{luaotfload} failed to provide a stable interface
 to internals in the past which resulted in an unmanageable situation
 of different packages abusing the raw access to font objects by means
-of the \luafunction{patch_font} callback.
+of the \luaident{patch_font} callback.
 %
 When the structure of the font object changed due to an update, all
 of these imploded and several packages had to be fixed while
@@ -1275,7 +1275,7 @@ additions.
 
 \beginsubsection {Callback Functions}
 
-The \luafunction{patch_font} callback is inserted in the wrapper
+The \luaident{patch_font} callback is inserted in the wrapper
 \identifier{luaotfload} provides for the font definition callback.
 %
 At this place it allows manipulating the font object immediately after
@@ -1367,8 +1367,8 @@ are defined for which scripts.
 \beginfunctionlist
 
   \beginaltitem  {aux.font_has_glyph (id : int, index : int)}
-            Predicate that returns true if the font \luafunction{id}
-            has glyph \luafunction{index}.
+            Predicate that returns true if the font \luaident{id}
+            has glyph \luaident{index}.
   \endaltitem
 
   \beginaltitem  {aux.slot_of_name(name : string)}
@@ -1377,33 +1377,33 @@ are defined for which scripts.
   \endaltitem
 
   \beginaltitem  {aux.name_of_slot(slot : int)}
-            The inverse of \luafunction{slot_of_name}; note that this
+            The inverse of \luaident{slot_of_name}; note that this
             might be incomplete as multiple glyph names may map to the
             same codepoint, only one of which is returned by
-            \luafunction{name_of_slot}.
+            \luaident{name_of_slot}.
   \endaltitem
 
   \beginaltitem  {aux.provides_script(id : int, script : string)}
-            Test if a font supports \luafunction{script}.
+            Test if a font supports \luaident{script}.
   \endaltitem
 
   \beginaltitem  {aux.provides_language(id : int, script : string, language : string)}
-            Test if a font defines \luafunction{language} for a given
-            \luafunction{script}.
+            Test if a font defines \luaident{language} for a given
+            \luaident{script}.
   \endaltitem
 
   \beginaltitem  {aux.provides_feature(id : int, script : string,
              language : string, feature : string)}
-            Test if a font defines \luafunction{feature} for
-            \luafunction{language} for a given \luafunction{script}.
+            Test if a font defines \luaident{feature} for
+            \luaident{language} for a given \luaident{script}.
   \endaltitem
 
   \beginaltitem  {aux.get_math_dimension(id : int, dimension : string)}
-            Get the dimension \luafunction{dimension} of font \luafunction{id}.
+            Get the dimension \luaident{dimension} of font \luaident{id}.
   \endaltitem
 
   \beginaltitem  {aux.sprint_math_dimension(id : int, dimension : string)}
-            Same as \luafunction{get_math_dimension()}, but output the value
+            Same as \luaident{get_math_dimension()}, but output the value
             in scaled points at the \TEX end.
   \endaltitem
 
@@ -1416,7 +1416,7 @@ are defined for which scripts.
 %% not implemented, may come back later
 \beginfunctionlist
 %   \beginaltitem  {aux.scan_external_dir(dir : string)}
-%             Include fonts in directory \luafunction{dir} in font lookups without
+%             Include fonts in directory \luaident{dir} in font lookups without
 %             adding them to the database.
 %
   \beginaltitem  {aux.read_font_index (void)}
@@ -1527,9 +1527,9 @@ Another strategy that helps avoiding problems is to not access raw
 Some of them, even though they are dangerous to access, have not been
 overridden or disabled.
 %
-Thus, whenever possible prefer the functions in the \luafunction{aux}
+Thus, whenever possible prefer the functions in the \luaident{aux}
 namespace over direct manipulation of font objects. For example, raw
-access to the \luafunction{font.fonts} table like:
+access to the \luaident{font.fonts} table like:
 
 \beginlisting
     local somefont = font.fonts[2]
@@ -1537,16 +1537,16 @@ access to the \luafunction{font.fonts} table like:
 
 \noindent can render already defined fonts unusable.
 %
-Instead, the function \luafunction{font.getfont()} should be used
+Instead, the function \luaident{font.getfont()} should be used
 because it has been replaced by a safe variant.
 
-However, \luafunction{font.getfont()} only covers fonts handled by the
+However, \luaident{font.getfont()} only covers fonts handled by the
 font loader, e.~g. \identifier{OpenType} and \identifier{TrueType}
 fonts, but not \abbrev{tfm} or \abbrev{ofm}.
 %
 Should you absolutely require access to all fonts known to \LUATEX,
 including the virtual and autogenerated ones, then you need to query
-both \luafunction{font.getfont()} and \luafunction{font.fonts}.
+both \luaident{font.getfont()} and \luaident{font.fonts}.
 %
 In this case, best define you own accessor:
 
-- 
cgit v1.2.3


From 6a7d1e67bb6e6fd073450a104ebe3ca934eaf14c Mon Sep 17 00:00:00 2001
From: Philipp Gesang <phg@phi-gamma.net>
Date: Fri, 6 Nov 2015 00:02:56 +0100
Subject: [doc] update manual wrt files

---
 doc/luaotfload-main.tex | 104 ++++++++++++++++++++++++++++--------------------
 1 file changed, 61 insertions(+), 43 deletions(-)

(limited to 'doc/luaotfload-main.tex')

diff --git a/doc/luaotfload-main.tex b/doc/luaotfload-main.tex
index 8f548fa..a5ed940 100644
--- a/doc/luaotfload-main.tex
+++ b/doc/luaotfload-main.tex
@@ -1056,23 +1056,21 @@ An example with explicit paths:
 \endsection
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\beginsection {Files from \CONTEXT and \LUATEX-Fonts}
+\beginsection {The Fontloader Package}
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
-\identifier{luaotfload} relies on code originally written by Hans
-Hagen for the \hyperlink[\identifier{\CONTEXT}]{http://wiki.contextgarden.net}
+To a large extent, \identifier{luaotfload} relies on code originally
+written by Hans Hagen for the
+\hyperlink[\identifier{\CONTEXT}]{http://wiki.contextgarden.net}
 format.
 %
-It integrates the font loader as distributed in
-the \identifier{\LUATEX-Fonts} package.
+It integrates the font loader, written entirely in \LUA, as distributed
+in the \identifier{\LUATEX-Fonts} package.
 %
 The original \LUA source files have been combined using the
-\fileent{mtx-package} script into a single, self-contained blob.
-In this form the font loader has no further dependencies\footnote{%
-  It covers, however, to some extent the functionality of the
-  \identifier{lualibs} package.
-}
-and requires only minor adaptions to integrate into
+\fileent{mtx-package} script into a single, self-contained blob. In
+this form the font loader depends only on the \identifier{lualibs}
+package and requires only minor adaptions to integrate into
 \identifier{luaotfload}.
 %
 The guiding principle is to let \CONTEXT/\LUATEX-Fonts take care of
@@ -1093,13 +1091,13 @@ Below is a commented list of the files distributed with
 See figure \ref{file-graph} on page \pageref{file-graph} for a
 graphical representation of the dependencies.
 %
-From \LUATEX-Fonts, only the file \fileent{luatex-fonts-merged.lua}
-has been imported as \fileent{luaotfload-fontloader.lua}.
-%
-It is generated by \fileent{mtx-package}, a \LUA source code merging
-too developed by Hans Hagen.\footnote{%
-  \fileent{mtx-package} is
-  \hyperlink [part of \CONTEXT]{http://repo.or.cz/w/context.git/blob_plain/refs/heads/origin:/scripts/context/lua/mtx-package.lua}
+Through the script \fileent{luaotfload-package.lua} the \CONTEXT
+utility \fileent{mtx-package} is invoked to create the
+\identifier{luaotfload} fontloader as a merged (amalgamated) source
+file.\footnote{%
+  \fileent{mtx-package}, a \LUA source code merging tool developed by
+  Hans Hagen, is
+  \hyperlink [part of \CONTEXT]{https://bitbucket.org/phg/context-mirror/src/726a663be481042003566d4614266b940b5a0c91/scripts/context/lua/mtx-package.lua?at=beta}
   and requires \fileent{mtxrun}.
   Run
   \inlinecode {mtxrun --script package --help}
@@ -1107,31 +1105,46 @@ too developed by Hans Hagen.\footnote{%
   For the actual merging code see the file
   \fileent{util-mrg.lua} that is part of \CONTEXT.
 }
-It houses several \LUA files that can be classed in three
-categories.
+%
+This file constitutes the “reference fontloader” and is part of the
+\identifier{luaotfload} package as \fileent{fontloader-reference.lua}.
+A companion to it, \fileent{luatex-basics-gen.lua} must be loaded
+beforehand to set up parts of the environment required by the \CONTEXT
+libraries.
+%
+During a \TEX\ run, the fontloader initialization and injection happens
+in the module \fileent{luaotfload-init.lua}.
+
+A number of \emphasis{\LUA utility libraries} that are already provided
+by \identifier{lualibs} package are not part of the \identifier{luaotfload}
+fontloader.\footnote{%
+  Faithful listeners will remember the pre-2.6 era when the fontloader
+  used to be integrated as-is which caused all kinds of code
+  duplication with the pervasive \identifier{Lualibs} package.
+  This conceptual glitch has since been amended by tightening the
+  coupling with the excellent \CONTEXT\ toolchain.
+}
+\beginnarrower
+  \begindoublecolumns
+    \begindefinitions
+        \beginaltitem {l-lua.lua}       \endaltitem
+        \beginaltitem {l-lpeg.lua}      \endaltitem
+        \beginaltitem {l-function.lua}  \endaltitem
+        \beginaltitem {l-string.lua}    \endaltitem
+        \beginaltitem {l-table.lua}     \endaltitem
+        \beginaltitem {l-io.lua}        \endaltitem
+        \beginaltitem {l-file.lua}      \endaltitem
+        \beginaltitem {l-boolean.lua}   \endaltitem
+        \beginaltitem {l-math.lua}      \endaltitem
+        \beginaltitem {util-str.lua}    \endaltitem
+    \enddefinitions
+  \enddoublecolumns
+\endnarrower
 
-\begindefinitions
-  \beginnormalitem
-    \emphasis{\LUA utility libraries}, a subset
-    of what is provided by the \identifier{lualibs}
-    package.
-
-    \begindoublecolumns
-      \begindefinitions
-          \beginaltitem {l-lua.lua}       \endaltitem
-          \beginaltitem {l-lpeg.lua}      \endaltitem
-          \beginaltitem {l-function.lua}  \endaltitem
-          \beginaltitem {l-string.lua}    \endaltitem
-          \beginaltitem {l-table.lua}     \endaltitem
-          \beginaltitem {l-io.lua}        \endaltitem
-          \beginaltitem {l-file.lua}      \endaltitem
-          \beginaltitem {l-boolean.lua}   \endaltitem
-          \beginaltitem {l-math.lua}      \endaltitem
-          \beginaltitem {util-str.lua}    \endaltitem
-      \enddefinitions
-    \enddoublecolumns
-  \endnormalitem
+The reference fontloader is home to several \LUA files that can be
+grouped twofold as below:
 
+\begindefinitions
   \beginnormalitem
     The \emphasis{font loader} itself.
     These files have been written for
@@ -1139,7 +1152,6 @@ categories.
     with \identifier{luaotfload}.
     \begindoublecolumns
       \begindefinitions
-        \beginaltitem{luatex-basics-gen.lua} \endaltitem
         \beginaltitem{luatex-basics-nod.lua} \endaltitem
         \beginaltitem{luatex-fonts-enc.lua}  \endaltitem
         \beginaltitem{luatex-fonts-syn.lua}  \endaltitem
@@ -1209,7 +1221,10 @@ files not contained in the merge. Some of these have no equivalent in
       font feature handling; incorporates some of the code from
       \fileent{font-otc} from \CONTEXT;
     \endaltitem
-    \beginaltitem {luaotfload-override.lua}
+    \beginaltitem {luaotfload-configuration.lua}
+      handling of \fileent{luaotfload.conf(5)}.
+    \endaltitem
+    \beginaltitem {luaotfload-log.lua}
       overrides the \CONTEXT logging functionality.
     \endaltitem
     \beginaltitem {luaotfload-loaders.lua}
@@ -1222,6 +1237,9 @@ files not contained in the merge. Some of these have no equivalent in
     \beginaltitem {luaotfload-database.lua}
       font names database.
     \endaltitem
+    \beginaltitem {luaotfload-resolvers.lua}
+      file name resolvers.
+    \endaltitem
     \beginaltitem {luaotfload-colors.lua}
       color handling.
     \endaltitem
-- 
cgit v1.2.3


From 8860ba7e4cb6009ac4abca9abd37cf276c786a45 Mon Sep 17 00:00:00 2001
From: Philipp Gesang <phg@phi-gamma.net>
Date: Fri, 6 Nov 2015 00:10:40 +0100
Subject: [doc] adapt to state of the art; stub section for configuration

---
 doc/luaotfload-main.tex | 28 +++++++++++++++++++---------
 1 file changed, 19 insertions(+), 9 deletions(-)

(limited to 'doc/luaotfload-main.tex')

diff --git a/doc/luaotfload-main.tex b/doc/luaotfload-main.tex
index a5ed940..46f66b5 100644
--- a/doc/luaotfload-main.tex
+++ b/doc/luaotfload-main.tex
@@ -1072,9 +1072,10 @@ The original \LUA source files have been combined using the
 this form the font loader depends only on the \identifier{lualibs}
 package and requires only minor adaptions to integrate into
 \identifier{luaotfload}.
-%
-The guiding principle is to let \CONTEXT/\LUATEX-Fonts take care of
-the implementation, and update the imported code from time to time.
+
+The guiding principle is to let \CONTEXT/\LUATEX-Fonts take care of the
+implementation, and update the imported code as frequently as
+necessary.
 %
 As maintainers, we aim at importing files from upstream essentially
 \emphasis{unmodified}, except for renaming them to prevent name
@@ -1194,11 +1195,12 @@ merged file, it will load the individual \LUA libraries
 instead.
 %
 Their names remain the same as in \CONTEXT (without the
-\inlinecode {otfl}-prefix) since we imported the relevant section of
-\fileent{luatex-fonts.lua} unmodified into \fileent{luaotfload-main.lua}.
-Thus if you prefer running bleeding edge code from the
-\CONTEXT beta, all you have to do is remove
-\fileent{luaotfload-merged.lua} from the search path.
+\inlinecode {luaotfload}-prefix) since the initialization mirrors
+the sequence in \LUATEX-Fonts.
+%% FIXME this is a config option nowadays!
+%Thus if you prefer running bleeding edge code from the \CONTEXT beta,
+%all you have to do is remove \fileent{luaotfload-merged.lua} from the
+%search path.
 
 Also, the merged file at some point loads the Adobe Glyph List from a
 \LUA table that is contained in \fileent{luaotfload-glyphlist.lua},
@@ -1206,8 +1208,9 @@ which is automatically generated by the script
 \fileent{mkglyphlist}.\footnote{%
   See \fileent{luaotfload-font-enc.lua}.
   The hard-coded file name is why we have to replace the procedure
-  that loads the file in \fileent{luaotfload-override.lua}.
+  that loads the file in \fileent{luaotfload-init.lua}.
 }
+%
 There is a make target \identifier{glyphs} that will create a fresh
 glyph list so we don’t need to import it from \CONTEXT any longer.
 
@@ -1259,6 +1262,13 @@ files not contained in the merge. Some of these have no equivalent in
 
 \endsection
 
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\beginsection {Configuration Files}
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\emphasis{Caution}: For the authoritative documentation, consult the
+manpage for \fileent{luaotfload.conf(5)}.
+
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 \beginsection {Auxiliary Functions}
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-- 
cgit v1.2.3


From 28dc7605d7875058227c5690a8f6354e1979d1b5 Mon Sep 17 00:00:00 2001
From: Philipp Gesang <phg@phi-gamma.net>
Date: Fri, 6 Nov 2015 00:17:32 +0100
Subject: [doc] remove redundant namespace prefixing for primitives

---
 doc/luaotfload-main.tex | 40 ++++++++++++++++++++--------------------
 1 file changed, 20 insertions(+), 20 deletions(-)

(limited to 'doc/luaotfload-main.tex')

diff --git a/doc/luaotfload-main.tex b/doc/luaotfload-main.tex
index 46f66b5..7badffd 100644
--- a/doc/luaotfload-main.tex
+++ b/doc/luaotfload-main.tex
@@ -1116,31 +1116,31 @@ libraries.
 During a \TEX\ run, the fontloader initialization and injection happens
 in the module \fileent{luaotfload-init.lua}.
 
-A number of \emphasis{\LUA utility libraries} that are already provided
-by \identifier{lualibs} package are not part of the \identifier{luaotfload}
-fontloader.\footnote{%
+A number of \emphasis{\LUA utility libraries} are not part of the
+\identifier{luaotfload} fontloader, contrary to its equivalent in
+\LUATEX-Fonts. These are already provided by the \identifier{lualibs}
+and have thus been omitted from the merge.\footnote{%
   Faithful listeners will remember the pre-2.6 era when the fontloader
   used to be integrated as-is which caused all kinds of code
-  duplication with the pervasive \identifier{Lualibs} package.
+  duplication with the pervasive \identifier{lualibs} package.
   This conceptual glitch has since been amended by tightening the
   coupling with the excellent \CONTEXT\ toolchain.
 }
-\beginnarrower
-  \begindoublecolumns
-    \begindefinitions
-        \beginaltitem {l-lua.lua}       \endaltitem
-        \beginaltitem {l-lpeg.lua}      \endaltitem
-        \beginaltitem {l-function.lua}  \endaltitem
-        \beginaltitem {l-string.lua}    \endaltitem
-        \beginaltitem {l-table.lua}     \endaltitem
-        \beginaltitem {l-io.lua}        \endaltitem
-        \beginaltitem {l-file.lua}      \endaltitem
-        \beginaltitem {l-boolean.lua}   \endaltitem
-        \beginaltitem {l-math.lua}      \endaltitem
-        \beginaltitem {util-str.lua}    \endaltitem
-    \enddefinitions
-  \enddoublecolumns
-\endnarrower
+
+\begindoublecolumns
+  \begindefinitions
+      \beginaltitem {l-lua.lua}       \endaltitem
+      \beginaltitem {l-lpeg.lua}      \endaltitem
+      \beginaltitem {l-function.lua}  \endaltitem
+      \beginaltitem {l-string.lua}    \endaltitem
+      \beginaltitem {l-table.lua}     \endaltitem
+      \beginaltitem {l-io.lua}        \endaltitem
+      \beginaltitem {l-file.lua}      \endaltitem
+      \beginaltitem {l-boolean.lua}   \endaltitem
+      \beginaltitem {l-math.lua}      \endaltitem
+      \beginaltitem {util-str.lua}    \endaltitem
+  \enddefinitions
+\enddoublecolumns
 
 The reference fontloader is home to several \LUA files that can be
 grouped twofold as below:
-- 
cgit v1.2.3


From 65c8b21ab3bf907357b203a7b5c6fb5b0a971cea Mon Sep 17 00:00:00 2001
From: Philipp Gesang <phg@phi-gamma.net>
Date: Sat, 7 Nov 2015 00:42:06 +0100
Subject: [doc] expand documentation of config files

---
 doc/luaotfload-main.tex | 73 ++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 66 insertions(+), 7 deletions(-)

(limited to 'doc/luaotfload-main.tex')

diff --git a/doc/luaotfload-main.tex b/doc/luaotfload-main.tex
index 7badffd..4b5e2e8 100644
--- a/doc/luaotfload-main.tex
+++ b/doc/luaotfload-main.tex
@@ -686,7 +686,7 @@ obviously, \inlinecode{random}.
          user.
   \endaltitem
 
-\ifcontextmkiv
+\iffalse
   \startbuffer [printvectors]
   \directlua{inspect(fonts.protrusions.setups.default)
              inspect(fonts.expansions.setups.default)}
@@ -706,7 +706,7 @@ obviously, \inlinecode{random}.
             %
             Alternatively and with loss of information, you can dump
             those tables into your terminal by issuing
-            \unless \ifcontextmkiv
+            \unless \iffalse
               \beginlisting
  \directlua{inspect(fonts.protrusions.setups.default)
             inspect(fonts.expansions.setups.default)}
@@ -763,7 +763,7 @@ Currently (2014) there are three of them:
             remapping feature.
           }:
 
-          \unless \ifcontextmkiv
+          \unless \iffalse
             %% Using braced arg syntax with inline code appears to be
             %% impossible within Latex tables -- just ignore the weird
             %% exclamation points below.
@@ -905,7 +905,7 @@ directories.
 \tablefloat {table-searchpaths}
   {List of paths searched for each supported operating system.}
   {%
-    \unless \ifcontextmkiv
+    \unless \iffalse
       \begincentered
         \begintabulate [lp{.5\textwidth}]
           \beginrow
@@ -1262,18 +1262,77 @@ files not contained in the merge. Some of these have no equivalent in
 
 \endsection
 
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\beginsection {Packaging a Fontloader}
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+TODO % it’s simple, though
+
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 \beginsection {Configuration Files}
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
-\emphasis{Caution}: For the authoritative documentation, consult the
-manpage for \fileent{luaotfload.conf(5)}.
+\beginnarrower
+  \emphasis{Caution}: For the authoritative documentation, consult the
+  manpage for \fileent{luaotfload.conf(5)}.
+\endnarrower
+
+The runtime behavior of \identifier{Luaotfload} can be customized by
+means of a configuration file.
+% location
+At startup, it attempts to locate a file called \fileent
+{luaotfload.conf} or \fileent {luaotfloadrc} at a number of candidate
+locations:
+
+\begincentered
+  \begindefinitions
+    \beginnormalitem \fileent{./luaotfload.conf}                            \endnormalitem
+    \beginnormalitem \fileent{./luaotfloadrc}                               \endnormalitem
+    \beginnormalitem \fileent{\$XDG_CONFIG_HOME/luaotfload/luaotfload.conf} \endnormalitem
+    \beginnormalitem \fileent{\$XDG_CONFIG_HOME/luaotfload/luaotfload.rc}   \endnormalitem
+    \beginnormalitem \fileent{~/.luaotfloadrc}                              \endnormalitem
+  \enddefinitions
+\endcentered
+
+\beginnarrower
+  \emphasis{Caution}: The configuration potentially modifies the final
+  document. A project-local file belongs under version control along
+  with the rest of the document. This is to ensure that everybody who
+  builds the project also receives the same customizations as the
+  author.
+\endnarrower
+
+% syntax
+% example settings
+
+An example for customization via \fileent {luaotfload.conf} might look
+as below:
+
+\beginlisting
+; Example luaotfload.conf containing a rudimentary configuration
+[db]
+  update-live = false
+[run]
+  color-callback = pre_linebreak_filter
+  definer = info_patch
+  log-level = 5
+[default-features]
+  global = mode=base
+\endlisting
+
+This specifies that for the given project, \identifier{Luaotfload}
+shall not attempt to automatically scan for fonts if it can’t resolve a
+request. The font-based colorization will happen during \LUATEX’s
+pre-linebreak filter. The fontloader will output verbose information
+about the fonts at definition time along with globally increased
+verbosity. Lastly, the fontloader defaults to the less expensive
+\luaident{base} mode like it does in \CONTEXT.
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 \beginsection {Auxiliary Functions}
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
-With release version 2.2, \identifier{luaotfload} received
+With release version 2.2, \identifier{Luaotfload} received
 additional functions for package authors to call from outside
 (see the file \fileent{luaotfload-auxiliary.lua} for details).
 %
-- 
cgit v1.2.3


From 54e6a5293dbff1e3775c2c3478b80c244608a4a5 Mon Sep 17 00:00:00 2001
From: Philipp Gesang <phg@phi-gamma.net>
Date: Sat, 7 Nov 2015 08:26:48 +0100
Subject: [doc] briefly describe config file syntax

---
 doc/luaotfload-main.tex | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

(limited to 'doc/luaotfload-main.tex')

diff --git a/doc/luaotfload-main.tex b/doc/luaotfload-main.tex
index 4b5e2e8..112572f 100644
--- a/doc/luaotfload-main.tex
+++ b/doc/luaotfload-main.tex
@@ -1303,8 +1303,14 @@ locations:
 \endnarrower
 
 % syntax
+The syntax is fairly close to the format used by
+\fileent{git-config(1)} which in turn was derived from the popular
+\identifier{.INI} format: Lines of key-value pairs are grouped under
+different configuration “sections”.\footnote{%
+  The configuration parser in \fileent {luoatfload-parsers.lua} might
+  be employed by other packages for similar purposes.
+}
 % example settings
-
 An example for customization via \fileent {luaotfload.conf} might look
 as below:
 
-- 
cgit v1.2.3


From 55945326011925fa81cca8cf2b5b9376025451a5 Mon Sep 17 00:00:00 2001
From: Philipp Gesang <phg@phi-gamma.net>
Date: Sat, 7 Nov 2015 08:44:55 +0100
Subject: [doc] introduce fontloader switching

---
 doc/luaotfload-main.tex | 31 ++++++++++++++++++++++++++-----
 1 file changed, 26 insertions(+), 5 deletions(-)

(limited to 'doc/luaotfload-main.tex')

diff --git a/doc/luaotfload-main.tex b/doc/luaotfload-main.tex
index 112572f..cc242e8 100644
--- a/doc/luaotfload-main.tex
+++ b/doc/luaotfload-main.tex
@@ -43,6 +43,11 @@
     This package is an adaptation of the \CONTEXT font loading system.
     It allows for loading \OpenType fonts with an extended syntax and adds
     support for a variety of font features.
+
+    After discussion of the font loading API, this manual gives an
+    overview of the core components of \identifier{Luaotfload}: The
+    packaged font loader code, the names database, configuration, and
+    helper functions on the \LUA\ end.
   \endabstractcontent
 
 \endfrontmatter
@@ -1056,9 +1061,11 @@ An example with explicit paths:
 \endsection
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\beginsection {The Fontloader Package}
+\beginsection {The Fontloader}
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
+\beginsubsection {Overview}
+
 To a large extent, \identifier{luaotfload} relies on code originally
 written by Hans Hagen for the
 \hyperlink[\identifier{\CONTEXT}]{http://wiki.contextgarden.net}
@@ -1086,6 +1093,10 @@ This job has been greatly alleviated since the advent of
 manually spotted and extracted from the \CONTEXT source code in a
 complicated and error-prone fashion.
 
+\endsubsection
+
+\beginsubsection {Contents and Dependencies}
+
 Below is a commented list of the files distributed with
 \identifier{luaotfload} in one way or the other.
 %
@@ -1260,14 +1271,23 @@ files not contained in the merge. Some of these have no equivalent in
   {Schematic of the files in \identifier{Luaotfload}}
   {filegraph.pdf}
 
-\endsection
+\endsubsection
 
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\beginsection {Packaging a Fontloader}
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\beginsubsection {Packaging}
+
+The fontloader code is integrated as an isolated component that can be
+switched out on demand.
+To specify the fontloader you wish to use, the configuration file
+(described in section \ref{sec:conf}) provides the option
+\inlinecode{fontloader}. Its value can be one of the identifiers
+\inlinecode{default} or \inlinecode{reference} or the name of a file
+somewhere in the search path of \LUATEX.
 
 TODO % it’s simple, though
 
+\endsubsection
+\endsection
+
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 \beginsection {Configuration Files}
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@@ -1277,6 +1297,7 @@ TODO % it’s simple, though
   manpage for \fileent{luaotfload.conf(5)}.
 \endnarrower
 
+\label{sec:conf}
 The runtime behavior of \identifier{Luaotfload} can be customized by
 means of a configuration file.
 % location
-- 
cgit v1.2.3


From 952d2c9b24c1b2e6f0f48df28981c1f2674137f4 Mon Sep 17 00:00:00 2001
From: Philipp Gesang <phg@phi-gamma.net>
Date: Tue, 10 Nov 2015 08:17:38 +0100
Subject: [doc] add directions for loading Context libs

---
 doc/luaotfload-main.tex | 24 +++++++++++-------------
 1 file changed, 11 insertions(+), 13 deletions(-)

(limited to 'doc/luaotfload-main.tex')

diff --git a/doc/luaotfload-main.tex b/doc/luaotfload-main.tex
index cc242e8..5ea70d8 100644
--- a/doc/luaotfload-main.tex
+++ b/doc/luaotfload-main.tex
@@ -1201,17 +1201,17 @@ grouped twofold as below:
   \endnormalitem
 \enddefinitions
 
-Note that if \identifier{luaotfload} cannot locate the
-merged file, it will load the individual \LUA libraries
-instead.
-%
-Their names remain the same as in \CONTEXT (without the
-\inlinecode {luaotfload}-prefix) since the initialization mirrors
-the sequence in \LUATEX-Fonts.
-%% FIXME this is a config option nowadays!
-%Thus if you prefer running bleeding edge code from the \CONTEXT beta,
-%all you have to do is remove \fileent{luaotfload-merged.lua} from the
-%search path.
+As an alternative to the merged file, \identifier {Luaotfload} may load
+individual unpackaged \LUA libraries that come with the source, or even
+use the files from Context directly.
+%
+Thus if you prefer running bleeding edge code from the \CONTEXT beta,
+all you have to do is to choose the \inlinecode {context} fontloader
+via the configuration file (see section \ref{sec:conf} below).
+%
+This will make \identifier {Luaotfload} locate the \CONTEXT source via
+\identifier{kpathsea} lookups and use those instead of the fontloader
+%% TODO allow choosing the context path
 
 Also, the merged file at some point loads the Adobe Glyph List from a
 \LUA table that is contained in \fileent{luaotfload-glyphlist.lua},
@@ -1283,8 +1283,6 @@ To specify the fontloader you wish to use, the configuration file
 \inlinecode{default} or \inlinecode{reference} or the name of a file
 somewhere in the search path of \LUATEX.
 
-TODO % it’s simple, though
-
 \endsubsection
 \endsection
 
-- 
cgit v1.2.3

