Skip to content

Document hooks #1981

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

Open
FrankMittelbach wants to merge 2 commits into
base: develop
Choose a base branch
from
+360 −153
Open

Document hooks #1981

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
fc87d4a
play around with hook indexing
FrankMittelbach Jan 22, 2026
bdab514
underlining additiional index entries leads to test changes
FrankMittelbach Jan 22, 2026
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
36 changes: 31 additions & 5 deletions base/doc.dtx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
% \iffalse meta-comment
%
% Copyright (C) 1993-2025
% Copyright (C) 1993-2026
% The LaTeX Project and any individual authors listed elsewhere
% in this file.
%
Expand Down Expand Up @@ -45,7 +45,7 @@
%<+package>
%<+package>\ProvidesPackage{doc}
%<+shortvrb>\ProvidesPackage{shortvrb}
%<+package|shortvrb> [2024/12/25 v3.0q
%<+package|shortvrb> [2026/01/22 v3.0r
%<+package|shortvrb> Standard LaTeX documentation package V3 (FMi)]
%\catcode`\<=12
%
Expand Down Expand Up @@ -4235,9 +4235,17 @@
% \begin{imacro}{\usage}
% The |\usage| macro is used to indicate entries describing
% the usage of a macro. The corresponding page number(s) will be
% set in \textit{italics}.
% set in \textit{italics} and underlined.
% \begin{macrocode}
\@ifundefined{usage}{\def\usage#1{\textit{#1}}}{}
\@ifundefined{usage}{\def\usage#1{\underline{\textit{#1}}}}{}
% \end{macrocode}
% \end{imacro}
%
% \begin{imacro}{\auxusage}
%
% \changes{v3.0r}{2026/01/23}{}
% \begin{macrocode}
\@ifundefined{mainusage}{\def\auxusage#1{\textit{#1}}}{}
% \end{macrocode}
% \end{imacro}
%
Expand Down Expand Up @@ -5777,7 +5785,7 @@
\fi
\noexpand\@esphack}%
% \end{macrocode}
%
%
% \begin{macrocode}
\@nameedef{Special#1Index}##1{%
\noexpand\@bsphack
Expand All @@ -5791,6 +5799,24 @@
\noexpand\index{\the\@temptokenb\noexpand\levelchar
##1\noexpand\actualchar{\string\ttfamily\space##1}%
\noexpand\doc@handleencap{usage}}%
\fi
\noexpand\@esphack}%
% \end{macrocode}
%
% \changes{v3.0r}{2026/01/23}{}
% \begin{macrocode}
\@nameedef{SpecialAux#1Index}##1{%
\noexpand\@bsphack
\ifdoc@toplevel
\noexpand\doc@providetarget
\noexpand\index{##1\noexpand\actualchar{\string\ttfamily\space##1}%
\ifx\@nil#2\@nil\else \the\@temptokena \fi
\noexpand\doc@handleencap{auxusage}}%
\fi
\ifx\@nil#3\@nil\else
\noexpand\index{\the\@temptokenb\noexpand\levelchar
##1\noexpand\actualchar{\string\ttfamily\space##1}%
\noexpand\doc@handleencap{auxusage}}%
\fi
\noexpand\@esphack}}
% \end{macrocode}
Expand Down
87 changes: 44 additions & 43 deletions base/lthooks.dtx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,8 +50,9 @@
%
% \fi
%
% \renewcommand\hook[1]{\texttt{#1}\SpecialAuxHookIndex{#1}}
% \newcommand\describehook[1]{\texttt{#1}\SpecialHookIndex{#1}}
%
% \providecommand\hook[1]{\texttt{#1}}
%
% \providecommand\fmi[1]{\marginpar{\footnotesize FMi: #1}}
% \providecommand\fmiinline[1]{\begin{quote}\itshape\footnotesize FMi: #1\end{quote}}
Expand Down Expand Up @@ -365,7 +366,7 @@
% \meta{default label} is used (see section~\ref{sec:default-label}).
% If \cs{AddToHook} is used in a package/class, the
% \meta{default label} is the package/class name, otherwise it is
% \hook{top-level} (the \hook{top-level} label is treated
% \texttt{top-level} (the \texttt{top-level} label is treated
% differently: see section~\ref{sec:top-level}).
%
% If there already exists code under the \meta{label} then the new
Expand Down Expand Up @@ -927,7 +928,7 @@
% its permanent code pool, or to its ``next'' token list. The hook
% doesn't need to be declared to have code added to its code pool.
% A hook is said to exist when it was declared with \cs{NewHook} or
% some variant thereof. Generic hooks such as \hook{file} and \hook{env} hooks are
% some variant thereof. Generic hooks such as \hook{file/\meta{???}} and \hook{env/\meta{???}} hooks are
% automatically declared when code is added to them.
%
% \begin{function}[EXP]{\IfHookEmptyTF,\IfHookEmptyT,\IfHookEmptyF}
Expand Down Expand Up @@ -1147,7 +1148,7 @@
% declared with \cs{hook_new:n}. This declaration should be used
% only in special situations, e.g., when a command from another package
% needs to be altered and it is not clear whether a
% generic \hook{cmd} hook (for that command) has been previously
% generic \hook{cmd/\meta{???}} hook (for that command) has been previously
% explicitly declared.
%
% Normally \cs{hook_new:n} should be used instead of this.
Expand Down Expand Up @@ -1584,17 +1585,17 @@
% enable them with \cs{ActivateGenericHook} as explained below.
%
% The generic hooks provided by \LaTeX{} are those for
% \hook{cmd},
% \hook{env},
% \hook{file},
% \hook{include},
% \hook{package}, and
% \hook{class},
% \hook{cmd/\meta{???}},
% \hook{env/\meta{???}},
% \hook{file/\meta{???}},
% \hook{include/\meta{???}},
% \hook{package/\meta{???}}, and
% \hook{class/\meta{???}},
% and all these 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 the case of \hook{cmd} hooks, the command’s code is
% you (or, in the case of \hook{cmd/\meta{???}} hooks, the command’s code is
% patched at \verb=\begin{document}=, if necessary).
%
% However, if you want to provide further generic hooks in your own
Expand Down Expand Up @@ -1809,7 +1810,7 @@
% \hook{begindocument}
% (which is executed inside \verb=\begin{document}=).
% However, all code added this way is labeled with the label
% \hook{top-level} (see section~\ref{sec:top-level})
% \texttt{top-level} (see section~\ref{sec:top-level})
% if done outside of a package or class or with the
% package/class name if called inside such a file
% (see section~\ref{sec:default-label}).
Expand Down Expand Up @@ -1913,28 +1914,28 @@
% Every environment \meta{env} has now four associated hooks coming
% with it:
% \begin{description}
% \item[\hook{env/\meta{env}/before}]
% \item[\describehook{env/\meta{env}/before}]
%
% This hook is executed as part of \cs{begin} as the very first
% action, in particular prior to starting the environment group.
% Its scope is therefore not restricted by the environment.
%
% \item[\hook{env/\meta{env}/begin}]
% \item[\describehook{env/\meta{env}/begin}]
%
% This hook is executed as part of \cs{begin} directly in front
% of the code specific to the environment start (e.g.,
% the third argument of \cs{NewDocumentEnvironment} and
% the second argument of \cs{newenvironment}).
% Its scope is the environment body.
%
% \item[\hook{env/\meta{env}/end}]
% \item[\describehook{env/\meta{env}/end}]
%
% This hook is executed as part of \cs{end} directly in front of the
% code specific to the end of the environment (e.g.,
% the forth argument of \cs{NewDocumentEnvironment} and
% the third argument of \cs{newenvironment}).
%
% \item[\hook{env/\meta{env}/after}]
% \item[\describehook{env/\meta{env}/after}]
%
% This hook is executed as part of \cs{end} after the
% code specific to the environment end and after the environment
Expand Down Expand Up @@ -2020,17 +2021,17 @@
% Similar to environments there are now (at least in theory) two
% generic hooks available for any \LaTeX{} command. These are
% \begin{description}
% \item[\hook{cmd/\meta{name}/before}]
% \item[\describehook{cmd/\meta{name}/before}]
%
% This hook is executed at the very start of the command
% execution.
%
% \item[\hook{cmd/\meta{name}/after}]
% \item[\describehook{cmd/\meta{name}/after}]
% This hook is executed at the very end of the command body. It is
% implemented as a reversed hook.
% \end{description}
% In practice there are restrictions and especially the
% \hook{after} hook works only with a subset of commands. Details
% \texttt{/after} hook works only with a subset of commands. Details
% about these restrictions are documented in
% \texttt{ltcmdhooks-doc.pdf} or with code in
% \texttt{ltcmdhooks-code.pdf}.
Expand Down Expand Up @@ -2065,7 +2066,7 @@
% \begin{description}
%
%
% \item[\hook{begindocument/before}]
% \item[\describehook{begindocument/before}]
%
% This hook is executed at the very start of \cs{document}, one can
% think of it as a hook for code at the end of the preamble
Expand All @@ -2074,7 +2075,7 @@
%
% \onetimetext
%
% \item[\hook{begindocument}]
% \item[\describehook{begindocument}]
%
% This hook is added to by using \cs{AddToHook}\texttt{\{begindocument\}}
% or by using \cs{AtBeginDocument} and it is
Expand All @@ -2091,7 +2092,7 @@
%
% \onetimetext
%
% \item[\hook{begindocument/end}]
% \item[\describehook{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
Expand Down Expand Up @@ -2128,7 +2129,7 @@
% Supported are now the following hooks (all of them one-time hooks):
% \begin{description}
%
% \item[\hook{enddocument}]
% \item[\describehook{enddocument}]
%
% The hook associated with \cs{AtEndDocument}. It is immediately
% called at the beginning of \cs{enddocument}.
Expand All @@ -2141,7 +2142,7 @@
%
% \onetimetext
%
% \item[\hook{enddocument/afterlastpage}]
% \item[\describehook{enddocument/afterlastpage}]
%
% As the name indicates this hook should not receive code that
% generates material for further pages. It is the right place to
Expand All @@ -2160,7 +2161,7 @@
%
% \onetimetext
%
% \item[\hook{enddocument/afteraux}]
% \item[\describehook{enddocument/afteraux}]
%
% At this point, the \texttt{.aux} file has been reprocessed and so
% this is a possible place for final checks and display of
Expand All @@ -2170,7 +2171,7 @@
%
% \onetimetext
%
% \item[\hook{enddocument/info}]
% \item[\describehook{enddocument/info}]
%
% This hook is meant to receive code that write final information
% messages to the terminal. It follows immediately after the
Expand All @@ -2186,7 +2187,7 @@
%
% \onetimetext
%
% \item[\hook{enddocument/end}]
% \item[\describehook{enddocument/end}]
%
% Finally, this hook is executed just in front of the final call
% to \cs{@{}@end}.
Expand Down Expand Up @@ -2247,26 +2248,26 @@
% such support can be added.
% \begin{description}
%
% \item[\hook{rmfamily}]
% \item[\describehook{rmfamily}]
%
% After \cs{rmfamily} has done its initial checks and prepared a
% font series update, this hook is executed before \cs{selectfont}.
%
% \item[\hook{sffamily}]
% \item[\describehook{sffamily}]
%
% This is like the \hook{rmfamily} hook, but for the \cs{sffamily} command.
%
% \item[\hook{ttfamily}]
% \item[\describehook{ttfamily}]
%
% This is like the \hook{rmfamily} hook, but for the \cs{ttfamily} command.
%
% \item[\hook{normalfont}]
% \item[\describehook{normalfont}]
%
% The \cs{normalfont} command resets the font encoding, family, series
% and shape to their document defaults. It then executes this
% hook and finally calls \cs{selectfont}.
%
% \item[\hook{expand@font@defaults}]
% \item[\describehook{expand@font@defaults}]
%
% The internal \cs{expand@font@defaults} command expands and
% saves the current defaults for the metafamilies (rm/sf/tt) and
Expand All @@ -2275,7 +2276,7 @@
% defaults may need to be set at this point. This can be done in
% this hook which is executed at the end of this macro.
%
% \item[\hook{bfseries/defaults}, \hook{bfseries}]
% \item[\describehook{bfseries/defaults}, \describehook{bfseries}]
%
% If the \cs{bfdefault} was explicitly changed by the user, its
% new value is used to set the bf series defaults for the
Expand All @@ -2287,12 +2288,12 @@
% new series.
%
%
% \item[\hook{mdseries/defaults}, \hook{mdseries}]
% \item[\describehook{mdseries/defaults}, \describehook{mdseries}]
%
% These two hooks are like the previous ones but they are in the
% \cs{mdseries} command.
%
% \item[\hook{selectfont}]
% \item[\describehook{selectfont}]
%
% This hook is executed inside \cs{selectfont}, after the current
% values for \textit{encoding}, \textit{family}, \textit{series},
Expand All @@ -2316,7 +2317,7 @@
% See \texttt{ltmarks-doc.pdf} for details.
% \begin{description}
%
% \item[\hook{insertmark}]
% \item[\describehook{insertmark}]
%
% This hook allows for a special setup while \cs{InsertMark}
% inserts a mark. It is executed in group so local changes only
Expand Down Expand Up @@ -4071,7 +4072,7 @@
\@@_if_usable:nF {#5}
{
% \end{macrocode}
% If the hook doesn't exist yet we check if it is a \texttt{cmd}
% If the hook doesn't exist yet we check if it is a \texttt{cmd/\meta{???}}
% hook and if so we attempt patching the command in addition to
% declaring the hook.
%
Expand All @@ -4093,7 +4094,7 @@
% message generated elsewhere).
%
% Here we use \cs{@@_make_usable:nn}, so that a \cs{hook_new:n} is
% still possible later. Generic hooks (except \hook{cmd} hooks) take
% still possible later. Generic hooks (except \hook{cmd/\meta{???}} hooks) take
% no arguments, so use zero as the second argument.
% \begin{macrocode}
\@@_make_usable:nn {#5} { 0 }
Expand Down Expand Up @@ -4368,11 +4369,11 @@
% Token lists defining the possible generic hooks. We don't provide
% any user interface to this as this is meant to be static.
% \begin{description}
% \item[\texttt{cmd}]
% \item[\hook{cmd/\meta{???}}]
% The generic hooks used for commands.
% \item[\texttt{env}]
% \item[\hook{env/\meta{???}}]
% The generic hooks used in \cs{begin} and \cs{end}.
% \item[\texttt{file}, \texttt{package}, \texttt{class}, \texttt{include}]
% \item[\hook{file/\meta{???}}, \hook{package/\meta{???}}, \hook{class/\meta{???}}, \hook{include/\meta{???}}]
% The generic hooks used when loading a file
% \end{description}
% \begin{macrocode}
Expand Down Expand Up @@ -4450,7 +4451,7 @@
%<latexrelease> {Hooks~with~args}
% \end{macrocode}
%
% \hook{cmd} hooks are declared with 9 arguments because they have a
% \hook{cmd/\meta{???}} hooks are declared with 9 arguments because they have a
% variable number of arguments (depending on the command they are
% attached to), so we use the maximum here.
% \begin{macrocode}
Expand Down Expand Up @@ -7289,7 +7290,7 @@
% \begin{macro}[pTF]{\@@_if_cmd_hook:n}
% \begin{macro}[pTF]{\@@_if_cmd_hook:w}
% An internal conditional that checks if a given hook is a valid
% generic \hook{cmd} hook.
% generic \hook{cmd/\meta{???}} hook.
% \changes{v1.1d}{2023/05/21}
% {Changes to allow support arguments in cmd hooks (cmd-args).}
% \begin{macrocode}
Expand Down
Loading