[latex3-commits] [git/LaTeX3-latex3-latex2e] hook-args: Document l3 programming layer functions (dc0e1f73)

[PhelypeOleinik]

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

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

commit dc0e1f7341dbc106365d9b52d2d3476b0c0256da
Author: PhelypeOleinik <phelype.oleinik at latex-project.org>
Date:   Sat Mar 18 23:27:03 2023 -0300

    Document l3 programming layer functions


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

dc0e1f7341dbc106365d9b52d2d3476b0c0256da
 base/lthooks.dtx | 70 ++++++++++++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 60 insertions(+), 10 deletions(-)

diff --git a/base/lthooks.dtx b/base/lthooks.dtx
index 5f281cf6..20476ba9 100644
--- a/base/lthooks.dtx
+++ b/base/lthooks.dtx
@@ -1009,8 +1009,11 @@
 % section even in \texttt{expl3} packages, but the choice is yours.
 %
 %
-% \begin{function}
-%   {\hook_new:n,\hook_new_reversed:n,\hook_new_pair:nn}
+% \begin{function}{
+%     \hook_new:n,
+%     \hook_new_reversed:n,
+%     \hook_new_pair:nn
+%   }
 %   \begin{syntax}
 %     \cs{hook_new:n} \Arg{hook}
 %     \cs{hook_new_reversed:n} \Arg{hook}
@@ -1026,6 +1029,27 @@
 %    the current package name. See section~\ref{sec:default-label}.
 % \end{function}
 %
+% \begin{function}{
+%     \hook_new_with_args:nn,
+%     \hook_new_reversed_with_args:nn,
+%     \hook_new_pair_with_args:nnn
+%   }
+%   \begin{syntax}
+%     \cs{hook_new_with_args:nn} \Arg{hook} \Arg{number}
+%     \cs{hook_new_reversed_with_args:nn} \Arg{hook} \Arg{number}
+%     \cs{hook_new_pair_with_args:nnn} \Arg{hook-1} \Arg{hook-2} \Arg{number}
+%   \end{syntax}
+%   Creates a new \meta{hook} with normal or reverse ordering of code
+%    chunks, that takes \meta{number} arguments from the input stream
+%    when it is used. \cs{hook_new_pair_with_args:nn} creates a pair of
+%    such hooks with \Arg{hook-2} being a reversed hook.
+%    If a hook name is already taken, an error is raised and the hook
+%    is not created.
+%
+%    The \meta{hook} can be specified using the dot-syntax to denote
+%    the current package name. See section~\ref{sec:default-label}.
+% \end{function}
+%
 %
 %
 % \begin{function}{\hook_disable_generic:n}
@@ -1061,37 +1085,56 @@
 %
 %
 %
-% \begin{function}{\hook_use:n}
+% \begin{function}{\hook_use:n,\hook_use:nw}
 %   \begin{syntax}
 %     \cs{hook_use:n} \Arg{hook}
+%     \cs{hook_use:nw} \Arg{hook} \Arg{arg_1} \ldots \Arg{arg_n}
 %   \end{syntax}
 %    Executes the \Arg{hook} code followed (if set up) by the code for next
 %    invocation only, then empties that next invocation code.
+%    \cs{hook_use:nw} should be used for hooks declared with arguments,
+%    and should be followed by as many brace groups as the declared
+%    number of arguments.
 %
 %    The \meta{hook} \emph{cannot} be specified using the dot-syntax.
 %    A leading |.| is treated literally.
 % \end{function}
 %
-% \begin{function}{\hook_use_once:n}
+% \begin{function}{\hook_use_once:n,\hook_use_once:nw}
 %   \begin{syntax}
 %     \cs{hook_use_once:n} \Arg{hook}
+%     \cs{hook_use_once:nw} \Arg{hook} \Arg{arg_1} \ldots \Arg{arg_n}
 %   \end{syntax}
 %     Changes the \Arg{hook} status so that from now on any addition to
 %     the hook code is executed immediately. Then execute any
 %     \Arg{hook} code already set up.
+%    \cs{hook_use_once:nw} should be used for hooks declared with arguments,
+%    and should be followed by as many brace groups as the declared
+%    number of arguments.
 %
 %    The \meta{hook} \emph{cannot} be specified using the dot-syntax.
 %    A leading |.| is treated literally.
 % \end{function}
 %
-% \begin{function}{\hook_gput_code:nnn}
+% \begin{function}{
+%     \hook_gput_code:nnn,
+%     \hook_gput_code_with_args:nnn
+%   }
 %   \begin{syntax}
 %     \cs{hook_gput_code:nnn} \Arg{hook} \Arg{label} \Arg{code}
+%     \cs{hook_gput_code_with_args:nnn} \Arg{hook} \Arg{label} \Arg{code}
 %   \end{syntax}
 %    Adds a chunk of \meta{code} to the \meta{hook} labeled
 %    \meta{label}. If the label already exists the \meta{code} is
 %    appended to the already existing code.
 %
+%    If \cs{hook_gput_code_with_args:nnn} is used, the \meta{code}
+%    can access the arguments passed to \cs{hook_use:nw}
+%    (or~\cs{hook_use_once:nw}) with \verb|#1|, \verb|#2|, \ldots,
+%    \verb|#n| (up to the number of arguments declared for the hook).
+%    In that case, if an actual parameter token should be added to the
+%    code, it should be doubled.
+%
 %    If code is added to an external \meta{hook} (of the kernel or
 %    another package) then the convention is to use the package name
 %    as the \meta{label} not some internal module name or some other
@@ -1102,18 +1145,26 @@
 %    See section~\ref{sec:default-label}.
 % \end{function}
 %
-% \begin{function}
-%   {\hook_gput_next_code:nn}
+% \begin{function}{
+%     \hook_gput_next_code:nn,
+%     \hook_gput_next_code_with_args:nn,
+%   }
 %   \begin{syntax}
 %     \cs{hook_gput_next_code:nn} \Arg{hook} \Arg{code}
 %   \end{syntax}
 %    Adds a chunk of \meta{code} for use only in the next invocation of the
 %    \meta{hook}. Once used it is gone.
 %
+%    If \cs{hook_gput_next_code_with_args:nn} is used, the \meta{code}
+%    can access the arguments passed to \cs{hook_use:nw}
+%    (or~\cs{hook_use_once:nw}) with \verb|#1|, \verb|#2|, \ldots,
+%    \verb|#n| (up to the number of arguments declared for the hook).
+%    In that case, if an actual parameter token should be added to the
+%    code, it should be doubled.
+%
 %    This is simpler than \cs{hook_gput_code:nnn}, the code is simply
 %    appended to the hook in the order of declaration at the very end,
 %    i.e., after all standard code for the hook got executed.
-%
 %    Thus if one needs to undo what the standard does one has to do
 %    that as part of \meta{code}.
 %
@@ -1122,8 +1173,7 @@
 % \end{function}
 %
 %
-% \begin{function}
-%   {\hook_gclear_next_code:n}
+% \begin{function}{\hook_gclear_next_code:n}
 %   \begin{syntax}
 %     \cs{hook_gclear_next_code:n} \Arg{hook}
 %   \end{syntax}