Merge pull request #291 from phi-gamma/master

pluggable fontloaders

6 files changed, 414 insertions, 650 deletions

diff --git a/doc/Makefile b/doc/Makefile
index ed340a4..0355a0e 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -1,6 +1,6 @@
 NAME		= luaotfload
 DOCPDF		= $(NAME).pdf
-DOCSRC		= $(NAME)-latex.tex
+DOCSRC		= $(NAME)-latex.tex $(NAME)-main.tex
 
 SCRIPTNAME	= luaotfload-tool
 TOOLMANSRC	= $(SCRIPTNAME).rst
@@ -47,7 +47,7 @@ $(DOTPDF): $(DOT)
 	@echo "creating file graph ($(DOTPDF))"
 	$(DO_GRAPHVIZ)
 
-.PHONY: clean mrproper
+.PHONY: clean mrproper graph doc all manuals
 
 clean:
 	@$(RM) -- *.log *.aux *.toc *.idx *.ind *.ilg *.out
diff --git a/doc/filegraph.dot b/doc/filegraph.dot
index e1a9937..af3c8ad 100644
--- a/doc/filegraph.dot
+++ b/doc/filegraph.dot
@@ -10,8 +10,8 @@ strict digraph luaotfload_files { //looks weird with circo ...
     size           = "21cm";
 
     rankdir        = LR;
-    ranksep  = 0.618;
-    nodesep  = 1.618;
+    ranksep        = 0.618;
+    nodesep        = 1.618;
 
     edge [
         arrowhead = onormal,
@@ -30,37 +30,38 @@ strict digraph luaotfload_files { //looks weird with circo ...
     fontdbutil  -> font_names   [label="--update",
                                  style=dashed]
 
-    luaotfload -> otfl_fonts_merged   [label="merged"]
-    luaotfload -> merged_lua_libs     [label="unmerged", style=solid]
-    luaotfload -> merged_luatex_fonts [label="unmerged", style=solid]
-    luaotfload -> merged_context_libs [label="unmerged", style=solid]
+    luaotfload -> merged_lua_libs     [style=solid]
+    luaotfload -> luaotfload_init     [label="main()",   style=solid]
+    luaotfload -> luaotfload_libs     [label="main()",   style=solid]
 
-    luaotfload -> luaotfload_libs
-    luaotfload -> otfl_blacklist_cnf
-
-    otfl_fonts_merged -> merged_lua_libs     [label="merged",
-                                              style=dotted,
-                                              lhead=cluster_merged]
-    otfl_fonts_merged -> merged_luatex_fonts [label="merged",
+    fontloader        -> merged_luatex_fonts [label="merged",
                                               style=dotted,
                                               lhead=cluster_merged]
-    otfl_fonts_merged -> merged_context_libs [label="merged",
+    fontloader        -> merged_context_libs [label="merged",
                                               style=dotted,
                                               lhead=cluster_merged]
 
+    luaotfload_init -> luaotfload_log        [label="init_early()", style=solid]
+    luaotfload_init -> luaotfload_basics_gen [label="init_early()", style=solid]
+    luaotfload_init -> fontloader            [label="init_main()",  style=solid]
+
+    luaotfload_init -> merged_luatex_fonts [label="unmerged", style=solid]
+    luaotfload_init -> merged_context_libs [label="unmerged", style=solid]
+
     merged_luatex_fonts -> font_age [label="luatex-fonts-enc.lua",
                                      ltail=cluster_merged]
 
     fontdbutil -> fontdbutil_diagnostics [label="--diagnose"]
-
     fontdbutil -> status [label="version information"]
 
-    fontdbutil_diagnostics -> status [constraint=no, label="hash files"]
+    luaotfload_package -> fontloader [label="merges", style=dashed]
 
     merged_luatex_fonts -> characters [label="luaotfload-auxiliary.lua",
                                        ltail=cluster_merged]
 
-    luaotfload_libs -> font_names [label="luaotfload-database.lua"]
+    luaotfload_libs -> font_names         [label="luaotfload-database.lua"]
+    luaotfload_libs -> otfl_blacklist_cnf [label="luaotfload-database.lua"]
+
 
     mkstatus    -> status     [label="generates from distribution files",
                                style=dashed]
@@ -71,13 +72,30 @@ strict digraph luaotfload_files { //looks weird with circo ...
     mkcharacters -> characters     [label="generates from Context’s char-def.lua",
                                     style=dashed]
 
+    fontdbutil_diagnostics -> status [label="hash files"]
+
+    mkimport -> merged_luatex_fonts [label="pulls", style=dashed, constraint=no];
+    mkimport -> merged_context_libs [label="pulls", style=dashed, constraint=no];
+
     subgraph { rank = same;
-               mkcharacters;
-               mkglyphlist;
-               mkstatus;
                fontdbutil;
                luaotfload }
 
+    subgraph cluster_scripts {
+        node [style=filled, color=white];
+        style     = "filled,rounded";
+        color     = "#44000011:#CCCCCC77";
+        //nodesep   = "3.0";
+        rank      = same;
+        label     = "Standalone scripts";
+        gradientangle=90;
+        mkcharacters;
+        mkglyphlist;
+        mkimport;
+        mktest;
+        mkstatus;
+    }
+
 /* ····································································
  * main files
  * ································································· */
@@ -90,6 +108,14 @@ strict digraph luaotfload_files { //looks weird with circo ...
                        style  = "filled,rounded",
                        penwidth=2]
 
+    luaotfload_package [label  = "luaotfload-package.lua",
+                        shape  = rect,
+                        width  = "3.2cm",
+                        height = "1.2cm",
+                        color  = "#01012222",
+                        style  = "filled,rounded",
+                        penwidth=2]
+
     fontdbutil_diagnostics [label  = "luaotfload-diagnostics.lua",
                             shape  = rect,
                             width  = "3.2cm",
@@ -98,27 +124,43 @@ strict digraph luaotfload_files { //looks weird with circo ...
                             style  = "filled,rounded",
                             penwidth=2]
 
+    mktest           [label  = "mktest",
+                       shape  = rect,
+                       width  = "3.2cm",
+                       height = "0.618cm",
+                       color  = "#FFFFFF66",
+                       style  = "filled,rounded",
+                       penwidth=2]
+
+    mkimport          [label  = "mkimport",
+                       shape  = rect,
+                       width  = "3.2cm",
+                       height = "0.618cm",
+                       color  = "#FFFFFF66",
+                       style  = "filled,rounded",
+                       penwidth=2]
+
     mkstatus          [label  = "mkstatus",
                        shape  = rect,
                        width  = "3.2cm",
-                       height = "1.2cm",
-                       color  = "#01012222",
+                       height = "0.618cm",
+                       color  = "#FFFFFF66",
                        style  = "filled,rounded",
                        penwidth=2]
 
     mkglyphlist       [label  = "mkglyphlist",
                        shape  = rect,
                        width  = "3.2cm",
-                       height = "1.2cm",
-                       color  = "#01012222",
+                       height = "0.618cm",
+                       color  = "#FFFFFF66",
                        style  = "filled,rounded",
                        penwidth=2]
 
     mkcharacters      [label  = "mkcharacters",
                        shape  = rect,
                        width  = "3.2cm",
-                       height = "1.2cm",
-                       color  = "#01012222",
+                       height = "0.618cm",
+                       color  = "#FFFFFF66",
                        style  = "filled,rounded",
                        penwidth=2]
 
@@ -138,13 +180,37 @@ strict digraph luaotfload_files { //looks weird with circo ...
      *                   style  = "filled,rounded",
      *                   penwidth=2]
      */
-    otfl_fonts_merged [label = "luaotfload-fontloader.lua",
-                       shape = rect,
-                       width  = "3.2cm",
-                       height = "1.2cm",
-                       color  = "#01012222",
-                       style  = "filled,rounded",
-                       penwidth=2]
+    luaotfload_init       [label = "luaotfload-init.lua",
+                           shape = rect,
+                           width  = "3.2cm",
+                           height = "1.2cm",
+                           color  = "#44440122",
+                           style  = "filled,rounded",
+                           penwidth=2]
+
+    luaotfload_log        [label = "luaotfload-log.lua",
+                           shape = rect,
+                           width  = "3.2cm",
+                           height = "1.2cm",
+                           color  = "#44440122",
+                           style  = "filled,rounded",
+                           penwidth=2]
+
+    luaotfload_basics_gen [label = "fontloader-basics-gen.lua",
+                           shape = rect,
+                           width  = "3.2cm",
+                           height = "1.2cm",
+                           color  = "#FFFFFF66",
+                           style  = "filled,rounded",
+                           penwidth=2]
+
+    fontloader            [label = "fontloader-reference.lua",
+                           shape = rect,
+                           width  = "3.2cm",
+                           height = "1.2cm",
+                           color  = "#FFFFFF66",
+                           style  = "filled,rounded",
+                           penwidth=2]
 
 /* ····································································
  * luaotfload files
@@ -193,15 +259,16 @@ strict digraph luaotfload_files { //looks weird with circo ...
     luaotfload_libs [
         shape      = box,
         style      = "filled,rounded",
-        color      = "grey90:goldenrod4",
+        color      = "grey90",
         fontsize   = 10,
         label      = <
             <table cellborder="0" bgcolor="#FFFFFFAA">
                 <th> <td colspan="2"> <font point-size="12" face="Iwona Italic">Luaotfload Libraries</font> </td> </th>
-                <tr> <td>luaotfload-auxiliary.lua</td>    <td>luaotfload-features.lua</td>    </tr>
-                <tr> <td>luaotfload-loaders.lua</td>      <td>luaotfload-color.lua</td>       </tr>
-                <tr> <td>luaotfload-log.lua</td>          <td>luaotfload-letterspace.lua</td> </tr>
-                <tr> <td>luaotfload-parsers.lua</td>      <td>luaotfload-database.lua</td>    </tr>
+                <tr> <td>luaotfload-auxiliary.lua</td>    <td>luaotfload-features.lua</td>      </tr>
+                <tr> <td>luaotfload-loaders.lua</td>      <td>luaotfload-colors.lua</td>        </tr>
+                <tr> <td>luaotfload-resolvers.lua</td>    <td>luaotfload-letterspace.lua</td>   </tr>
+                <tr> <td>luaotfload-parsers.lua</td>      <td>luaotfload-database.lua</td>      </tr>
+                <tr> <td>luaotfload-configuration.lua</td><td></td>                             </tr>
             </table>
         >,
     ]
@@ -213,28 +280,40 @@ strict digraph luaotfload_files { //looks weird with circo ...
    subgraph cluster_merged {
        node [style=filled, color=white];
        style     = "filled,rounded";
-       color     = "grey90:dodgerblue4";
+       color     = "#912CEE33";
        //nodesep   = "3.0";
        rank      = same;
        label     = "Merged Libraries";
        gradientangle=0;
-       merged_lua_libs;
        merged_luatex_fonts;
        merged_context_libs;
    }
 
-    otfl_fonts_merged -> merged_lua_libs
-    otfl_fonts_merged -> merged_luatex_fonts
-    otfl_fonts_merged -> merged_context_libs
+    fontloader -> merged_luatex_fonts
+    fontloader -> merged_context_libs
+
+   subgraph cluster_fontloader {
+       node [style=filled, color=white];
+       style     = "filled,rounded";
+       color     = "bisque";
+       //nodesep   = "3.0";
+       rank      = same;
+       label     = "Fontloader";
+       gradientangle=0;
+       luaotfload_basics_gen;
+       fontloader;
+   }
 
     merged_lua_libs [
         shape      = box,
         style      = "filled,rounded",
-        color      = "#FFFFFFAA",
+        color      = "#CCCC1166",
+        fontsize   = 10,
         fontsize   = 10,
         label      = <
             <table border="0">
-                <th> <td colspan="3"> <font point-size="12" face="Iwona Italic">Lua Libraries from Context</font> </td> </th>
+                <th> <td colspan="3"> <font point-size="12" face="Iwona Italic">
+                        Lualibs &ndash; Lua Libraries from Context</font> </td> </th>
                 <tr> <td>l-lua.lua</td>     <td>l-lpeg.lua</td>    <td>l-function.lua</td>  </tr>
                 <tr> <td>l-string.lua</td>  <td>l-table.lua</td>   <td>l-io.lua</td>        </tr>
                 <tr> <td>l-file.lua</td>    <td>l-boolean.lua</td> <td>l-math.lua</td>      </tr>
@@ -251,17 +330,13 @@ strict digraph luaotfload_files { //looks weird with circo ...
         label      = <
             <table border="0">
                 <th> <td colspan="2"> <font point-size="12" face="Iwona Italic">Font Loader (LuaTeX-Fonts)</font> </td> </th>
-                <tr> <td>luatex-basics-gen.lua</td> <td>luatex-basics-nod.lua</td> </tr>
+                <tr> <td>luatex-fonts-cbk.lua</td>  <td>luatex-basics-nod.lua</td> </tr>
                 <tr> <td>luatex-fonts-enc.lua</td>  <td>luatex-fonts-syn.lua</td>  </tr>
                 <tr> <td>luatex-font-tfm.lua</td>   <td>luatex-font-afm.lua</td>   </tr>
                 <tr> <td>luatex-font-afk.lua</td>   <td>luatex-fonts-tfm.lua</td>  </tr>
                 <tr> <td>luatex-fonts-chr.lua</td>  <td>luatex-fonts-lua.lua</td>  </tr>
                 <tr> <td>luatex-fonts-inj.lua</td>  <td>luatex-fonts-otn.lua</td>  </tr>
                 <tr> <td>luatex-fonts-def.lua</td>  <td>luatex-fonts-ext.lua</td>  </tr>
-                <tr> <td>luatex-fonts-cbk.lua</td>                                 </tr>
- 
- 
- 
             </table>
         >,
     ]
diff --git a/doc/luaotfload-context.tex b/doc/luaotfload-context.tex
deleted file mode 100644
index 6c8d4b2..0000000
--- a/doc/luaotfload-context.tex
+++ /dev/null
@@ -1,485 +0,0 @@
-% macros=mkvi
-%% Copyright (C) 2009-2014
-%%
-%%      by  Elie Roux      <elie.roux@telecom-bretagne.eu>
-%%      and Khaled Hosny   <khaledhosny@eglug.org>
-%%      and Philipp Gesang <philipp.gesang@alumni.uni-heidelberg.de>
-%%
-%% This file is part of Luaotfload.
-%%
-%%      Home:      https://github.com/lualatex/luaotfload
-%%      Support:   <lualatex-dev@tug.org>.
-%%
-%% Luaotfload is under the GPL v2.0 (exactly) license.
-%%
-%% ----------------------------------------------------------------------------
-%%
-%% Luaotfload is free software; you can redistribute it and/or
-%% modify it under the terms of the GNU General Public License
-%% as published by the Free Software Foundation; version 2
-%% of the License.
-%%
-%% Luaotfload is distributed in the hope that it will be useful,
-%% but WITHOUT ANY WARRANTY; without even the implied warranty of
-%% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
-%% GNU General Public License for more details.
-%%
-%% You should have received a copy of the GNU General Public License
-%% along with Luaotfload; if not, see <http://www.gnu.org/licenses/>.
-%%
-%% ----------------------------------------------------------------------------
-%%
-
-\unprotect
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-%% layout and paper
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-
-\setuppapersize [A5] [A5] %% 148×210
-
-\definelayout [mainlayout] [
-  backspace=15mm, %% 133
-  textwidth=103mm,
-  topspace=15mm,
-]
-
-\setuplayout [mainlayout]
-
-\setuppagenumbering [location=,alternative=doublesided]
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-%% colors
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-
-\usecolors [x11]
-\definecolor [primarycolor]   [dodgerblue4]
-\definecolor [secondarycolor] [goldenrod4]
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-%% interaction
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-
-\setupinteraction [
-  state=start,
-  page=no,
-  click=yes,
-  style=italic,
-  color=primarycolor,
-  contrastcolor=secondarycolor,
-  title={The Luaotfload package},
-  subtitle={OpenType layout system for Plain TeX and LaTeX},
-  author={Elie Roux & Khaled Hosny & Philipp Gesang},
-  keywords={luatex, lualatex, unicode, opentype},
-]
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-%% fonts
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-
-\usemodule [simplefonts]
-
-\definefontfeature [default]   [default] [mode=base,liga=yes,dlig=yes,tlig=yes,onum=yes]
-\definefontfeature [monospace]           [liga=no,tlig=no,onum=no]
-
-\definefontfamily [mainface] [serif] [Linux Libertine O] [features=default]
-%definefontfamily [mainface] [serif] [Liberation Serif] [feature=default]
-%definefontfamily [mainface] [sans]  [Iwona]             [feature=default]
-\definefontfamily [mainface] [sans]  [Iwona Medium] [
-  feature=default,
-  it=file:IwonaMedium-Italic.otf,
-  tf=file:IwonaMedium-Regular.otf,
-  bf=file:Iwona-Bold.otf,
-  bi=file:Iwona-BoldItalic.otf,
-]
-%definefontfamily [mainface] [sans]  [DejaVu Sans]       [feature=default]
-\definefontfamily [mainface] [mono]  [Liberation Mono]   [scale=0.85,features=monospace]
-
-\setupbodyfont [mainface,10pt]
-
-\def \LUA      {Lua}
-\def \LUALATEX {Lua\LATEX}
-\def \OpenType {\identifier{Open\kern-.25ex Type}}
-
-\definealternativestyle [emphasis:texmacro]        [\ss \it \letterbackslash]       [\ss \it \letterbackslash]
-\definealternativestyle [emphasis:identifier]      [\ss]                            [\ss]
-\definealternativestyle [emphasis:normal]          [\sl]                            [\sl]
-\definealternativestyle [emphasis:abbrev]          [{\feature [+][smallcaps]}]      [{\feature [+][smallcaps]}]
-\definealternativestyle [emphasis:Largefont]       [{\switchtobodyfont[14pt]}]      [{\switchtobodyfont[14pt]}]
-\definealternativestyle [emphasis:smallcaps]       [{\feature [+][smallcaps]}]      [{\feature [+][smallcaps]}]
-%definealternativestyle [emphasis:nonproportional] [\mono]                          [\mono]
-\definealternativestyle [emphasis:nonproportional] [\tt]                            [\tt]
-\definealternativestyle [head:section]             [{\roman\feature[+][smallcaps]}] [{\roman\feature[+][smallcaps]}]
-\definealternativestyle [head:subsection]          [{\roman\feature[+][smallcaps]}] [{\roman\feature[+][smallcaps]}]
-\definealternativestyle [head:subsubsection]       [{\roman\feature[+][smallcaps]}] [{\roman\feature[+][smallcaps]}]
-\definealternativestyle [typing:luafunction]       [\italic]                        [\italic]
-\definealternativestyle [typing:fileent]           [\tt]                            [\tt]
-
-\definehighlight        [texmacro] [style=emphasis:texmacro]        %% cs
-\definehighlight      [identifier] [style=emphasis:identifier]      %% names
-\definehighlight          [abbrev] [style=emphasis:abbrev]          %% acronyms
-\definehighlight        [emphasis] [style=emphasis:normal]          %% level 1 emph
-
-\definehighlight       [Largefont] [style=emphasis:Largefont]       %% font size
-\definehighlight       [smallcaps] [style=emphasis:smallcaps]       %% font feature
-\definehighlight [nonproportional] [style=emphasis:nonproportional] %% font switch
-
-\definetype [fileent]     [style=typing:fileent]
-\definetype [luafunction] [style=typing:luafunction]
-\setuptyping [style=ttx]
-
-\definebodyfontenvironment  [8pt]
-\definebodyfontenvironment [10pt]
-\definebodyfontenvironment [12pt]
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-%% headings
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-
-\setuphead [section]       [style=head:section,      alternative=inmargin]
-\setuphead [subsection]    [style=head:subsection,   alternative=inmargin]
-\setuphead [subsubsection] [style=head:subsubsection,alternative=inmargin]
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-%% running headers
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-
-\setupheadertexts
-  [{\tfx \getmarking[section]}] [pagenumber]
-  [pagenumber] [{\tfx \fileent{Luaotfload} Manual}]
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-%% structurals
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-
-%% section
-\def \beginsection {\dosingleempty \section_begin_indeed}
-
-\def \section_begin_indeed [#ref]#title{%
-  \iffirstargument
-    \startsection [reference=#ref,title=#title]%
-  \else
-    \startsection [title=#title]%
-  \fi
-}
-
-\let \endsection \stopsection
-
-%% subsection
-\def \beginsubsection {\dosingleempty \section_begin_indeed}
-
-\def \subsection_begin_indeed [#ref]#title{%
-  \iffirstargument
-    \startsubsection [reference=#ref,title=#title]%
-  \else
-    \startsubsection [title=#title]%
-  \fi
-}
-
-\let \endsubsection \stopsection
-
-%% subsubsection
-\def \beginsubsubsection {\dosingleempty \section_begin_indeed}
-
-\def \subsubsection_begin_indeed [#ref]#title{%
-  \iffirstargument
-    \startsubsubsection [reference=#ref,title=#title]%
-  \else
-    \startsubsubsection [title=#title]%
-  \fi
-}
-
-\let \endsubsubsection \stopsection
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-%% inline verbatim
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-
-%% Context offers both \type{…} and \type<<…>>, but not an unbalanced
-%% one that we could map directly onto Latex’s \verb|…|.
-
-\definetype [inlinecode_indeed] [style=emphasis:nonproportional]
-
-%% The listings macros don’t seem to handle backslashes and braces
-%% well. We emulate this behavior by handling the escaping in Lua.
-
-\startluacode
-  local lpeg           = require "lpeg"
-  local Cs, P, S       = lpeg.Cs, lpeg.P, lpeg.S
-  local lpegmatch      = lpeg.match
-  local unescape_char  = S[[\letterbackslash\letterleftbrace\letterrightbrace]]
-  local backslash      = P[[\letterbackslash]]
-  local unescape       = Cs (((backslash / "" * unescape_char) + 1)^0)
-  commands.unescape_things = function (str)
-    context.type (lpegmatch (unescape, str))
-  end
-\stopluacode
-
-\unexpanded \def \inlinecode #content{%
-  \ctxcommand {unescape_things \!!bs \detokenize {#content}\!!es}%
-}
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-%% codelistings
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-%% Now *that’s* what I call easy.
-
-\unexpanded \def \beginlisting {%
-  \grabbufferdatadirect{listing}{beginlisting}{endlisting}%
-}
-
-\unexpanded \def \endlisting {\typebuffer [listing]}
-
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-%% enumerations and lists
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-
-\definedescription [descriptionitem] [
-  align=right,
-  alternative=hanging,
-  width=2em,
-]
-
-\def \begindescriptions {%
-  \begingroup
-    \def \beginnormalitem ##1\endnormalitem{%
-      \startitem##1\stopitem
-    }
-    \let \endnormalitem   \relax
-    \let \beginaltitem    \startdescriptionitem
-    \let \endaltitem      \stopdescriptionitem
-}
-
-\let \enddescriptions \endgroup
-
-
-\definedescription [definitionitem] [
-  align=right,
-  alternative=hanging,
-]
-
-\def \begindefinitions {%
-  \begingroup
-    \def \beginnormalitem ##1\endnormalitem{%
-      \startitem##1\stopitem
-    }
-    \let \endnormalitem   \relax
-    \let \beginaltitem    \startdefinitionitem
-    \let \endaltitem      \stopdefinitionitem
-}
-
-\let \enddefinitions \endgroup
-
-
-\definedescription [filelistitem] [
-  align=normal,
-  alternative=hanging,
-  headstyle=typing:fileent,
-  width=4cm,
-]
-
-\def \beginfilelist {%
-  \begingroup
-    \def \beginnormalitem ##1\endnormalitem{%
-      \startitem##1\stopitem
-    }
-    \let \endnormalitem   \relax
-    \let \beginaltitem    \startfilelistitem
-    \let \endaltitem      \stopfilelistitem
-}
-
-\let \endfilelist \endgroup
-
-\definedescription [functionlistitem] [
-  align=normal,
-  alternative=hanging,
-  headstyle=typing:luafunction,
-  width=4cm,
-]
-
-\def \beginfunctionlist {%
-  \begingroup
-    \def \beginnormalitem ##1\endnormalitem{%
-      \startitem##1\stopitem
-    }
-    \let \endnormalitem   \relax
-    \let \beginaltitem    \startfunctionlistitem
-    \let \endaltitem      \stopfunctionlistitem
-}
-
-\let \endfunctionlist \endgroup
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-%% columns
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-
-\def \begindoublecolumns {\startcolumns [2]}
-\let \enddoublecolumns   \stopcolumns
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-%% alignment
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-
-\setupnarrower [before={\blank[line]},after={\blank[line]}]
-\let \beginnarrower \startnarrower
-\let \endnarrower   \stopnarrower
-
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-%% special elements
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-
-\definefont [lmromantenregular] [file:lmroman10-regular.otf*default]
-
-\def \meta #1{%
-  {\lmromantenregular<}%
-  {\italic #1}%
-  {\lmromantenregular>}%
-}
-
-\def \beginabstractcontent {%
-  \grabbufferdatadirect{abstractcontent}{beginabstractcontent}{endabstractcontent}%
-}
-
-\let \endabstractcontent \relax
-
-\def \setdocumenttitle   #1{\setvalue  {document_title}{#1}}
-\def \setdocumentdate    #1{\setvalue   {document_date}{#1}}
-\def \setdocumentauthor  #1{\setvalue {document_author}{#1}}
-
-\let \typesetdocumenttitle \relax
-\let \beginfrontmatter \relax
-
-\def \endfrontmatter {
-  \startstandardmakeup
-    \vfill
-    \strut \hfill
-      \startframed [frame=off,align=middle,width=.5\textwidth]
-        \Largefont{\getvalue {document_title}}
-      \stopframed
-    \hfill \strut \par
-
-    \blank [2*big]
-
-    \strut \hfill
-      \startframed [frame=off,align=middle,width=.65\textwidth]
-        \setuplocalinterlinespace [18pt]
-        \getvalue {document_author}
-      \stopframed
-    \hfill \strut \par
-
-    \vfill
-    \strut \hfill \getvalue {document_date} \hfill \strut
-    \blank [2*big]
-
-    \strut \hfill
-    \startframed [width=.7\textwidth,align=normal,style=tfx,frame=off]%
-      \getbuffer [abstractcontent]
-    \stopframed
-    \hfill \strut 
-  \stopstandardmakeup
-}
-
-\let \typesetcontent \completecontent
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-%% floats
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-%% XXX we can improve on this part later
-
-\usemodule [vim]
-\definevimtyping [bnf] [syntax=bnf]
-\definefloat [syntax] [figure]
-
-\def \beginsyntaxfloat #reference#caption{%
-  \begingroup
-    \edef \currentreference {#reference}%
-    \edef \currentcaption   {#caption}%
-    \grabbufferdatadirect{rawsyntaxdata}{beginsyntaxfloat}{endsyntaxfloat}%
-}
-
-\def \endsyntaxfloat {%
-    \savebuffer [rawsyntaxdata] [rawsyntaxdata]
-    \startplacesyntax [
-      reference=\currentreference,
-      title={\currentcaption},
-    ]
-      %% there’s no \typebnfbuffer in t-vim :(
-      \typebnffile {\jobname-rawsyntaxdata.tmp}
-    \stopplacesyntax
-  \endgroup%
-}
-
-\def \figurefloat #reference#caption#file{%
-  \startplacefigure [
-    reference=#reference,
-    title={#caption},
-  ]
-    \externalfigure [#file] [width=\textwidth]
-  \stopplacefigure
-}
-
-
-\def \tablefloat #reference#caption#content{%
-  \startplacetable [
-    reference=#reference,
-    title={#caption},
-  ]
-    #content
-  \stopplacetable
-}
-
-
-%% tables
-
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-%% tables
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-
-\setupxtable [frame=off,option=stretch,textwidth=\dimexpr(\textwidth/2)]
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-%% hyperlinks and references
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-
-\unexpanded \def \hyperlink{%
-  \dosingleempty \hyperlink_indeed%
-}
-
-\def \hyperlink_indeed [#text]#url{%
-  \iffirstargument
-    \useURL [temporary_url] [#url] [] [#text]%
-  \else
-    \useURL [temporary_url] [#url]%
-  \fi%
-  \from [temporary_url]%
-}
-
-
-\def \email #1{\goto{#1}[url(mailto:#1)]}
-
-\def \label #tag{\reference [#tag]\empty}
-\def \pageref #tag{\at{page}{#tag}}
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-%% escaped characters
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-
-\let \charpercent   \letterpercent
-\let \charbackslash \letterbackslash
-\let \chartilde     \lettertilde
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-%% main
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-
-\protect
-
-\newif \ifcontextmkiv \contextmkivtrue
-
-\starttext
-  \input luaotfload-main.tex
-\stoptext
-
diff --git a/doc/luaotfload-latex.tex b/doc/luaotfload-latex.tex
index 34c494d..e3541c5 100644
--- a/doc/luaotfload-latex.tex
+++ b/doc/luaotfload-latex.tex
@@ -1,4 +1,4 @@
-\luatexsuppresslongerror1%% sigh ...
+\suppresslongerror1%% sigh ...
 %% Copyright (C) 2009-2014
 %%
 %%      by  Elie Roux      <elie.roux@telecom-bretagne.eu>
@@ -129,7 +129,7 @@
 
 \definehighlight         [fileent][\ttfamily\restoreunderscore]         %% files, dirs
 \definehighlight        [texmacro][\sffamily\itshape\textbackslash]     %% cs
-\definehighlight     [luafunction][\sffamily\itshape\restoreunderscore] %% lua identifiers
+\definehighlight        [luaident][\sffamily\itshape\restoreunderscore] %% lua identifiers
 \definehighlight      [identifier][\sffamily]                           %% names
 \definehighlight          [abbrev][\rmfamily\scshape]                   %% acronyms
 \definehighlight        [emphasis][\rmfamily\slshape]                   %% level 1 emph
@@ -220,9 +220,9 @@
 \newcount \othercatcode  \othercatcode 12
 \newcount \activecatcode \othercatcode 13
 
-\newluatexcatcodetable \vrbcatcodes
-\setluatexcatcodetable \vrbcatcodes {%
-  \luatexcatcodetable \CatcodeTableIniTeX
+\newcatcodetable \vrbcatcodes
+\setcatcodetable \vrbcatcodes {%
+  \catcodetable \CatcodeTableIniTeX
   \catcode  9 \othercatcode %% \tabasciicode
   \catcode 13 \othercatcode %% \endoflineasciicode
   \catcode 12 \othercatcode %% \formfeedasciicode
@@ -230,48 +230,85 @@
   \catcode 32 \othercatcode %% \spaceasciicode
 }
 
-\newluatexcatcodetable \literalcatcodes
-\setluatexcatcodetable \literalcatcodes {%
-  \luatexcatcodetable \CatcodeTableString
+\directlua {
+  document = document or { }
+  document.vrbcatcodesidx = tonumber (\the \vrbcatcodes)
+}
+
+\newcatcodetable \literalcatcodes
+\setcatcodetable \literalcatcodes {%
+  \catcodetable \CatcodeTableString
   \catcode 32 \activecatcode %% \spaceasciicode
 }
 
+\def \listingsurroundskip {\vskip \baselineskip}
+
 \def \beginlisting {%
+  \noindent
   \begingroup
-    \luatexcatcodetable \vrbcatcodes
+    \catcodetable \vrbcatcodes
     \beginlistingindeed%
 }
 
 \directlua {
-  local texprint   = tex.print
-  local stringsub  = string.sub
-  local backslash  = string.byte (0x5c)
-  document         = document or { }
+  local texsprint       = tex.sprint
+  local stringis_empty  = string.is_empty
+  local stringsub       = string.sub
+  local stringgsub      = string.gsub
+  %local backslash       = unicode.utf8.char (0x200c)
+  local backslash       = unicode.utf8.char (0x5c)
+  local escaped         = [[\string\string\string\]]
   document.printlines = function (buffer)
-    for _, line in next, string.explode (buffer, "\noexpand\n") do
-      if stringsub (line, 1, 1) == " " then
-        line = backslash .. line
+    local lines = string.explode (buffer, "\noexpand\n")
+    print ""
+    for i, line in next, lines do
+      local line = stringgsub (line, backslash, escaped)
+      if stringis_empty (line) then
+        print (i, "listing: <empty line />")
+        texsprint [[\string\listingpar]]
+      else
+        local line = [[\string\beginlistingline]]
+                  .. line
+                  .. [[\string\endlistingline]]
+                  .. [[\string\listingpar]]
+        print (i, "listing: «" .. line .. "»")
+        texsprint (document.vrbcatcodesidx, line)
       end
-      texprint (-1, line)
-      texprint (-1, "")
     end
   end
 }
 
+\def \listingpar {\endgraf}
+
+\let \endlistingline \relax
+\let \endlisting     \relax
+
+\protected \def \beginlistingline{%
+  \leavevmode
+  \begingroup
+    \beginlistinglineindeed%
+}
+
+\def \beginlistinglineindeed #1\endlistingline{%
+  \endgroup
+  \hbox{%
+    \addfontfeature {RawFeature=-tlig;-liga}%% So one can’t just turn them all off at once using the ``Ligatures`` key?
+    \obeyspaces
+    #1}%
+}
+
 \def \beginlistingindeed#1\endlisting{%
   \endgroup
   \begingroup
+    \endgraf
+    \listingsurroundskip
     \ttfamily
     \small
-    \begin {quote}
-      \bgroup
-        \addfontfeature {RawFeature=-tlig;-liga}%% So one can’t just turn them all off at once using the ``Ligatures`` key?
-        \luatexcatcodetable \literalcatcodes
-        \obeyspaces
-        \obeylines
-        \directlua{document.printlines ([==[\detokenize {#1}]==])}
-      \egroup
-    \end {quote}
+    \parindent = 0em
+    \leftskip = 2em
+    \hangindent = 2em
+    \directlua{document.printlines ([==[\detokenize {#1}]==])}%
+    \listingsurroundskip
   \endgroup
 }
 
@@ -301,7 +338,7 @@
 \definelist  [descriptions]{\normalitem {\textbf \first}\hfill\break}
 \definelist   [definitions]{\normalitem {\fileent {\first}}}
 \definelist      [filelist]{\normalitem {\fileent {\first}}\space--\hskip 1em}
-\definelist  [functionlist]{\normalitem {\luafunction {\first}}\hfill\break}
+\definelist  [functionlist]{\normalitem {\luaident {\first}}\hfill\break}
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 %% columns
diff --git a/doc/luaotfload-main.tex b/doc/luaotfload-main.tex
index c01beba..5ea70d8 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}}
@@ -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
@@ -233,7 +238,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 +669,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 +678,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
@@ -686,7 +691,7 @@ obviously, \inlinecode{random}.
          user.
   \endaltitem
 
-\ifcontextmkiv
+\iffalse
   \startbuffer [printvectors]
   \directlua{inspect(fonts.protrusions.setups.default)
              inspect(fonts.expansions.setups.default)}
@@ -706,7 +711,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 +768,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 +910,7 @@ directories.
 \tablefloat {table-searchpaths}
   {List of paths searched for each supported operating system.}
   {%
-    \unless \ifcontextmkiv
+    \unless \iffalse
       \begincentered
         \begintabulate [lp{.5\textwidth}]
           \beginrow
@@ -1056,27 +1061,28 @@ An example with explicit paths:
 \endsection
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\beginsection {Files from \CONTEXT and \LUATEX-Fonts}
+\beginsection {The Fontloader}
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
-\identifier{luaotfload} relies on code originally written by Hans
-Hagen for the \hyperlink[\identifier{\CONTEXT}]{http://wiki.contextgarden.net}
+\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}
 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
-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
@@ -1087,19 +1093,23 @@ 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.
 %
 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 +1117,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.
-
-\begindefinitions
-  \beginnormalitem
-    \emphasis{\LUA utility libraries}, a subset
-    of what is provided by the \identifier{lualibs}
-    package.
+%
+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} 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.
+  This conceptual glitch has since been amended by tightening the
+  coupling with the excellent \CONTEXT\ toolchain.
+}
 
-    \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
+\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:
 
+\begindefinitions
   \beginnormalitem
     The \emphasis{font loader} itself.
     These files have been written for
@@ -1139,7 +1164,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
@@ -1177,16 +1201,17 @@ categories.
   \endnormalitem
 \enddefinitions
 
-Note that if \identifier{luaotfload} cannot locate the
-merged file, it will load the individual \LUA libraries
-instead.
+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).
 %
-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.
+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},
@@ -1194,8 +1219,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.
 
@@ -1209,7 +1235,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 +1251,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
@@ -1239,13 +1271,93 @@ files not contained in the merge. Some of these have no equivalent in
   {Schematic of the files in \identifier{Luaotfload}}
   {filegraph.pdf}
 
+\endsubsection
+
+\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.
+
+\endsubsection
 \endsection
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\beginsection {Configuration Files}
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\beginnarrower
+  \emphasis{Caution}: For the authoritative documentation, consult the
+  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
+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
+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:
+
+\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).
 %
@@ -1254,7 +1366,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 +1387,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 +1479,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 +1489,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 +1528,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 +1639,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 +1649,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:
 
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.