[latex3-commits] [git/LaTeX3-latex3-latex2e] gh648: Some documentation (caf09407)

[PhelypeOleinik]

Repository : https://github.com/latex3/latex2e
On branch  : gh648
Link       : https://github.com/latex3/latex2e/commit/caf0940727fd4892197c7e0cfd869a52ecca2578

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

commit caf0940727fd4892197c7e0cfd869a52ecca2578
Author: PhelypeOleinik <phelype.oleinik at latex-project.org>
Date:   Mon Aug 30 12:37:46 2021 -0300

    Some documentation


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

caf0940727fd4892197c7e0cfd869a52ecca2578
 base/lthooks.dtx | 68 +++++++++++++++++++++++++++++++++++++++++++-------------
 1 file changed, 52 insertions(+), 16 deletions(-)

diff --git a/base/lthooks.dtx b/base/lthooks.dtx
index 0fc23d7e..921e196b 100644
--- a/base/lthooks.dtx
+++ b/base/lthooks.dtx
@@ -127,14 +127,10 @@
 %
 % \subsubsection{Declaring hooks}
 %
-%    With a few exceptions, hooks have to be declared before they can
-%    be used. The exceptions are the generic hooks for commands,
-%    environments (i.e., executed at \cs{begin} and \cs{end}) and
-%    hooks run when loading files, e.g. before and after a package is
-%    loaded, etc. Their hook names depend on the command,
-%    environment or the
-%    file name and so declaring them beforehand is not practical.
-%
+%  With a few exceptions, hooks have to be declared before they can
+%  be used. The exceptions are the generic hooks for commands,
+%  environments (i.e., executed at \cs{begin} and \cs{end}) and
+%  hooks run when loading files (see section~\ref{sec:generic}).
 %
 % \begin{function}{\NewHook}
 %   \begin{syntax}
@@ -1523,13 +1519,53 @@
 %    the processing.
 %
 %
-% \subsection{\LaTeXe{} commands and environments augmented by
-%    hooks}
+% \section{\LaTeXe{} commands and environments augmented by hooks}
 %
 %    In this section we describe the standard hooks that are now
 %    offered by \LaTeX{} or give pointers to other documents in which
 %    they are described. This section is will grow over time (and
-%    perhaps move to userguide3 eventually.
+%    perhaps move to usrguide3 eventually.
+%
+% \subsection{Generic hooks}
+% \label{sec:generic}
+%
+% As stated earlier, all hooks have to be declared with \cs{NewHook}
+% before they can be used with the exception of generic hooks.  All
+% generic hooks are named
+% \enquote{\meta{type}/\meta{name}/\meta{position}}, where \meta{type}
+% is one in the predefined list shown below, \meta{name} is the variable
+% part, whose meaning will depend on the \meta{type}, and
+% \meta{position}, which can be |before| or |after|, and also |begin| or
+% |end| for |env| hooks, and |end| for |include| hooks.  Each specific
+% hook is documented below or in \texttt{ltcmdhooks-doc.pdf} or
+% \texttt{ltfilehook-doc.pdf}.
+%
+% The generic hooks provided by \LaTeX{} belong to one of the six types:
+% \begin{description}
+%   \item[env] Hooks executed before and after environments.
+%     \meta{name} is the name of the environment, and available values
+%     for \meta{position} are |before|, |begin|, |end|, and |after|;
+%   \item[cmd] Hooks added to and executed before and after commands.
+%     \meta{name} is the name of the command, and available values
+%     for \meta{position} are |before| and |after|;
+%   \item[file] Hooks executed before and after reading a file;
+%     \meta{name} is the name of the file (with extension), and
+%     available values for \meta{position} are |before| and |after|;
+%   \item[package] Hooks executed before and after packages;
+%     \meta{name} is the name of the package, and available values for
+%     \meta{position} are |before| and |after|;
+%   \item[class] Hooks executed before and after classes;
+%     \meta{name} is the name of the class, and available values for
+%     \meta{position} are |before| and |after|;
+%   \item[include] Hooks executed before and after \cs{include}d files;
+%     \meta{name} is the name of the included file (without the |.tex|
+%     extension), and available values for \meta{position} are |before|,
+%     |end|, and |after|.
+% \end{description}
+%
+% Each of the hooks above are detailed in the following sections and
+% in linked documentation.
+% ^^A^^A^^A \pho{Wouldn't it be better to document all hooks here?}
 %
 % \subsubsection{Generic hooks for all environments}
 %
@@ -1661,7 +1697,7 @@
 %
 %
 %
-% \subsubsection{Hooks provided by \cs{begin}\texttt{\{document\}}}
+% \subsection{Hooks provided by \cs{begin}\texttt{\{document\}}}
 % \label{sec:begindocument-hooks}
 %
 %    Until 2020 \cs{begin}\texttt{\{document\}} offered exactly one
@@ -1720,7 +1756,7 @@
 %
 %
 %
-% \subsubsection{Hooks provided by \cs{end}\texttt{\{document\}}}
+% \subsection{Hooks provided by \cs{end}\texttt{\{document\}}}
 %
 %    \LaTeXe{} always provided \cs{AtEndDocument} to add code to the
 %    execution of \verb=\end{document}= just in front of the code that
@@ -1828,7 +1864,7 @@
 %
 %
 %
-% \subsubsection{Hooks provided by \cs{shipout} operations}
+% \subsection{Hooks provided by \cs{shipout} operations}
 % \label{sec:shipout}
 %
 %    There are several hooks and mechanisms added to \LaTeX{}'s
@@ -1837,7 +1873,7 @@
 %    \texttt{ltshipout-code.pdf}.
 %
 %
-% \subsubsection{Hooks provided for paragraphs}
+% \subsection{Hooks provided for paragraphs}
 % \label{sec:para}
 %
 %    The paragraph processing has be augmented to include a number of
@@ -1847,7 +1883,7 @@
 %
 %
 %
-% \subsubsection{Hooks provided in NFSS commands}
+% \subsection{Hooks provided in NFSS commands}
 %
 %    In languages that need to support for more than one script in
 %    parallel (and thus several sets of fonts), e.g., Latin and