From 36c87427e9bba1b3ca1dc58a0d6f914ca21bc9a6 Mon Sep 17 00:00:00 2001 From: Philipp Gesang Date: Sat, 28 Nov 2015 00:08:20 +0100 Subject: [doc,init] clarify default/reference distinction * default: our package (without lualibs) * reference: the package from upstream --- doc/filegraph.dot | 2 +- doc/luaotfload-main.tex | 27 +++++++++++++++++++-------- 2 files changed, 20 insertions(+), 9 deletions(-) (limited to 'doc') 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..ad38eb6 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,15 @@ 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,10 +1310,9 @@ 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}.% -- cgit v1.2.3 From 2ccf33b69115034605e0623a5e5d70c0bed11bff Mon Sep 17 00:00:00 2001 From: Philipp Gesang Date: Sat, 28 Nov 2015 00:35:10 +0100 Subject: [doc] explain usual packaging commands --- doc/luaotfload-main.tex | 22 +++++++++++++++++----- 1 file changed, 17 insertions(+), 5 deletions(-) (limited to 'doc') diff --git a/doc/luaotfload-main.tex b/doc/luaotfload-main.tex index ad38eb6..26d7314 100644 --- a/doc/luaotfload-main.tex +++ b/doc/luaotfload-main.tex @@ -1287,9 +1287,11 @@ files not contained in the merge. Some of these have no equivalent in \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} (see above, section \ref{package}) or the name of a file somewhere in the search path of \LUATEX. @@ -1316,11 +1318,6 @@ 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: @@ -1340,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 -- cgit v1.2.3 From 91ae11f974db282b675e8582fab2c1bd5eb1f13b Mon Sep 17 00:00:00 2001 From: Philipp Gesang Date: Sat, 28 Nov 2015 00:59:43 +0100 Subject: [doc] clarify fontloader options in luaotfload.conf(5) --- doc/luaotfload.conf.rst | 44 +++++++++++++++++++++++--------------------- 1 file changed, 23 insertions(+), 21 deletions(-) (limited to 'doc') 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 -- cgit v1.2.3