Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Gh1501 gh1091 and gh1430 #1506

Merged
merged 3 commits into from
Oct 23, 2024
Merged

Gh1501 gh1091 and gh1430 #1506

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
55d8ced
doc for #1501
FrankMittelbach Oct 22, 2024
810f766
grumble
FrankMittelbach Oct 22, 2024
4ef30a8
also add docu for #1091 and #1430
FrankMittelbach Oct 22, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 7 additions & 2 deletions base/changes.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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).

Expand All @@ -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>
Expand All @@ -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:
Expand Down
78 changes: 68 additions & 10 deletions base/ltcmdhooks.dtx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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}
Expand Down Expand Up @@ -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}]
%
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down