diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/filegraph.dot | 2 | ||||
| -rw-r--r-- | doc/luaotfload-main.tex | 49 | ||||
| -rw-r--r-- | doc/luaotfload.conf.rst | 44 |
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 |