[latex3-commits] [git/LaTeX3-latex3-latex2e] hotfix/gh441: Update docs for #441 and document new functions (f40df48c)
PhelypeOleinik
phelype.oleinik at latex-project.org
Thu Dec 17 05:06:07 CET 2020
Repository : https://github.com/latex3/latex2e
On branch : hotfix/gh441
Link : https://github.com/latex3/latex2e/commit/f40df48c9e9e3c8376adb8e411efd209db6e33db
>---------------------------------------------------------------
commit f40df48c9e9e3c8376adb8e411efd209db6e33db
Author: PhelypeOleinik <phelype.oleinik at latex-project.org>
Date: Thu Dec 17 01:06:07 2020 -0300
Update docs for #441 and document new functions
\PushDefaultHookLabel and \PopDefaultHookLabel
>---------------------------------------------------------------
f40df48c9e9e3c8376adb8e411efd209db6e33db
base/lthooks.dtx | 244 ++++++++++++++++++++++++++++++++++++++-----------------
1 file changed, 171 insertions(+), 73 deletions(-)
diff --git a/base/lthooks.dtx b/base/lthooks.dtx
index acbe2583..30a7292b 100644
--- a/base/lthooks.dtx
+++ b/base/lthooks.dtx
@@ -222,11 +222,13 @@
% \begin{syntax}
% \cs{AddToHook} \Arg{hook}\oarg{label}\Arg{code}
% \end{syntax}
-% Adds \meta{code} to the \meta{hook} labeled by \meta{label}. If
-% the optional argument \meta{label} is not provided, if \cs{AddToHook}
-% is used in a package/class, then the current
-% package/class name is used, otherwise \hook{top-level} is
-% used~(see section~\ref{sec:default-label}).
+% Adds \meta{code} to the \meta{hook} labeled by \meta{label}.
+% When the optional argument \meta{label} is not provided, the
+% \meta{default label} is used (see section~\ref{sec:default-label}).
+% If \cs{AddToHook} is used in a package/class, the
+% \meta{default label} is the package/class name, otherwise it is
+% \hook{top-level} (the \hook{top-level} label is treated
+% differently: see section~\ref{sec:top-level}).
%
% If there already exists code under the \meta{label} then the new
% \meta{code} is appended to the existing one (even if this is a reversed hook).
@@ -251,10 +253,8 @@
% \cs{RemoveFromHook} \Arg{hook}\oarg{label}
% \end{syntax}
% Removes any code labeled by \meta{label} from the \meta{hook}.
-% If the optional
-% argument \meta{label} is not provided, if \cs{AddToHook}
-% is used in a package/class, then the current
-% package/class name is used, otherwise \hook{top-level} is used.
+% When the optional argument \meta{label} is not provided, the
+% \meta{default label} is used (see section~\ref{sec:default-label}).
%
% If the code for that \meta{label} wasn't yet added to the
% \meta{hook}, an order is set so that when some code attempts to add
@@ -403,12 +403,12 @@
% \AddToHook {file/after/foo.tex}{code} % unchanged
% \end{verbatim}
%
-% 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
-% the current file wasn't loaded with \cs{usepackage} or
-% \cs{documentclass}), then the \texttt{top-level} is used as the
-% \meta{default label}.
+% The \meta{default label} is automatically set equal to the name of the
+% current package or class at the time the package is loaded. If the
+% hook command is used outside of a package, or the current file wasn't
+% loaded with \cs{usepackage} or \cs{documentclass}, then the
+% \texttt{top-level} is used as the \meta{default label}. This may have
+% exceptions---see \cs{PushDefaultHookLabel}.
%
% This syntax is available in all \meta{label} arguments and most
% \meta{hook}, both in the \LaTeXe{} interface, and the \LaTeX3
@@ -430,22 +430,97 @@
% 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
-% \cs{SetDefaultHookLabel}:
+% \cs{SetDefaultHookLabel} or
+% \cs{PushDefaultHookLabel}..\cs{PopDefaultHookLabel}.
+%
+% \begin{function}{\PushDefaultHookLabel,\PopDefaultHookLabel}
+% \begin{syntax}
+% \cs{PushDefaultHookLabel} \Arg{default label}
+% \quad \meta{code}
+% \cs{PopDefaultHookLabel}
+% \end{syntax}
+% \cs{PushDefaultHookLabel} sets the current \meta{default label} to
+% be used in \meta{label} arguments, or when replacing a leading
+% ``|.|'' (see above). \cs{PopDefaultHookLabel} reverts the
+% \meta{default label} to its previous value.
+%
+% Inside a package or class, the \meta{default label} is equal to the
+% package or class name, unless explicitly changed. Everywhere else,
+% the \meta{default label} is |top-level| (see
+% section~\ref{sec:top-level}) unless explicitly changed.
+%
+% The effect of \cs{PushDefaultHookLabel} holds until the next
+% \cs{PopDefaultHookLabel}. \cs{usepackage} (and \cs{RequirePackage}
+% and \cs{documentclass}) internally use
+% \begin{quote}
+% \cs{PushDefaultHookLabel}\Arg{package name} \\
+% \null \quad \meta{package code} \\
+% \cs{PopDefaultHookLabel}
+% \end{quote}
+% to set the \meta{default label} for the package or class file.
+% Inside the \meta{package code} the \meta{default label} can also be
+% changed with \cs{SetDefaultHookLabel}. \cs{input} and other
+% file input-related commands from the \LaTeX{} kernel do not use
+% \cs{PushDefaultHookLabel}, so code within files loaded by these
+% commands does \emph{not} get a dedicated \meta{label}! (that is, the
+% \meta{default label} is the current active one when the file was
+% loaded.)
+%
+% Packages that provide their own package-like interfaces
+% (Ti\textit{k}Z's \cs{usetikzlibrary}, for example) can use
+% \cs{PushDefaultHookLabel} and \cs{PopDefaultHookLabel} to set
+% dedicated labels and emulate \cs{usepackage}-like hook behaviour
+% within those contexts.
+%
+% The |top-level| label is treated differently, and is reserved to the
+% user document, so it is not allowed to change the
+% \meta{default label} to |top-level|.
+% \end{function}
%
% \begin{function}{\SetDefaultHookLabel}
% \begin{syntax}
% \cs{SetDefaultHookLabel} \Arg{default label}
% \end{syntax}
-% Sets the \meta{default label} to be used in \meta{label} arguments.
-% If \cs{SetDefaultHookLabel} is not used in the
-% current package, \cs{@currname} is used instead. If \cs{@currname}
-% is not set, the code is assumed to be in the main document, in which
-% case \texttt{top-level} is used.
-%
-% The effect of \cs{SetDefaultHookLabel} holds for the current
-% file, and is reset to the previous value when the file is closed.
+% Similarly to \cs{PushDefaultHookLabel},
+% sets the current \meta{default label} to
+% be used in \meta{label} arguments, or when replacing a leading
+% ``|.|''. The effect holds until the label is changed again or until
+% the next \cs{PopDefaultHookLabel}. The difference between
+% \cs{PushDefaultHookLabel} and \cs{SetDefaultHookLabel} is that the
+% latter does not save the current \meta{default label}.
+%
+% This command is useful when a large package is composed of several
+% smaller packages, but all should have the same \meta{label}, so
+% \cs{SetDefaultHookLabel} can be used at the beginning of each
+% package file to set the correct label.
+%
+% \cs{SetDefaultHookLabel} is not allowed in the main document, where
+% the \meta{default label} is |top-level| and there is no
+% \cs{PopDefaultHookLabel} to end its effect.
+% It is also not allowed to change the \meta{default label} to
+% |top-level|.
% \end{function}
%
+% \subsubsection{The \texttt{top-level} label}
+% \label{sec:top-level}
+%
+% The |top-level| label, assigned to code added from the main document,
+% is different from other labels. Code added to hooks (usually
+% \cs{AtBeginDocument}) in the preamble is almost always to change
+% something defined by a package, so it should go at the very end of the
+% hook.
+%
+% Therefore, code added in the |top-level| is always executed at the end
+% of the hook, regardless of where it was declared. If the hook is
+% reversed (see \cs{NewReversedHook}), the |top-level| chunk is executed
+% at the very beginning instead.
+%
+% Rules regarding |top-level| have no effect: if a user wants to have a
+% specific set of rules for a code chunk, they should use a different
+% label to said code chunk, and provide a rule for that label instead.
+%
+% The |top-level| label is exclusive for the user, so trying to add code
+% with that label from a package results in an error.
%
% \subsubsection{Defining relations between hook code}
%
@@ -650,6 +725,7 @@
% \item
% any code executed on the next invocation only.
% \end{itemize}
+% \end{function}
%
% \cs{LogHook} prints the information to the |.log| file, and
% \cs{ShowHook} prints them to the terminal/command window and starts
@@ -660,6 +736,7 @@
%
%^^A % Code for the listing below:
%^^A \NewHook{example-hook}
+%^^A \AddToHook{example-hook}{[code from 'top-level']}
%^^A \AddToHook{example-hook}[foo]{[code from package 'foo']}
%^^A \AddToHook{example-hook}[bar]{[from package 'bar']}
%^^A \AddToHook{example-hook}[baz]{[package 'baz' is here]}
@@ -680,13 +757,15 @@
% > foo -> [code from package 'foo']
% > bar -> [from package 'bar']
% > baz -> [package 'baz' is here]
+% > Document-level (top-level) code (executed last):
+% > -> [code from 'top-level']
% > Extra code for next invocation:
% > -> [one-time code]
% > Rules:
% > foo|baz with relation >
% > baz|bar with default relation <
% > Execution order (after applying rules):
-% > bar, baz, foo.
+% > baz, foo, bar.
% \end{verbatim}
%
% In the listing above, lines~3 to~5 show the three code chunks added
@@ -695,7 +774,18 @@
% \quad \meta{label}\verb| -> |\meta{code}
% \end{quote}
%
-% Line~7 shows the code chunk for the next execution of the hook in
+% Line~7 shows the code chunk added by the user in the main document
+% (labeled |top-level|) in the format
+% \begin{quote}
+% \quad\verb|Document-level (top-level) code (executed |%^^A
+% \meta{first\texttt{\string|}last}\verb|):|\\
+% \quad\verb| -> |\meta{\texttt{top-level} code}
+% \end{quote}
+% This code will be either the first or last code executed by the hook
+% (|last| if the hook is normal, |first| if it is reversed). This
+% chunk is not affected by rules and does not take part in sorting.
+%
+% Line~9 shows the code chunk for the next execution of the hook in
% the format
% \begin{quote}
% \quad \verb|-> |\meta{next-code}
@@ -705,7 +795,7 @@
% earlier, which can only be removed from that hook by doing
% \verb|\RemoveFromHook{|\meta{label}|}[example-hook]|.
%
-% Lines~9 and~10 show the rules declared that affect this hook in the
+% Lines~11 and~12 show the rules declared that affect this hook in the
% format
% \begin{quote}
% \quad \meta{label-1}\verb+|+\meta{label-2}| with |%^^A
@@ -717,9 +807,8 @@
% to \meta{label-1} and \meta{label-2} in \emph{all} hooks, (unless
% overrided by a non-default relation).
%
-% Finally, line~12 lists the labels in the hook after sorting;
+% Finally, line~14 lists the labels in the hook after sorting;
% that is, in the order they will be executed when the hook is used.
-% \end{function}
%
%
% \subsubsection{Debugging hook code}
@@ -954,17 +1043,19 @@
% \texttt{packageB}, \texttt{packageC} which you can verify with
% \cs{ShowHook}\texttt{\{myhook\}}:
%\begin{verbatim}
-% The hook 'myhook':
-% Code chunks:
-% packageA -> \typeout {A}
-% packageB -> \typeout {B}
-% packageC -> \typeout {C}
-% Extra code next invocation:
-% ---
-% Rules:
-% ---
-% Execution order:
-% packageA, packageB, packageC
+% -> The hook 'myhook':
+% > Code chunks:
+% > packageA -> \typeout {A}
+% > packageB -> \typeout {B}
+% > packageC -> \typeout {C}
+% > Document-level (top-level) code (executed last):
+% > ---
+% > Extra code for next invocation:
+% > ---
+% > Rules:
+% > ---
+% > Execution order:
+% > packageA, packageB, packageC.
%\end{verbatim}
% The reason is that the code chunks are internally saved in a property list
% and the initial order of such a property list is the order in
@@ -988,17 +1079,19 @@
%\end{verbatim}
% instead of the previous lines we get
%\begin{verbatim}
-% The hook 'myhook':
-% Code chunks:
-% packageA -> \typeout {A}
-% packageB -> \typeout {B}
-% packageC -> \typeout {C}
-% Extra code next invocation:
-% ---
-% Rules:
-% packageA|packageB with relation before
-% Execution order (after applying rules):
-% packageA, packageC, packageB
+% -> The hook 'myhook':
+% > Code chunks:
+% > packageA -> \typeout {A}
+% > packageB -> \typeout {B}
+% > packageC -> \typeout {C}
+% > Document-level (top-level) code (executed last):
+% > ---
+% > Extra code for next invocation:
+% > ---
+% > Rules:
+% > packageB|packageA with relation >
+% > Execution order (after applying rules):
+% > packageA, packageC, packageB.
%\end{verbatim}
% As you can see the code chunks are still in the same order, but
% in the execution order for the labels \texttt{packageB} and
@@ -1010,7 +1103,7 @@
% doesn't run at all as there is nothing to resolve).
% Incidentally, if we had instead specified the redundant rule
%\begin{verbatim}
-% \DeclareHookRule{myhook}{packageB}{before}{label-3}
+% \DeclareHookRule{myhook}{packageB}{before}{packageC}
%\end{verbatim}
% the execution order would not have changed.
%
@@ -1039,17 +1132,17 @@
% \AddToHook{env/quote/after} [package-1]{\end{itshape}}
%\end{verbatim}
% As a result, all quotes will be in italics.
-% Now suppose further that the user wants the quotes also in blue
-% and therefore adds:
+% Now suppose further that another |package-too| makes the quotes
+% also in blue and therefore adds:
%\begin{verbatim}
% \usepackage{color}
-% \AddToHook{env/quote/before}{\begin{color}{blue}}
-% \AddToHook{env/quote/after} {\end{color}}
+% \AddToHook{env/quote/before}[package-too]{\begin{color}{blue}}
+% \AddToHook{env/quote/after} [package-too]{\end{color}}
%\end{verbatim}
% Now if the \hook{env/quote/after} hook would be a normal hook we
% would get the same execution order in both hooks, namely:
%\begin{verbatim}
-% package-1, top-level
+% package-1, package-too
%\end{verbatim}
% (or vice versa) and as a result, would get:
%\begin{verbatim}
@@ -1063,16 +1156,18 @@
% the correct sequence and \cs{ShowHook} would give us the
% following output:
%\begin{verbatim}
-% The hook 'env/quote/after':
-% Code chunks:
-% package-1 -> \end {itshape}
-% top-level -> \end {color}
-% Extra code next invocation:
-% ---
-% Rules:
-% ---
-% Execution order (after reversal):
-% top-level, package-1
+% -> The hook 'env/quote/after':
+% > Code chunks:
+% > package-1 -> \end {itshape}
+% > package-too -> \end {color}
+% > Document-level (top-level) code (executed first):
+% > ---
+% > Extra code for next invocation:
+% > ---
+% > Rules:
+% > ---
+% > Execution order (after reversal):
+% > package-too, package-1.
%\end{verbatim}
%
% The reversal of the execution order happens before applying any
@@ -1206,13 +1301,15 @@
% \hook{begindocument}
% (which is executed inside \verb=\begin{document}=).
% However, all code added this way is labeled with the label
-% \hook{top-level} if done outside of a package or class or with the
-% package/class name if called inside such a file.
+% \hook{top-level} (see section~\ref{sec:top-level})
+% if done outside of a package or class or with the
+% package/class name if called inside such a file
+% (see section~\ref{sec:default-label}).
%
% This way one can add further code to the hook using
% \cs{AddToHook} or \cs{AtBeginDocument} using a different label
% and explicitly order the code chunks as necessary, e.g., run some
-% code before or after the \hook{top-level} code. When using the
+% code before or after another package's code. When using the
% optional argument the call is equivalent to running
% \cs{AddToHook} \texttt{\{begindocument\}} \oarg{label}
% \Arg{code}.
@@ -1333,8 +1430,8 @@
% \cs{BeforeBeginEnvironment} \oarg{label} \Arg{code}
% \end{syntax}
% This declaration adds to the \hook{env/\meta{env}/before} hook
-% using by default the current package or class name as a label or
-% \texttt{top-level} if used in the document directly.
+% using the \meta{label}. If \meta{label} is not given, the
+% \meta{default label} is used (see section~\ref{sec:default-label}).
% \end{function}
%
% \begin{function}{\AtBeginEnvironment}
@@ -1811,7 +1908,8 @@
% \item[\cs{@@_toplevel~\meta{name}}] This token list stores the code
% inserted in the hook from the user's document, in the |top-level|
% label. This label is special, and doesn't participate in sorting.
-% Instead, all code is appended to it and executed after the normal
+% Instead, all code is appended to it and executed after (or before,
+% if the hook is reversed) the normal
% hook code, but before the |next| code chunk.
%
% \item[\cs{@@_next~\meta{name}}] Finally there is extra code
More information about the latex3-commits
mailing list.