[latex3-commits] [git/LaTeX3-latex3-latex2e] hook-args: More documentation (9ac1f168)

[PhelypeOleinik]

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

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

commit 9ac1f168778044f4a87e49ec22502e32fd8b6599
Author: PhelypeOleinik <phelype.oleinik at latex-project.org>
Date:   Wed Mar 22 00:24:19 2023 -0300

    More documentation


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

9ac1f168778044f4a87e49ec22502e32fd8b6599
 base/lthooks.dtx | 75 ++++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 73 insertions(+), 2 deletions(-)

diff --git a/base/lthooks.dtx b/base/lthooks.dtx
index e53fe086..c3da9df1 100644
--- a/base/lthooks.dtx
+++ b/base/lthooks.dtx
@@ -1566,7 +1566,10 @@
 %    \cs{AddToHookWithArguments}, and when the hook is used
 %    (\cs{UseHookWithArguments} instead of \cs{UseHook}).
 %
-%    A hook with arguments must be declared as such with
+%    \medskip
+%
+%    A hook with arguments must be declared as such (before it is first
+%    used, as all regular hooks) using
 %    \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
@@ -1577,12 +1580,14 @@
 %    is raised if you try to reference an argument number that doesn't
 %    exist.
 %
+%    \medskip
+%
 %    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}
+%    \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
@@ -1595,6 +1600,72 @@
 %       code does with its arguments.}
 %    if too few arguments are provided.
 %
+%    \medskip
+%
+%    Adding code to a hook with arguments can be done with
+%    \cs{AddToHookWithArguments} as well as with the regular
+%    \cs{AddToHook}, to achieve different outcomes.  The main difference
+%    when it comes to adding code to a hook, in this case, is firstly
+%    the possibility of accessing a hook's arguments, of course, and
+%    second, how parameter tokens (\verb|#|$_6$) are treated.
+%
+%    Using \cs{AddToHook} in a hook that takes arguments will work as it
+%    does for all other hooks. This allows a package developer to add
+%    arguments to a hook that otherwise had none without having to worry
+%    about compatibility.  This means that, for example:
+%\begin{verbatim}
+%    \AddToHook{test}{\def\foo#1{Hello, #1!}}
+%\end{verbatim}
+%    will define the same macro \cs[no-index]{foo} regardless if the
+%    hook \hook{test} takes arguments or not.
+%
+%    Using \cs{AddToHookWithArguments} allows the \meta{code} added to
+%    access the arguments of the hook with \verb|#1|, \verb|#2|, and so
+%    forth, up to the number of the arguments declared in the hook.
+%    This means that if one wants to add a \verb|#|$_6$ to the
+%    \meta{code} that token must be doubled in the input.  The same
+%    definition from above, using \cs{AddToHookWithArguments}, needs to
+%    be rewritten:
+%\begin{verbatim}
+%    \AddToHookWithArguments{test}{\def\foo##1{Hello, ##1!}}
+%\end{verbatim}
+%
+%    Extending the above example to use the hook arguments, we could
+%    rewrite something like (now from declaration to usage, to get the
+%    whole picture):
+%\begin{verbatim}
+%    \NewHookWithArguments{test}{1}
+%    \AddToHookWithArguments{test}{%
+%      \typeout{Defining foo with "#1"}
+%      \def\foo##1{Hello, ##1! Some text after: #1}%
+%    }
+%    \UseHook{test}{Howdy!}
+%    \ShowCommand\foo
+%\end{verbatim}
+%    Running the code above prints in the terminal:
+%\begin{verbatim}
+%    Defining foo with "Howdy!"
+%    > \foo=macro:
+%    #1->Hello, #1! Some text after: Howdy!.
+%\end{verbatim}
+%    Note how \verb|##1| in the call to \cs{AddToHookWithArguments}
+%    became \verb|#1|, and the \verb|#1| was replaced by the argument
+%    passed to the hook.  Should the hook be used again, with a
+%    different argument, the definition would naturally change.
+%
+%    \bigskip
+%
+%    It is possible to add code referencing a hook's arguments before
+%    such hook is declared and the number of hooks is fixed.  However,
+%    if some code is added to the hook, that references more arguments
+%    than will be declared for the hook, there will be a low-level
+%    \TeX{} error about an \enquote{Illegal parameter number} at the
+%    time the hook is declared, which will be hard to track down because
+%    at that point \TeX{} can't know whence the offending code came
+%    from.  Thus it is important that package writers explicitly
+%    document how many arguments (if any) each hook can take, so users
+%    of those packages know how many arguments can be referenced, and
+%    equally important, what each argument means.
 %
 % \subsection{Private \LaTeX{} kernel hooks}
 %