summaryrefslogtreecommitdiff
path: root/luatexbase-mcb.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'luatexbase-mcb.dtx')
-rw-r--r--luatexbase-mcb.dtx54
1 files changed, 28 insertions, 26 deletions
diff --git a/luatexbase-mcb.dtx b/luatexbase-mcb.dtx
index 3a86b00..5ec79c7 100644
--- a/luatexbase-mcb.dtx
+++ b/luatexbase-mcb.dtx
@@ -354,22 +354,15 @@ local err, warning, info = luatexbase.provides_module({
})
% \end{macrocode}
%
-% \subsubsection{Initialisations}
+% \subsubsection{Housekeeping}
%
-% \texttt{callbacklist} is the main list, that contains the callbacks as
-% keys and a table of the registered functions a values.
+% The main table: keys are callback names, and values are the associated
+% lists of functions.
%
% \begin{macrocode}
local callbacklist = callbacklist or { }
% \end{macrocode}
%
-% A table with the default functions of the created callbacks. See
-% \texttt{create} for further informations.
-%
-% \begin{macrocode}
-local lua_callbacks_defaults = { }
-% \end{macrocode}
-%
% Numerical codes for callback types.
%
% \begin{macrocode}
@@ -441,14 +434,25 @@ if luatexbase.luatexversion > 42 then
end
% \end{macrocode}
%
-% As we overwrite \texttt{callback.register}, we save it as
-% \texttt{internalregister}.
+% All user-defined callbacks have a default function: this property is used
+% to identify them as being user-defined. Those are kept in the following
+% table.
+%
+% \begin{macrocode}
+local lua_callbacks_defaults = { }
+% \end{macrocode}
+%
+% Overwrite |callback.register|, but save it first.
%
% \begin{macrocode}
local internalregister = internalregister or callback.register
+callback.register = function ()
+ err("function callback.register has been trapped,\n"
+ .."please use luatexbase.add_to_callback instead.")
+end
% \end{macrocode}
%
-% \subsubsection{Unsorted stuff}
+% \subsubsection{Misc}
%
% A simple function we'll use later to understand the arguments of the
% \texttt{create} function. It takes a string and returns the type
@@ -470,9 +474,14 @@ local function str_to_type(str)
end
% \end{macrocode}
%
-% This function and the following ones are only internal. This one is the
-% handler for the first type of callbacks: the ones that take a list head
-% and return true, false, or a new list head.
+% \subsubsection{Handlers}
+%
+% Normal (as opposed to user-defined) callbacks have handlers depending on
+% their type. The handler function is registered into the callback when the
+% first function is added to this callback's list. Then, when the callback
+% is called, then handler takes care of running all functions in the list.
+% When the last function is removed from the callback's list, the handler
+% is unregistered.
%
% \begin{macrocode}
-- local
@@ -556,7 +565,7 @@ local function simplehandler (name)
end
% \end{macrocode}
%
-% \subsubsection{Public functions}
+% \subsubsection{Public functions for functions management}
%
% Add a function to a callback. First check arguments.
%
@@ -732,6 +741,8 @@ function priority_in_callback (name, description)
end
% \end{macrocode}
%
+% \subsubsection{Public functions for user-defined callbacks}
+%
% This first function creates a new callback. The signature is
% \texttt{create(name, ctype, default)} where \texttt{name} is the name of
% the new callback to create, \texttt{ctype} is the type of callback, and
@@ -804,15 +815,6 @@ function call_callback(name, ...)
end
% \end{macrocode}
%
-% Finally, overwrite |callback.register| so that bails out in error.
-%
-% \begin{macrocode}
-callback.register = function ()
- err("function callback.register has been trapped,\n"
- .."please use luatexbase.add_to_callback instead.")
-end
-% \end{macrocode}
-%
% That's all folks!
%
% \begin{macrocode}