[latex3-commits] [git/LaTeX3-latex3-latex2e] onetime-doc: Explicitly say which hooks are one-time [ci skip] (cb9f036a)

[PhelypeOleinik]

Repository : https://github.com/latex3/latex2e
On branch  : onetime-doc
Link       : https://github.com/latex3/latex2e/commit/cb9f036a52689f28a0ede0e5b4527bc334516f82

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

commit cb9f036a52689f28a0ede0e5b4527bc334516f82
Author: PhelypeOleinik <phelype.oleinik at latex-project.org>
Date:   Fri Oct 23 15:43:30 2020 -0300

    Explicitly say which hooks are one-time [ci skip]
    
    Missing documentation reported at https://github.com/plk/biblatex/issues/1066


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

cb9f036a52689f28a0ede0e5b4527bc334516f82
 base/lthooks.dtx | 37 +++++++++++++++++++++++++++++++------
 1 file changed, 31 insertions(+), 6 deletions(-)

diff --git a/base/lthooks.dtx b/base/lthooks.dtx
index a5953cc2..a8774eb6 100644
--- a/base/lthooks.dtx
+++ b/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.
@@ -1346,8 +1360,8 @@
 %
 %
 %
-%
 % \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
@@ -1470,11 +1491,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}
 %
 %