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.dtx41
1 files changed, 34 insertions, 7 deletions
diff --git a/macros/latex/base/lthooks.dtx b/macros/latex/base/lthooks.dtx
index a5953cc25d..e4ff7dd2ed 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.0d}
-\def\lthooksdate{2020/10/09}
+\def\lthooksversion{v1.0e}
+\def\lthooksdate{2020/10/23}
% \end{macrocode}
%
%<*driver>
@@ -1084,6 +1084,7 @@
%
% \subsection{Difference between \enquote{normal} and
% \enquote{one-time} hooks}
+% \label{sec:onetime-hooks}
%
% When executing a hook a developer has the choice of using
% either \cs{UseHook} or \cs{UseOneTimeHook} (or their \pkg{expl3}
@@ -1182,6 +1183,11 @@
%
% \subsection{Legacy \LaTeXe{} interfaces}
%
+% \newcommand\onetimetext{%
+% This is a one-time hook, so after it is executed, all further
+% attempts to add code to it will execute such code immediately
+% (see section~\ref{sec:onetime-hooks}).}
+%
% \LaTeXe{} offered a small number of hooks together with commands to
% add to them. They are listed here and are retained for backwards
% compatibility.
@@ -1211,6 +1217,14 @@
% \cs{AddToHook} \texttt{\{begindocument\}} \oarg{label}
% \Arg{code}.
%
+% \cs{AtBeginDocument} is a wrapper around the \hook{begindocument}
+% hook (see section~\ref{sec:begindocument-hooks}), which is a
+% one-time hook. As such, after the \hook{begindocument} hook is
+% executed at \verb=\begin{document}= any attempt to add \meta{code}
+% to this hook with \cs{AtBeginDocument} or with \cs{AddToHook} will
+% cause that \meta{code} to execute immediately instead.
+% See section~\ref{sec:onetime-hooks} for more on one-time hooks.
+%
% For important packages with known order requirement we may over
% time add rules to the kernel (or to those packages) so that they
% work regardless of the loading-order in the document.
@@ -1345,9 +1359,9 @@
% \end{function}
%
%
-%
%
% \subsubsection{Hooks provided by \cs{begin}\texttt{\{document\}}}
+% \label{sec:begindocument-hooks}
%
% Until 2020 \cs{begin}\texttt{\{document\}} offered exactly one
% hook that one could add to using
@@ -1370,12 +1384,12 @@
% section and this is how it is used by \pkg{etoolbox}'s
% \cs{AtEndPreamble}.
%
-%
+% \onetimetext
%
% \item[\hook{begindocument}]
%
-% This hook is added to when using \cs{AtBeginDocument} and it is executed
-% after the \texttt{.aux} file as be read in and most
+% This hook is added to when using \cs{AtBeginDocument} and it is
+% executed after the \texttt{.aux} file as be read in and most
% initialization are done, so they can be altered and inspected by
% the hook code. It is followed by a small number of further
% initializations that shouldn't be altered and are therefore
@@ -1386,12 +1400,16 @@
% document body. If such material needs to be added to the document
% body use the next hook instead.
%
+% \onetimetext
+%
% \item[\hook{begindocument/end}]
%
% This hook is executed at the end of the \cs{document} code in
% other words at the beginning of the document body. The only
% command that follows it is \cs{ignorespaces}.
%
+% \onetimetext
+%
% \end{description}
% The generic hooks executed by \cs{begin} also exist, i.e.,
% \hook{env/document/before} and \hook{env/document/begin}, but
@@ -1432,6 +1450,7 @@
% called to ensure that all such material gets typeset. If there
% is nothing waiting the \cs{clearpage} has no effect.
%
+% \onetimetext
%
% \item[\hook{enddocument/afterlastpage}]
%
@@ -1448,6 +1467,8 @@
% closed for writing and then read back in to do some tests
% (e.g., looking for missing references or duplicated labels, etc.).
%
+% \onetimetext
+%
% \item[\hook{enddocument/afteraux}]
%
% At this point, the \texttt{.aux} file has been reprocessed and so
@@ -1456,6 +1477,8 @@
% prefer the next hook, so that your information is displayed after the
% (possibly longish) list of files if that got requested via \cs{listfiles}.
%
+% \onetimetext
+%
% \item[\hook{enddocument/info}]
%
% This hook is meant to receive code that write final information
@@ -1470,11 +1493,15 @@
% \cs{listfiles} has been used and the warnings for duplicate
% labels, missing references, font substitutions etc.
%
+% \onetimetext
+%
% \item[\hook{enddocument/end}]
%
% Finally, this hook is executed just in front of the final call
% to \cs{@{}@end}.
%
+% \onetimetext % is it even possible to add code after this one?
+%
% \end{description}
%
%
@@ -3314,7 +3341,7 @@
\cs_new_protected:Npn \@@_log:nN #1 #2
{
\@@_preamble_hook:n {#1}
- \iow_term:x { ^^J ->~The~hook~'#1': }
+ \@@_log_cmd:x { ^^J ->~The~hook~'#1': }
% \end{macrocode}
%
% \begin{macrocode}