summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorPhilipp Gesang <phg@phi-gamma.net>2015-11-29 22:53:50 +0100
committerPhilipp Gesang <phg@phi-gamma.net>2015-11-29 22:53:50 +0100
commit12b177a7f918797314efadf3a70afe40b3e060e5 (patch)
tree3254587ae3352186b2f6798c2a06b89cbf1d6ee0 /doc
parent3966255142bdf450ea92376349160f90a69368f8 (diff)
parent9ceba217e323ab5572ab32708af1f4e1934397a7 (diff)
downloadluaotfload-12b177a7f918797314efadf3a70afe40b3e060e5.tar.gz
Merge pull request #301 from phi-gamma/master
fixes, rc3
Diffstat (limited to 'doc')
-rw-r--r--doc/filegraph.dot2
-rw-r--r--doc/luaotfload-main.tex49
-rw-r--r--doc/luaotfload.conf.rst44
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