Merge pull request #301 from phi-gamma/master

fixes, rc3

3 files changed, 60 insertions, 35 deletions

diff --git a/doc/filegraph.dot b/doc/filegraph.dot
index af3c8ad..9773ebd 100644
--- a/doc/filegraph.dot
+++ b/doc/filegraph.dot
@@ -204,7 +204,7 @@ strict digraph luaotfload_files { //looks weird with circo ...
                            style  = "filled,rounded",
                            penwidth=2]
 
-    fontloader            [label = "fontloader-reference.lua",
+    fontloader            [label = "fontloader-YY-MM-DD.lua",
                            shape = rect,
                            width  = "3.2cm",
                            height = "1.2cm",
diff --git a/doc/luaotfload-main.tex b/doc/luaotfload-main.tex
index 28f92f7..26d7314 100644
--- a/doc/luaotfload-main.tex
+++ b/doc/luaotfload-main.tex
@@ -1105,6 +1105,7 @@ 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.
 %
+\label{package}%
 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
@@ -1120,14 +1121,24 @@ file.\footnote{%
   \fileent{util-mrg.lua} that is part of \CONTEXT.
 }
 %
-This file constitutes the “reference fontloader” and is part of the
-\identifier{luaotfload} package as \fileent{fontloader-reference.lua}.
+This file constitutes the “default fontloader” and is part of the
+\identifier{luaotfload} package as \fileent{fontloader-YY-MM-DD.lua},
+where the uppercase letters are placeholders for the build date.
+%
 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}.
+%
+Additionally, the “reference fontloader” as imported from \LUATEX-Fonts
+is provided as the file \fileent{fontloader-reference.lua}.
+%
+This file is self-contained in that it packages all the auxiliary \LUA
+libraries too, as Luaotfload did up to the 2.5 series; since that job
+has been offloaded to the \identifier{Lualibs} package, loading this
+fontloader introduces a certain code duplication.
 
 A number of \emphasis{\LUA utility libraries} are not part of the
 \identifier{luaotfload} fontloader, contrary to its equivalent in
@@ -1273,14 +1284,17 @@ files not contained in the merge. Some of these have no equivalent in
 
 \beginsubsection {Packaging}
 
+\label{sec:pkg}%
 The fontloader code is integrated as an isolated component that can be
 switched out on demand.
+%
 To specify the fontloader you wish to use, the configuration file
 (described in section \ref{sec:conf}) provides the option
 \inlinecode{fontloader}.
+%
 Its value can be one of the identifiers \inlinecode{default} or
-\inlinecode{reference} or the name of a file somewhere in the search
-path of \LUATEX.
+\inlinecode{reference} (see above, section \ref{package}) or the name
+of a file somewhere in the search path of \LUATEX.
 %
 This will make \identifier {Luaotfload} locate the \CONTEXT source by
 means of \identifier{kpathsea} lookups and use those instead of the
@@ -1298,18 +1312,12 @@ The parameter may be extended with a path to the \CONTEXT
 standalone distribution or a source repository -- outside the current
 \TEX distribution.
 
-Like the \identifier{Lualibs} package, the reference fontloader is
-deployed as a \emphasis{merged package} containing a series of \LUA
-files joined together in their expected order and stripped of
-non-significant parts.
+Like the \identifier{Lualibs} package, the fontloader is deployed as a
+\emphasis{merged package} containing a series of \LUA files joined
+together in their expected order and stripped of non-significant parts.
 %
 The \fileent{mkimport} utility assists in pulling the files from a
 \CONTEXT tree and packaging them for use with \identifier{Luaotfload}.%
-\footnote{%
-  These tasks are performed, respectively, by the build targets
-  \inlinecode{import} and \inlinecode{package} of the
-  \identifier{Luaotfload} makefile.
-}
 %
 The state of the files currently in \identifier{Luaotfload}’s
 repository can be queried:
@@ -1329,6 +1337,21 @@ Whereas the command for packaging requires a path to the
 ./scripts/mkimport package ./src/fontloader/luaotfload-package.lua fontloader-custom.lua
 \endlisting
 
+From the toplevel makefile, the targets \inlinecode{import} and
+\inlinecode{package} provide easy access to the commands as invoked during
+the \identifier{Luaotfload} build process.\footnote{%
+  \emphasis{Hint for those interested in the packaging process}: issue
+  \inlinecode{make show} for a list of available build routines.
+}
+These will call \inlinecode{mkimport} script with the correct
+parameters to generate a datestamped package.
+%
+Whether files have been updated in the upstream distribution can be
+queried by \inlinecode{./scripts/mkimport news}.
+%
+This will compare the imported files with their counterparts in the
+\CONTEXT distribution and report changes.
+
 \endsubsection
 
 \endsection
diff --git a/doc/luaotfload.conf.rst b/doc/luaotfload.conf.rst
index 12dd887..958ecee 100644
--- a/doc/luaotfload.conf.rst
+++ b/doc/luaotfload.conf.rst
@@ -297,27 +297,29 @@ break tools like Fontspect that rely on the ``patch_font`` callback
 provided by Luaotfload to perform important corrections on font data.
 
 The fontloader backend can be selected by setting the value of
-``fontloader``. Other than the default, which selects the packaged
-``reference`` loader as shipped with Luaotfload, a file name accessible
-by kpathsea can be specified. Alternatively, the individual files that
-constitute the fontloader can be loaded directly. While less efficient,
-this greatly aids debugging since error messages will reference the
-actual line numbers of the source files and explanatory comments are
-not stripped. Currently, three distinct loading strategies are
-available: ``unpackaged`` will load the batch that is part of
-Luaotfload. These contain the identical source code that the reference
-fontloader has been compiled from. Another option, ``context`` will
-attempt to load the same files by their names in the Context format
-from the search path. Consequently this option allows to use the
-version of Context that comes with the TeX distribution. Distros tend
-to prefer the stable version (“current” in Context jargon) of those
-files so certain bugs encountered in the more bleeding edge Luaotfload
-can be avoided this way. A third option is to use ``context`` with a
-colon to specify a directory prefix where the *TEXMF* is located that
-the files should be loaded from, e. g. ``context:~/context/tex/texmf-context``.
-This can be used when referencing another distribution like the Context
-minimals that is installed under a different path not indexed by
-kpathsea.
+``fontloader``. The most important choices are ``default``, which will
+load the dedicated Luaotfload fontloader, and ``reference``, the
+upstream package as shipped with Luaotfload. Other than those, a file
+name accessible via kpathsea can be specified.
+
+Alternatively, the individual files that constitute the fontloader can
+be loaded directly. While less efficient, this greatly aids debugging
+since error messages will reference the actual line numbers of the
+source files and explanatory comments are not stripped. Currently,
+three distinct loading strategies are available: ``unpackaged`` will
+load the batch that is part of Luaotfload. These contain the identical
+source code that the reference fontloader has been compiled from.
+Another option, ``context`` will attempt to load the same files by
+their names in the Context format from the search path. Consequently
+this option allows to use the version of Context that comes with the
+TeX distribution. Distros tend to prefer the stable version (“current”
+in Context jargon) of those files so certain bugs encountered in the
+more bleeding edge Luaotfload can be avoided this way. A third option
+is to use ``context`` with a colon to specify a directory prefix where
+the *TEXMF* is located that the files should be loaded from, e. g.
+``context:~/context/tex/texmf-context``. This can be used when
+referencing another distribution like the Context minimals that is
+installed under a different path not indexed by kpathsea.
 
 The value of ``log-level`` sets the default verbosity of messages
 printed by Luaotfload. Only messages defined with a verbosity of less