[latex3-commits] [git/LaTeX3-latex3-latex2e] hook-args: Document document-level functions (5cbdc206)

[PhelypeOleinik]

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

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

commit 5cbdc2069381631ed9f52ee112d8ff36c69b9b87
Author: PhelypeOleinik <phelype.oleinik at latex-project.org>
Date:   Sat Mar 18 23:14:37 2023 -0300

    Document document-level functions


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

5cbdc2069381631ed9f52ee112d8ff36c69b9b87
 base/lthooks.dtx | 109 +++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 106 insertions(+), 3 deletions(-)

diff --git a/base/lthooks.dtx b/base/lthooks.dtx
index ec8ab9de..5f281cf6 100644
--- a/base/lthooks.dtx
+++ b/base/lthooks.dtx
@@ -148,7 +148,6 @@
 %    the current package name. See section~\ref{sec:default-label}.
 % \end{function}
 %
-%
 % \begin{function}{\NewMirroredHookPair}
 %   \begin{syntax}
 %     \cs{NewMirroredHookPair} \Arg{hook-1} \Arg{hook-2}
@@ -156,7 +155,45 @@
 %     A shorthand for
 %    \cs{NewHook}\Arg{hook-1}\cs{NewReversedHook}\Arg{hook-2}.
 %
-%    The \meta{hooks} can be specified using the dot-syntax to denote
+%    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}{\NewHookWithArguments}
+%   \begin{syntax}
+%     \cs{NewHookWithArguments} \Arg{hook} \Arg{number}
+%   \end{syntax}
+%   Creates a new \meta{hook} whose code takes \meta{number} arguments,
+%   and otherwise works exactly like \cs{NewHook}.
+%   Section~\ref{sec:hook-args} explains hooks with arguments.
+%
+%    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}{\NewReversedHookWithArguments}
+%   \begin{syntax}
+%     \cs{NewReversedHookWithArguments} \Arg{hook} \Arg{number}
+%   \end{syntax}
+%   Like \cs{NewReversedHook}, but creates a hook whose code takes
+%   \meta{number} arguments.
+%   Section~\ref{sec:hook-args} explains hooks with arguments.
+%
+%    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}{\NewMirroredHookPairWithArguments}
+%   \begin{syntax}
+%     \cs{NewMirroredHookPairWithArguments} \Arg{hook-1} \Arg{hook-2} \Arg{number}
+%   \end{syntax}
+%   A shorthand for
+%   \cs{NewHookWithArguments}\Arg{hook-1}\Arg{number}\\
+%   \cs{NewReversedHookWithArguments}\Arg{hook-2}\Arg{number}.
+%   Section~\ref{sec:hook-args} explains hooks with arguments.
+%
+%    The \meta{hook} can be specified using the dot-syntax to denote
 %    the current package name. See section~\ref{sec:default-label}.
 % \end{function}
 %
@@ -215,7 +252,7 @@
 %   \begin{syntax}
 %     \cs{UseHook} \Arg{hook}
 %   \end{syntax}
-%    Execute the hook code inside a command or environment.
+%    Execute the code stored in the \meta{hook}.
 %
 %    Before \verb=\begin{document}= the fast execution code for a hook
 %    is not set up, so in order to use a hook there it is explicitly
@@ -227,6 +264,19 @@
 %    A leading |.| is treated literally.
 % \end{function}
 %
+% \begin{function}{\UseHookWithArguments}
+%   \begin{syntax}
+%     \cs{UseHookWithArguments} \Arg{hook} \Arg{arg_1} \ldots \Arg{arg_n}
+%   \end{syntax}
+%    Execute the code stored in the \meta{hook} and pass the arguments
+%    \Arg{arg_1} through \Arg{arg_n} to the \meta{hook}.  Otherwise, it
+%    works exactly like \cs{UseHook}.
+%   Section~\ref{sec:hook-args} explains hooks with arguments.
+%
+%    The \meta{hook} \emph{cannot} be specified using the dot-syntax.
+%    A leading |.| is treated literally.
+% \end{function}
+%
 % \begin{function}{\UseOneTimeHook}
 %   \begin{syntax}
 %     \cs{UseOneTimeHook} \Arg{hook}
@@ -258,7 +308,19 @@
 %    Mixing \cs{UseHook} and \cs{UseOneTimeHook} for the same
 %    \Arg{hook} should be avoided, but if this is done then neither will execute
 %    after the first \cs{UseOneTimeHook}.
+% \end{function}
+%
+% \begin{function}{\UseOneTimeHookWithArguments}
+%   \begin{syntax}
+%     \cs{UseOneTimeHookWithArguments} \Arg{hook} \Arg{arg_1} \ldots \Arg{arg_n}
+%   \end{syntax}
+%    Works exactly like \cs{UseOneTimeHook}, but passes arguments
+%    \Arg{arg_1} through \Arg{arg_n} to the \meta{hook}.
 %
+%    It should be noted that after a one-time hook is used, it is no
+%    longer possible to use \cs{AddToHookWithArguments} or similar in
+%    that hook.  \cs{AddToHook} continues to work as normal.
+%   Section~\ref{sec:hook-args} explains hooks with arguments.
 % \end{function}
 %
 %
@@ -294,6 +356,34 @@
 %    See section~\ref{sec:default-label}.
 % \end{function}
 %
+% \begin{function}{\AddToHookWithArguments}
+%   \begin{syntax}
+%     \cs{AddToHookWithArguments} \Arg{hook}\oarg{label}\Arg{code}
+%   \end{syntax}
+%    Works exactly like \cs{AddToHook}, except that the \meta{code} can
+%    access the hooks passed to the argument using \verb|#1|, \verb|#2|,
+%    \ldots, \verb|#n| (up to the number of arguments declared for the
+%    hook).  If the \meta{code} should contain \emph{parameter tokens}
+%    (\verb|#|) that are not supposed to be understood as the arguments
+%    of the hook, such tokens should be doubled.  For example, with
+%    \cs{AddToHook} one can write:
+%\begin{verbatim}
+%   \AddToHook{myhook}{\def\foo#1{Hello, #1!}}
+%\end{verbatim}
+%    but to achieve the same with \cs{AddToHookWithArguments}, one should
+%    write:
+%\begin{verbatim}
+%   \AddToHookWithArguments{myhook}{\def\foo##1{Hello, ##1!}}
+%\end{verbatim}
+%    because in the latter case, \verb|#1| refers to the first argument
+%    of the hook \hook{myhook}.
+%   Section~\ref{sec:hook-args} explains hooks with arguments.
+%
+%    The \meta{hook} and \meta{label} can be specified using the
+%    dot-syntax to denote the current package name.
+%    See section~\ref{sec:default-label}.
+% \end{function}
+%
 % \begin{function}{\RemoveFromHook}
 %   \begin{syntax}
 %     \cs{RemoveFromHook} \Arg{hook}\oarg{label}
@@ -403,6 +493,19 @@
 % \end{function}\footnotetext{There is
 %    no mechanism to reorder such code chunks (or delete them).}
 %
+% \begin{function}{\AddToHookNextWithArguments}
+%   \begin{syntax}
+%     \cs{AddToHookNextWithArguments} \Arg{hook}\Arg{code}
+%   \end{syntax}
+%    Works exactly like \cs{AddToHookNext}, but the \meta{code} can
+%    contain references to the arguments of the \meta{hook} as described
+%    for \cs{AddToHookWithArguments} above.
+%   Section~\ref{sec:hook-args} explains hooks with arguments.
+%
+%    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}{\ClearHookNext}