Merge pull request #909 from latex3/callback_rules

Callback rules

base/changes.txt

@@ -6,6 +6,11 @@ completeness or accuracy and it contains some references to files that
 are not part of the distribution.
 ================================================================================
 
+2022-10-03  Marcel Krüger  <marcel.krueger@latex-project.org>
+
+	* ltluatex.dtx:
+	Add ordering rules for callback handlers
+
 2022-09-20  Frank Mittelbach  <Frank.Mittelbach@latex-project.org>
 
 	* ltfssdcl.dtx (section{Interface Commands}):

base/doc/ltnews36.tex

@@ -281,7 +281,6 @@ \subsection{Improve \pkg{l3docstrip} integration into \pkg{docstrip}}
 \githubissue{903}
 
 
-
 \subsection{Improve font series handling with incorrect \texttt{.fd} files}
 
 By convention, the font series value is supposed to contain no
@@ -304,6 +303,35 @@ \subsection{Improve font series handling with incorrect \texttt{.fd} files}
 \githubissue{918}
 
 
+\subsection{Rule based ordering for \LuaTeX\ callback handlers}
+
+In \hologo{LuaLaTeX} the callback handlers used to be called in the order
+they are registered in, but this was often rather fragile.
+It depends a lot on the load order and any attempts to enforce a
+different order required to unregister and reregister the handlers to
+be reordered. Additionally even if some ordering constraints where
+enforced that way another package loaded later could accidentally
+overwrite it.
+
+To improve this, we now order the callback handlers based on ordering
+rules similar to the hook rules.
+
+When registering a callback which should run before or after another
+callback, \verb+luatexbase.declare_callback_rule+ can now be used to
+record this ordering constraint.
+For example
+\begin{verbatim}
+  luatexbase.add_to_callback('pre_shaping_filter', my_handler, 'my_name')
+  luatexbase.declare_callback_rule('pre_shaping_filter', 'my_name', 'before', 'other_name')
+\end{verbatim}
+will ensure that \verb+my_handler+ will always be called before the
+handler registered as \verb+other_name+.
+
+This also means that the order in which callbacks are registered no
+longer implicitly defines an order.
+Code which relied on this implicit order should now define the order
+rules explicitly.
+
 
 \section{Bug fixes}