[latex3-commits] [git/LaTeX3-latex3-latex2e] lthooks: merged from private (59f4bd4a)
Frank Mittelbach
frank.mittelbach at latex-project.org
Mon Jul 13 11:14:03 CEST 2020
Repository : https://github.com/latex3/latex2e
On branch : lthooks
Link : https://github.com/latex3/latex2e/commit/59f4bd4a41ac54a7dda81cd86c1cd5009cf5be6c
>---------------------------------------------------------------
commit 59f4bd4a41ac54a7dda81cd86c1cd5009cf5be6c
Author: Frank Mittelbach <frank.mittelbach at latex-project.org>
Date: Mon Jul 13 11:14:03 2020 +0200
merged from private
>---------------------------------------------------------------
59f4bd4a41ac54a7dda81cd86c1cd5009cf5be6c
base/lthooks.dtx | 198 +++++++++++++++++++++++++++++++++++++++++++------------
1 file changed, 156 insertions(+), 42 deletions(-)
diff --git a/base/lthooks.dtx b/base/lthooks.dtx
index 9546323e..3692bb15 100644
--- a/base/lthooks.dtx
+++ b/base/lthooks.dtx
@@ -128,6 +128,9 @@
% can further subdivide the name by adding more \texttt{/} parts.
% 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}{\NewReversedHook}
@@ -140,6 +143,9 @@
% Any rules for the hook are applied after the default ordering.
% See sections~\ref{sec:order} and \ref{sec:reversed-order}
% for further details.
+%
+% The \meta{hook} can be specified using the dot-syntax to denote
+% the current package name. See section~\ref{sec:default-label}.
% \end{function}
%
%
@@ -149,6 +155,9 @@
% \end{syntax}
% 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 current package name. See section~\ref{sec:default-label}.
% \end{function}
%
@@ -168,6 +177,9 @@
% initialized first. As that involves assignments using a hook at
% those times is not 100\% the same as using it after
% \verb=\begin{document}=.
+%
+% The \meta{hook} \emph{cannot} be specified using the dot-syntax.
+% A leading |.| is treated literally.
% \end{function}
%
% \begin{function}{\UseOneTimeHook}
@@ -189,6 +201,9 @@
% executing the code to be added immediately.
%
% \fmi{Maybe add an error version as well?}
+%
+% The \meta{hook} \emph{cannot} be specified using the dot-syntax.
+% A leading |.| is treated literally.
% \end{function}
%
%
@@ -216,6 +231,10 @@
% enables packages to add to hook of other packages without
% worrying whether they are actually used in the current document.
% See section~\ref{sec:querying}.
+%
+% 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}
@@ -231,6 +250,10 @@
% If the optional argument is \texttt{*}, then all code chunks are
% removed. This is rather dangerous as it drops code from other
% packages one may not know about!
+%
+% 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}
%
% \medskip
@@ -278,10 +301,13 @@
% The hook doesn't have to exist for code to be added to it. This
% allows for hooks to work regardless of package loading order.
% See section~\ref{sec:querying}.
+%
+% The \meta{hook} can be specified using the dot-syntax to denote
+% the current package name. See section~\ref{sec:default-label}.
% \end{function}\footnotetext{There is
% no mechanism to reorder such code chunks (or delete them).}
%
-% \subsubsection{Default labels}
+% \subsection{Hook names and default labels}
% \label{sec:default-label}
%
% It is best practice to use \cs{AddToHook} in packages or classes
@@ -299,32 +325,38 @@
% \meta{label} throughout the sub-packages in order to avoid
% that the labels change if you internally reorganize your code.
%
-% It is not enforced, but highly recommended that the label contains
-% the package name to easily identify the source of the code chunk and
-% to prevent clashes. This should be the standard practice, so this
-% hook management code provides a shortcut to refer to the current
-% package name in a \meta{label}. If a \meta{label} consists just of
-% a single dot (|.|), or starts with a dot followed by a slash (|./|)
-% then the dot denotes the \meta{default label} (usually the current
-% package or class name---see~\cs{DeclareDefaultHookLabel}). A
-% \enquote{|.|} or \enquote{|./|} anywhere else in a \meta{label} is
-% treated literally and is not replaced. For example, inside the package
-% \texttt{mypackage.sty}, the default label is \texttt{mypackage}, so
-% the instructions:
+% It is not enforced, but highly recommended that the hooks defined by
+% a package, and the \meta{labels} used to add code to other hooks
+% contain the package name to easily identify the source of the code
+% chunk and to prevent clashes. This should be the standard practice,
+% so this hook management code provides a shortcut to refer to the
+% current package in the name of a \meta{hook} and in a \meta{label}.
+% If \meta{hook} name or \meta{label} consist just of a single dot
+% (|.|), or starts with a dot followed by a slash (|./|) then the dot
+% denotes the \meta{default label} (usually the current package or class
+% name---see~\cs{DeclareDefaultHookLabel}).
+% A \enquote{|.|} or \enquote{|./|} anywhere else in a \meta{hook} or in
+% \meta{label} is treated literally and is not replaced.
+
+% For example,
+% inside the package \texttt{mypackage.sty}, the default label is
+% \texttt{mypackage}, so the instructions:
% \begin{verbatim}
-% \AddToHook {hook}[.]{code} % Same as \AddToHook {hook}{code}
-% \AddToHook {hook}[./sub]{code}
+% \NewHook {./hook}
+% \AddToHook {./hook}[.]{code} % Same as \AddToHook{./hook}{code}
+% \AddToHook {./hook}[./sub]{code}
+% \DeclareHookRule{begindocument}{.}{<}{babel}
+% \AddToHook {file/after/foo.tex}{code}
% \end{verbatim}
% are equivalent to:
% \begin{verbatim}
-% \AddToHook {hook}[mypackage]{code}
-% \AddToHook {hook}[mypackage/sub]{code}
+% \NewHook {mypackage/hook}[mypackage]{code}
+% \AddToHook {mypackage/hook}[mypackage]{code}
+% \AddToHook {mypackage/hook}[mypackage/sub]{code}
+% \DeclareHookRule{begindocument}{mypackage}{<}{babel}
+% \AddToHook {file/after/foo.tex}{code} % unchanged
% \end{verbatim}
%
-% This syntax is available in all \meta{label} arguments, both in
-% the \LaTeXe{} interface, and the \LaTeX3 interface described in
-% section~\ref{sec:l3hook-interface}.
-%
% The \meta{default label} is automatically set to the name of the
% current package or class (using \cs{@currname}). If \cs{@currname}
% is not set (because the hook command is used outside of a package, or
@@ -332,6 +364,23 @@
% \cs{documentclass}), then the \texttt{top-level} is used as the
% \meta{default label}.
%
+% This syntax is available in all \meta{label} arguments and most
+% \meta{hook}, both in the \LaTeXe{} interface, and the \LaTeX3
+% interface described in section~\ref{sec:l3hook-interface}.
+%
+% Note, however, that the replacement of |.| by the \meta{default label}
+% takes place when the hook command is executed, so actions that are
+% somehow executed after the package ends will have the wrong
+% \meta{default label} if the dot-syntax is used. For that reason,
+% this syntax is not available in \cs{UseHook} (and \cs{hook_use:n})
+% because the hook is most of the time used outside of the package file
+% in which it was defined. This syntax is also not available in the hook
+% conditionals \cs{IfHookEmptyTF} (and \cs{hook_if_empty:nTF}) and
+% \cs{IfHookExistTF} (and \cs{hook_if_exist:nTF}) because these
+% conditionals are used in some performance-critical parts of the hook
+% management code, and because they are usually used to refer to other
+% package's hooks, so the dot-syntax doesn't make much sense.
+%
% In some cases, for example in large packages, one may want to separate
% it in logical parts, but still use the main package name as
% \meta{label}, then the \meta{default label} can be set using
@@ -422,9 +471,19 @@
%
% \end{itemize}
%
+% 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}{\ClearHookRule}
+% \begin{syntax}
+% \cs{ClearHookRule}\Arg{hook}\Arg{label1}\Arg{label2}
+% \end{syntax}
+% Syntactic sugar for saying that \meta{label1} and \meta{label2}
+% are unrelated for the given \meta{hook}.
+% \end{function}
%
%
%
@@ -445,6 +504,9 @@
% \cs{DeclareHookRule} with \texttt{??} has bad side-effects and
% is not supported (though not explicitly caught for performance
% reasons.}
+%
+% The \meta{label} can be specified using the dot-syntax to denote
+% the current package name. See section~\ref{sec:default-label}.
% \end{function}
%
%
@@ -486,6 +548,9 @@
% it using either \cs{AddToHook} or \cs{AddToHookNext}), and
% branches to either \meta{true code} or \meta{false code} depending
% on the result.
+%
+% The \meta{hook} \emph{cannot} be specified using the dot-syntax.
+% A leading |.| is treated literally.
% \end{function}
%
% \begin{function}[EXP]{\IfHookExistTF}
@@ -502,6 +567,9 @@
% loading order may vary, thus the creation of hooks is asynchronous
% to adding and removing code from it, so this test should be used
% sparingly.
+%
+% The \meta{hook} \emph{cannot} be specified using the dot-syntax.
+% A leading |.| is treated literally.
% \end{function}
%
% \fmi{Would be helpful if we provide some use cases}
@@ -529,6 +597,9 @@
% \item
% any code executed on the next invocation only.
% \end{itemize}
+%
+% The \meta{hook} can be specified using the dot-syntax to denote
+% the current package name. See section~\ref{sec:default-label}.
% \end{function}
%
%
@@ -567,6 +638,9 @@
% \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}
%
%
@@ -577,6 +651,9 @@
% \end{syntax}
% Executes the \Arg{hook} code followed (if set up) by the code for next
% invocation only, then empties that next invocation code.
+%
+% The \meta{hook} \emph{cannot} be specified using the dot-syntax.
+% A leading |.| is treated literally.
% \end{function}
%
% \begin{function}{\hook_use_once:n}
@@ -587,6 +664,9 @@
% the hook code is executed immediately. Then execute any
% \Arg{hook} code already set up.
% \fmi{better L3 name?}
+%
+% The \meta{hook} \emph{cannot} be specified using the dot-syntax.
+% A leading |.| is treated literally.
% \end{function}
%
% \begin{function}{\hook_gput_code:nnn}
@@ -602,8 +682,9 @@
% as the \meta{label} not some internal module name or some other
% arbitrary string.
%
-% The \meta{label} can be specified using the dot-syntax to denote
-% the current package name. See section~\ref{sec:default-label}.
+% 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}
@@ -620,6 +701,9 @@
%
% Thus if one needs to undo what the standard does one has to do
% that as part of \meta{code}.
+%
+% The \meta{hook} can be specified using the dot-syntax to denote
+% the current package name. See section~\ref{sec:default-label}.
% \end{function}
%
@@ -640,8 +724,9 @@
% packages one may not know about, so think twice before using
% that!
%
-% The \meta{label} can be specified using the dot-syntax to denote
-% the current package name. See section~\ref{sec:default-label}.
+% 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}
@@ -653,8 +738,9 @@
% See \cs{DeclareHookRule} for the allowed \meta{relation}s.
% If \meta{hook} is \texttt{??} a default rule is specified.
%
-% The \meta{label} can be specified using the dot-syntax to denote
-% the current package name. See section~\ref{sec:default-label}.
+% 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}.
% The dot-syntax is parsed in both \meta{label} arguments, but it
% usually makes sense to be used in only one of them.
% \end{function}
@@ -667,6 +753,9 @@
% it using either \cs{AddToHook} or \cs{AddToHookNext}), and
% branches to either \meta{true code} or \meta{false code} depending
% on the result.
+%
+% The \meta{hook} \emph{cannot} be specified using the dot-syntax.
+% A leading |.| is treated literally.
% \end{function}
%
% \begin{function}[pTF]{\hook_if_exist:n}
@@ -685,6 +774,9 @@
% loading order may vary, thus the creation of hooks is asynchronous
% to adding and removing code from it, so this test should be used
% sparingly.
+%
+% The \meta{hook} \emph{cannot} be specified using the dot-syntax.
+% A leading |.| is treated literally.
% \end{function}
%
%
@@ -1135,10 +1227,11 @@
% can vary from document to document. Furthermore to determine correctly
% which of the \cs{shipout}s is the last one, \LaTeX{} needs to be run
% several times, so initially it might get executed on the wrong
-% page. See section~\ref{sec:shipout} for details.
+% page. See section~\ref{sec:shipout} for where to find the details.
%
%
% \subsubsection{Hooks provided \cs{shipout} operations}
+% \label{sec:shipout}
%
% There are several hooks and mechanisms added to \LaTeX{}'s
% process of generating pages. These are documented in
@@ -1269,7 +1362,7 @@
% \end{macro}
%
% \begin{macro}{\tl_gremove_once:Nx}
-% Some variants of \pkg{expl3} functions.
+% Some variants of \pkg{expl3} functions. \fmi{should be moved to expl3}
% \begin{macrocode}
\cs_generate_variant:Nn \tl_gremove_once:Nn { Nx }
% \end{macrocode}
@@ -1324,7 +1417,12 @@
% the hook \meta{name} as its argument, e.g.,
% \hook{begindocument}.
% \begin{macrocode}
-\cs_new_protected:Npn \hook_new:n #1 {
+\cs_new_protected:Npn \hook_new:n #1
+ {
+ \exp_args:Nx \@@_new:n
+ { \@@_parse_label_default:nn {#1} { top-level } }
+ }
+\cs_new_protected:Npn \@@_new:n #1 {
% \end{macrocode}
% We check for one of the internal data structures and if it
% already exists we complain.
@@ -1551,10 +1649,11 @@
% chunk of \meta{code} is added to an existing \meta{hook} labeled
% with \meta{label}.
% \begin{macrocode}
-\cs_new_protected:Npn \hook_gput_code:nnn #1 #2 #3
+\cs_new_protected:Npn \hook_gput_code:nnn #1 #2
{
- \exp_args:Nnx \@@_gput_code:nnn {#1}
- { \@@_parse_label_default:nn {#2} { top-level } } {#3}
+ \exp_args:Nxx \@@_gput_code:nnn
+ { \@@_parse_label_default:nn {#1} { top-level } }
+ { \@@_parse_label_default:nn {#2} { top-level } }
}
\cs_new_protected:Npn \@@_gput_code:nnn #1 #2 #3
{
@@ -1740,7 +1839,8 @@
% \begin{macrocode}
\cs_new_protected:Npn \hook_gremove_code:nn #1 #2
{
- \exp_args:Nnx \@@_gremove_code:nn {#1}
+ \exp_args:Nxx \@@_gremove_code:nn
+ { \@@_parse_label_default:nn {#1} { top-level } }
{ \@@_parse_label_default:nn {#2} { top-level } }
}
\cs_new_protected:Npn \@@_gremove_code:nn #1 #2
@@ -1944,7 +2044,7 @@
% \subsection{Setting rules for hooks code}
%
% \begin{macro}{\hook_gset_rule:nnnn}
-% \begin{macro}{\@@_gset_rule:nnnn,\@@_gset_rule:nxnx}
+% \begin{macro}{\@@_gset_rule:nnnn}
%
% \fmi{needs docu correction given new implementation}
%
@@ -1956,9 +2056,14 @@
% \begin{macrocode}
\cs_new_protected:Npn \hook_gset_rule:nnnn #1#2#3#4
{
- \@@_gset_rule:nxnx {#1}
- { \@@_parse_label_default:nn {#2} { top-level } } {#3}
- { \@@_parse_label_default:nn {#4} { top-level } }
+ \use:x
+ {
+ \@@_gset_rule:nnnn
+ { \@@_parse_label_default:nn {#1} { top-level } }
+ { \@@_parse_label_default:nn {#2} { top-level } }
+ {#3}
+ { \@@_parse_label_default:nn {#4} { top-level } }
+ }
}
% \end{macrocode}
%
@@ -1987,7 +2092,6 @@
\debug_resume:
\@@_debug_gset_rule:nnnn {#1} {#2} {#3} {#4} % for debugging
}
-\cs_generate_variant:Nn \@@_gset_rule:nnnn { nxnx }
% \end{macrocode}
% \end{macro}
% \end{macro}
@@ -2689,6 +2793,11 @@
% \begin{macrocode}
\cs_new_protected:Npn \hook_log:n #1
{
+ \exp_args:Nx \@@_log:n
+ { \@@_parse_label_default:nn {#1} { top-level } }
+ }
+\cs_new_protected:Npn \@@_log:n #1
+ {
\iow_term:x{^^JThe~ hook~ '#1':}
% \end{macrocode}
%
@@ -2764,7 +2873,12 @@
% \begin{macro}{\hook_gput_next_code:nn}
%
% \begin{macrocode}
-\cs_new_protected:Npn \hook_gput_next_code:nn #1 #2
+\cs_new_protected:Npn \hook_gput_next_code:nn #1
+ {
+ \exp_args:Nx \@@_gput_next_code:nn
+ { \@@_parse_label_default:nn {#1} { top-level } }
+ }
+\cs_new_protected:Npn \@@_gput_next_code:nn #1 #2
{
\@@_declare:n {#1}
\hook_if_exist:nTF {#1}
@@ -2887,7 +3001,7 @@
% \begin{macro}[pTF]{\@@_if_exist:n}
% An internal check if the hook has already been declared with
-% \cs{@@_new:n}. This means that the hook was already used somehow
+% \cs{@@_declare:n}. This means that the hook was already used somehow
% (a code chunk or rule was added to it), but it still wasn't declared
% with \cs{hook_new:n}.
% \begin{macrocode}
@@ -3103,7 +3217,7 @@
\@onlypreamble\DeclareDefaultHookRule
% \end{macrocode}
% \end{macro}
-
+%
% \begin{macro}{\ClearHookRule}
% A special setup rule that removes an existing relation.
% Basically {@@_rule_gclear:nnn} plus fixing the property list for debugging.
More information about the latex3-commits
mailing list.