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