Merge pull request #5 from phi-gamma/master

this could go into TeX Live

4 files changed, 696 insertions, 315 deletions

diff --git a/lualibs-basic.lua b/lualibs-basic.lua
deleted file mode 100644
index cd28e75..0000000
--- a/lualibs-basic.lua
+++ /dev/null
@@ -1,48 +0,0 @@
-lualibs = lualibs or { }
-
-local lualibs_basic_module = {
-  name          = "lualibs-basic",
-  version       = 2.00,
-  date          = "2013/04/30",
-  description   = "ConTeXt Lua libraries -- basic collection.",
-  author        = "Hans Hagen, PRAGMA-ADE, Hasselt NL & Elie Roux & Philipp Gesang",
-  copyright     = "PRAGMA ADE / ConTeXt Development Team",
-  license       = "See ConTeXt's mreadme.pdf for the license",
-}
-
-local error, warn, info = lualibs.error, lualibs.warn, lualibs.info
-
-local loadmodule      = lualibs.loadmodule
-local stringformat    = string.format
-
-local loaded = false
-if lualibs.prefer_merged then
-  info"Loading merged package for collection “basic”."
-  loaded = loadmodule('lualibs-basic-merged.lua')
-else
-  info"Ignoring merged packages."
-  info"Falling back to individual libraries from collection “basic”."
-end
-
-if loaded == false then
-  loadmodule("lualibs-lua.lua")
-  loadmodule("lualibs-package.lua")
-  loadmodule("lualibs-lpeg.lua")
-  loadmodule("lualibs-function.lua")
-  loadmodule("lualibs-string.lua")
-  loadmodule("lualibs-table.lua")
-  loadmodule("lualibs-boolean.lua")
-  loadmodule("lualibs-number.lua")
-  loadmodule("lualibs-math.lua")
-  loadmodule("lualibs-io.lua")
-  loadmodule("lualibs-os.lua")
-  loadmodule("lualibs-file.lua")
-  loadmodule("lualibs-md5.lua")
-  loadmodule("lualibs-dir.lua")
-  loadmodule("lualibs-unicode.lua")
-  loadmodule("lualibs-url.lua")
-  loadmodule("lualibs-set.lua")
-end
-
-lualibs.basic_loaded = true
--- vim:tw=71:sw=2:ts=2:expandtab
diff --git a/lualibs-extended.lua b/lualibs-extended.lua
deleted file mode 100644
index 293df39..0000000
--- a/lualibs-extended.lua
+++ /dev/null
@@ -1,157 +0,0 @@
-lualibs = lualibs or { }
-
-local lualibs_extended_module = {
-  name          = "lualibs-extended",
-  version       = 2.00,
-  date          = "2013/04/30",
-  description   = "ConTeXt Lua libraries -- extended collection.",
-  author        = "Hans Hagen, PRAGMA-ADE, Hasselt NL & Elie Roux & Philipp Gesang",
-  copyright     = "PRAGMA ADE / ConTeXt Development Team",
-  license       = "See ConTeXt's mreadme.pdf for the license",
-}
-
-local error, warn, info = lualibs.error, lualibs.warn, lualibs.info
-
-local stringformat     = string.format
-local loadmodule       = lualibs.loadmodule
-local texiowrite       = texio.write
-local texiowrite_nl    = texio.write_nl
-
---[[doc--
-Here we define some functions that fake the elaborate logging/tracking
-mechanism Context provides.
---doc]]--
-local error, logger, mklog
-if luatexbase and luatexbase.provides_module then
-  --- TODO test how those work out when running tex
-  local __error,_,_,__logger =
-    luatexbase.provides_module(lualibs_extended_module)
-  error  = __error
-  logger = __logger
-  mklog = function ( ) return logger end
-else
-  local stringformat  = string.format
-  mklog = function (t)
-    local prefix = stringformat("[%s] ", t)
-    return function (...)
-      texiowrite_nl(prefix)
-      texiowrite   (stringformat(...))
-    end
-  end
-  error  = mklog"ERROR"
-  logger = mklog"INFO"
-end
-
---[[doc--
-We temporarily put our own global table in place and restore whatever
-we overloaded afterwards.
-
-\CONTEXT\ modules each have a custom logging mechanism that can be
-enabled for debugging.
-In order to fake the presence of this facility we need to define at
-least the function \verb|logs.reporter|.
-For now it’s sufficient to make it a reference to \verb|mklog| as
-defined above.
---doc]]--
-
-local dummy_function = function ( ) end
-local newline        = function ( ) texiowrite_nl"" end
-
-local fake_logs = function (name)
-  return {
-    name     = name,
-    enable   = dummy_function,
-    disable  = dummy_function,
-    reporter = mklog,
-    newline  = newline
-  }
-end
-
-local fake_trackers = function (name)
-  return {
-    name     = name,
-    enable   = dummy_function,
-    disable  = dummy_function,
-    register = mklog,
-    newline  = newline,
-  }
-end
-
---[[doc--
-Among the libraries loaded is \verb|util-env.lua|, which adds
-\CONTEXT’s own, superior command line argument handler.
-Packages that rely on their own handling of arguments might not be
-aware of this, or the library might have been loaded by another package
-altogether.
-For these cases we provide a copy of the original \verb|arg| list and
-restore it after we are done loading.
---doc]]--
-
-local backup_store = { }
-
-local fake_context = function ( )
-  if logs     then backup_store.logs     = logs     end
-  if trackers then backup_store.trackers = trackers end
-  logs     = fake_logs"logs"
-  trackers = fake_trackers"trackers"
-
-  backup_store.argv = table.fastcopy(arg)
-end
-
-
---[[doc--
-Restore a backed up logger if appropriate.
---doc]]--
-local unfake_context = function ( )
-  if backup_store then
-    local bl, bt = backup_store.logs, backup_store.trackers
-    local argv   = backup_store.argv
-    if bl   then logs     = bl   end
-    if bt   then trackers = bt   end
-    if argv then arg      = argv end
-  end
-end
-
-fake_context()
-
-local loaded = false
-if lualibs.prefer_merged then
-  info"Loading merged package for collection “extended”."
-  loaded = loadmodule('lualibs-extended-merged.lua')
-else
-  info"Ignoring merged packages."
-  info"Falling back to individual libraries from collection “extended”."
-end
-
-if loaded == false then
-  loadmodule("lualibs-util-str.lua")--- string formatters (fast)
-  loadmodule("lualibs-util-tab.lua")--- extended table operations
-  loadmodule("lualibs-util-sto.lua")--- storage (hash allocation)
-  ----------("lualibs-util-pck.lua")---!packers; necessary?
-  ----------("lualibs-util-seq.lua")---!sequencers (function chaining)
-  ----------("lualibs-util-mrg.lua")---!only relevant in mtx-package
-  loadmodule("lualibs-util-prs.lua")--- miscellaneous parsers; cool. cool cool cool
-  ----------("lualibs-util-fmt.lua")---!column formatter (rarely used)
-  loadmodule("lualibs-util-dim.lua")--- conversions between dimensions
-  ----------("lualibs-util-jsn.lua")--- JSON parser
-
-  ----------("lualibs-trac-set.lua")---!generalization of trackers
-  ----------("lualibs-trac-log.lua")---!logging
-  loadmodule("lualibs-trac-inf.lua")--- timing/statistics
-  loadmodule("lualibs-util-lua.lua")--- operations on lua bytecode
-  loadmodule("lualibs-util-deb.lua")--- extra debugging
-  loadmodule("lualibs-util-tpl.lua")--- templating
-  loadmodule("lualibs-util-sta.lua")--- stacker (for writing pdf)
-  -------------------------------------!data-* -- Context specific
-  ----------("lualibs-util-lib.lua")---!swiglib; there is a luatex-swiglib
-  loadmodule("lualibs-util-env.lua")--- environment arguments
-  ----------("lualibs-mult-ini.lua")---
-  ----------("lualibs-core-con.lua")---
-end
-
-loadmodule"lualibs-util-jsn.lua"--- cannot be merged because of return statement
-
-unfake_context() --- TODO check if this works at runtime
-
-lualibs.extended_loaded = true
--- vim:tw=71:sw=2:ts=2:expandtab
diff --git a/lualibs.dtx b/lualibs.dtx
index 71f7b53..4e0d721 100644
--- a/lualibs.dtx
+++ b/lualibs.dtx
@@ -1,6 +1,6 @@
 % \iffalse meta-comment
 %
-% Copyright (C) 2009 by PRAGMA ADE / ConTeXt Development Team
+% Copyright (C) 2009--2013 by PRAGMA ADE / ConTeXt Development Team
 %
 % See ConTeXt's mreadme.pdf for the license.
 %
@@ -33,7 +33,7 @@
 \input docstrip.tex
 \Msg{************************************************************************}
 \Msg{* Installation}
-\Msg{* Package: lualibs 2012/10/19 v0.97 Lua additional functions.}
+\Msg{* Package: lualibs 2013/05/04 v2.00 Lua additional functions.}
 \Msg{************************************************************************}
 
 \keepsilent
@@ -67,7 +67,17 @@ and the derived file lualibs.lua.
 
 \generate{%
   \usedir{tex/luatex/lualibs}%
-  \file{lualibs.lua}{\from{lualibs.dtx}{lua}}%
+  \file{lualibs.lua}{\from{lualibs.dtx}{lualibs}}%
+}
+
+\generate{%
+  \usedir{tex/luatex/lualibs}%
+  \file{lualibs-basic.lua}{\from{lualibs.dtx}{basic}}%
+}
+
+\generate{%
+  \usedir{tex/luatex/lualibs}%
+  \file{lualibs-extended.lua}{\from{lualibs.dtx}{extended}}%
 }
 
 \obeyspaces
@@ -90,10 +100,80 @@ and the derived file lualibs.lua.
 %<*driver>
 \NeedsTeXFormat{LaTeX2e}
 \ProvidesFile{lualibs.drv}
-  [2012/10/19 v0.97 Lua additional functions.]
+  [2013/05/04 v2.00 Lua Libraries.]
 \documentclass{ltxdoc}
+\usepackage{fancyvrb,xspace}
+\usepackage[x11names]{xcolor}
+%
+\def\primarycolor{DodgerBlue4}  %%-> rgb  16  78 139 | #104e8b
+\def\secondarycolor{Goldenrod4} %%-> rgb 139 105 200 | #8b6914
+%
+\usepackage[
+    bookmarks=true,
+   colorlinks=true,
+    linkcolor=\primarycolor,
+     urlcolor=\secondarycolor,
+    citecolor=\primarycolor,
+     pdftitle={The lualibs package},
+   pdfsubject={Port of the ConTeXt Lua libraries},
+    pdfauthor={Elie Roux & Philipp Gesang},
+  pdfkeywords={luatex, lualatex, unicode, opentype}
+]{hyperref}
+\newcommand*\email[1]{\href{mailto:#1}{#1}}
+\usepackage{fontspec}
+\setmainfont[
+  Numbers=OldStyle,
+  Ligatures=TeX,
+]{Linux Libertine O}
+\setmonofont [Ligatures=TeX,Scale=MatchLowercase] {Liberation Mono}
+\setsansfont [Ligatures=TeX,Scale=MatchLowercase] {Iwona Medium}
+\usepackage{hologo}
 \EnableCrossrefs
 \CodelineIndex
+\newcommand\TEX     {\TeX\xspace}
+\newcommand\LATEX   {\LaTeX\xspace}
+\newcommand\LUA     {Lua\xspace}
+\newcommand\LUATEX  {Lua\TEX}
+\newcommand\CONTEXT {Con\TeX t\xspace}
+\def\definehighlight[#1][#2]%
+ {\ifcsname #1\endcsname\else
+    \expandafter\def\csname #1\endcsname%
+      {\bgroup#2\csname #1_indeed\endcsname}
+    \expandafter\def\csname #1_indeed\endcsname##1%
+      {##1\egroup}%
+  \fi}
+
+\def\restoreunderscore{\catcode`\_=12\relax}
+
+\definehighlight    [fileent][\ttfamily\restoreunderscore]         %% files, dirs
+\definehighlight   [texmacro][\sffamily\itshape\textbackslash]     %% cs
+\definehighlight[luafunction][\sffamily\itshape\restoreunderscore] %% lua identifiers
+\definehighlight [identifier][\sffamily]                           %% names
+\definehighlight     [abbrev][\rmfamily\scshape]                   %% acronyms
+\definehighlight   [emphasis][\rmfamily\slshape]                   %% level 1 emph
+
+\usepackage{titlesec}
+\def\movecountertomargin#1{\llap{\rmfamily\upshape#1\hskip2em}}
+\def\zeropoint{0pt}
+%% we don’t have to grab attention like a child
+\titleformat \part
+             {\normalsize\bfseries}
+             {\movecountertomargin\thepart} \zeropoint {}
+\titleformat \section
+             {\normalsize\scshape}%% no \word; life is full of disappointments
+             {\movecountertomargin\thesection} \zeropoint {}
+\titleformat \subsection
+             {\small\itshape}
+             {\movecountertomargin\thesubsection} \zeropoint {}
+\renewcommand\partname{Part}%% gets rid of the stupid “file” heading
+
+\usepackage{tocloft}
+\renewcommand \cftpartfont   {\rmfamily\upshape}
+\renewcommand \cftsecfont    {\rmfamily\upshape}
+\renewcommand \cftsubsecfont {\rmfamily\upshape}
+\setlength \cftbeforepartskip {1ex}
+\setlength \cftbeforesecskip  {1ex}
+
 \begin{document}
   \DocInput{lualibs.dtx}%
 \end{document}
@@ -119,151 +199,614 @@ and the derived file lualibs.lua.
 %
 % \GetFileInfo{lualibs.drv}
 %
-% \title{The \textsf{lualibs} package}
-% \date{2012/10/19 v0.97}
-% \author{Elie Roux \\ \texttt{elie.roux@telecom-bretagne.eu}}
+% \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}}
 %
 % \maketitle
 %
 % \begin{abstract}
-% Additional lua functions taken from the libs of Con\TeX t. For an
-% introduction on this package (among others), please refer to the document
-% \texttt{luatex-reference.pdf}.
+% Additional \LUA functions taken from the \verb|l-*| and \verb|util-*| files
+% of \CONTEXT.
+% For an introduction on this package (among others), please refer
+% to the document \fileent{lualatex-doc.pdf}.
 % \end{abstract}
 %
+% \tableofcontents
+%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% \part{Package Description}
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 % \section{Overview}
 %
-% Lua is a very minimal language, and it does not have a minimal standard
+% \LUA is a very minimal language, and it does only have a minimal standard
 % library. The aim of this package is to provide an extended standard library,
-% 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.
+% to be used by various \LUATEX packages. The code is specific to \LUATEX
+% and depends on \LUATEX 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}
 %
-% You can either load the \texttt{lualibs} module, which will load all other
-% modules, provided by this package: |require("lualibs")|, or explicitly
-% load the modules you need, e.g.: |require("lualibs-table")|, please note that
-% some modules depend on others.
+% You can either load the \identifier{lualibs} module, which will in turn load
+% one of two sets of libraries provided by this package: |require("lualibs")|, or
+% explicitly load the modules you need, e.g.: |require("lualibs-table")|,
+% please note that some modules depend on others.
+%
+% \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 { }
 %
-% \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")|.
+%     --- 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
+% it as follows:
+%
+% \begin{quote}\begin{verbatim}
+%   require"lualibs-lua"
+%   require"lualibs-lpeg"
+%   require"lualibs-table"
+% \end{verbatim}\end{quote}
+%
+% \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.
-% (For a list see table~\ref{tab:extensions}.)
+% adds full-fledged serialization capabilities to the \LUA table library.
+% 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}[h]
+% \begin{table}[t]
+%  \hrule
 %  \centering
-%  \caption{Extensions of the Lua standard library.}
+%  \caption{The \identifier{basic} set.}
+%  \vskip1em
 %  \begin{tabular}{l l l}
-%   \textsf{lualibs} name & Con\TeX t name & content                        \\
-%   \hline
-%   lualibs-lua.lua       & l-lua.lua      & compatibility, library paths   \\
-%   lualibs-lpeg.lua      & l-lpeg.lua     & patterns                       \\
-%   lualibs-function.lua  & l-function.lua & empty except for dummy         \\
-%   lualibs-string.lua    & l-string.lua   & string manipulation            \\
-%   lualibs-table.lua     & l-table.lua    & serialization, conversion      \\
-%   lualibs-boolean.lua   & l-boolean.lua  & boolean converter              \\
-%   lualibs-number.lua    & l-number.lua   & bit operations                 \\
-%   lualibs-math.lua      & l-math.lua     & math functions                 \\
-%   lualibs-io.lua        & l-io.lua       & reading and writing files      \\
-%   lualibs-os.lua        & l-os.lua       & platform specific code         \\
-%   lualibs-file.lua      & l-file.lua     & filesystem operations          \\
-%   lualibs-md5.lua       & l-md5.lua      & checksum functions             \\
-%   lualibs-dir.lua       & l-dir.lua      & directory handling             \\
-%   lualibs-unicode.lua   & l-unicode.lua  & utf and unicode                \\
-%   lualibs-url.lua       & l-url.lua      & url handling                   \\
-%   lualibs-set.lua       & l-set.lua      & sets                           \\
+%   \identifier{lualibs} name & \CONTEXT name  & primary purpose                \\[1ex]
+%   lualibs-lua.lua           & l-lua.lua      & compatibility                  \\
+%   lualibs-package.lua       & l-package.lua  & \LUA file loaders              \\
+%   lualibs-lpeg.lua          & l-lpeg.lua     & patterns                       \\
+%   lualibs-function.lua      & l-function.lua & defines a dummy function       \\
+%   lualibs-string.lua        & l-string.lua   & string manipulation            \\
+%   lualibs-table.lua         & l-table.lua    & serialization, conversion      \\
+%   lualibs-boolean.lua       & l-boolean.lua  & boolean converter              \\
+%   lualibs-number.lua        & l-number.lua   & bit operations                 \\
+%   lualibs-math.lua          & l-math.lua     & math functions                 \\
+%   lualibs-io.lua            & l-io.lua       & reading and writing files      \\
+%   lualibs-os.lua            & l-os.lua       & platform specific code         \\
+%   lualibs-file.lua          & l-file.lua     & filesystem operations          \\
+%   lualibs-md5.lua           & l-md5.lua      & checksum functions             \\
+%   lualibs-dir.lua           & l-dir.lua      & directory handling             \\
+%   lualibs-unicode.lua       & l-unicode.lua  & utf and unicode                \\
+%   lualibs-url.lua           & l-url.lua      & url handling                   \\
+%   lualibs-set.lua           & l-set.lua      & sets                           \\[1ex]
 %  \end{tabular}
-%  \label{tab:extensions}
+%  \label{tab:basic}
+%  \hrule
 % \end{table}
 %
-% The second category comprises a selection of files mostly from the
-% utilities namespace (|util-|; cf. table~\ref{tab:utilities}).
+% 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}[h]
+% \begin{table}[t]
+%  \hrule
 %  \centering
-%  \caption{Utility functions.}
+%  \caption{The \identifier{extended} set.}
+%  \vskip1em
 %  \begin{tabular}{l l l}
-%   \textsf{lualibs} name & Con\TeX t name & content                     \\
-%   \hline
-%   lualibs-util-lua.lua  & util-lua.lua   & operations on bytecode      \\
-%   lualibs-util-sto.lua  & util-sto.lua   & table allocation            \\
-%   lualibs-util-mrg.lua  & util-mrg.lua   & merging lua sources         \\
-%   lualibs-util-dim.lua  & util-dim.lua   & converters for dimensions   \\
-%   lualibs-util-str.lua  & util-str.lua   & extra string functions      \\
-%   lualibs-util-tab.lua  & util-tab.lua   & extra table functions       \\
-%   lualibs-util-jsn.lua  & util-jsn.lua   & conversion to and from json \\
+%   \identifier{lualibs} name & \CONTEXT name  & primary purpose                  \\[1ex]
+%   lualibs-util-str.lua      & util-str.lua   & extra |string| functions         \\
+%   lualibs-util-tab.lua      & util-tab.lua   & extra |table| functions          \\
+%   lualibs-util-sto.lua      & util-sto.lua   & table allocation                 \\
+%   lualibs-util-prs.lua      & util-sto.lua   & miscellaneous parsers            \\
+%   lualibs-util-dim.lua      & util-dim.lua   & conversion between dimensions    \\
+%   lualibs-trac-inf.lua      & trac-inf.lua   & timing, statistics               \\
+%   lualibs-util-lua.lua      & util-lua.lua   & operations on bytecode           \\
+%   lualibs-util-deb.lua      & util-deb.lua   & extra |debug| functionality      \\
+%   lualibs-util-tpl.lua      & util-tpl.lua   & templating                       \\
+%   lualibs-util-sta.lua      & util-sta.lua   & stacker (e.~g. for \abbrev{pdf}) \\
+%   lualibs-util-env.lua      & util-env.lua   & |argv| handling                  \\
+%   lualibs-util-jsn.lua      & util-jsn.lua   & conversion to and from json      \\[1ex]
 %  \end{tabular}
-%  \label{tab:utilities}
+%  \label{tab:extended}
+%  \hrule
 % \end{table}
 %
-% \pagebreak
-% \section{\texttt{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}}
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 %
 % \iffalse
-%<*lua>
+%<*lualibs>
 % \fi
+%    \begin{macrocode}
+lualibs = lualibs or { }
+
+lualibs.module_info = {
+  name          = "lualibs",
+  version       = 2.00,
+  date          = "2013/04/30",
+  description   = "ConTeXt Lua standard libraries.",
+  author        = "Hans Hagen, PRAGMA-ADE, Hasselt NL & Elie Roux & Philipp Gesang",
+  copyright     = "PRAGMA ADE / ConTeXt Development Team",
+  license       = "See ConTeXt's mreadme.pdf for the license",
+}
+
+%    \end{macrocode}
+%   The behavior of the lualibs can be configured to some extent.
+%   \begin{itemize}
+%     \item Based on the parameter \verb|lualibs.prefer_merged|, the
+%           libraries can be loaded via the included merged packages or
+%           the individual files.
+%     \item Two classes of libraries are distinguished, mainly because
+%           of a similar distinction in \CONTEXT, but also to make
+%           loading of the less fundamental functionality optional.
+%           While the “basic” collection is always loaded, the
+%           configuration setting \verb|lualibs.load_extended| triggers
+%           inclusion of the extended collection.
+%     \item Verbosity can be increased via the \verb|verbose| switch.
+%   \end{itemize}
+%
+%    \begin{macrocode}
+
+config           = config or { }
+config.lualibs   = config.lualibs or { }
+
+if config.lualibs.prefer_merged == nil then
+  lualibs.prefer_merged = true
+end
+if config.lualibs.load_extended == nil then
+  lualibs.load_extended = true
+end
+config.lualibs.verbose = config.lualibs.verbose == false
+
+%    \end{macrocode}
+%     The lualibs may be loaded in scripts.
+%     To account for the different environment, fallbacks for
+%     the luatexbase facilities are installed.
+%
+%    \begin{macrocode}
+
+local dofile          = dofile
+local kpsefind_file   = kpse.find_file
+local stringformat    = string.format
+local texiowrite_nl   = texio.write_nl
+
+local find_file, error, warn, info
+do
+  local _error, _warn, _info
+  if luatexbase and luatexbase.provides_module then
+    _error, _warn, _info = luatexbase.provides_module(lualibs.module_info)
+  else
+    _error, _warn, _info = texiowrite_nl, texiowrite_nl, texiowrite_nl
+  end
+
+  if lualibs.verbose then
+    error, warn, info = _error, _warn, _info
+  else
+    local dummylogger = function ( ) end
+    error, warn, info = _error, dummylogger, dummylogger
+  end
+  lualibs.error, lualibs.warn, lualibs.info = error, warn, info
+end
+
+if luatexbase and luatexbase.find_file then
+  find_file = luatexbase.find_file
+else
+  kpse.set_program_name"luatex"
+  find_file = kpsefind_file
+end
+
+%    \end{macrocode}
+%     The lualibs load a merged package by default.
+%     In order to create one of these, the meta file that includes the
+%     libraries must satisfy certain assumptions \verb|mtx-package| makes
+%     about the coding style.
+%     Most important is that the functions that indicates which files
+%     to include must go by the name \verb|loadmodule()|.
+%     For this reason we define a \verb|loadmodule()| function as a
+%     wrapper around \verb|dofile()|.
 %
 %    \begin{macrocode}
-module('lualibs', package.seeall)
-
-local lualibs_module = {
-    name          = "lualibs",
-    version       = 0.97,
-    date          = "2012/10/19",
-    description   = "Lua additional functions.",
-    author        = "Hans Hagen, PRAGMA-ADE, Hasselt NL & Elie Roux",
-    copyright     = "PRAGMA ADE / ConTeXt Development Team",
-    license       = "See ConTeXt's mreadme.pdf for the license",
+
+local loadmodule = loadmodule or function (name, t)
+  if not t then t = "library" end
+  local filepath  = find_file(name, "lua")
+  if not filepath or filepath == "" then
+    warn(stringformat("Could not locate %s “%s”.", t, name))
+    return false
+  end
+  dofile(filepath)
+  return true
+end
+
+lualibs.loadmodule = loadmodule
+
+%    \end{macrocode}
+%     The separation of the “basic” from the “extended” sets coincides
+%     with the split into luat-bas.mkiv and luat-lib.mkiv.
+%
+%    \begin{macrocode}
+
+if lualibs.basic_loaded ~= true then
+  loadmodule"lualibs-basic.lua"
+  loadmodule"lualibs-compat.lua" --- restore stuff gone since v1.*
+end
+
+if  lualibs.load_extended   == true
+and lualibs.extended_loaded ~= true then
+  loadmodule"lualibs-extended.lua"
+end
+
+--- This restores the default of loading everything should a package
+--- have requested otherwise. Will be gone once there is a canonical
+--- interface for parameterized loading of libraries.
+lualibs.load_extended = true
+
+-- vim:tw=71:sw=2:ts=2:expandtab
+
+%    \end{macrocode}
+%
+% \iffalse
+%</lualibs>
+% \fi
+%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% \part{\fileent{lualibs-basic.lua}}
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%
+% \iffalse
+%<*basic>
+% \fi
+%    \begin{macrocode}
+lualibs                 = lualibs or { }
+local info              = lualibs.info
+local loadmodule        = lualibs.loadmodule
+
+local lualibs_basic_module = {
+  name          = "lualibs-basic",
+  version       = 2.00,
+  date          = "2013/04/30",
+  description   = "ConTeXt Lua libraries -- basic collection.",
+  author        = "Hans Hagen, PRAGMA-ADE, Hasselt NL & Elie Roux & Philipp Gesang",
+  copyright     = "PRAGMA ADE / ConTeXt Development Team",
+  license       = "See ConTeXt's mreadme.pdf for the license",
+}
+
+local loaded = false --- track success of package loading
+
+if lualibs.prefer_merged then
+  info"Loading merged package for collection “basic”."
+  loaded = loadmodule('lualibs-basic-merged.lua')
+else
+  info"Ignoring merged packages."
+  info"Falling back to individual libraries from collection “basic”."
+end
+
+%    \end{macrocode}
+%     \verb|mtx-package| expects the files to be included by
+%     \verb|loadmodule|.
+%     If run on this file, it will create \verb|lualibs-basic-merged.lua|
+%     from all the files mentioned in the next block.
+%
+%    \begin{macrocode}
+
+if loaded == false then
+  loadmodule("lualibs-lua.lua")
+  loadmodule("lualibs-package.lua")
+  loadmodule("lualibs-lpeg.lua")
+  loadmodule("lualibs-function.lua")
+  loadmodule("lualibs-string.lua")
+  loadmodule("lualibs-table.lua")
+  loadmodule("lualibs-boolean.lua")
+  loadmodule("lualibs-number.lua")
+  loadmodule("lualibs-math.lua")
+  loadmodule("lualibs-io.lua")
+  loadmodule("lualibs-os.lua")
+  loadmodule("lualibs-file.lua")
+  loadmodule("lualibs-md5.lua")
+  loadmodule("lualibs-dir.lua")
+  loadmodule("lualibs-unicode.lua")
+  loadmodule("lualibs-url.lua")
+  loadmodule("lualibs-set.lua")
+end
+
+lualibs.basic_loaded = true
+-- vim:tw=71:sw=2:ts=2:expandtab
+
+%    \end{macrocode}
+%
+% \iffalse
+%</basic>
+% \fi
+%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% \part{\fileent{lualibs-extended.lua}}
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%
+% \iffalse
+%<*extended>
+% \fi
+%    \begin{macrocode}
+lualibs = lualibs or { }
+
+%    \end{macrocode}
+%     Loading the \emph{extended} set requires a tad more effort, but
+%     it’s well invested.
+%
+%     Since we only want the functionality, we have to simulate parts
+%     of a running \CONTEXT environment, above all logging, that some
+%     of the more involved libraries cannot be loaded without.
+%     Also, one utility file cannot be packaged because it returns a
+%     table which would preclude loading of later code.
+%     Thus, we remove it from the natural loading chain (it is not
+%     critical) and append it at the end.
+%
+%    \begin{macrocode}
+
+local lualibs_extended_module = {
+  name          = "lualibs-extended",
+  version       = 2.00,
+  date          = "2013/04/30",
+  description   = "ConTeXt Lua libraries -- extended collection.",
+  author        = "Hans Hagen, PRAGMA-ADE, Hasselt NL & Elie Roux & Philipp Gesang",
+  copyright     = "PRAGMA ADE / ConTeXt Development Team",
+  license       = "See ConTeXt's mreadme.pdf for the license",
 }
 
+
+local stringformat     = string.format
+local loadmodule       = lualibs.loadmodule
+local texiowrite       = texio.write
+local texiowrite_nl    = texio.write_nl
+
+%    \end{macrocode}
+%     Here we define some functions that fake the elaborate
+%     logging/tracking mechanism Context provides.
+%
+%    \begin{macrocode}
+
+local error, logger, mklog
 if luatexbase and luatexbase.provides_module then
-    luatexbase.provides_module(lualibs_module)
+  --- TODO test how those work out when running tex
+  local __error,_,_,__logger =
+    luatexbase.provides_module(lualibs_extended_module)
+  error  = __error
+  logger = __logger
+  mklog = function ( ) return logger end
+else
+  mklog = function (t)
+    local prefix = stringformat("[%s] ", t)
+    return function (...)
+      texiowrite_nl(prefix)
+      texiowrite   (stringformat(...))
+    end
+  end
+  error  = mklog"ERROR"
+  logger = mklog"INFO"
+end
+
+local info = lualibs.info
+
+%    \end{macrocode}
+%     We temporarily put our own global table in place and restore
+%     whatever we overloaded afterwards.
+%
+%     \CONTEXT\ modules each have a custom logging mechanism that can be
+%     enabled for debugging.
+%     In order to fake the presence of this facility we need to define at
+%     least the function \verb|logs.reporter|.
+%     For now it’s sufficient to make it a reference to \verb|mklog| as
+%     defined above.
+%
+%    \begin{macrocode}
+
+local dummy_function = function ( ) end
+local newline        = function ( ) texiowrite_nl"" end
+
+local fake_logs = function (name)
+  return {
+    name     = name,
+    enable   = dummy_function,
+    disable  = dummy_function,
+    reporter = mklog,
+    newline  = newline
+  }
 end
+
+local fake_trackers = function (name)
+  return {
+    name     = name,
+    enable   = dummy_function,
+    disable  = dummy_function,
+    register = mklog,
+    newline  = newline,
+  }
+end
+
 %    \end{macrocode}
+% Among the libraries loaded is \verb|util-env.lua|, which adds
+% \CONTEXT’s own, superior command line argument handler.
+% Packages that rely on their own handling of arguments might not be
+% aware of this, or the library might have been loaded by another package
+% altogether.
+% For these cases we provide a copy of the original \verb|arg| list and
+% restore it after we are done loading.
 %
-% Load the modules.
+%    \begin{macrocode}
+
+local backup_store = { }
+
+local fake_context = function ( )
+  if logs     then backup_store.logs     = logs     end
+  if trackers then backup_store.trackers = trackers end
+  logs     = fake_logs"logs"
+  trackers = fake_trackers"trackers"
+
+  backup_store.argv = table.fastcopy(arg)
+end
+
+
+%    \end{macrocode}
+% Restore a backed up logger if appropriate.
 %
 %    \begin{macrocode}
-require("lualibs-lua")
-require("lualibs-lpeg")
-require("lualibs-function")
-require("lualibs-string")
-require("lualibs-table")
-require("lualibs-boolean")
-require("lualibs-number")
-require("lualibs-math")
-require("lualibs-io")
-require("lualibs-os")
-require("lualibs-file")
-require("lualibs-md5")
-require("lualibs-dir")
-require("lualibs-unicode")
-require("lualibs-url")
-require("lualibs-set")
-require("lualibs-util-str")
---[[everything below apparently not required for the fontloader]]
-require("lualibs-util-tab")
-require("lualibs-util-sto")
-require("lualibs-util-dim")
-require("lualibs-util-jsn")
---require("lualibs-util-mrg")-- not required
---require("lualibs-util-lua")
+local unfake_context = function ( )
+  if backup_store then
+    local bl, bt = backup_store.logs, backup_store.trackers
+    local argv   = backup_store.argv
+    if bl   then logs     = bl   end
+    if bt   then trackers = bt   end
+    if argv then arg      = argv end
+  end
+end
+
+fake_context()
+
+local loaded = false
+if lualibs.prefer_merged then
+  info"Loading merged package for collection “extended”."
+  loaded = loadmodule('lualibs-extended-merged.lua')
+else
+  info"Ignoring merged packages."
+  info"Falling back to individual libraries from collection “extended”."
+end
+
+if loaded == false then
+  loadmodule("lualibs-util-str.lua")--- string formatters (fast)
+  loadmodule("lualibs-util-tab.lua")--- extended table operations
+  loadmodule("lualibs-util-sto.lua")--- storage (hash allocation)
+  ----------("lualibs-util-pck.lua")---!packers; necessary?
+  ----------("lualibs-util-seq.lua")---!sequencers (function chaining)
+  ----------("lualibs-util-mrg.lua")---!only relevant in mtx-package
+  loadmodule("lualibs-util-prs.lua")--- miscellaneous parsers; cool. cool cool cool
+  ----------("lualibs-util-fmt.lua")---!column formatter (rarely used)
+  loadmodule("lualibs-util-dim.lua")--- conversions between dimensions
+  ----------("lualibs-util-jsn.lua")--- JSON parser
+
+  ----------("lualibs-trac-set.lua")---!generalization of trackers
+  ----------("lualibs-trac-log.lua")---!logging
+  loadmodule("lualibs-trac-inf.lua")--- timing/statistics
+  loadmodule("lualibs-util-lua.lua")--- operations on lua bytecode
+  loadmodule("lualibs-util-deb.lua")--- extra debugging
+  loadmodule("lualibs-util-tpl.lua")--- templating
+  loadmodule("lualibs-util-sta.lua")--- stacker (for writing pdf)
+  -------------------------------------!data-* -- Context specific
+  ----------("lualibs-util-lib.lua")---!swiglib; there is a luatex-swiglib
+  loadmodule("lualibs-util-env.lua")--- environment arguments
+  ----------("lualibs-mult-ini.lua")---
+  ----------("lualibs-core-con.lua")---
+end
+
+loadmodule"lualibs-util-jsn.lua"--- cannot be merged because of return statement
+
+unfake_context() --- TODO check if this works at runtime
+
+lualibs.extended_loaded = true
+-- vim:tw=71:sw=2:ts=2:expandtab
+
 %    \end{macrocode}
 %
 % \iffalse
-%</lua>
+%</extended>
 % \fi
+%
 % \Finale
 \endinput
diff --git a/lualibs.lua b/lualibs.lua
index aa6a736..6ba82cc 100644
--- a/lualibs.lua
+++ b/lualibs.lua
@@ -10,6 +10,24 @@ lualibs.module_info = {
   license       = "See ConTeXt's mreadme.pdf for the license",
 }
 
+--[[doc--
+
+  The behavior of the lualibs can be configured to some extent.
+  \begin{itemize}
+    \item Based on the parameter \verb|lualibs.prefer_merged|, the
+          libraries can be loaded via the included merged packages or
+          the individual files.
+    \item Two classes of libraries are distinguished, mainly because
+          of a similar distinction in \CONTEXT, but also to make
+          loading of the less fundamental functionality optional.
+          While the “basic” collection is always loaded, the
+          configuration setting \verb|lualibs.load_extended| triggers
+          inclusion of the extended collection.
+    \item Verbosity can be increased via the \verb|verbose| switch.
+  \end{itemize}
+
+--doc]]--
+
 config           = config or { }
 config.lualibs   = config.lualibs or { }
 
@@ -19,18 +37,26 @@ end
 if config.lualibs.load_extended == nil then
   lualibs.load_extended = true
 end
-config.lualibs.verbose = config.lualibs.verbose == true
+config.lualibs.verbose = config.lualibs.verbose == false
+
+--[[doc--
+
+    The lualibs may be loaded in scripts.
+    To account for the different environment, fallbacks for
+    the luatexbase facilities are installed.
+
+--doc]]--
 
-local dofile        = dofile
-local kpsefind_file = kpse.find_file
-local stringformat  = string.format
-local texiowrit_nl  = texio.write_nl
+local dofile          = dofile
+local kpsefind_file   = kpse.find_file
+local stringformat    = string.format
+local texiowrite_nl   = texio.write_nl
 
 local find_file, error, warn, info
 do
   local _error, _warn, _info
   if luatexbase and luatexbase.provides_module then
-    _error, _warn, _info = luatexbase.provides_module(lualibs_module)
+    _error, _warn, _info = luatexbase.provides_module(lualibs.module_info)
   else
     _error, _warn, _info = texiowrite_nl, texiowrite_nl, texiowrite_nl
   end
@@ -51,9 +77,22 @@ else
   find_file = kpsefind_file
 end
 
-loadmodule = loadmodule or function (name, t)
+--[[doc--
+
+    The lualibs load a merged package by default.
+    In order to create one of these, the meta file that includes the
+    libraries must satisfy certain assumptions \verb|mtx-package| makes
+    about the coding style.
+    Most important is that the functions that indicates which files
+    to include must go by the name \verb|loadmodule()|.
+    For this reason we define a \verb|loadmodule()| function as a
+    wrapper around \verb|dofile()|.
+
+--doc]]--
+
+local loadmodule = loadmodule or function (name, t)
   if not t then t = "library" end
-  local filepath  = kpsefind_file(name, "lua")
+  local filepath  = find_file(name, "lua")
   if not filepath or filepath == "" then
     warn(stringformat("Could not locate %s “%s”.", t, name))
     return false
@@ -61,12 +100,16 @@ loadmodule = loadmodule or function (name, t)
   dofile(filepath)
   return true
 end
+
 lualibs.loadmodule = loadmodule
 
 --[[doc--
-The separation of the “basic” from the “extended” sets coincides with
-the split into luat-bas.mkiv and luat-lib.mkiv.
+
+    The separation of the “basic” from the “extended” sets coincides
+    with the split into luat-bas.mkiv and luat-lib.mkiv.
+
 --doc]]--
+
 if lualibs.basic_loaded ~= true then
   loadmodule"lualibs-basic.lua"
   loadmodule"lualibs-compat.lua" --- restore stuff gone since v1.*