Merge pull request #228 from phi-gamma/master

merge version 2.5 (texlive2014) into master

8 files changed, 3571 insertions, 0 deletions

diff --git a/doc/Makefile b/doc/Makefile
new file mode 100644
index 0000000..ed340a4
--- /dev/null
+++ b/doc/Makefile
@@ -0,0 +1,58 @@
+NAME		= luaotfload
+DOCPDF		= $(NAME).pdf
+DOCSRC		= $(NAME)-latex.tex
+
+SCRIPTNAME	= luaotfload-tool
+TOOLMANSRC	= $(SCRIPTNAME).rst
+TOOLMAN		= $(SCRIPTNAME).1
+
+CONFNAME	= luaotfload.conf
+CONFMANSRC	= $(CONFNAME).rst
+CONFMAN		= $(CONFNAME).5
+
+MANPAGES	= $(TOOLMAN) $(CONFMAN)
+
+GRAPH		= filegraph
+DOTPDF		= $(GRAPH).pdf
+DOT		= $(GRAPH).dot
+
+DOCS		= $(DOTPDF) $(DOCPDF) $(MANPAGES)
+
+DO_LATEXMK	= @latexmk -e '$$max_repeat = 5' -pdf -lualatex -silent $< >/dev/null
+# latexmk does only one run on my machine, so we’re not going to rely on it
+DO_LATEX	= @lualatex -interaction=batchmode $< >/dev/null
+DO_GRAPHVIZ	= @dot -Tpdf -o $@ $< > /dev/null
+DO_DOCUTILS	= @rst2man $< >$@ 2>/dev/null
+
+doc: graph $(DOCPDF)
+all: manuals doc
+graph: $(DOTPDF)
+manuals: $(TOOLMAN) $(CONFMAN)
+
+$(DOCPDF): $(DOCSRC)
+	@echo "creating PDF documentation ($@)"
+	$(DO_LATEX)
+	$(DO_LATEX)
+	mv -f -- $(<:tex=pdf) $@
+
+$(TOOLMAN): $(TOOLMANSRC)
+	@echo "creating man page ($(TOOLMAN))"
+	$(DO_DOCUTILS)
+
+$(CONFMAN): $(CONFMANSRC)
+	@echo "creating man page ($(CONFMAN))"
+	$(DO_DOCUTILS)
+
+$(DOTPDF): $(DOT)
+	@echo "creating file graph ($(DOTPDF))"
+	$(DO_GRAPHVIZ)
+
+.PHONY: clean mrproper
+
+clean:
+	@$(RM) -- *.log *.aux *.toc *.idx *.ind *.ilg *.out
+
+mrproper: clean
+	@$(RM) -- $(DOCS)
+
+# vim:noexpandtab:tabstop=8:shiftwidth=2
diff --git a/doc/filegraph.dot b/doc/filegraph.dot
new file mode 100644
index 0000000..47db9ea
--- /dev/null
+++ b/doc/filegraph.dot
@@ -0,0 +1,287 @@
+strict digraph luaotfload_files { //looks weird with circo ...
+    compound       = true;
+
+//  label          = "Schematic of the files included in Luaotfload.";
+//  labelloc       = "b";
+
+    fontsize       = "14.4";
+    labelfontname  = "Iwona Medium Regular";
+    fontname       = "Iwona Light Regular";
+    size           = "21cm";
+
+    rankdir        = LR;
+    ranksep  = 0.618;
+    nodesep  = 1.618;
+
+    edge [
+        arrowhead = onormal,
+        fontname  = "Iwona Cond Regular",
+        penwidth  = 1.0,
+    ];
+    node [
+        //penwidth = 0.7,
+        fontname = "Liberation Mono",
+        fontsize = 12,
+    ];
+
+/* ····································································
+ * file structure
+ * ································································· */
+    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 -> 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",
+                                              style=dotted,
+                                              lhead=cluster_merged]
+    otfl_fonts_merged -> merged_context_libs [label="merged",
+                                              style=dotted,
+                                              lhead=cluster_merged]
+
+    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"]
+
+    merged_luatex_fonts -> characters [label="luaotfload-auxiliary.lua",
+                                       ltail=cluster_merged]
+
+    luaotfload_libs -> font_names [label="luaotfload-database.lua"]
+
+    mkstatus    -> status     [label="generates from distribution files",
+                               style=dashed]
+
+    mkglyphlist -> font_age     [label="generates from glyphlist.txt",
+                                 style=dashed]
+
+    mkcharacters -> characters     [label="generates from Context’s char-def.lua",
+                                    style=dashed]
+
+    subgraph { rank = same;
+               mkcharacters;
+               mkglyphlist;
+               mkstatus;
+               fontdbutil;
+               luaotfload }
+
+/* ····································································
+ * main files
+ * ································································· */
+
+    fontdbutil        [label  = "luaotfload-tool.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",
+                            height = "1.2cm",
+                            color  = "#01012222",
+                            style  = "filled,rounded",
+                            penwidth=2]
+
+    mkstatus          [label  = "mkstatus",
+                       shape  = rect,
+                       width  = "3.2cm",
+                       height = "1.2cm",
+                       color  = "#01012222",
+                       style  = "filled,rounded",
+                       penwidth=2]
+
+    mkglyphlist       [label  = "mkglyphlist",
+                       shape  = rect,
+                       width  = "3.2cm",
+                       height = "1.2cm",
+                       color  = "#01012222",
+                       style  = "filled,rounded",
+                       penwidth=2]
+
+    mkcharacters      [label  = "mkcharacters",
+                       shape  = rect,
+                       width  = "3.2cm",
+                       height = "1.2cm",
+                       color  = "#01012222",
+                       style  = "filled,rounded",
+                       penwidth=2]
+
+    luaotfload        [label  = "luaotfload-main.lua",
+                       shape  = rect,
+                       width  = "3.2cm",
+                       height = "1.2cm",
+                       color  = "#01012222",
+                       style  = "filled,rounded",
+                       penwidth=2]
+    /*
+     *otfl_fonts        [label = "luaotfload-fonts.lua",
+     *                   shape = rect,
+     *                   width  = "3.2cm",
+     *                   height = "1.2cm",
+     *                   color  = "#01012222",
+     *                   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 files
+ * ································································· */
+
+    characters [style      = "filled,dashed",
+                shape      = rect,
+                width      = "3.2cm",
+                fillcolor  = "#01012222",
+                color      = grey40,
+                style      = "filled,dotted,rounded",
+                label      = "luaotfload-characters.lua"]
+
+    font_age [style      = "filled,dashed",
+              shape      = rect,
+              width      = "3.2cm",
+              fillcolor  = "#01012222",
+              color      = grey40,
+              style      = "filled,dotted,rounded",
+              label      = "luaotfload-glyphlist.lua"]
+
+    font_names [style      = "filled,dashed",
+                shape      = rect,
+                width      = "3.2cm",
+                fillcolor  = "#01012222",
+                color      = grey40,
+                style      = "filled,dotted,rounded",
+                label      = "luaotfload-names.lua.gz\nluaotfload-names.luc"]
+
+    status [style      = "filled,dashed",
+            shape      = rect,
+            width      = "3.2cm",
+            fillcolor  = "#01012222",
+            color      = grey40,
+            style      = "filled,dotted,rounded",
+            label      = "luaotfload-status.lua"]
+
+    otfl_blacklist_cnf [style      = "filled,dashed",
+                        shape      = rect,
+                        width      = "3.2cm",
+                        fillcolor  = "#01012222",
+                        color      = grey40,
+                        style      = "filled,dotted,rounded",
+                        label      = "luaotfload-blacklist.cnf"]
+
+    luaotfload_libs [
+        shape      = box,
+        style      = "filled,rounded",
+        color      = "grey90:goldenrod4",
+        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-override.lua</td>     <td>luaotfload-loaders.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-color.lua</td>                                            </tr>
+            </table>
+        >,
+    ]
+
+/* ····································································
+ * merged files
+ * ································································· */
+
+   subgraph cluster_merged {
+       node [style=filled, color=white];
+       style     = "filled,rounded";
+       color     = "grey90:dodgerblue4";
+       //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
+
+    merged_lua_libs [
+        shape      = box,
+        style      = "filled,rounded",
+        color      = "#FFFFFFAA",
+        fontsize   = 10,
+        label      = <
+            <table border="0">
+                <th> <td colspan="3"> <font point-size="12" face="Iwona Italic">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>
+                <tr> <td>util-str.lua</td>                                                  </tr>
+            </table>
+        >,
+    ]
+
+    merged_luatex_fonts [
+        shape      = box,
+        style      = "filled,rounded",
+        color      = "#FFFFFFAA",
+        fontsize   = 10,
+        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-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>
+        >,
+    ]
+
+    merged_context_libs [
+        shape      = box,
+        style      = "filled,rounded",
+        color      = "#FFFFFFAA",
+        fontsize   = 10,
+        label      = <
+            <table border="0">
+                <th> <td colspan="3"> <font point-size="12" face="Iwona Italic"> Font and Node Libraries from Context </font> </td> </th>
+                <tr> <td>data-con.lua</td> <td>font-ini.lua</td> <td>font-con.lua</td> </tr>
+                <tr> <td>font-cid.lua</td> <td>font-map.lua</td> <td>font-oti.lua</td> </tr>
+                <tr> <td>font-otf.lua</td> <td>font-otb.lua</td> <td>font-ota.lua</td> </tr>
+                <tr> <td>font-def.lua</td> </tr>
+            </table>
+        >,
+    ]
+}
+
+// vim:ft=dot:sw=4:ts=4:expandtab
diff --git a/doc/luaotfload-context.tex b/doc/luaotfload-context.tex
new file mode 100644
index 0000000..6c8d4b2
--- /dev/null
+++ b/doc/luaotfload-context.tex
@@ -0,0 +1,485 @@
+% 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
new file mode 100644
index 0000000..34c494d
--- /dev/null
+++ b/doc/luaotfload-latex.tex
@@ -0,0 +1,448 @@
+\luatexsuppresslongerror1%% sigh ...
+%% 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/>.
+%%
+%% ----------------------------------------------------------------------------
+%%
+
+\documentclass{ltxdoc}
+
+\makeatletter
+
+\usepackage {metalogo,multicol,fancyvrb,xspace}
+\usepackage [x11names] {xcolor}
+
+\def \primarycolor   {DodgerBlue4} %%-> rgb  16  78 139 | #104e8b
+\def \secondarycolor {Goldenrod4}  %%-> rgb 139 105 200 | #8b6914
+
+\usepackage[
+    bookmarks=true,
+   colorlinks=true,
+    linkcolor=\primarycolor,
+     urlcolor=\secondarycolor,
+    citecolor=\primarycolor,
+     pdftitle={The Luaotfload package},
+   pdfsubject={OpenType layout system for Plain TeX and LaTeX},
+    pdfauthor={Elie Roux & Khaled Hosny & Philipp Gesang},
+  pdfkeywords={luatex, lualatex, unicode, opentype}
+]{hyperref}
+
+\usepackage {fontspec}
+\usepackage {unicode-math}
+
+\setmainfont[
+% Numbers     = OldStyle, %% buggy with font cache
+  Ligatures   = TeX,
+  BoldFont    = {Linux Libertine O Bold},
+  ItalicFont  = {Linux Libertine O Italic},
+  SlantedFont = {Linux Libertine O Italic},
+]{Linux Libertine O}
+\setmonofont[Ligatures=TeX,Scale=MatchLowercase]{Liberation Mono}
+%setsansfont[Ligatures=TeX]{Linux Biolinum O}
+\setsansfont[Ligatures=TeX,Scale=MatchLowercase]{Iwona Medium}
+%setmathfont{XITS Math}
+
+\usepackage{hologo}
+
+\newcommand\TEX      {\TeX\xspace}
+\newcommand\LUA      {Lua\xspace}
+\newcommand\PDFTEX   {pdf\TeX\xspace}
+\newcommand\LUATEX   {Lua\TeX\xspace}
+\newcommand\XETEX    {\XeTeX\xspace}
+\newcommand\LATEX    {\LaTeX\xspace}
+\newcommand\LUALATEX {Lua\LaTeX\xspace}
+\newcommand\CONTEXT  {Con\TeX t\xspace}
+\newcommand\OpenType {\identifier{Open\kern-.25ex Type}\xspace}
+
+%% \groupedcommand, with some omissions taken from syst-aux.mkiv
+\let \handlegroupnormalbefore \relax
+\let \handlegroupnormalafter  \relax
+
+\protected \def \handlegroupnormal #1#2{%
+  \bgroup % 1
+  \def \handlegroupbefore {#1}%
+  \def \handlegroupafter  {#2}%
+  \afterassignment \handlegroupnormalbefore
+  \let \next =
+}
+
+\def \handlegroupnormalbefore {%
+  \bgroup % 2
+  \handlegroupbefore
+  \bgroup % 3
+  \aftergroup \handlegroupnormalafter%
+}
+
+\def \handlegroupnormalafter {%
+  \handlegroupafter
+  \egroup % 3
+  \egroup % 2
+}
+
+\let \groupedcommand \handlegroupnormal %% only the two arg version
+
+\def \definehighlight [#1][#2]{%
+  \ifcsname #1\endcsname\else
+    \expandafter\def\csname #1\endcsname{%
+      \leavevmode
+      \groupedcommand {#2}\empty%
+    }
+  \fi%
+}
+
+%% old, simplistic definition: obsolete now that we have
+%% \groupedcommand
+%\def\definehighlight[#1][#2]%
+ %{\ifcsname #1\endcsname\else
+    %\expandafter\def\csname #1\endcsname%
+      %{\bgroup#2\csname #1_indeed\endcsname}
+    %\expandafter\def\csname #1_indeed\endcsname##1%
+      %{##1\egroup}%
+  %\fi}
+
+\def\restoreunderscore{\catcode`\_=12\relax}
+
+\definehighlight         [fileent][\ttfamily\restoreunderscore]         %% files, dirs
+\definehighlight        [texmacro][\sffamily\itshape\textbackslash]     %% cs
+\definehighlight     [luafunction][\sffamily\itshape\restoreunderscore] %% lua identifiers
+\definehighlight      [identifier][\sffamily]                           %% names
+\definehighlight          [abbrev][\rmfamily\scshape]                   %% acronyms
+\definehighlight        [emphasis][\rmfamily\slshape]                   %% level 1 emph
+
+\definehighlight       [Largefont][\Large]                              %% font size
+\definehighlight       [smallcaps][\sc]                                 %% font feature
+\definehighlight [nonproportional][\tt]                                 %% font switch
+
+\newcommand*\email[1]{\href{mailto:#1}{#1}}
+
+\renewcommand\partname{Part}%% gets rid of the stupid “file” heading
+
+\usepackage{syntax}%% bnf for font request syntax
+
+\usepackage{titlesec}
+
+\def\movecountertomargin#1{\llap{\rmfamily\upshape#1\hskip2em}}
+\def\zeropoint{0pt}
+\titleformat \part
+             {\normalsize\rmfamily\bfseries}
+             {\movecountertomargin\thepart} \zeropoint {}
+\titleformat \section
+             {\normalsize\rmfamily\scshape}
+             {\movecountertomargin\thesection} \zeropoint {}
+\titleformat \subsection
+             {\small\rmfamily\itshape}
+             {\movecountertomargin\thesubsection} \zeropoint {}
+\titleformat \subsubsection
+             {\normalsize\rmfamily\upshape}
+             {\movecountertomargin\thesubsubsection} \zeropoint {}
+
+\usepackage{tocloft}
+\renewcommand \cftpartfont   {\rmfamily\upshape}
+\renewcommand \cftsecfont    {\rmfamily\upshape}
+\renewcommand \cftsubsecfont {\rmfamily\upshape}
+\setlength \cftbeforepartskip {1ex}
+\setlength \cftbeforesecskip  {1ex}
+
+\VerbatimFootnotes
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%% structurals
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\def \definestructural #1{%
+  \expandafter \let \csname end#1\endcsname \relax
+
+  \expandafter \def \csname begin#1\endcsname {%
+    \@ifnextchar[{\csname begin#1indeed\endcsname}
+                 {\csname begin#1indeed\endcsname[]}%
+  }
+
+  \expandafter \def \csname begin#1indeed\endcsname [##1]##2{%
+    \edef \first {##1}%
+    \ifx \first \empty
+      \csname #1\endcsname [##2]{##2}%
+    \else
+      \csname #1\endcsname [\first]{##2}%
+    \fi
+  }
+}
+
+\definestructural {section}
+\definestructural {subsection}
+\definestructural {subsubsection}
+
+\def \fakesection #1{\section*{#1}}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%% inline verbatim
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+%% Context offers both \type{…} and \type<<…>>, but not an unbalanced
+%% one that we could map directly onto Latex’s \verb|…|.
+
+\usepackage {listings}
+\lstset {
+  basicstyle=\ttfamily,
+}
+
+%\let \inlinecode \lstinline
+\protected \def \inlinecode {\lstinline}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%% codelistings; this sucks hard since we lack access to buffers
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\newcount \othercatcode  \othercatcode 12
+\newcount \activecatcode \othercatcode 13
+
+\newluatexcatcodetable \vrbcatcodes
+\setluatexcatcodetable \vrbcatcodes {%
+  \luatexcatcodetable \CatcodeTableIniTeX
+  \catcode  9 \othercatcode %% \tabasciicode
+  \catcode 13 \othercatcode %% \endoflineasciicode
+  \catcode 12 \othercatcode %% \formfeedasciicode
+  \catcode 26 \othercatcode %% \endoffileasciicode
+  \catcode 32 \othercatcode %% \spaceasciicode
+}
+
+\newluatexcatcodetable \literalcatcodes
+\setluatexcatcodetable \literalcatcodes {%
+  \luatexcatcodetable \CatcodeTableString
+  \catcode 32 \activecatcode %% \spaceasciicode
+}
+
+\def \beginlisting {%
+  \begingroup
+    \luatexcatcodetable \vrbcatcodes
+    \beginlistingindeed%
+}
+
+\directlua {
+  local texprint   = tex.print
+  local stringsub  = string.sub
+  local backslash  = string.byte (0x5c)
+  document         = document or { }
+  document.printlines = function (buffer)
+    for _, line in next, string.explode (buffer, "\noexpand\n") do
+      if stringsub (line, 1, 1) == " " then
+        line = backslash .. line
+      end
+      texprint (-1, line)
+      texprint (-1, "")
+    end
+  end
+}
+
+\def \beginlistingindeed#1\endlisting{%
+  \endgroup
+  \begingroup
+    \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}
+  \endgroup
+}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%% enumerations and lists
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\def \definelist [#1]#2{% name, itemcode
+  \expandafter \def \csname begin#1\endcsname {%
+    \begin {itemize}
+      \let \normalitem = \item
+      \def \altitem ####1{%
+        \def \first {####1}%
+        #2
+      }
+      \let \beginnormalitem \item
+      \let \endnormalitem   \relax
+      \let \beginaltitem    \altitem
+      \let \endaltitem      \relax
+  }
+
+  \expandafter \def \csname end#1\endcsname {%
+    \end {itemize}
+  }
+}
+
+\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}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%% columns
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\def \begindoublecolumns {\begin {multicols} {2}}
+\def \enddoublecolumns   {\end {multicols}}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%% alignment
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\def \begincentered {\begin {center}}
+\def \endcentered   {\end {center}}
+
+\def \beginnarrower {\begin {quote}}
+\def \endnarrower   {\end {quote}}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%% special elements
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\let \beginfrontmatter \relax
+\let \endfrontmatter   \relax
+
+\def \beginabstractcontent {\begin {abstract}}
+\def \endabstractcontent   {\end {abstract}}
+
+\let \setdocumenttitle      \title
+\let \setdocumentdate       \date
+\let \setdocumentauthor     \author
+\let \typesetdocumenttitle  \maketitle
+
+\AtBeginDocument {%% seriously?
+  \let \typesetcontent \tableofcontents%
+}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%% floats
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+%% syntax definition
+\def \beginsyntaxfloat #1#2{%% #1:label #2:caption
+  \begin {figure} [b]
+    \edef \syntaxlabel  {#1}%
+    \def \syntaxcaption {#2}%
+    \setlength\grammarparsep{12pt plus 2pt minus 2pt}%
+    \setlength\grammarindent{5cm}%
+    \begingroup
+      \small
+      \begin {grammar}
+}
+
+\def \endsyntaxfloat {%
+      \end {grammar}
+    \endgroup
+    \caption \syntaxcaption
+    \label   \syntaxlabel
+  \end {figure}
+}
+
+%% figures, e.g. the file graph
+\def \figurefloat #1#2#3{%% #1:label #2:caption #3:file
+  \begin {figure} [b]
+    \caption {#2}%
+    \includegraphics[width=\textwidth]{#3}%
+    \label {#1}
+  \end {figure}
+}
+
+%% tables
+\def \tablefloat #1#2{%% #1:label #2:caption
+  \begin {table} [t]
+    \hrule
+    \caption {#2}%
+    \label {#1}
+    \hrule
+  \end {table}
+}
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%% hyperlinks
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\protected \def \hyperlink{%
+  \@ifnextchar[{\hyperlinkindeed}%
+               {\hyperlinkindeed[]}%
+}
+
+\def \hyperlinkindeed [#1]#2{%
+  \def \first {#1}%
+  \ifx \first \empty
+    \url {#2}%
+  \else
+    \href {#2}{#1}%
+  \fi%
+}
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%% tables
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%% Our tables aren’t anything special so we stick with “tabular” on the
+%% Latex end.
+%%
+%% This is going to be largely incompatible with Context since format
+%% specifications work quite differently (even between different
+%% Context table variants).
+
+\def \begintabulate [#1]#2\endtabulate{%
+  \begingroup
+    \let \beginrow  = \relax %% -> \NC in Context
+    \let \newcell   = &      %% -> \NC
+    \let \endrow    = \cr    %% -> \NC \NR
+    \begin {tabular}{#1}%
+      #2
+    \end {tabular}
+  \endgroup
+}
+
+\let \endtabulate \relax
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%% escaped characters
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\let \charpercent   \textpercent
+\let \charbackslash \textbackslash
+\let \chartilde     \textasciitilde
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%% main
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\makeatother
+
+\newif \ifcontextmkiv \contextmkivfalse
+
+\begin {document}
+  \input {luaotfload-main.tex}
+\end {document}
+
+
diff --git a/doc/luaotfload-main.tex b/doc/luaotfload-main.tex
new file mode 100644
index 0000000..034b704
--- /dev/null
+++ b/doc/luaotfload-main.tex
@@ -0,0 +1,1591 @@
+%% 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/>.
+%%
+%% ----------------------------------------------------------------------------
+%%
+
+\beginfrontmatter
+
+  \setdocumenttitle  {The \identifier{luaotfload} package}
+  \setdocumentdate   {2014/**/** v2.5}
+  \setdocumentauthor {Elie Roux · Khaled Hosny · Philipp Gesang\\
+                      Home:    \hyperlink {https://github.com/lualatex/luaotfload}\\
+                      Support: \email     {lualatex-dev@tug.org}}
+
+  \typesetdocumenttitle
+
+  \beginabstractcontent
+    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.
+  \endabstractcontent
+
+\endfrontmatter
+
+\typesetcontent
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\beginsection {Introduction}
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+Font management and installation has always been painful with \TEX.  A
+lot of files are needed for one font (\abbrev{tfm}, \abbrev{pfb},
+\abbrev{map}, \abbrev{fd}, \abbrev{vf}), and due to the 8-Bit encoding
+each font is limited to 256 characters.
+
+But the font world has evolved since the original \TEX, and new
+typographic systems have appeared, most notably the so called
+\emphasis{smart font} technologies like \OpenType fonts (\abbrev{otf}).
+
+These fonts can contain many more characters than \TEX fonts, as well
+as additional functionality like ligatures, old-style numbers, small
+capitals, etc., and support more complex writing systems like Arabic
+and Indic\footnote{%
+  Unfortunately, \identifier{luaotfload} doesn‘t support many Indic
+  scripts right now.
+  Assistance in implementing the prerequisites is greatly
+  appreciated.
+}
+scripts.
+
+\OpenType fonts are widely deployed and available for all modern
+operating systems.
+
+As of 2013 they have become the de facto standard for advanced text
+layout.
+
+However, until recently the only way to use them directly in the \TEX
+world was with the \XETEX engine.
+
+Unlike \XETEX, \LUATEX has no built-in support for \OpenType or
+technologies other than the original \TEX fonts.
+
+Instead, it provides hooks for executing \LUA code during the \TEX run
+that allow implementing extensions for loading fonts and manipulating
+how input text is processed without modifying the underlying engine.
+
+This is where \identifier{luaotfload} comes into play:
+Based on code from \CONTEXT, it extends \LUATEX with functionality necessary
+for handling \OpenType fonts.
+
+Additionally, it provides means for accessing fonts known to the operating
+system conveniently by indexing the metadata.
+
+\endsection
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\beginsection {Thanks}
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\identifier{Luaotfload} is part of \LUALATEX, the community-driven
+project to provide a foundation for using the \LATEX format with the
+full capabilites of the \LUATEX engine.
+%
+As such, the distinction between end users, contributors, and project
+maintainers is intentionally kept less strict, lest we unduly
+personalize the common effort.
+
+Nevertheless, the current maintainers would like to express their
+gratitude to Khaled Hosny, Akira Kakuto, Hironori Kitagawa and Dohyun
+Kim.
+%
+Their contributions -- be it patches, advice, or systematic
+testing -- made the switch from version 1.x to 2.2 possible.
+%
+Also, Hans Hagen, the author of the font loader, made porting the
+code to \LATEX a breeze due to the extra effort he invested into
+isolating it from the rest of \CONTEXT, not to mention his assistance
+in the task and willingness to respond to our suggestions.
+
+\endsection
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\beginsection {Loading Fonts}
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\identifier{luaotfload} supports an extended font request syntax:
+
+\beginnarrower
+      \nonproportional{\string\font\string\foo\space= \string{}%
+      \meta{prefix}\nonproportional{:}%
+      \meta{font name}\nonproportional{:}%
+      \meta{font features}\nonproportional{\string}}%
+      \meta{\TEX font features}
+\endnarrower
+
+\noindent
+The curly brackets are optional and escape the spaces in the enclosed
+font name.
+%
+Alternatively, double quotes serve the same purpose.
+%
+A selection of individual parts of the syntax are discussed below;
+for a more formal description see figure \ref{font-syntax}.
+
+\beginsyntaxfloat
+  {font-syntax}
+  {Font request syntax.
+   Braces or double quotes around the
+   \emphasis{specification} rule will
+   preserve whitespace in file names.
+   In addition to the font style modifiers
+   (\emphasis{slash-notation}) given above, there
+   are others that are recognized but will be silently
+   ignored: \nonproportional{aat},
+            \nonproportional{icu}, and
+            \nonproportional{gr}.
+   The special terminals are:
+   \smallcaps {feature\textunderscore id} for a valid font
+      feature name and
+   \smallcaps {feature\textunderscore value} for the corresponding
+      value.
+   \smallcaps {tfmname} is the name of a \abbrev{tfm} file.
+   \smallcaps {digit}  again refers to bytes 48--57, and
+   \smallcaps {all\textunderscore characters} to all byte values.
+   \smallcaps {csname} and \smallcaps {dimension} are the \TEX concepts.}
+%
+      <definition>      ::= `\\font', {\sc csname}, `=', <font request>, [ <size> ] ;
+
+      <size>            ::= `at', {\sc dimension} ;
+
+      <font request>    ::= `"', <unquoted font request> `"'
+      \alt                  `{', <unquoted font request> `}'
+      \alt                  <unquoted font request> ;
+
+      <unquoted font request> ::= <specification>, [`:', <feature list> ]
+      \alt                        `[', <path lookup> `]', [ [`:'], <feature list> ] ;
+
+      <specification>    ::= <prefixed spec>, [ <subfont no> ], \{ <modifier> \}
+      \alt                   <anon lookup>, \{ <modifier> \} ;
+
+      <prefixed spec>    ::= `file:', <file lookup>
+      \alt                   `name:', <name lookup> ;
+
+      <file lookup>      ::= \{ <name character> \} ;
+
+      <name lookup>      ::= \{ <name character> \} ;
+
+      <anon lookup>      ::= {\sc tfmname} | <name lookup> ;
+
+      <path lookup>      ::= \{ {\sc all_characters} - `]' \} ;
+
+      <modifier>         ::= `/', (`I' | `B' | `BI' | `IB' | `S=', \{ {\sc digit} \} ) ;
+
+      <subfont no>       ::= `(', \{ {\sc digit} \}, `)' ;
+
+      <feature list>     ::= <feature expr>, \{ `;', <feature expr> \} ;
+
+      <feature expr>     ::= {\sc feature_id}, `=', {\sc feature_value}
+      \alt                   <feature switch>, {\sc feature_id} ;
+
+      <feature switch>   ::= `+' | `-' ;
+
+      <name character>   ::= {\sc all_characters} - ( `(' | `/' | `:' ) ;
+\endsyntaxfloat
+
+\beginsubsection{Prefix -- the \identifier{luaotfload}{ }Way}
+
+In \identifier{luaotfload}, the canonical syntax for font requests
+requires a \emphasis{prefix}:
+%
+\beginnarrower
+  \nonproportional{\string\font\string\fontname\space= }%
+  \meta{prefix}%
+  \nonproportional{:}%
+  \meta{fontname}%
+  \dots
+\endnarrower
+%
+where \meta{prefix} is either \inlinecode{file:} or \inlinecode {name:}.\footnote{%
+  The development version also knows two further prefixes,
+  \inlinecode {kpse:} and \inlinecode {my:}.
+  %
+  A \inlinecode {kpse} lookup is restricted to files that can be found by
+  \identifier{kpathsea} and
+  will not attempt to locate system fonts.
+  %
+  This behavior can be of value when an extra degree of encapsulation is
+  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}
+  callback.
+  %
+  This ensures full control over how a file is located.
+  %
+  For a working example see the
+  \hyperlink [test repo]{https://bitbucket.org/phg/lua-la-tex-tests/src/5f6a535d/pln-lookup-callback-1.tex}.
+}
+%
+It determines whether the font loader should interpret the request as
+a \emphasis{file name} or
+  \emphasis{font name}, respectively,
+which again influences how it will attempt to locate the font.
+%
+Examples for font names are
+            “Latin Modern Italic”,
+            “GFS Bodoni Rg”, and
+            “PT Serif Caption”
+-- they are the human readable identifiers
+usually listed in drop-down menus and the like.\footnote{%
+  Font names may appear like a great choice at first because they
+  offer seemingly more intuitive identifiers in comparison to arguably
+  cryptic file names:
+  %
+  “PT Sans Bold” is a lot more descriptive than \fileent{PTS75F.ttf}.
+  On the other hand, font names are quite arbitrary and there is no
+  universal method to determine their meaning.
+  %
+  While \identifier{luaotfload} provides fairly sophisticated heuristic
+  to figure out a matching font style, weight, and optical size, it
+  cannot be relied upon to work satisfactorily for all font files.
+  %
+  For an in-depth analysis of the situation and how broken font names
+  are, please refer to
+  \hyperlink [this post]{http://www.ntg.nl/pipermail/ntg-context/2013/073889.html}
+  by Hans Hagen, the author of the font loader.
+  %
+  If in doubt, use filenames.
+  %
+  \fileent{luaotfload-tool} can perform the matching for you with the
+  option \inlinecode {--find=<name>}, and you can use the file name it returns
+  in your font definition.
+}
+%
+In order for fonts installed both in system locations and in your
+\fileent{texmf} to be accessible by font name, \identifier{luaotfload} must
+first collect the metadata included in the files.
+%
+Please refer to section~\ref{sec:fontdb} below for instructions on how to
+create the database.
+
+File names are whatever your file system allows them to be, except
+that that they may not contain the characters
+  \inlinecode {(},
+  \inlinecode {:}, and
+  \inlinecode {/}.
+%
+As is obvious from the last exception, the \inlinecode {file:} lookup will
+not process paths to the font location -- only those
+files found when generating the database are addressable this way.
+%
+Continue below in the \XETEX section if you need to load your fonts
+by path.
+%
+The file names corresponding to the example font names above are
+  \fileent{lmroman12-italic.otf},
+  \fileent{GFSBodoni.otf}, and
+  \fileent{PTZ56F.ttf}.
+
+\endsubsection
+
+\beginsubsection {Compatibility Layer}
+
+In addition to the regular prefixed requests, \identifier{luaotfload}
+accepts loading fonts the \XETEX way.
+%
+There are again two modes: bracketed and unbracketed.
+A bracketed request looks as follows.
+
+\beginnarrower
+  \nonproportional{\string\font\string\fontname\space = [}%
+  \meta{/path/to/file}%
+  \nonproportional{]}
+\endnarrower
+
+\noindent
+Inside the square brackets, every character except for a closing
+bracket is permitted, allowing for specifying paths to a font file.
+%
+Naturally, path-less file names are equally valid and processed the
+same way as an ordinary \inlinecode {file:} lookup.
+
+\beginnarrower
+  \nonproportional{\string\font\string\fontname\space= }%
+  \meta{font name}
+  \dots
+\endnarrower
+
+Unbracketed (or, for lack of a better word: \emphasis{anonymous})
+font requests resemble the conventional \TEX syntax.
+%
+However, they have a broader spectrum of possible interpretations:
+before anything else, \identifier{luaotfload} attempts to load a
+traditional \TEX Font Metric (\abbrev{tfm} or \abbrev{ofm}).
+%
+If this fails, it performs a \inlinecode {name:} lookup, which itself will
+fall back to a \inlinecode {file:} lookup if no database entry matches
+\meta{font name}.
+
+Furthermore, \identifier{luaotfload} supports the slashed (shorthand)
+font style notation from \XETEX.
+
+\beginnarrower
+  \nonproportional{\string\font\string\fontname\space= }%
+  \meta{font name}%
+  \nonproportional{/}%
+  \meta{modifier}
+  \dots
+\endnarrower
+
+\noindent
+Currently, four style modifiers are supported:
+  \inlinecode {I} for italic shape,
+  \inlinecode {B} for bold   weight,
+  \inlinecode {BI} or \inlinecode {IB} for the combination of both.
+%
+Other “slashed” modifiers are too specific to the \XETEX engine and
+have no meaning in \LUATEX.
+
+\endsubsection
+
+\beginsubsection{Examples}
+
+\beginsubsubsection{Loading by File Name}
+
+For example, conventional \abbrev{type1} font can be loaded with a
+\inlinecode {file:} request like so:
+
+\beginlisting
+  \font \lmromanten = {file:ec-lmr10} at 10pt
+\endlisting
+
+The \OpenType version of Janusz Nowacki’s font \emphasis{Antykwa
+Półtawskiego}\footnote{%
+  \hyperlink {http://jmn.pl/antykwa-poltawskiego/}, also available in
+  in \TEX Live.
+}
+in its condensed variant can be loaded as follows:
+
+\beginlisting
+  \font \apcregular = file:antpoltltcond-regular.otf at 42pt
+\endlisting
+
+The next example shows how to load the \emphasis{Porson} font digitized by
+the Greek Font Society using \XETEX-style syntax and an absolute path from a
+non-standard directory:
+
+\beginlisting
+  \font \gfsporson = "[/tmp/GFSPorson.otf]" at 12pt
+\endlisting
+
+\endsubsubsection
+
+\beginsubsubsection{Loading by Font Name}
+
+The \inlinecode {name:} lookup does not depend on cryptic filenames:
+
+\beginlisting
+  \font \pagellaregular = {name:TeX Gyre Pagella} at 9pt
+\endlisting
+
+A bit more specific but essentially the same lookup would be:
+
+\beginlisting
+  \font \pagellaregular = {name:TeX Gyre Pagella Regular} at 9pt
+\endlisting
+
+\noindent
+Which fits nicely with the whole set:
+
+\beginlisting
+  \font\pagellaregular    = {name:TeX Gyre Pagella Regular}    at 9pt
+  \font\pagellaitalic     = {name:TeX Gyre Pagella Italic}     at 9pt
+  \font\pagellabold       = {name:TeX Gyre Pagella Bold}       at 9pt
+  \font\pagellabolditalic = {name:TeX Gyre Pagella Bolditalic} at 9pt
+
+  {\pagellaregular     foo bar baz\endgraf}
+  {\pagellaitalic      foo bar baz\endgraf}
+  {\pagellabold        foo bar baz\endgraf}
+  {\pagellabolditalic  foo bar baz\endgraf}
+
+  ...
+\endlisting
+
+\endsubsubsection
+
+\beginsubsubsection{Modifiers}
+
+If the entire \emphasis{Iwona} family\footnote{%
+  \hyperlink {http://jmn.pl/kurier-i-iwona/},
+  also in \TEX Live.
+}
+is installed in some location accessible by \identifier{luaotfload},
+the regular shape can be loaded as follows:
+
+\beginlisting
+  \font \iwona = Iwona at 20pt
+\endlisting
+
+\noindent
+To load the most common of the other styles, the slash notation can
+be employed as shorthand:
+
+\beginlisting
+  \font \iwonaitalic     = Iwona/I    at 20pt
+  \font \iwonabold       = Iwona/B    at 20pt
+  \font \iwonabolditalic = Iwona/BI   at 20pt
+\endlisting
+
+\noindent
+which is equivalent to these full names:
+
+\beginlisting
+  \font \iwonaitalic     = "Iwona Italic"       at 20pt
+  \font \iwonabold       = "Iwona Bold"         at 20pt
+  \font \iwonabolditalic = "Iwona BoldItalic"   at 20pt
+\endlisting
+
+\endsubsubsection
+\endsubsection
+\endsection
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\beginsection {Font features}
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\emphasis{Font features} are the second to last component in the
+general scheme for font requests:
+
+\beginnarrower
+  \nonproportional{\string\font\string\foo\space= "}%
+  \meta{prefix}%
+  \nonproportional{:}%
+  \meta{font name}%
+  \nonproportional{:}%
+  \meta{font features}%
+  \meta{\TEX font features}%
+  \nonproportional{"}
+\endnarrower
+
+\noindent
+If style modifiers are present (\XETEX style), they must precede
+\meta{font features}.
+
+The element \meta{font features} is a semicolon-separated list of feature
+tags\footnote{%
+  Cf. \hyperlink {http://www.microsoft.com/typography/otspec/featurelist.htm}.
+}
+and font options.
+%
+Prepending a font feature with a \inlinecode{+} (plus sign) enables it,
+whereas a \inlinecode{-} (minus) disables it. For instance, the request
+
+\beginlisting
+  \font \test = LatinModernRoman:+clig;-kern
+\endlisting
+
+\noindent activates contextual ligatures (\inlinecode{clig}) and
+disables kerning (\inlinecode{kern}).
+%
+Alternatively the options \inlinecode{true} or \inlinecode{false} can
+be passed to the feature in a key/value expression.
+%
+The following request has the same meaning as the last one:
+
+\beginlisting
+  \font \test = LatinModernRoman:clig=true;kern=false
+\endlisting
+
+\noindent
+Furthermore, this second syntax is required should a font feature
+accept other options besides a true/false switch.
+%
+For example, \emphasis{stylistic alternates} (\inlinecode{salt}) are
+variants of given glyphs.
+%
+They can be selected either explicitly by supplying the variant
+index (starting from one), or randomly by setting the value to,
+obviously, \inlinecode{random}.
+
+%% TODO   verify that this actually works with a font that supports
+%%        the salt/random feature!\fi
+\beginlisting
+  \font \librmsaltfirst = LatinModernRoman:salt=1
+\endlisting
+
+\beginsubsection {Basic font features}
+
+\begindescriptions
+
+  \beginaltitem {mode}
+         \identifier{luaotfload} has two \OpenType processing
+         \emphasis{modes}:
+         \identifier{base} and \identifier{node}.
+
+         \identifier{base} mode works by mapping \OpenType
+         features to traditional \TEX ligature and kerning mechanisms.
+         %
+         Supporting only non-contextual substitutions and kerning
+         pairs, it is the slightly faster, albeit somewhat limited, variant.
+         %
+         \identifier{node} mode works by processing \TeX’s internal
+         node list directly at the \LUA end and supports
+         a wider range of \OpenType features.
+         %
+         The downside is that the intricate operations required for
+         \identifier{node} mode may slow down typesetting especially
+         with complex fonts and it does not work in math mode.
+
+         By default \identifier{luaotfload} is in \identifier{node}
+         mode, and \identifier{base} mode has to be requested where needed,
+         e.~g. for math fonts.
+  \endaltitem
+
+  \beginaltitem {script} \label{script-tag}
+         An \OpenType script tag;\footnote{%
+           See \hyperlink {http://www.microsoft.com/typography/otspec/scripttags.htm}
+           for a list of valid values.
+           %
+           For scripts derived from the Latin alphabet the value
+           \inlinecode{latn} is good choice.
+         }
+         the default value is \inlinecode{dlft}.
+         %
+         Some fonts, including very popular ones by foundries like Adobe,
+         do not assign features to the \inlinecode{dflt} script, in
+         which case the script needs to be set explicitly.
+  \endaltitem
+
+  \beginaltitem {language}
+         An \OpenType language system identifier,\footnote{%
+           Cf. \hyperlink {http://www.microsoft.com/typography/otspec/languagetags.htm}.
+         }
+         defaulting to \inlinecode{dflt}.
+  \endaltitem
+
+  \beginaltitem {featurefile}
+         A comma-separated list of feature files to be applied to the
+         font.
+         %
+         Feature files contain a textual representation of
+         \OpenType tables and extend the features of a font
+         on fly.
+         %
+         After they are applied to a font, features defined in a
+         feature file can be enabled or disabled just like any
+         other font feature.
+         %
+         The syntax is documented in \identifier{Adobe}’s
+         \OpenType Feature File Specification.\footnote{%
+           Cf. \hyperlink {http://www.adobe.com/devnet/opentype/afdko/topic_feature_file_syntax.html}.
+           Feature file support is part of the engine which at the
+           time of this writing (2014) implements the spec only
+           partially.
+           See the
+           \hyperlink [\LUATEX tracker]{http://tracker.luatex.org/view.php?id=231}
+            for details.
+         }
+
+         For a demonstration of how to set a \inlinecode{tkrn} feature consult
+         the file \inlinecode{tkrn.fea} that is part of \identifier{luaotfload}.
+         It can be read and applied as follows:
+
+         \inlinecode{\\font \\test = Latin Modern Roman:featurefile=tkrn.fea;+tkrn}
+  \endaltitem
+
+  \beginaltitem {color}
+         A font color, defined as a triplet of two-digit hexadecimal
+         \abbrev{rgb} values, with an optional fourth value for
+         transparency
+         (where \inlinecode{00} is completely transparent and
+         \inlinecode{FF} is opaque).
+
+         For example, in order to set text in semitransparent red:
+
+         \beginlisting
+\font \test = "Latin Modern Roman:color=FF0000BB"
+         \endlisting
+  \endaltitem
+
+  \beginaltitem {kernfactor \& letterspace}
+         Define a font with letterspacing (tracking) enabled.
+         %
+         In \identifier{luaotfload}, letterspacing is implemented by
+         inserting additional kerning between glyphs.
+
+         This approach is derived from and still quite similar to the
+         \emphasis{character kerning} (\texmacro{setcharacterkerning} /
+         \texmacro{definecharacterkerning} \& al.) functionality of
+         Context, see the file \fileent{typo-krn.lua} there.
+         %
+         The main difference is that \identifier{luaotfload} does not
+         use \LUATEX attributes to assign letterspacing to regions,
+         but defines virtual letterspaced versions of a font.
+
+         The option \identifier{kernfactor} accepts a numeric value that
+         determines the letterspacing factor to be applied to the font
+         size.
+         %
+         E.~g. a kern factor of $0.42$ applied to a $10$ pt font
+         results in $4.2$ pt of additional kerning applied to each
+         pair of glyphs.
+         %
+         Ligatures are split into their component glyphs unless
+         explicitly ignored (see below).
+
+         For compatibility with \XETEX an alternative
+         \identifier{letterspace} option is supplied that interprets the
+         supplied value as a \emphasis{percentage} of the font size but
+         is otherwise identical to \identifier{kernfactor}.
+         %
+         Consequently, both definitions in below snippet yield the same
+         letterspacing width:
+
+         \beginlisting
+\font \iwonakernedA = "file:Iwona-Regular.otf:kernfactor=0.125"
+\font \iwonakernedB = "file:Iwona-Regular.otf:letterspace=12.5"
+         \endlisting
+
+         Specific pairs of letters and ligatures may be exempt from
+         letterspacing by defining the \LUA functions
+         \luafunction{keeptogether} and \luafunction{keepligature},
+         respectively, inside the namespace \inlinecode {luaotfload.letterspace}.
+         %
+         Both functions are called whenever the letterspacing callback
+         encounters an appropriate node or set of nodes.
+         %
+         If they return a true-ish value, no extra kern is inserted at
+         the current position.
+         %
+         \luafunction{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
+         analyzed into components.
+         %
+         (For details refer to the \emphasis{glyph nodes} section in the
+         \LUATEX reference manual.)
+         %
+         The implementation of both functions is left entirely to the
+         user.
+  \endaltitem
+
+\ifcontextmkiv
+  \startbuffer [printvectors]
+  \directlua{inspect(fonts.protrusions.setups.default)
+             inspect(fonts.expansions.setups.default)}
+  \stopbuffer
+\fi
+
+  \beginaltitem {protrusion \& expansion}
+         These keys control microtypographic features of the font,
+         namely \emphasis{character protrusion} and \emphasis{font
+         expansion}.
+         %
+         Their arguments are names of \LUA tables that contain
+         values for the respective features.\footnote{%
+            For examples of the table layout please refer to the
+            section of the file \fileent{luaotfload-fonts-ext.lua} where the
+            default values are defined.
+            %
+            Alternatively and with loss of information, you can dump
+            those tables into your terminal by issuing
+            \unless \ifcontextmkiv
+              \beginlisting
+ \directlua{inspect(fonts.protrusions.setups.default)
+            inspect(fonts.expansions.setups.default)}
+              \endlisting
+            \else
+              \typebuffer [printvectors]
+            \fi
+            at some point after loading \fileent{luaotfload.sty}.
+         }
+         %
+         For both, only the set \identifier{default} is predefined.
+
+         For example, to define a font with the default
+         protrusion vector applied\footnote{%
+           You also need to set
+               \inlinecode {pdfprotrudechars=2} and
+               \inlinecode {pdfadjustspacing=2}
+           to activate protrusion and expansion, respectively.
+           See the
+           \hyperlink [\PDFTEX manual]{http://mirrors.ctan.org/systems/pdftex/manual/pdftex-a.pdf}%
+           for details.
+         }:
+
+         \beginlisting
+\font \test = LatinModernRoman:protrusion=default
+         \endlisting
+  \endaltitem
+\enddescriptions
+
+\endsubsection
+
+\beginsubsection {Non-standard font features}
+\identifier{luaotfload} adds a number of features that are not defined
+in the original \OpenType specification, most of them
+aiming at emulating the behavior familiar from other \TEX engines.
+%
+Currently (2014) there are three of them:
+
+\begindescriptions
+
+  \beginaltitem {anum}
+          Substitutes the glyphs in the \abbrev{ascii} number range
+          with their counterparts from eastern Arabic or Persian,
+          depending on the value of \identifier{language}.
+  \endaltitem
+
+  \beginaltitem {tlig}
+          Applies legacy \TEX ligatures\footnote{%
+            These contain the feature set \inlinecode {trep} of earlier
+            versions of \identifier{luaotfload}.
+
+            Note to \XETEX users: this is the equivalent of the
+            assignment \inlinecode {mapping=text-tex} using \XETEX's input
+            remapping feature.
+          }:
+
+          \unless \ifcontextmkiv
+            %% Using braced arg syntax with inline code appears to be
+            %% impossible within Latex tables -- just ignore the weird
+            %% exclamation points below.
+            \begintabulate [rlrl]
+              \beginrow ``  \newcell  {\inlinecode !``! } \newcell  ''  \newcell  {\inlinecode !''!} \endrow
+              \beginrow `   \newcell  {\inlinecode !`!  } \newcell  '   \newcell  {\inlinecode !'! } \endrow
+              \beginrow "   \newcell  {\inlinecode !"!  } \newcell  --  \newcell  {\inlinecode !--!} \endrow
+              \beginrow --- \newcell  {\inlinecode !---!} \newcell  !`  \newcell  {\inlinecode ?!`?} \endrow
+              \beginrow ?`  \newcell  {\inlinecode !?`! } \newcell      \newcell                     \endrow
+            \endtabulate
+          \else
+            %% XXX find a way to wrap these in the tabulate environment
+            \startframed [frame=off,width=broad,align=middle]
+              \startframed [frame=off,width=\dimexpr(\textwidth/2)]
+                \startxtable [align=middle]
+                    \startxrow \startxcell ``  \stopxcell \startxcell  \inlinecode {``}  \stopxcell \startxcell  ''  \stopxcell \startxcell  \inlinecode {''}  \stopxcell \stopxrow
+                    \startxrow \startxcell `   \stopxcell \startxcell  \inlinecode {`}   \stopxcell \startxcell  '   \stopxcell \startxcell  \inlinecode {'}   \stopxcell \stopxrow
+                    \startxrow \startxcell "   \stopxcell \startxcell  \inlinecode {"}   \stopxcell \startxcell  --  \stopxcell \startxcell  \inlinecode {--}  \stopxcell \stopxrow
+                    \startxrow \startxcell --- \stopxcell \startxcell  \inlinecode {---} \stopxcell \startxcell  !`  \stopxcell \startxcell  \inlinecode {!`}  \stopxcell \stopxrow
+                    \startxrow \startxcell ?`  \stopxcell \startxcell  \inlinecode {?`}  \stopxcell \startxcell      \stopxcell \startxcell                    \stopxcell \stopxrow
+                \stopxtable
+              \stopframed
+            \stopframed
+          \fi
+  \endaltitem
+
+  \beginaltitem {itlc}
+          Computes italic correction values (active by default).
+  \endaltitem
+
+\enddescriptions
+
+\endsubsection
+\endsection
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\beginsection {Font names database}
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\label{sec:fontdb}
+
+As mentioned above, \identifier{luaotfload} keeps track of which
+fonts are available to \LUATEX by means of a \emphasis{database}.
+%
+This allows referring to fonts not only by explicit filenames but
+also by the proper names contained in the metadata which is often
+more accessible to humans.\footnote{%
+  The tool \hyperlink[\fileent{otfinfo}]{http://www.lcdf.org/type/}
+  (comes with \TEX Live), when invoked on a font file with the
+  \inlinecode {-i} option, lists the variety of name fields defined for
+  it.
+}
+
+When \identifier{luaotfload} is asked to load a font by a font name,
+it will check if the database exists and load it, or else generate a
+fresh one.
+%
+Should it then fail to locate the font, an update to the database is
+performed in case the font has been added to the system only
+recently.
+%
+As soon as the database is updated, the resolver will try
+and look up the font again, all without user intervention.
+%
+The goal is for \identifier{luaotfload} to act in the background and
+behave as unobtrusively as possible, while providing a convenient
+interface to the fonts installed on the system.
+
+Generating the database for the first time may take a while since it
+inspects every font file on your computer.
+%
+This is particularly noticeable if it occurs during a typesetting run.
+In any case, subsequent updates to the database will be quite fast.
+
+\beginsubsection[luaotfload-tool]
+                {\fileent{luaotfload-tool}}
+
+It can still be desirable at times to do some of these steps
+manually, and without having to compile a document.
+%
+To this end, \identifier{luaotfload} comes with the utility
+\fileent{luaotfload-tool} that offers an interface to the database
+functionality.
+%
+Being a \LUA script, there are two ways to run it:
+either make it executable (\inlinecode {chmod +x} on unixoid systems) or
+pass it as an argument to \fileent{texlua}.\footnote{%
+  Tests by the maintainer show only marginal performance gain by
+  running with Luigi Scarso’s
+  \hyperlink [\identifier{Luajit\kern-.25ex\TEX}]{https://foundry.supelec.fr/projects/luajittex/},
+  which is probably due to the fact that most of the time is spent
+  on file system operations.
+
+  \emphasis{Note}:
+  On \abbrev{MS} \identifier{Windows} systems, the script can be run
+  either by calling the wrapper application
+  \fileent{luaotfload-tool.exe} or as
+  \inlinecode {texlua.exe luaotfload-tool.lua}.
+}
+%
+Invoked with the argument \inlinecode {--update} it will perform a database
+update, scanning for fonts not indexed.
+
+\beginlisting
+  luaotfload-tool --update
+\endlisting
+
+Adding the \inlinecode {--force} switch will initiate a complete
+rebuild of the database.
+
+\beginlisting
+  luaotfload-tool --update --force
+\endlisting
+
+\endsubsection
+
+\beginsubsection{Search Paths}
+
+\identifier{luaotfload} scans those directories where fonts are
+expected to be located on a given system.
+%
+On a Linux machine it follows the paths listed in the
+\identifier{Fontconfig} configuration files;
+consult \inlinecode {man 5 fonts.conf} for further information.
+%
+On \identifier{Windows} systems, the standard location is
+\inlinecode {Windows\\Fonts},
+%
+while \identifier{Mac OS~X} requires a multitude of paths to
+be examined.
+%
+The complete list is is given in table \ref{table-searchpaths}.
+Other paths can be specified by setting the environment variable
+\inlinecode {OSFONTDIR}.
+%
+If it is non-empty, then search will be extended to the included
+directories.
+
+\tablefloat {table-searchpaths}
+  {List of paths searched for each supported operating system.}
+  {%
+    \unless \ifcontextmkiv
+      \begincentered
+        \begintabulate [lp{.5\textwidth}]
+          \beginrow
+            Windows   \newcell \inlinecode !\% WINDIR\%\\ Fonts!
+          \endrow
+          \beginrow
+            Linux     \newcell \fileent{/usr/local/etc/fonts/fonts.conf} and\hfill\break
+                               \fileent{/etc/fonts/fonts.conf}
+          \endrow
+          \beginrow
+            Mac       \newcell \fileent{\textasciitilde/Library/Fonts},\break
+                               \fileent{/Library/Fonts},\break
+                               \fileent{/System/Library/Fonts}, and\hfill\break
+                               \fileent{/Network/Library/Fonts}
+          \endrow
+        \endtabulate
+      \endcentered
+    \else
+      \setuplocalinterlinespace [14pt]
+      \starttabulate [|l|p(.5\textwidth)|]
+        \NC Windows   \NC \inlinecode {\% WINDIR\%\\ Fonts} \NC \NR
+        \NC Linux     \NC \fileent{/usr/local/etc/fonts/fonts.conf} and\crlf
+                          \fileent{/etc/fonts/fonts.conf} \NC \NR
+        \NC
+          Mac         \NC \fileent{\textasciitilde/Library/Fonts},\crlf
+                          \fileent{/Library/Fonts},\break
+                          \fileent{/System/Library/Fonts}, and\crlf
+                          \fileent{/Network/Library/Fonts} \NC \NR
+      \stoptabulate
+    \fi%
+  }
+
+\endsubsection
+
+\beginsubsection{Querying from Outside}
+
+\fileent{luaotfload-tool} also provides rudimentary means of
+accessing the information collected in the font database.
+%
+If the option \inlinecode {--find=}\emphasis{name} is given, the script will
+try and search the fonts indexed by \identifier{luaotfload} for a
+matching name.
+%
+For instance, the invocation
+
+\beginlisting
+  luaotfload-tool  --find="Iwona Regular"
+\endlisting
+
+\noindent
+will verify if “Iwona Regular” is found in the database and can be
+readily requested in a document.
+
+If you are unsure about the actual font name, then add the
+\inlinecode {-F} (or \inlinecode {--fuzzy}) switch to the command line to enable
+approximate matching.
+%
+Suppose you cannot precisely remember if the variant of
+\identifier{Iwona} you are looking for was “Bright” or “Light”.
+The query
+
+\beginlisting
+  luaotfload-tool  -F --find="Iwona Bright"
+\endlisting
+
+\noindent
+will tell you that indeed the latter name is correct.
+
+Basic information about fonts in the database can be displayed
+using the \inlinecode {-i} option (\inlinecode {--info}).
+%
+\beginlisting
+  luaotfload-tool  -i --find="Iwona Light Italic"
+\endlisting
+%
+\noindent
+The meaning of the printed values is described in section 4.4 of the
+\LUATEX reference manual.\footnote{%
+  In \TEX Live: \fileent{texmf-dist/doc/luatex/base/luatexref-t.pdf}.
+}
+
+For a much more detailed report about a given font try the
+\inlinecode {-I} option instead (\inlinecode {--inspect}).
+\beginlisting
+  luaotfload-tool  -I --find="Iwona Light Italic"
+\endlisting
+
+\inlinecode {luaotfload-tool --help} will list the available command line
+switches, including some not discussed in detail here.
+%
+For a full documentation of \identifier{luaotfload-tool} and its
+capabilities refer to the manpage
+(\inlinecode {man 1 luaotfload-tool}).\footnote{%
+  Or see \inlinecode {luaotfload-tool.rst} in the source directory.
+}
+
+\endsubsection
+
+\beginsubsection {Blacklisting Fonts}
+\label{font-blacklist}
+
+Some fonts are problematic in general, or just in \LUATEX.
+%
+If you find that compiling your document takes far too long or eats
+away all your system’s memory, you can track down the culprit by
+running \inlinecode {luaotfload-tool -v} to increase verbosity.
+%
+Take a note of the \emphasis{filename} of the font that database
+creation fails with and append it to the file
+\fileent{luaotfload-blacklist.cnf}.
+
+A blacklist file is a list of font filenames, one per line.
+Specifying the full path to where the file is located is optional, the
+plain filename should suffice.
+%
+File extensions (\fileent{.otf}, \fileent{.ttf}, etc.) may be omitted.
+%
+Anything after a percent (\inlinecode {\%}) character until the end of the line
+is ignored, so use this to add comments.
+%
+Place this file to some location where the \identifier{kpse}
+library can find it, e.~g.
+\fileent{texmf-local/tex/luatex/luaotfload} if you are running
+\identifier{\TEX Live},\footnote{%
+  You may have to run \inlinecode {mktexlsr} if you created a new file in
+  your \fileent{texmf} tree.
+}
+or just leave it in the working directory of your document.
+%
+\identifier{luaotfload} reads all files named
+\fileent{luaotfload-blacklist.cnf} it finds, so the fonts in
+\fileent{./luaotfload-blacklist.cnf} extend the global blacklist.
+
+Furthermore, a filename prepended with a dash character (\inlinecode{-}) is
+removed from the blacklist, causing it to be temporarily whitelisted
+without modifying the global file.
+%
+An example with explicit paths:
+
+\beginlisting
+% example otf-blacklist.cnf
+/Library/Fonts/GillSans.ttc  % Luaotfload ignores this font.
+-/Library/Fonts/Optima.ttc   % This one is usable again, even if
+                             % blacklisted somewhere else.
+\endlisting
+
+\endsubsection
+\endsection
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\beginsection {Files from \CONTEXT and \LUATEX-Fonts}
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\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.
+%
+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
+\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.
+%
+As maintainers, we aim at importing files from upstream essentially
+\emphasis{unmodified}, except for renaming them to prevent name
+clashes.
+%
+This job has been greatly alleviated since the advent of
+\LUATEX-Fonts, prior to which the individual dependencies had to be
+manually spotted and extracted from the \CONTEXT source code in a
+complicated and error-prone fashion.
+
+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}
+  and requires \fileent{mtxrun}.
+  Run
+  \inlinecode {mtxrun --script package --help}
+  to display further information.
+  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.
+
+    \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
+
+  \beginnormalitem
+    The \emphasis{font loader} itself.
+    These files have been written for
+    \LUATEX-Fonts and they are distributed along
+    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
+        \beginaltitem{luatex-fonts-tfm.lua}  \endaltitem
+        \beginaltitem{luatex-fonts-chr.lua}  \endaltitem
+        \beginaltitem{luatex-fonts-lua.lua}  \endaltitem
+        \beginaltitem{luatex-fonts-inj.lua}  \endaltitem
+        \beginaltitem{luatex-fonts-otn.lua}  \endaltitem
+        \beginaltitem{luatex-fonts-def.lua}  \endaltitem
+        \beginaltitem{luatex-fonts-ext.lua}  \endaltitem
+        \beginaltitem{luatex-fonts-cbk.lua}  \endaltitem
+      \enddefinitions
+    \enddoublecolumns
+  \endnormalitem
+
+  \beginnormalitem
+    Code related to \emphasis{font handling and
+    node processing}, taken directly from
+    \CONTEXT.
+    \begindoublecolumns
+      \begindefinitions
+        \beginaltitem{data-con.lua} \endaltitem
+        \beginaltitem{font-ini.lua} \endaltitem
+        \beginaltitem{font-con.lua} \endaltitem
+        \beginaltitem{font-cid.lua} \endaltitem
+        \beginaltitem{font-map.lua} \endaltitem
+        \beginaltitem{font-oti.lua} \endaltitem
+        \beginaltitem{font-otf.lua} \endaltitem
+        \beginaltitem{font-otb.lua} \endaltitem
+        \beginaltitem{font-ota.lua} \endaltitem
+        \beginaltitem{font-def.lua} \endaltitem
+        \beginaltitem{font-otp.lua} \endaltitem
+      \enddefinitions
+    \enddoublecolumns
+  \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 {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.
+
+Also, the merged file at some point loads the Adobe Glyph List from a
+\LUA table that is contained in \fileent{luaotfload-glyphlist.lua},
+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}.
+}
+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.
+
+In addition to these, \identifier{luaotfload} requires a number of
+files not contained in the merge. Some of these have no equivalent in
+\LUATEX-Fonts or \CONTEXT, some were taken unmodified from the latter.
+
+
+\beginfilelist
+    \beginaltitem {luaotfload-features.lua}
+      font feature handling; incorporates some of the code from
+      \fileent{font-otc} from \CONTEXT;
+    \endaltitem
+    \beginaltitem {luaotfload-override.lua}
+      overrides the \CONTEXT logging functionality.
+    \endaltitem
+    \beginaltitem {luaotfload-loaders.lua}
+      registers the \OpenType font reader as handler for Postscript
+      fonts (\abbrev{pfa}, \abbrev{pfb}).
+    \endaltitem
+    \beginaltitem {luaotfload-parsers.lua}
+      various \abbrev{lpeg}-based parsers.
+    \endaltitem
+    \beginaltitem {luaotfload-database.lua}
+      font names database.
+    \endaltitem
+    \beginaltitem {luaotfload-colors.lua}
+      color handling.
+    \endaltitem
+    \beginaltitem {luaotfload-auxiliary.lua}
+      access to internal functionality for package authors (proposals
+      for additions welcome).
+    \endaltitem
+    \beginaltitem {luaotfload-letterspace.lua}
+      font-based letterspacing.
+    \endaltitem
+\endfilelist
+
+\figurefloat
+  {file-graph}
+  {Schematic of the files in \identifier{Luaotfload}}
+  {filegraph.pdf}
+
+\endsection
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\beginsection {Auxiliary Functions}
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+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).
+%
+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.
+%
+When the structure of the font object changed due to an update, all
+of these imploded and several packages had to be fixed while
+simultaneously providing fallbacks for earlier versions.
+%
+Now the patching is done on the \identifier{luaotfload} side and can
+be adapted with future modifications to font objects without touching
+the packages that depend on it.
+%
+Second, some the capabilities of the font loader and the names
+database are not immediately relevant in \identifier{luaotfload}
+itself but might nevertheless be of great value to package authors or
+end users.
+
+Note that the current interface is not yet set in stone and the
+development team is open to suggestions for improvements or
+additions.
+
+\beginsubsection {Callback Functions}
+
+The \luafunction{patch_font} callback is inserted in the wrapper
+\identifier{luaotfload} provides for the font definition callback
+(see below, page \pageref{define-font}).
+%
+At this place it allows manipulating the font object immediately after
+the font loader is done creating it.
+%
+For a short demonstration of its usefulness, here is a snippet that
+writes an entire font object to the file \fileent{fontdump.lua}:
+
+\beginlisting
+  \input luaotfload.sty
+  \directlua{
+    local dumpfile    = "fontdump.lua"
+    local dump_font   = function (tfmdata)
+      local data = table.serialize(tfmdata)
+      io.savedata(dumpfile, data)
+    end
+
+    luatexbase.add_to_callback(
+      "luaotfload.patch_font",
+      dump_font,
+      "my_private_callbacks.dump_font"
+    )
+  }
+  \font \dumpme = name:Iwona
+  \bye
+\endlisting
+
+\emphasis{Beware}: this creates a Lua file of around 150,000 lines of
+code, taking up 3~\abbrev{mb} of disk space.
+%
+By inspecting the output you can get a first impression of how a font
+is structured in \LUATEX’s memory, what elements it is composed of,
+and in what ways it can be rearranged.
+
+\beginsubsubsection {Compatibility with Earlier Versions}
+
+As has been touched on in the preface to this section, the structure
+of the object as returned by the fontloader underwent rather drastic
+changes during different stages of its development, and not all
+packages that made use of font patching have kept up with every one
+of it.
+%
+To ensure compatibility with these as well as older versions of
+some packages, \identifier{luaotfload} sets up copies of or references
+to data in the font table where it used to be located.
+%
+For instance, important parameters like the requested point size, the
+units factor, and the font name have again been made accessible from
+the toplevel of the table even though they were migrated to different
+subtables in the meantime.
+
+\endsubsubsection
+
+\beginsubsubsection{Patches}
+
+These are mostly concerned with establishing compatibility with \XETEX.
+
+\beginfunctionlist
+
+  \beginaltitem  {set_sscale_dimens}
+    Calculate \texmacro{fontdimen}s 10 and 11 to emulate \XETEX.
+  \endaltitem
+
+  \beginaltitem  {set_capheight}
+    Calculates \texmacro{fontdimen} 8 like \XETEX.
+  \endaltitem
+
+  \beginaltitem  {patch_cambria_domh}
+    Correct some values of the font \emphasis{Cambria Math}.
+  \endaltitem
+
+\endfunctionlist
+
+\endsubsection
+
+\beginsubsection {Package Author’s Interface}
+
+As \LUATEX release 1.0 is nearing, the demand for a reliable interface
+for package authors increases.
+
+\endsubsubsection
+
+\beginsubsubsection{Font Properties}
+
+Below functions mostly concern querying the different components of a
+font like for instance the glyphs it contains, or what font features
+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}.
+  \endaltitem
+
+  \beginaltitem  {aux.slot_of_name(name : string)}
+            Translates an Adobe Glyph name to the corresponding glyph
+            slot.
+  \endaltitem
+
+  \beginaltitem  {aux.name_of_slot(slot : int)}
+            The inverse of \luafunction{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}.
+  \endaltitem
+
+  \beginaltitem  {aux.provides_script(id : int, script : string)}
+            Test if a font supports \luafunction{script}.
+  \endaltitem
+
+  \beginaltitem  {aux.provides_language(id : int, script : string, language : string)}
+            Test if a font defines \luafunction{language} for a given
+            \luafunction{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}.
+  \endaltitem
+
+  \beginaltitem  {aux.get_math_dimension(id : int, dimension : string)}
+            Get the dimension \luafunction{dimension} of font \luafunction{id}.
+  \endaltitem
+
+  \beginaltitem  {aux.sprint_math_dimension(id : int, dimension : string)}
+            Same as \luafunction{get_math_dimension()}, but output the value
+            in scaled points at the \TEX end.
+  \endaltitem
+
+\endfunctionlist
+
+\endsubsubsection
+
+\beginsubsubsection{Database}
+
+%% not implemented, may come back later
+\beginfunctionlist
+%   \beginaltitem  {aux.scan_external_dir(dir : string)}
+%             Include fonts in directory \luafunction{dir} in font lookups without
+%             adding them to the database.
+%
+  \beginaltitem  {aux.read_font_index (void)}
+            Read the index file from the appropriate location (usually
+            the bytecode file \fileent{luaotfload-names.luc} somewhere
+            in the \fileent{texmf-var} tree) and return the result as a
+            table. The file is processed with each call so it is up to
+            the user to store the result for later access.
+  \endaltitem
+
+  \beginaltitem  {aux.font_index (void)}
+            Return a reference of the font names table used internally
+            by \identifier{luaotfload}. The index will be read if it
+            has not been loaded up to this point. Also a font scan that
+            overwrites the current index file might be triggered. Since
+            the return value points to the actual index, any
+            modifications to the table might influence runtime behavior
+            of \identifier{luaotfload}.
+  \endaltitem
+
+\endfunctionlist
+
+\endsubsubsection
+
+\endsubsection
+\endsection
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\beginsection {Troubleshooting}
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\beginsubsection {Database Generation}
+
+If you encounter problems with some fonts, please first update to the
+latest version of this package before reporting a bug, as
+\identifier{luaotfload} is under active development and still a moving
+target.
+%
+The development takes place on \identifier{github} at
+\hyperlink {https://github.com/lualatex/luaotfload} where there is an issue
+tracker for submitting bug reports, feature requests and the likes.
+
+Bug reports are more likely to be addressed if they contain the output
+of
+
+\beginlisting
+    luaotfload-tool --diagnose=environment,files,permissions
+\endlisting
+
+\noindent Consult the man page for a description of these options.
+
+Errors during database generation can be traced by increasing the
+verbosity level and redirecting log output to \fileent{stdout}:
+
+\beginlisting
+    luaotfload-tool -fuvvv --log=stdout
+\endlisting
+
+\noindent or to a file in \fileent{/tmp}:
+
+\beginlisting
+    luaotfload-tool -fuvvv --log=file
+\endlisting
+
+\noindent In the latter case, invoke the \inlinecode {tail(1)} utility on the
+file for live monitoring of the progress.
+
+If database generation fails, the font last printed to the terminal or
+log file is likely to be the culprit.
+%
+Please specify it when reporting a bug, and blacklist it for the time
+being (see above, page \pageref{font-blacklist}).
+
+\endsubsection
+
+\beginsubsection {Font Features}
+
+A common problem is the lack of features for some
+\OpenType fonts even when specified.
+%
+This can be related to the fact that some fonts do not provide features
+for the \inlinecode {dflt} script (see above on page \pageref{script-tag}),
+which is the default one in this package.
+%
+If this happens, assigning a noth script when the font is defined should
+fix it.
+%
+For example with \inlinecode {latn}:
+
+\beginlisting
+    \font \test = file:MyFont.otf:script=latn;+liga;
+\endlisting
+
+You can get a list of features that a font defines for scripts and
+languages by querying it in \fileent{luaotfload-tool}:
+
+\beginlisting
+    luaotfload-tool --find="Iwona" --inspect
+\endlisting
+
+\endsubsection
+
+\beginsubsection {\LUATEX Programming}
+
+Another strategy that helps avoiding problems is to not access raw
+\LUATEX internals directly.
+%
+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}
+namespace over direct manipulation of font objects. For example, raw
+access to the \luafunction{font.fonts} table like:
+
+\beginlisting
+    local somefont = font.fonts[2]
+\endlisting
+
+\noindent can render already defined fonts unusable.
+%
+Instead, the function \luafunction{font.getfont()} should be used
+because it has been replaced by a safe variant.
+
+However, \luafunction{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}.
+%
+In this case, best define you own accessor:
+
+\beginlisting
+    local unsafe_getfont = function (id)
+        local tfmdata = font.getfont (id)
+        if not tfmdata then
+            tfmdata = font.fonts[id]
+        end
+        return tfmdata
+    end
+
+    --- use like getfont()
+    local somefont = unsafe_getfont (2)
+\endlisting
+
+\endsubsection
+\endsection
+
+\beginsection {License}
+
+\identifier {luaotfload} is licensed under the terms of the
+\hyperlink [GNU General Public License version 2.0]%
+           {https://www.gnu.org/licenses/old-licenses/gpl-2.0.html}.
+Following the underlying fontloader code \identifier {luaotfload}
+recognizes only that exact version as its license.
+The „any later version” clause of the original license text as
+copyrighted by the \hyperlink [Free Software Foundation]{http://www.fsf.org/}
+\emphasis {does not apply} to either \identifier {luaotfload} or the
+code imported from \CONTEXT.
+
+The complete text of the license is given as a separate file \fileent
+{COPYING} in the toplevel directory of the
+\hyperlink [\fileent {Luaotfload} Git repository]{https://github.com/lualatex/luaotfload/blob/master/COPYING}.
+Distributions probably package it as \fileent
+{doc/luatex/luaotfload/COPYING} in the relevant \fileent {texmf} tree.
+
+\endsection
+
+\endinput
+
diff --git a/doc/luaotfload-tool.rst b/doc/luaotfload-tool.rst
new file mode 100644
index 0000000..4b1a934
--- /dev/null
+++ b/doc/luaotfload-tool.rst
@@ -0,0 +1,325 @@
+=======================================================================
+                            luaotfload-tool
+=======================================================================
+
+-----------------------------------------------------------------------
+         generate and query the Luaotfload font names database
+-----------------------------------------------------------------------
+
+:Date:                  2014-03-30
+:Copyright:             GPL v2.0
+:Version:               2.5
+:Manual section:        1
+:Manual group:          text processing
+
+SYNOPSIS
+=======================================================================
+
+**luaotfload-tool** [ -bcDfFiIlLnpqRSuvVhw ]
+
+**luaotfload-tool** --update [ --force ] [ --quiet ] [ --verbose ]
+                             [ --prefer-texmf ] [ --dry-run ]
+                             [ --formats=[+|-]EXTENSIONS ]
+                             [ --no-compress ] [ --no-strip ]
+                             [ --local ] [ --max-fonts=N ]
+
+**luaotfload-tool** --find=FONTNAME [ --fuzzy ] [ --info ] [ --inspect ]
+                                    [ --no-reload ]
+
+**luaotfload-tool** --flush-lookups
+
+**luaotfload-tool** --cache=DIRECTIVE
+
+**luaotfload-tool** --list=CRITERION[:VALUE] [ --fields=F1,F2,...,Fn ]
+
+**luaotfload-tool** --bisect=DIRECTIVE
+
+**luaotfload-tool** --help
+
+**luaotfload-tool** --version
+
+**luaotfload-tool** --show-blacklist
+
+**luaotfload-tool** --diagnose=CHECK
+
+DESCRIPTION
+=======================================================================
+
+luaotfload-tool accesses the font names database that is required by
+the *Luaotfload* package. There are two general modes: **update** and
+**query**.
+
++ **update**:  update the database or rebuild it entirely;
++ **query**:   resolve a font name or display close matches.
+
+OPTIONS
+=======================================================================
+
+update mode
+-----------------------------------------------------------------------
+--update, -u            Update the database; indexes new fonts.
+--force, -f             Force rebuilding of the database; re-indexes
+                        all fonts.
+--local, -L             Include font files in ``$PWD``. This option
+                        will cause large parts of the database to be
+                        rebuilt. Thus it is quite inefficient.
+                        Additionally, if local font files are found,
+                        the database is prevented from being saved
+                        to disk, so the local fonts need to be parsed
+                        with every invocation of ``luaotfload-tool``.
+--no-reload, -n         Suppress auto-updates to the database (e.g.
+                        when ``--find`` is passed an unknown name).
+--no-compress, -c       Do not filter the plain text version of the
+                        font index through gzip. Useful for debugging
+                        if your editor is built without zlib.
+
+--prefer-texmf, -p      Organize the file name database in a way so
+                        that it prefer fonts in the *TEXMF* tree over
+                        system fonts if they are installed in both.
+--formats=EXTENSIONS    Extensions of the font files to index.
+                        Where *EXTENSIONS* is a comma-separated list of
+                        supported file extensions (otf, ttf, ttc,
+                        dfont, pfa, and pfb).  If the list is prefixed
+                        with a ``+`` sign, the given list is added to
+                        the currently active one; ``-`` subtracts.
+                        Default: *otf,ttf,ttc,dfont*.
+                        Examples:
+
+                        1) ``--formats=-ttc,ttf`` would skip
+                           TrueType fonts and font collections;
+                        2) ``--formats=otf`` would scan only OpenType
+                           files;
+                        3) ``--formats=+pfb`` includes binary
+                           Postscript files. **Warning**: with a
+                           standard TeX Live installation this will
+                           grow the database considerably and slow down
+                           font indexing.
+
+query mode
+-----------------------------------------------------------------------
+--find=NAME             Resolve a font name; this looks up <name> in
+                        the database and prints the file name it is
+                        mapped to.
+                        ``--find`` also understands request syntax,
+                        i.e. ``--find=file:foo.otf`` checks whether
+                        ``foo.otf`` is indexed.
+--fuzzy, -F             Show approximate matches to the file name if
+                        the lookup was unsuccessful (requires
+                        ``--find``).
+
+--info, -i              Display basic information to a resolved font
+                        file (requires ``--find``).
+--inspect, -I           Display detailed information by loading the
+                        font and analyzing the font table; very slow!
+                        For the meaning of the returned fields see
+                        the LuaTeX documentation.
+                        (requires ``--find``).
+--warnings, -w          Print the warnings generated by the fontloader
+                        library (assumes ``-I``). Automatically enabled
+                        if the verbosity level exceeds 2.
+
+--list=CRITERION        Show entries, where *CRITERION* is one of the
+                        following:
+
+                        1) the character ``*``, selecting all entries;
+                        2) a field of a database entry, for instance
+                           *version* or *format**, according to which
+                           the output will be sorted.
+                           Information in an unstripped database (see
+                           the option ``--no-strip`` above) is nested:
+                           Subfields of a record can be addressed using
+                           the ``->`` separator, e. g.
+                           ``file->location``, ``style->units_per_em``,
+                           or
+                           ``names->sanitized->english->prefmodifiers``.
+                           NB: shell syntax requires that arguments
+                           containing ``->`` be properly quoted!
+                        3) an expression of the form ``field:value`` to
+                           limit the output to entries whose ``field``
+                           matches ``value``.
+
+                        For example, in order to output file names and
+                        corresponding versions, sorted by the font
+                        format::
+
+                            ./luaotfload-tool.lua --list="format" --fields="file->base,version"
+
+                        This prints::
+
+                            otf latinmodern-math.otf  Version 1.958
+                            otf lmromancaps10-oblique.otf 2.004
+                            otf lmmono8-regular.otf 2.004
+                            otf lmmonoproplt10-bold.otf 2.004
+                            otf lmsans10-oblique.otf  2.004
+                            otf lmromanslant8-regular.otf 2.004
+                            otf lmroman12-italic.otf  2.004
+                            otf lmsansdemicond10-oblique.otf  2.004
+                            ...
+
+--fields=FIELDS         Comma-separated list of fields that should be
+                        printed.
+                        Information in an unstripped database (see the
+                        option ``--no-strip`` above) is nested:
+                        Subfields of a record can be addressed using
+                        the ``->`` separator, e. g.
+                        ``file->location``, ``style->units_per_em``,
+                        or ``names->sanitized->english->subfamily``.
+                        The default is plainname,version*.
+                        (Only meaningful with ``--list``.)
+
+font and lookup caches
+-----------------------------------------------------------------------
+--flush-lookups         Clear font name lookup cache (experimental).
+
+--cache=DIRECTIVE       Cache control, where *DIRECTIVE* is one of the
+                        following:
+
+                        1) ``purge`` -> delete Lua files from cache;
+                        2) ``erase`` -> delete Lua and Luc files from
+                           cache;
+                        3) ``show``  -> print stats.
+
+debugging methods
+-----------------------------------------------------------------------
+--show-blacklist, -b    Show blacklisted files (not directories).
+--dry-run, -D           Don’t load fonts when updating the database;
+                        scan directories only.
+                        (For debugging file system related issues.)
+--no-strip              Do not strip redundant information after
+                        building the database. Warning: this will
+                        inflate the index to about two to three times
+                        the normal size.
+--max-fonts=N           Process at most *N* font files, including fonts
+                        already indexed in the count.
+--bisect=DIRECTIVE      Bisection of the font database.
+                        This mode is intended as assistance in
+                        debugging the Luatex engine, especially when
+                        tracking memleaks or buggy fonts.
+
+                        *DIRECTIVE* can be one of the following:
+
+                        1) ``run`` -> Make ``luaotfload-tool`` respect
+                           the bisection progress when running.
+                           Combined with ``--update`` and possibly
+                           ``--force`` this will only process the files
+                           from the start up until the pivot and ignore
+                           the rest.
+                        2) ``start`` -> Start bisection: create a
+                           bisection state file and initialize the low,
+                           high, and pivot indices.
+                        3) ``stop`` -> Terminate the current bisection
+                           session by deleting the state file.
+                        4) ``good`` | ``bad`` -> Mark the section
+                           processed last as “good” or “bad”,
+                           respectively. The next bisection step will
+                           continue with the bad section.
+                        5) ``status`` -> Print status information about
+                           the current bisection session. Hint: Use
+                           with higher verbosity settings for more
+                           output.
+
+                        A bisection session is initiated by issuing the
+                        ``start`` directive. This sets the pivot to the
+                        middle of the list of available font files.
+                        Now run *luaotfload-tool* with the ``--update``
+                        flag set as well as ``--bisect=run``: only the
+                        fonts up to the pivot will be considered. If
+                        that task exhibited the issue you are tracking,
+                        then tell Luaotfload using ``--bisect=bad``.
+                        The next step of ``--bisect=run`` will continue
+                        bisection with the part of the files below the
+                        pivot.
+                        Likewise, issue ``--bisect=good`` in order to
+                        continue with the fonts above the pivot,
+                        assuming the tested part of the list did not
+                        trigger the bug.
+
+                        Once the culprit font is tracked down, ``good``
+                        or ``bad`` will have no effect anymore. ``run``
+                        will always end up processing the single font
+                        file that was left.
+                        Use ``--bisect=stop`` to clear the bisection
+                        state.
+
+miscellaneous
+-----------------------------------------------------------------------
+--verbose=N, -v         Set verbosity level to *n* or the number of
+                        repetitions of ``-v``.
+--quiet                 No verbose output (log level set to zero).
+--log=CHANNEL           Redirect log output (for database
+                        troubleshooting), where *CHANNEL* can be
+
+                        1) ``stdout`` -> all output will be
+                           dumped to the terminal (default); or
+                        2) ``file`` -> write to a file to the temporary
+                           directory (the name will be chosen
+                           automatically.
+
+--version, -V           Show version numbers of components as well as
+                        some basic information and exit.
+--help, -h              Show help message and exit.
+
+--diagnose=CHECK        Run the diagnostic procedure *CHECK*. Available
+                        procedures are:
+
+                        1) ``files`` -> check *Luaotfload* files for
+                           modifications;
+                        2) ``permissions`` -> check permissions of
+                           cache directories and files;
+                        3) ``environment`` -> print relevant
+                            environment and kpse variables;
+                        4) ``repository`` -> check the git repository
+                           for new releases,
+                        5) ``index`` -> check database, display
+                           information about it.
+
+                        Procedures can be chained by concatenating with
+                        commas, e.g. ``--diagnose=files,permissions``.
+                        Specify ``thorough`` to run all checks.
+
+FILES
+=======================================================================
+
+The font name database is usually located in the directory
+``texmf-var/luatex-cache/generic/names/`` (``$TEXMFCACHE`` as set in
+``texmf.cnf``) of your *TeX Live* distribution as a zlib-compressed
+file ``luaotfload-names.lua.gz``.
+The experimental lookup cache will be created as
+``luaotfload-lookup-cache.lua`` in the same directory.
+These Lua tables are not used directly by Luaotfload, though.
+Instead, they are compiled to Lua bytecode which is written to
+corresponding files with the extension ``.luc`` in the same directory.
+When modifying the files by hand keep in mind that only if the bytecode
+files are missing will Luaotfload use the plain version instead.
+Both kinds of files are safe to delete, at the cost of regenerating
+them with the next run of *LuaTeX*.
+
+SEE ALSO
+=======================================================================
+
+**luatex** (1), **lua** (1)
+
+* ``texdoc luaotfload`` to display the manual for the *Luaotfload*
+  package
+* Luaotfload development `<https://github.com/lualatex/luaotfload>`_
+* LuaLaTeX mailing list  `<http://tug.org/pipermail/lualatex-dev/>`_
+* LuaTeX                 `<http://luatex.org/>`_
+* ConTeXt                `<http://wiki.contextgarden.net>`_
+* Luaotfload on CTAN     `<http://ctan.org/pkg/luaotfload>`_
+
+BUGS
+=======================================================================
+
+Tons, probably.
+
+AUTHORS
+=======================================================================
+
+*Luaotfload* is maintained by the LuaLaTeX dev team
+(`<https://github.com/lualatex/>`__).
+The fontloader code is provided by Hans Hagen of Pragma ADE, Hasselt
+NL (`<http://pragma-ade.com/>`__).
+
+This manual page was written by Philipp Gesang
+<philipp.gesang@alumni.uni-heidelberg.de>.
+
diff --git a/doc/luaotfload.conf.example b/doc/luaotfload.conf.example
new file mode 100644
index 0000000..2756d62
--- /dev/null
+++ b/doc/luaotfload.conf.example
@@ -0,0 +1,30 @@
+;; Example configuration file for Luaotfload. This file contains the
+;; defaults only, see luaotfload.conf(5) for more information.
+
+[db]
+    compress        = true
+    formats         = otf, ttf, ttc, dfont
+    max-fonts       = 2.2517998136852e15
+    scan-local      = false
+    skip-read       = false
+    strip           = true
+    update-live     = true
+
+[misc]
+    statistics      = false
+    termwidth       = nil
+
+[paths]
+    cache-dir       = fonts
+    names-dir       = names
+    index-file      = luaotfload-names.lua
+    lookups-file    = luaotfload-lookup-cache.lua
+
+[run]
+    color-callback  = pre_linebreak_filter
+    definer         = patch
+    log-level       = 0
+    resolver        = cached
+
+;; vim:ft=dosini:et:sw=4:ts=8
+
diff --git a/doc/luaotfload.conf.rst b/doc/luaotfload.conf.rst
new file mode 100644
index 0000000..774095b
--- /dev/null
+++ b/doc/luaotfload.conf.rst
@@ -0,0 +1,347 @@
+=======================================================================
+                            luaotfload.conf
+=======================================================================
+
+-----------------------------------------------------------------------
+                     Luaotfload configuration file
+-----------------------------------------------------------------------
+
+:Date:                  2014-06-09
+:Copyright:             GPL v2.0
+:Version:               2.5
+:Manual section:        5
+:Manual group:          text processing
+
+SYNOPSIS
+=======================================================================
+
+- **./luaotfload{.conf,rc}**
+- **XDG_CONFIG_HOME/luaotfload/luaotfload{.conf,rc}**
+- **~/.luaotfloadrc**
+
+DESCRIPTION
+=======================================================================
+
+The file ``luaotfload.conf`` contains configuration options for
+*Luaotfload*, a font loading and font management component for LuaTeX.
+
+
+EXAMPLE
+=======================================================================
+
+A small Luaotfload configuration file with few customizations could
+look as follows: ::
+
+    [db]
+        formats = afm, pfa, pfb
+        compress = false
+    
+    [misc]
+        termwidth = 60
+    
+    [run]
+        log-level = 6
+
+This will make Luaotfload ignore all font files except for PostScript
+formats. NB: With a default Tex Live install the PS fonts will take
+much longer to index than OpenType or TrueType ones. Also, an
+uncompressed index file will be dumped which is going to be much larger
+due to the huge amount of PostScript fonts indexed. The terminal width
+is truncated to 60 characters which influences the verbose output
+during indexing. Finally, the verbosity is increased greatly: each font
+file being processed will be printed to the stdout on a separate line,
+along with lots of other information.
+
+To observe the difference in behavior, save above snippet to
+``./luaotfload.conf`` and update the font index: ::
+
+    luaotfload --update --force
+
+
+SYNTAX
+=======================================================================
+
+The configuration file syntax follows the common INI format. For a more
+detailed description please refer to the section “CONFIGURATION FILE”
+of **git-config**\(1). A brief list of rules is given below:
+
+  * Blank lines and lines starting with a semicolon (``;``) are ignored.
+
+  * A configuration file is partitioned into sections that are declared
+    by specifying the section title in brackets on a separate line: ::
+
+        [some-section]
+        ... section content ...
+
+  * Sections consist of one or more variable assignments of the form
+    ``variable-name = value``  E. g.::
+
+        [foo]
+            bar = baz
+            quux = xyzzy
+            ...
+
+  * Section and variable names may contain only uppercase and lowercase
+    letters as well as dashes (``-``).
+
+
+VARIABLES
+=======================================================================
+
+Variables in belong into a configuration section and their values must
+be of a certain type. Some of them have further constraints. For
+example, the “color callback” must be a string of one of the values
+``pre_linebreak_filter`` or ``pre_output_filter``, defined in the
+section *run*.
+
+Currently, the configuration is organized into four sections:
+
+db
+    Options relating to the font index.
+
+misc
+    Options without a clearly defined category.
+
+paths
+    Path and file name settings.
+
+run
+    Options controlling runtime behavior of Luaotfload.
+
+The list of valid variables, the sections they are part of and their
+type is given below. Types represent Lua types that the values must be
+convertible to; they are abbreviated as follows: ``s`` for the *string*
+type, ``n`` for *number*, ``b`` for *boolean*. A value of ``nil`` means
+the variable is unset.
+
+
+Section ``db``
+-----------------------------------------------------------------------
+
++---------------+--------+---------------------------+
+|  variable     |  type  |  default                  |
++---------------+--------+---------------------------+
+|  compress     |   b    |  ``true``                 |
++---------------+--------+---------------------------+
+|  formats      |   s    |  ``"otf,ttf,ttc,dfont"``  |
++---------------+--------+---------------------------+
+|  max-fonts    |   n    |  ``2^51``                 |
++---------------+--------+---------------------------+
+|  scan-local   |   b    |  ``false``                |
++---------------+--------+---------------------------+
+|  skip-read    |   b    |  ``false``                |
++---------------+--------+---------------------------+
+|  strip        |   b    |  ``true``                 |
++---------------+--------+---------------------------+
+|  update-live  |   b    |  ``true``                 |
++---------------+--------+---------------------------+
+
+The flag ``compress`` determines whether the font index (usually
+``luaotfload-names.lua[.gz]`` will be stored in compressed forms.
+If unset it is equivalent of passing ``--no-compress`` to
+**luaotfload-tool**. Since the file is only created for convenience
+and has no effect on the runtime behavior of Luaotfload, the flag
+should remain set. Most editors come with zlib support anyways.
+
+The list of ``formats`` must be a comma separated sequence of strings
+containing one or more of these elements:
+
+* ``otf``               (OpenType format),
+* ``ttf`` and ``ttc``   (TrueType format),
+* ``dfont``             (Macintosh TrueType format),
+* ``afm``               (Adobe Font Metrics),
+* ``pfb`` and ``pfa``   (PostScript format).
+
+It corresponds loosely to the ``--formats`` option to
+**luaotfload-tool**. Invalid or duplicate members are ignored; if the
+list does not contain any useful identifiers, the default list
+``"otf,ttf,ttc,dfont"`` will be used.
+
+The variable ``max-fonts`` determines after processing how many font
+files the font scanner will terminate the search. This is useful for
+debugging issues with the font index and has the same effect as the
+option ``--max-fonts`` to **luaotfload-tools**.
+
+The ``scan-local`` flag, if set, will incorporate the current working
+directory as a font search location. NB: This will potentially slow
+down document processing because a font index with local fonts will not
+be saved to disk, so these fonts will have to be re-indexed whenever
+the document is built.
+
+The ``skip-read`` flag is only useful for debugging: It makes
+Luaotfload skip reading fonts. The font information for rebuilding the
+index is taken from the presently existing one.
+
+Unsetting the ``strip`` flag prevents Luaotfload from removing data
+from the index that is only useful when processing font files. NB: this
+can increase the size of the index files significantly and has no
+effect on the runtime behavior.
+
+If ``update-live`` is set, Luaotfload will reload the database if it
+cannot find a requested font. Those who prefer to update manually using
+**luaotfload-tool** should unset this flag.
+
+
+Section ``default-features``
+-----------------------------------------------------------------------
+
+By default Luaotfload enables ``node`` mode and picks the default font
+features that are prescribed in the OpenType standard. This behavior
+may be overridden in the ``default-features`` section. Global defaults
+that will be applied for all scripts can be set via the ``global``
+option, others by the script they are to be applied to. For example,
+a setting of ::
+
+  [default-features]
+      global = mode=base,color=0000FF
+      dflt   = smcp,onum
+
+would force *base* mode, tint all fonts blue and activate small
+capitals and text figures globally. Features are specified as a comma
+separated list of variables or variable-value pairs. Variables without
+an explicit value are set to ``true``.
+
+
+Section ``misc``
+-----------------------------------------------------------------------
+
++---------------+--------+-------------------------+
+|  variable     |  type  |  default                |
++---------------+--------+-------------------------+
+|  statistics   |   b    |  ``false``              |
++---------------+--------+-------------------------+
+|  termwidth    |   n    |  ``nil``                |
++---------------+--------+-------------------------+
+|  version      |   s    |  <Luaotfload version>   |
++---------------+--------+-------------------------+
+
+With ``statistics`` enabled, extra statistics will be collected during
+index creation and appended to the index file. It may then be queried
+at the Lua end or inspected by reading the file itself.
+
+The value of ``termwidth``, if set, overrides the value retrieved by
+querying the properties of the terminal in which Luatex runs. This is
+useful if the engine runs with ``shell_escape`` disabled and the actual
+terminal dimensions cannot be retrieved.
+
+The value of ``version`` is derived from the version string hard-coded
+in the Luaotfload source. Override at your own risk.
+
+
+Section ``paths``
+-----------------------------------------------------------------------
+
++------------------+--------+------------------------------------+
+|  variable        |  type  |  default                           |
++------------------+--------+------------------------------------+
+|  cache-dir       |   s    |  ``"fonts"``                       |
++------------------+--------+------------------------------------+
+|  names-dir       |   s    |  ``"names"``                       |
++------------------+--------+------------------------------------+
+|  index-file      |   s    |  ``"luaotfload-names.lua"``        |
++------------------+--------+------------------------------------+
+|  lookups-file    |   s    |  ``"luaotfload-lookup-cache.lua"`` |
++------------------+--------+------------------------------------+
+
+The paths ``cache-dir`` and ``names-dir`` determine the subdirectory
+inside the Luaotfload subtree of the ``luatex-cache`` directory where
+the font cache and the font index will be stored, respectively.
+
+Inside the index directory, the names of the index file and the font
+lookup cache will be derived from the respective values of
+``index-file`` and ``lookups-file``. This is the filename base for the
+bytecode compiled version as well as -- for the index -- the gzipped
+version.
+
+
+Section ``run``
+-----------------------------------------------------------------------
+
++------------------+--------+------------------------------+
+|  variable        |  type  |  default                     |
++------------------+--------+------------------------------+
+|  color-callback  |   s    |  ``"pre_linebreak_filter"``  |
++------------------+--------+------------------------------+
+|  definer         |   s    |  ``"patch"``                 |
++------------------+--------+------------------------------+
+|  log-level       |   n    |  ``0``                       |
++------------------+--------+------------------------------+
+|  resolver        |   s    |  ``"cached"``                |
++------------------+--------+------------------------------+
+
+The ``color-callback`` option determines the stage at which fonts that
+defined with a ``color=xxyyzz`` feature will be colorized. By default
+this happens in a ``pre_linebreak_filter`` but alternatively the
+``pre_output_filter`` may be chosen, which is faster but might produce
+inconsistent output. The latter also was the default in the 1.x series
+of Luaotfload.
+
+The ``definer`` allows for switching the ``define_font`` callback.
+Apart from the default ``patch`` one may also choose the ``generic``
+one that comes with the vanilla fontloader. Beware that this might
+break tools like Fontspect that rely on the ``patch_font`` callback
+provided by Luaotfload to perform important corrections on font data.
+
+The value of ``log-level`` sets the default verbosity of messages
+printed by Luaotfload. Only messages defined with a verbosity of less
+than or equal to the supplied value will be output on the terminal.
+At a log level of five Luaotfload can be very noisy. Also, printing too
+many messages will slow down the interpreter due to line buffering
+being disabled (see **setbuf**\(3)).
+
+The ``resolver`` setting allows choosing the font name resolution
+function: With the default value ``cached`` Luaotfload saves the result
+of a successful font name request to a cache file to speed up
+subsequent lookups. The alternative, ``normal`` circumvents the cache
+and resolves every request individually. (Since to the restructuring of
+the font name index in Luaotfload 2.4 the performance difference
+between the cached and uncached lookups should be marginal.)
+
+
+FILES
+=======================================================================
+
+Luaotfload only processes the first configuration file it encounters at
+one of the search locations. The file name may be either
+``luaotfload.conf`` or ``luaotfloadrc``, except for the dotfile in the
+user’s home directory which is expected at ``~/.luaotfloadrc``.
+
+Configuration files are located following a series of steps. The search
+terminates as soon as a suitable file is encountered. The sequence of
+locations that Luaotfload looks at is
+
+i.    The current working directory of the LuaTeX process.
+ii.   The subdirectory ``luaotfload/`` inside the XDG configuration
+      tree, e. g. ``/home/oenothea/config/luaotfload/``.
+iii.  The dotfile.
+iv.   The *TEXMF* (using kpathsea).
+
+
+SEE ALSO
+=======================================================================
+
+**luaotfload-tool**\(1), **luatex**\(1), **lua**\(1)
+
+* ``texdoc luaotfload`` to display the PDF manual for the *Luaotfload*
+  package
+* Luaotfload development `<https://github.com/lualatex/luaotfload>`_
+* LuaLaTeX mailing list  `<http://tug.org/pipermail/lualatex-dev/>`_
+* LuaTeX                 `<http://luatex.org/>`_
+* Luaotfload on CTAN     `<http://ctan.org/pkg/luaotfload>`_
+
+
+REFERENCES
+=======================================================================
+
+* The XDG base specification
+  `<http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html>`_.
+
+AUTHORS
+=======================================================================
+
+*Luaotfload* is maintained by the LuaLaTeX dev team
+(`<https://github.com/lualatex/>`_).
+
+This manual page was written by Philipp Gesang
+<philipp.gesang@alumni.uni-heidelberg.de>.
+