From ec15f7b21d34db663b9ef626f47cce4d463135fb Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Manuel=20P=C3=A9gouri=C3=A9-Gonnard?= <mpg@elzevir.fr>
Date: Sun, 28 Mar 2010 23:12:05 +0200
Subject: Document loader.

---
 luatexbase-loader.dtx | 29 ++++++++++++++++++++++++++++-
 1 file changed, 28 insertions(+), 1 deletion(-)

diff --git a/luatexbase-loader.dtx b/luatexbase-loader.dtx
index a6fa7e7..8584aa9 100644
--- a/luatexbase-loader.dtx
+++ b/luatexbase-loader.dtx
@@ -122,10 +122,33 @@ See source file '\inFileName' for details.
 % \maketitle
 %
 % \begin{abstract}
+% Lua modules are loaded using the |require()| function which, similarly to
+% \tex's |\input|, takes care of locating the file and load it, but also makes
+% a few supplementary checks, for example to avoid loading the same module
+% twice. This package adapts the way the files are searched in order to
+% accomodate the TDS as well as usual Lua naming conventions.
+%
+% For higher-level functions related to Lua modules, see
+% \href{file:luatexbase-modutils.pdf}{\pk{luatexbase-modutils}}, which also
+% loads the present package.
 % \end{abstract}
 %
 % \section{Documentation}
 %
+% Starting with \luatex 0.45.0, |require()| uses Kpathsea for file searching
+% when the library is initalised (which is always the case in \tex mode, unless
+% explicitly disabled by the user). However, it does not respect the Lua
+% convention that |require("foo.bar")| should look for |foo/bar.lua|.
+%
+% This package implements such behaviour. More precisely, it looks for file
+% |foo/bar| using Kpathsea with the format |lua| (that is, search along
+% |LUAINPUTS| and try the following extensions:  |.luc|, |.luctex|, |.texluc|,
+% |.lua|, |.luatex|, |.texlua|). If this search fails, it falls back to
+% |foo.bar|.
+%
+% It also implements this behaviour with older versions of \luatex (or it soon
+% will).
+%
 %    \section{Implementation}
 %
 %    \subsection{\tex package}
@@ -219,7 +242,9 @@ See source file '\inFileName' for details.
 %
 %    \subsubsection{Main content}
 %
-%    Load the supporting Lua module.
+%    Load the supporting Lua module. This one doesn't follow the usual naming
+%    conventions, since it won't be loaded with the usual functions for
+%    obvious bootstraping reasons.
 %
 %    \begin{macrocode}
 \directlua{%
@@ -244,6 +269,8 @@ See source file '\inFileName' for details.
 module('luatexbase', package.seeall)
 %    \end{macrocode}
 %
+%    Find the full path corresponding to a mudole name.
+%
 %    \begin{macrocode}
 local function find_module_file(mod)
   return kpse.find_file(mod:gsub('%.', '/'), 'lua')
-- 
cgit v1.2.3