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

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

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

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

