[latex3-commits] [git/LaTeX3-latex3-latex2e] lthooks-doc-updates: documentation on generic hooks for packages (b4e90f85)
Frank Mittelbach
frank.mittelbach at latex-project.org
Thu Aug 5 19:55:21 CEST 2021
Repository : https://github.com/latex3/latex2e
On branch : lthooks-doc-updates
Link : https://github.com/latex3/latex2e/commit/b4e90f856e184abc540808898538af2151bc59bc
>---------------------------------------------------------------
commit b4e90f856e184abc540808898538af2151bc59bc
Author: Frank Mittelbach <frank.mittelbach at latex-project.org>
Date: Thu Aug 5 19:55:21 2021 +0200
documentation on generic hooks for packages
>---------------------------------------------------------------
b4e90f856e184abc540808898538af2151bc59bc
base/doc/ltnews34.tex | 44 ++++++++++++++++++++++++++++++
base/lthooks.dtx | 74 +++++++++++++++++++++++++++++++++++++++++++++++----
2 files changed, 113 insertions(+), 5 deletions(-)
diff --git a/base/doc/ltnews34.tex b/base/doc/ltnews34.tex
index 1239d4e5..d07922a6 100644
--- a/base/doc/ltnews34.tex
+++ b/base/doc/ltnews34.tex
@@ -144,6 +144,50 @@
\section{Hook business}
+\subsection{Providing \cs{ActivateGenericHook}}
+
+The hook management system offers a number of generic hooks, i.e.,
+hooks whose names contain a variable component, for example the name
+of an environment. Predeclaring such hooks as not really feasible
+which is why these hooks use a different mechanism: they are
+implicitly available end spring into life the moment a package or the
+user in the preamble adds cde to them using \cs{AddToHook}. The
+kernel offers such hooks for environments \texttt{env/...}, commands
+\texttt{cmd/...}, and files, package or classes, \texttt{file/...},
+\texttt{include/...}, \texttt{package/...}, and \texttt{class/...}.
+
+It is possible to offer generic hooks in packages, e.g., if you have
+hooks that depend on the current language and therefore need the
+language name as part of the hook name and you don't know all possible
+names beforehand.
+
+If you want to offer your generic hooks you do this by using
+\cs{UseHook} or \cs{UseOneTimeHook} in your (package) code, but
+\emph{without declaring the hook} with \cs{NewHook}. Without any
+further work a call to \cs{UseHook} with an undeclared hook name does
+nothing. So as an additional setup step, it is necessary to explicitly
+activate the generic hook with \cs{ActivateGenericHook}.\footnote{Note
+ that in the previous release we offered \cs{ProvideHook} as a means
+ to achieve this effect, but the name was badly chosen so we decided
+ to deprecate it and now offer \cs{ActivateGenericHook} instead
+ because that is what it is meant for.}
+
+Assuming
+that you don't know all the different hook names up front it will
+remain the task of the users of your package to activate the hook
+themselves before adding code to it. For example, Babel offers hooks
+such as \texttt{babel/afterextras/\meta{language}} enabling the user
+to add language specific declarations there. They can then write
+\begin{verbatim}
+\ActivateGenericHook{babel/afterextras/ngerman}
+\AddToHook{babel/afterextras/ngerman}{\color{blue}}
+\end{verbatim}
+after which all German words would be colored in blue in the text.
+
+Note that a generic hook produced in this way is always a normal hook.
+
+
+
\subsection{Clear extra hook code for next invocation}
diff --git a/base/lthooks.dtx b/base/lthooks.dtx
index f880553e..22bf9712 100644
--- a/base/lthooks.dtx
+++ b/base/lthooks.dtx
@@ -190,7 +190,7 @@
% \begin{syntax}
% \cs{DisableGenericHook} \Arg{hook}
% \end{syntax}
-% After this declaration the \meta{hook} is no longer usable: Any
+% After this declaration\footnotemark{} the \meta{hook} is no longer usable: Any
% attempt to add further code to it will result in an error and any
% use, e.g., via \cs{UseHook}, will simply do nothing.
%
@@ -201,7 +201,9 @@
%
% The \meta{hook} can be specified using the dot-syntax to denote
% the current package name. See section~\ref{sec:default-label}.
-% \end{function}
+% \end{function}\footnotetext{In the 2020/06 release this command was
+% called \cs{DisableHook}, but that name was misleading as it
+% shouldn't be used to disable non-generic hooks.}
%
%
% \begin{function}{\ActivateGenericHook}
@@ -209,13 +211,13 @@
% \cs{ActivateGenericHook} \Arg{hook}
% \end{syntax}
% This delcaration activates a generic hook provided by a package/class
-% (e.g., one the is used in code with \cs{UseHook} or
+% (e.g., one used in code with \cs{UseHook} or
% \cs{UseOnteTimeHook} without it being explicitly declared with
% \cs{NewHook}).
% If already activated it does nothing.
%
-% See section~\ref{sec:?} for a discussion when this declaration is
-% appropriate.
+% See section~\ref{sec:generic-hooks} for a discussion of when this
+% declaration is appropriate.
% \end{function}
%
%
@@ -1335,6 +1337,68 @@
%
%
%
+% \subsection{Generic hooks provided by packages}
+% \label{sec:generic-hooks}
+%
+% The hook management system also implements a category of hooks
+% that are called \enquote{Generic Hooks}. Normally a hook has to
+% be explicitly declared before it can be used in code. This
+% ensures that different packages are not using the same hook name
+% for unrelated purposes---something that would result in absolute
+% chaos. However, there are a number of \enquote{standard} hooks
+% where it is unreasonable to declare them beforehand, e.g, each
+% and every command has (in theory) an associated \texttt{before}
+% and \texttt{after} hook. In such cases, i.e., for command,
+% environment or file hooks, they can simply by used by adding code
+% to them with \cs{AddToHook}. For more specialized generic hooks,
+% e.g., those provided by \pkg{babel}, you have to additionally
+% enable them with \cs{ActivateGenericHook} as explained below.
+%
+% The generic hooks provided by \LaTeX{}, i.e., for
+% \hook{cmd},
+% \hook{env},
+% \hook{file},
+% \hook{include}
+% \hook{package}, and
+% \hook{class},
+% are available out of the box. You only have to use \cs{AddToHook} to
+% add code to them, but you don't have to add \cs{UseHook} or
+% \cs{UseOneTimeHook} to your code, because this is already done for
+% you (or, in case of \hook{cmd} hooks, the command is patched at
+% \verb=\begin{document}=, if necessary).
+%
+% However, if you want to offer your own generic hooks in your
+% code, the situation is slightly different. You provide for such a
+% generic hook by using \cs{UseHook} or \cs{UseOneTimeHook}, but
+% \emph{without declaring the hook} with \cs{NewHook}. As
+% mentioned earlier, a call to \cs{UseHook} with an undeclared hook
+% name does nothing. So as an additional setup step, you need to
+% explicitly activate the generic hook. Note that a generic hook
+% produced in this way is always a normal hook.
+%
+% For a truly generic hook, with a variable part in the hook name,
+% an upfront activation would be difficult or impossible, because
+% you typically do not know what kind of variable parts may come up
+% in real documents.
+%
+% For example, \pkg{babel} may want to provide hooks such as
+% \hook{babel/afterextras/\meta{language}}. Language support in
+% \pkg{babel} is often done through external language
+% packages. Thus doing the activation for all languages inside the
+% core \pkg{babel} code is not a viable approach. Instead it needs
+% to by done by such language packages (or by the user who wants to
+% use a particular hook).
+%
+% Because the hooks are not declared with \cs{NewHook} their names
+% should be carefully chosen to ensure that they are (likely to be)
+% unique. Best practice is to include the package or
+% command name as it was
+% done in the \pkg{babel} example.
+%
+% Generic hooks defined in this way are always normal hooks (i.e.,
+% you can't implement reversed hooks this way). This is a
+% deliberate limitation, because it speeds up and the processessing
+% conciderably.
%
%
% \subsection{Private \LaTeX{} kernel hooks}
More information about the latex3-commits
mailing list.