Gh1501 gh1091 and gh1430 (#1506)

* doc for #1501

* grumble

* also add docu for #1091 and #1430

base/changes.txt

@@ -5,6 +5,12 @@ hotfixes). It is provided for convenience only.  It therefore makes no claims
 to completeness or accuracy and it contains some references to files that are
 not part of the distribution.
 ================================================================================
+
+2024-10-22  Frank Mittelbach  <Frank.Mittelbach@latex-project.org>
+	* ltcmdhooks.dtx:
+	Some clarification why not all
+	commands allow generic cmd hooks (gh/1091, gh/1430 and gh/1501)
+
 2024-10-22 Ulrike Fischer <Ulrike.Fischer@latex-project.org>
 	* ltshipout.dtx: correct documentation (gh/1470).
 
@@ -21,7 +27,7 @@ not part of the distribution.
 	Correct passing of token list content using \KeyValue
 
 2024-10-02 Ulrike Fischer <Ulrike.Fischer@latex-project.org>
-	* lttagging.dtx: restore also paratagging in the para/restore socket, 
+	* lttagging.dtx: restore also paratagging in the para/restore socket,
 	see https://github.com/latex3/tagging-project/issues/723
 
 2024-09-25 Matthew Bertucci <bertucci@math.utah.edu>
@@ -40,7 +46,6 @@ not part of the distribution.
       Use sockets in \refstepcounter for target and tagging support.
     * ltmeta.dtx: move patches and change of \MakeLinkTarget from latex-lab.
     * lttagging.dtx: add tagging socket for targets.
-
 
 2024-09-15  Joseph Wright  <Joseph.Wright@latex-project.org>
 	* lttemplates-doc.tex, lttemplates-code.tex:

base/ltcmdhooks.dtx

@@ -20,7 +20,7 @@
 %<*driver>
 % \fi
 \ProvidesFile{ltcmdhooks.dtx}
-             [2024/07/08 v1.0j LaTeX Kernel (Command hooks)]
+             [2024/10/22 v1.0j LaTeX Kernel (Command hooks)]
 % \iffalse
 %
 \documentclass{l3doc}
@@ -68,7 +68,15 @@
 %    supported
 %    for all types of commands, see section~\ref{sec:look-ahead} for
 %    the restrictions that apply and what happens if one tries to use
-%    this with commands for which this is not supported.}  These are:
+%    this with commands for which this is not supported.}
+%
+%    However, this is only true \enquote{in theory}. In practice there
+%    are a number of restrictions that makes it impossible to use such
+%    generic command hooks in a number of cases, so please read all
+%    of section~\ref{sec:restrictions} to understand what may prevent
+%    you from using them successfully.
+%
+%    The generic command hooks are:
 %    \begin{description}
 %    \item[\hook{cmd/\meta{name}/before}]
 %
@@ -152,7 +160,55 @@
 % and \TeX{} doesn't have a reliable way to see that, so some guesswork
 % has to be employed.
 %
-% \subsection{Patching}
+% We can do this in most cases when commands are defined using
+% \cs{NewDocumentCommand} or \cs{newcommand} (with a few exceptions).
+% For commands defined with \tn{def} the situation is less good.
+% Common cases where the command hooks will not work are:
+% \begin{itemize}
+% \item
+%
+%   Commands that use special catcode settings within their
+%   definition. In that case it is usually not possible to augment the
+%   definition (see~\ref{sec:patching}).
+%
+% \item
+%
+%   If a command is defined while \cs{ExplSyntaxOn} is in force
+%   \textbf{and} the command contains \verb=~= characters to represent
+%   spaces, then it can't be patched to include the command hooks. In
+%   fact in some very special circumstances you might even get a
+%   low-level error rather than the information that the command can't
+%   be patched (see,  for example,
+%   \url{https://github.com/latex3/latex2e/issues/1430}.
+%
+% \item
+%
+%   Commands that have arguments as far as the user is concerned
+%   (e.g., \cs{section} or \cs{caption}), but are defined in a way that these
+%   arguments are not read by the user level command but only later
+%   during the processing. In that case the \texttt{after} hook
+%   doesn't work at all.  The \text{before} hook only works with
+%   \cs{AddToHook} but not with \cs{AddToHookWithArguments} because the
+%   arguments haven't been read at that point where the hook is
+%   patched in. See
+%   section~\ref{sec:look-ahead}.
+%
+%
+% \item
+%   Adding a specific  generic command hook is only attempted once per
+%   command, thus after redefining a command such hooks will no longer
+%   be there and will also not being re-added, see section~\ref{sec:timing}.
+%
+% \end{itemize}
+% All this means that you have to have a good understanding of how
+% commands are defined when you attempt to make use of such hooks and
+% something goes wrong.
+% What can help in that case is to turn on \cs{DebugHooksOn} in which
+% case you get much more (low-level) details on why something fails and
+% what was tried to enable the hooks.
+%
+%
+% \subsection{Patching}\label{sec:patching}
 %
 % The code here tries to find out if a command was defined with
 % \tn{newcommand} or \tn{DeclareRobustCommand} or
@@ -172,7 +228,7 @@
 % catcode settings are not the same as the ones at the time of command's
 % definition, so not always adding a hook to a command will work.
 %
-% \subsubsection{Timing}
+% \subsubsection{Timing}\label{sec:timing}
 %
 % When \cs{AddToHook} (or its \pkg{expl3} equivalent) is called with
 % a generic |cmd| hook, say, \hook{cmd/foo/before}, for the first time
@@ -211,12 +267,14 @@
 % hooks attached to them.
 %
 % One good example is the \tn{section} command.  You can add something
-% to the \hook{cmd/section/before} hook, but if you try to add something
-% to the \hook{cmd/section/after} hook, \tn{section} will no longer
-% work.  That happens because the \tn{section} macro takes no argument,
-% but instead calls a few internal \LaTeX{} macros to look for the
-% optional and mandatory arguments.  By adding code to the
-% \hook{cmd/section/after} hook, you get in the way of that scanning.
+% to the \hook{cmd/section/before} hook (but only with \cs{AddToHook}
+% not \cs{AddToHookWithArguments}),
+% but if you try to add anything to the \hook{cmd/section/after}
+% hook, \tn{section} will no longer work at all.  That happens because the
+% \tn{section} macro takes no argument, but instead calls a few
+% internal \LaTeX{} macros to look for the optional and mandatory
+% arguments.  By adding code to the \hook{cmd/section/after} hook, you
+% get in the way of that scanning.
 %
 % In such a case, where it is known that a specific generic command
 % hook does not work if code is added to it, the package author can