summaryrefslogtreecommitdiff
path: root/macros/latex/base/lthooks.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/base/lthooks.dtx')
-rw-r--r--macros/latex/base/lthooks.dtx93
1 files changed, 81 insertions, 12 deletions
diff --git a/macros/latex/base/lthooks.dtx b/macros/latex/base/lthooks.dtx
index cb48570a0d..a5953cc25d 100644
--- a/macros/latex/base/lthooks.dtx
+++ b/macros/latex/base/lthooks.dtx
@@ -31,8 +31,8 @@
%%% From File: lthooks.dtx
%
% \begin{macrocode}
-\def\lthooksversion{v1.0b}
-\def\lthooksdate{2020/09/21}
+\def\lthooksversion{v1.0d}
+\def\lthooksdate{2020/10/09}
% \end{macrocode}
%
%<*driver>
@@ -256,6 +256,11 @@
% is used in a package/class, then the current
% package/class name is used, otherwise \hook{top-level} is used.
%
+% 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
+% that label, the removal order takes action and the code is not
+% added.
+%
% 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!
@@ -648,10 +653,72 @@
%
% \cs{LogHook} prints the information to the |.log| file, and
% \cs{ShowHook} prints them to the terminal/command window and starts
-% \TeX's prompt (only if \cs{errorstopmode}) to wait for user action.
+% \TeX's prompt (only in \cs{errorstopmode}) to wait for user action.
%
% The \meta{hook} can be specified using the dot-syntax to denote
% the current package name. See section~\ref{sec:default-label}.
+%
+%^^A % Code for the listing below:
+%^^A \NewHook{example-hook}
+%^^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]}
+%^^A \AddToHookNext{example-hook}{[one-time code]}
+%^^A \DeclareHookRule{example-hook}{baz}{before}{foo}
+%^^A \DeclareDefaultHookRule{bar}{after}{baz}
+%^^A \ShowHook{example-hook}
+%
+% \def\theFancyVerbLine{\textcolor[gray]{0.5}{%^^A
+% \sffamily\tiny\arabic{FancyVerbLine}}}
+%
+% \bigskip
+% Suppose a hook \texttt{example-hook} whose output of
+% \cs{ShowHook}|{example-hook}| is:
+% \begin{verbatim}[numbers=left]
+% -> The hook 'example-hook':
+% > Code chunks:
+% > foo -> [code from package 'foo']
+% > bar -> [from package 'bar']
+% > baz -> [package 'baz' is here]
+% > 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.
+% \end{verbatim}
+%
+% In the listing above, lines~3 to~5 show the three code chunks added
+% to the hook and their respective labels in the format
+% \begin{quote}
+% \quad \meta{label}\verb| -> |\meta{code}
+% \end{quote}
+%
+% Line~7 shows the code chunk for the next execution of the hook in
+% the format
+% \begin{quote}
+% \quad \verb|-> |\meta{next-code}
+% \end{quote}
+% This code will be used and disappear at the next
+% \verb|\UseHook{example-hook}|, in contrast to the chunks mentioned
+% 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
+% format
+% \begin{quote}
+% \quad \meta{label-1}\verb+|+\meta{label-2}| with |%^^A
+% \meta{\texttt{default}?}| relation |\meta{relation}
+% \end{quote}
+% which means that the \meta{relation} applies to \meta{label-1} and
+% \meta{label-2}, in that order, as detailed in \cs{DeclareHookRule}.
+% If the relation is \texttt{default} it means that that rule applies
+% 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;
+% that is, in the order they will be executed when the hook is used.
% \end{function}
%
%
@@ -3964,19 +4031,21 @@
% may be used in packages without rollback functionality. So we
% just make them do nothing which may or may not work depending on
% the code usage.
+% \changes{v1.0d}{2020/10/04}{Definition \cs{AddToHookNext} was supposed
+% to be for \cs{AddToHook} vize versa (gh/401)}
% \begin{macrocode}
%</2ekernel|latexrelease>
%<latexrelease>\EndIncludeInRelease
%<latexrelease>\IncludeInRelease{0000/00/00}%
%<latexrelease> {\NewHook}{The hook management}%
%<latexrelease>
-%<latexrelease>\def \NewHook#1{}
-%<latexrelease>\def \NewReversedHook#1{}
-%<latexrelease>\def \NewMirroredHookPair#1#2{}
+%<latexrelease>\def\NewHook#1{}
+%<latexrelease>\def\NewReversedHook#1{}
+%<latexrelease>\def\NewMirroredHookPair#1#2{}
%<latexrelease>
-%<latexrelease>\long\def \AddToHook#1#2{}
+%<latexrelease>\long\def\AddToHookNext#1#2{}
%<latexrelease>
-%<latexrelease>\def \AddToHookNext#1{\@gobble@AddToHook@args}
+%<latexrelease>\def\AddToHook#1{\@gobble@AddToHook@args}
%<latexrelease>\providecommand\@gobble@AddToHook@args[2][]{}
%<latexrelease>
%<latexrelease>\def\RemoveFromHook#1{\@gobble@RemoveFromHook@arg}
@@ -3988,17 +4057,17 @@
%<latexrelease>\let \DebugHooksOn \@empty
%<latexrelease>\let \DebugHooksOff\@empty
%<latexrelease>
-%<latexrelease>\def \DeclareHookRul#1#2#3#4{}
+%<latexrelease>\def \DeclareHookRule #1#2#3#4{}
%<latexrelease>\def \DeclareDefaultHookRule #1#2#3{}
-%<latexrelease>\def \ClearHookRule#1#2#3{}
+%<latexrelease>\def \ClearHookRule #1#2#3{}
% \end{macrocode}
% If the hook management is not provided we make the test for existence
% false and the test for empty true in the hope that this is most
% of the time reasonable. If not a package would need to guard
% against running in an old kernel.
% \begin{macrocode}
-%<latexrelease>\def \IfHookExistTF #1#2#3{#3}
-%<latexrelease>\def \IfHookEmptyTF #1#2#3{#2}
+%<latexrelease>\long\def \IfHookExistsTF #1#2#3{#3}
+%<latexrelease>\long\def \IfHookEmptyTF #1#2#3{#2}
%<latexrelease>
%<latexrelease>\EndIncludeInRelease
% \end{macrocode}