summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorPhilipp Gesang <phg42.2a@gmail.com>2013-05-05 11:37:45 +0200
committerPhilipp Gesang <phg42.2a@gmail.com>2013-05-05 11:37:45 +0200
commit1a6dba44990a59cd0fd68bc27facf2d53284576a (patch)
treedfb739da7de68074fb013ae8513c7426812ef357
parent4903e523bb3f6ad6147d32a836d2cb8cb79bee26 (diff)
downloadlualibs-1a6dba44990a59cd0fd68bc27facf2d53284576a.tar.gz
[doc] document partial loading
-rw-r--r--lualibs.dtx52
1 files changed, 42 insertions, 10 deletions
diff --git a/lualibs.dtx b/lualibs.dtx
index 4e77eb6..d6c80ed 100644
--- a/lualibs.dtx
+++ b/lualibs.dtx
@@ -130,6 +130,7 @@ and the derived file lualibs.lua.
\EnableCrossrefs
\CodelineIndex
\newcommand\TEX {\TeX\xspace}
+\newcommand\LATEX {\LaTeX\xspace}
\newcommand\LUA {Lua\xspace}
\newcommand\CONTEXT {Con\TeX t\xspace}
\def\definehighlight[#1][#2]%
@@ -177,7 +178,7 @@ and the derived file lualibs.lua.
%
% \GetFileInfo{lualibs.drv}
%
-% \title{The \textsf{lualibs} package}
+% \title{The \identifier{lualibs} package}
% \date{2013/05/04 v2.00}
% \author{Élie Roux · \email{elie.roux@telecom-bretagne.eu}\\
% Philipp Gesang · \email{philipp.gesang@alumni.uni-heidelberg.de}}
@@ -186,7 +187,7 @@ and the derived file lualibs.lua.
%
% \begin{abstract}
% Additional \LUA functions taken from the \verb|l-*| and \verb|util-*| files
-% of Con\TeX t.
+% of \CONTEXT.
% For an introduction on this package (among others), please refer
% to the document \fileent{lualatex-doc.pdf}.
% \end{abstract}
@@ -203,7 +204,7 @@ and the derived file lualibs.lua.
% to be used by various Lua\TeX\ packages. The code is specific to Lua\TeX\
% and depends on Lua\TeX\ functions and modules not available in regular lua.
%
-% \noindent The code is derived from Con\TeX t libraries.
+% \noindent The code is derived from \CONTEXT libraries.
%
% \section{Usage}
%
@@ -214,7 +215,37 @@ and the derived file lualibs.lua.
%
% \subsection{Loading Library Collections}
%
+% The libraries are split into a \identifier{basic} and an
+% \identifier{extended} collection.
+% Though neither initialization time nor memory consumption will be noticably
+% impacted,\footnote{%
+% Note that in terms of code this is only a small fraction of what
+% \CONTEXT loads with every run.
+% }
+% the \identifier{lualibs} package can skip loading of the latter on demand.
+% The \luafunction{config} table needs to be present prior to loading the
+% package for this to work (in the future this may be achieved by an option of
+% \texmacro{usepackage}) for \LATEX users).
+% In the \verb|lualibs| field, set \verb|load_extended| to false:
%
+% \begin{quote}\begin{verbatim}
+% \directlua{
+% --- 1) create config table safely
+% config = config or { }
+% config.lualibs = config.lualibs or { }
+%
+% --- 2) unset the load_extended entry
+% config.lualibs.load_extended = false
+%
+% --- 3) load the lualibs
+% require "lualibs"
+% }
+% \end{verbatim}\end{quote}
+%
+% However, there is no guarantee that the \identifier{extended} set remains
+% permanently excluded.
+% Re-loading the package at a later point will cancel this option and possibly
+% add the missing libraries.
%
% \subsection{Loading libraries Individually}
% In order to load the \fileent{table} module you would actually have to prepare
@@ -226,25 +257,26 @@ and the derived file lualibs.lua.
% require"lualibs-table"
% \end{verbatim}\end{quote}
%
-% \noindent If your code is running under \textsf{texlua}, you will need to
-% initialize \textsf{kpse} library so that |require()| can find files under
-% TEXMF tree: |kpse.set_program_name("luatex")|.
+% \noindent
+% If your code is run by the \fileent{texlua} intepreter, you will need to
+% initialize \luafunction{kpse} library so that |require()| can find files
+% under \abbrev{texmf} tree: |kpse.set_program_name("luatex")|.
%
% \section{Files}
%
-% The \textsf{lualibs} bundle contains files from two Con\TeX t Lua
+% The \identifier{lualibs} bundle contains files from two \CONTEXT \LUA
% library categories: The generic auxiliary functions (original file prefix:
% |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 \textsf{lualibs}-prefix.
+% They were imported under the \identifier{lualibs}-prefix.
% (For a list see table~\ref{tab:extensions}.)
%
% \begin{table}[h]
% \centering
% \caption{Extensions of the Lua standard library.}
% \begin{tabular}{l l l}
-% \textsf{lualibs} name & Con\TeX t name & content \\
+% \identifier{lualibs} name & \CONTEXT name & content \\
% \hline
% lualibs-lua.lua & l-lua.lua & compatibility, library paths \\
% lualibs-lpeg.lua & l-lpeg.lua & patterns \\
@@ -274,7 +306,7 @@ and the derived file lualibs.lua.
% \centering
% \caption{Utility functions.}
% \begin{tabular}{l l l}
-% \textsf{lualibs} name & Con\TeX t name & content \\
+% \identifier{lualibs} name & \CONTEXT name & content \\
% \hline
% lualibs-util-lua.lua & util-lua.lua & operations on bytecode \\
% lualibs-util-sto.lua & util-sto.lua & table allocation \\