[latex3-commits] [git/LaTeX3-latex3-latex2e] hook-args: Some documentation (3624124b)

[PhelypeOleinik]

Repository : https://github.com/latex3/latex2e
On branch  : hook-args
Link       : https://github.com/latex3/latex2e/commit/3624124b3e40aa84525264e94545157e39d964c1

>---------------------------------------------------------------

commit 3624124b3e40aa84525264e94545157e39d964c1
Author: PhelypeOleinik <phelype.oleinik at latex-project.org>
Date:   Tue Mar 21 00:40:42 2023 -0300

    Some documentation


>---------------------------------------------------------------

3624124b3e40aa84525264e94545157e39d964c1
 base/lthooks.dtx | 47 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 47 insertions(+)

diff --git a/base/lthooks.dtx b/base/lthooks.dtx
index 20476ba9..d381c699 100644
--- a/base/lthooks.dtx
+++ b/base/lthooks.dtx
@@ -1549,6 +1549,53 @@
 %    conciderably.
 %
 %
+% \subsection{Hooks with arguments}
+% \label{sec:hook-args}
+%
+%    Sometimes it is necessary to pass contextual information to a hook,
+%    and, for one reason or another, it is not feasible to store such
+%    information in macros.  To serve this purpose, hooks can be
+%    declared with arguments, so that the programmer can pass along the
+%    data necessary for the code in the hook to function properly.
+%    
+%    A hook with arguments works mostly like a regular hook, and most
+%    commands that work for regular hooks, also work for hooks that take
+%    arguments.  The differences are when the hook is declared
+%    (\cs{NewHookWithArguments} is used instead of \cs{NewHook}), then
+%    code can be added with both \cs{AddToHook} and
+%    \cs{AddToHookWithArguments}, and when the hook is used
+%    (\cs{UseHookWithArguments} instead of \cs{UseHook}).
+%    
+%    A hook with arguments must be declared as such with
+%    \cs{NewHookWithArguments}\Arg{hook}\Arg{number}.  All code added to
+%    that hook can then use \verb|#1| to access the first argument,
+%    \verb|#2| to access the second, and so forth up to the number of
+%    arguments declared.  However, it is still possible to add code with
+%    references to the arguments of a hook that was not yet declared
+%    (we will discuss that later).  At their core, hooks are macros, so
+%    \TeX's limit of 9~arguments applies, and a low-level \TeX{} error
+%    is raised if you try to reference an argument number that doesn't
+%    exist.
+%    
+%    To use a hook with arguments, just write
+%    \cs{UseHookWithArguments}\Arg{hook} followed by a braced list of
+%    the arguments.  For example, if the hook \hook{test} takes three
+%    arguments, write:
+%\begin{verbatim}
+%\UseHookWithArguments{test}{arg-1}{arg-2}{arg-3}
+%\end{verbatim}
+%    then, in the \meta{code} of the hook, all instances of \verb|#1|
+%    will be replaced by \verb|arg-1|, \verb|#2| by \verb|arg-2| and so
+%    on.  If, at the point of usage, the programmer provides more
+%    arguments than the hook is declared to take, the excess arguments
+%    are simply ignored by the hook.  Behaviour is
+%    unpredictable\footnote
+%      {The hook \emph{will} take the declared number of arguments, and
+%       what will happen depends on what was grabbed, and what the hook
+%       code does with its arguments.}
+%    if too few arguments are provided.
+%
+%
 % \subsection{Private \LaTeX{} kernel hooks}
 %
 %    There are a few places where it is absolutely essential for