[doc] describe the packaging

1 files changed, 60 insertions, 3 deletions

diff --git a/lualibs.dtx b/lualibs.dtx
index 2269f66..7393605 100644
--- a/lualibs.dtx
+++ b/lualibs.dtx
@@ -290,7 +290,8 @@ and the derived file lualibs.lua.
 % |l-|) together form something close to a standard libary. Most of these are
 % extensions of an existing namespace, like for instance |l-table.lua| which
 % adds full-fledged serialization capabilities to the \LUA table library.
-% They were imported under the \identifier{lualibs}-prefix.
+% They were imported under the \identifier{lualibs}-prefix and are contained
+% in the \identifier{basic} collection.
 % (For a list see table~\ref{tab:basic}.)
 %
 % \begin{table}[t]
@@ -322,9 +323,11 @@ and the derived file lualibs.lua.
 %  \hrule
 % \end{table}
 %
-% The second category comprises a selection of files mostly from the
-% utilities namespace (|util-|; cf. table~\ref{tab:extended}).
+% The \identifier{extended} category comprises a selection of files mostly from
+% the utilities namespace (|util-|; cf. table~\ref{tab:extended}).
 % Their purpose is more specific and at times quite low-level.
+% Additionally, the file \fileent{trac-inf.lua} has been included because it is
+% essential to some of the code loaded subsequently.
 %
 % \begin{table}[t]
 %  \hrule
@@ -352,6 +355,60 @@ and the derived file lualibs.lua.
 %
 % \section{Packaging}
 %
+  By default, \identifier{lualibs} will not load the libraries individually.
+  Instead, it includes two \emphasis{merged packages} that have been compiled
+  from the original files.
+  This is achieved by means of \identifier{mtx-package}, a script for bundling
+  \LUA code shipped with \CONTEXT.
+  This concatenates the code of several \LUA files into a single file that is
+  both easier to distribute and loading (marginally) faster.
+  \identifier{mtx-package} ensures that the code from each file gets its
+  own closure and strips newlines and comments, resulting in a smaller payload.
+  Another package that relies on it heavily is the font loader as contained in
+  \identifier{luaotfload} and \identifier{luatex-fonts}.
+
+  If \CONTEXT is installed on the system, the merge files can be created
+  by running:
+  
+  \begin{quote}\begin{verbatim}
+    mtxrun --script package --merge lualibs-basic.lua
+    mtxrun --script package --merge lualibs-extended.lua
+  \end{verbatim}\end{quote}
+
+  \noindent
+  Of course there is a make target for that:
+
+  \begin{quote}\begin{verbatim}
+    make merge
+  \end{verbatim}\end{quote}
+  \noindent
+  will take care of assembling the packages from the files distributed with
+  \identifier{lualibs}.
+
+  For this to work, the syntax of the \LUA file needs to be well-formed:
+  files that should be merged must be included via a function
+  \verb|loadmodule()|.
+  It doesn’t matter if the function actually does something; a dummy will
+  suffice.
+  Also, the argument to \verb|loadmodule()| must be wrapped in parentheses.
+  This rule is quite convenient, actually, since it allows excluding files
+  from the merge while still using \verb|loadmodule()| consistently.
+
+  \begin{quote}\begin{verbatim}
+    ...
+    loadmodule("my-lua-file.lua") -- <= will be merged
+    loadmodule('my-2nd-file.lua') -- <= will be merged
+    loadmodule "my-3rd-file.lua"  -- <= will be ignored
+    ...
+  \end{verbatim}\end{quote}
+
+  Note that there is one exception to the packaging:
+  \fileent{lualibs-util-jsn.lua} cannot be successfully packaged because
+  it follows a different coding convention, returning a \LUA table on exit.
+  Therefore, the file is loaded separately as part of the \identifier{extended}
+  set like any other \LUA module.
+
+%
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 % \part{\fileent{lualibs.lua}}
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%