From 92c04b971e3ee97f945b462cc1ae6a26b18196d6 Mon Sep 17 00:00:00 2001
From: Philipp Gesang <phg42.2a@gmail.com>
Date: Sat, 4 May 2013 22:24:55 +0200
Subject: add some documentation to ``lualibs-basic.lua`` and
 ``lualibs-merged.lua``

---
 lualibs-basic.lua    | 19 +++++++++++++------
 lualibs-extended.lua | 45 +++++++++++++++++++++++++++++++++------------
 2 files changed, 46 insertions(+), 18 deletions(-)

diff --git a/lualibs-basic.lua b/lualibs-basic.lua
index cd28e75..6c14e9f 100644
--- a/lualibs-basic.lua
+++ b/lualibs-basic.lua
@@ -1,4 +1,6 @@
-lualibs = lualibs or { }
+lualibs                 = lualibs or { }
+local info              = lualibs.info
+local loadmodule        = lualibs.loadmodule
 
 local lualibs_basic_module = {
   name          = "lualibs-basic",
@@ -10,12 +12,8 @@ local lualibs_basic_module = {
   license       = "See ConTeXt's mreadme.pdf for the license",
 }
 
-local error, warn, info = lualibs.error, lualibs.warn, lualibs.info
+local loaded = false --- track success of package loading
 
-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')
@@ -24,6 +22,15 @@ else
   info"Falling back to individual libraries from collection “basic”."
 end
 
+--[[doc--
+
+    \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.
+
+--doc]]--
+
 if loaded == false then
   loadmodule("lualibs-lua.lua")
   loadmodule("lualibs-package.lua")
diff --git a/lualibs-extended.lua b/lualibs-extended.lua
index 293df39..db790bd 100644
--- a/lualibs-extended.lua
+++ b/lualibs-extended.lua
@@ -1,5 +1,20 @@
 lualibs = lualibs or { }
 
+--[[doc--
+
+    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.
+
+--doc]]--
+
 local lualibs_extended_module = {
   name          = "lualibs-extended",
   version       = 2.00,
@@ -10,7 +25,6 @@ local lualibs_extended_module = {
   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
@@ -18,9 +32,12 @@ 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.
+
+    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
@@ -42,16 +59,20 @@ else
   logger = mklog"INFO"
 end
 
+local info = lualibs.info
+
 --[[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.
+
+    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
-- 
cgit v1.2.3