summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/base/lthooks.dtx
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2022-06-08 20:41:20 +0000
committerKarl Berry <karl@freefriends.org>2022-06-08 20:41:20 +0000
commit0525ef25305c7f48ef158ac19f68bae09c664d60 (patch)
tree30bec1f740b86109fd5c0e21b1337f7f563d9dee /Master/texmf-dist/source/latex/base/lthooks.dtx
parent1ad2a2e7d1e951099f662da861d573aa77eeedce (diff)
latex2e (8jun22)
git-svn-id: svn://tug.org/texlive/trunk@63514 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/base/lthooks.dtx')
-rw-r--r--Master/texmf-dist/source/latex/base/lthooks.dtx165
1 files changed, 117 insertions, 48 deletions
diff --git a/Master/texmf-dist/source/latex/base/lthooks.dtx b/Master/texmf-dist/source/latex/base/lthooks.dtx
index 5b3d80e9844..06a0e8258f6 100644
--- a/Master/texmf-dist/source/latex/base/lthooks.dtx
+++ b/Master/texmf-dist/source/latex/base/lthooks.dtx
@@ -1,6 +1,6 @@
% \iffalse meta-comment
%
-% Copyright (C) 2020-2021
+% Copyright (C) 2020-2022
% Frank Mittelbach, Phelype Oleinik & LaTeX Team
%
% This file is part of the LaTeX base system.
@@ -31,28 +31,13 @@
%%% From File: lthooks.dtx
%
% \begin{macrocode}
-\def\lthooksversion{v1.0s}
-\def\lthooksdate{2021/09/28}
+\def\lthooksversion{v1.0u}
+\def\lthooksdate{2022/05/19}
% \end{macrocode}
%
%<*driver>
\documentclass{l3doc}
-% bug fix fo l3doc.cls
-\ExplSyntaxOn
-\cs_set_protected:Npn \__codedoc_macro_typeset_one:nN #1#2
- {
- \vbox_set:Nn \l__codedoc_macro_box
- {
- \vbox_unpack_drop:N \l__codedoc_macro_box
- \hbox { \llap { \__codedoc_print_macroname:nN {#1} #2
- \MacroFont % <----- without it the \ is in lmr10 if a link is made
- \
- } }
- }
- \int_incr:N \l__codedoc_macro_int
- }
-\ExplSyntaxOff
\providecommand\InternalDetectionOff{}
\providecommand\InternalDetectionOn{}
@@ -798,6 +783,7 @@
% \begin{function}{\ShowHook,\LogHook}
% \begin{syntax}
% \cs{ShowHook} \Arg{hook}
+% \cs{LogHook} \Arg{hook}
% \end{syntax}
% Displays information about the \meta{hook} such as
% \begin{itemize}
@@ -1096,6 +1082,7 @@
% \begin{function}{\hook_show:n,\hook_log:n}
% \begin{syntax}
% \cs{hook_show:n} \Arg{hook}
+% \cs{hook_log:n} \Arg{hook}
% \end{syntax}
% Displays information about the \meta{hook} such as
% \begin{itemize}
@@ -1391,7 +1378,7 @@
% in real documents.
%
% For example, \pkg{babel} may want to provide hooks such as
-% \hook{babel/afterextras/\meta{language}}. Language support in
+% \hook{babel/\meta{language}/afterextras}. 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
@@ -1417,7 +1404,7 @@
% hook management (by adding various rules to ensure the
% appropriate ordering with respect to other code added by
% packages). However, this makes every document unnecessary
-% slow, because there has to be sorting even through the result is
+% slow, because there has to be sorting even though the result is
% predetermined. Furthermore it forces package writers to
% unnecessarily add such rules if they add further code to the hook
% (or break \LaTeX{}).
@@ -1502,9 +1489,6 @@
% Like \cs{AtBeginDocument} but for the \hook{enddocument} hook.
% \end{function}
%
-% There is also \cs{AtBeginDvi} which is discussed in conjunction
-% with the shipout hooks.
-%
% \bigskip
%
% The few hooks that existed previously in \LaTeXe{} used internally
@@ -1962,7 +1946,21 @@
% \end{description}
%
%
-% \StopEventually{\setlength\IndexMin{200pt} \PrintIndex }
+%
+% \subsection{Hook provided by the mark mechanism}
+%
+% See \texttt{ltmarks-doc.pdf} for details.
+% \begin{description}
+%
+% \item[\hook{insertmark}]
+%
+% This hook allows for a special setup while \cs{InsertMark}
+% inserts a mark. It is executed in group so local changes only
+% apply to the mark being inserted.
+%
+% \end{description}
+%
+% \MaybeStop{\setlength\IndexMin{200pt} \PrintIndex }
%
%
% \section{The Implementation}
@@ -2198,7 +2196,6 @@
% \end{macro}
%
%
-%
% \subsection{Providing new hooks}
%
% \subsubsection{The data structures of a hook}
@@ -2219,7 +2216,7 @@
% A token list holding the relation between \meta{label1} and
% \meta{label2} in the \meta{hook}. The \meta{labels} are lexically
% (reverse) sorted to ensure that two labels always point to the same
-% token list. For global rules, the \meta{hook} name is |??|.
+% token list. For global rules, the \meta{hook} name is \texttt{??}.
%
% \item[\cs{@@\textvisiblespace\meta{hook}}] The code that is actually executed
% when the hook is called in the document is stored in this token
@@ -3458,7 +3455,12 @@
}
\tl_const:cn { c_@@_generic_env/./begin_tl } { + }
\tl_const:cn { c_@@_generic_env/./end_tl } { + }
+% \end{macrocode}
+%
+% \changes{v1.0t}{2022/04/01}{Support generic \texttt{include/.../excluded} hooks}
+% \begin{macrocode}
\tl_const:cn { c_@@_generic_include/./end_tl } { - }
+\tl_const:cn { c_@@_generic_include/./excluded_tl } { + }
% \end{macrocode}
%
% Deprecated generic hooks:
@@ -3589,7 +3591,7 @@
% expansion in the code later on.
%
% \cs{@@\textvisiblespace??} isn't used, but it has to be defined to trick
-% the code into thinking that \verb=??= is actually a hook.
+% the code into thinking that \texttt{??} is actually a hook.
% \begin{macrocode}
\prop_new:c {g_@@_??_code_prop}
\prop_new:c {@@~??}
@@ -3624,6 +3626,11 @@
% \end{macrocode}
%
% \begin{macrocode}
+%<latexrelease>\IncludeInRelease{2022/06/01}{\@@_gset_rule:nnnn}
+%<latexrelease> {Refuse~setting~rule~for~one-time~hooks}
+% \end{macrocode}
+%
+% \begin{macrocode}
\cs_new_protected:Npn \@@_gset_rule:nnnn #1#2#3#4
{
\@@_if_deprecated_generic:nT {#1}
@@ -3631,7 +3638,13 @@
\@@_deprecated_generic_warn:n {#1}
\@@_do_deprecated_generic:Nn \@@_gset_rule:nnnn {#1}
{#2} {#3} {#4}
- \exp_after:wN \use_none:nnnnnnnnn \use_none:n
+ \@@_clean_to_scan:w
+ }
+ \@@_if_execute_immediately:nT {#1}
+ {
+ \msg_error:nnnnnn { hooks } { rule-too-late }
+ {#1} {#2} {#3} {#4}
+ \@@_clean_to_scan:w
}
% \end{macrocode}
% First we ensure the basic data structure of the hook exists:
@@ -3650,10 +3663,41 @@
{#1} {#2} {#4}
\@@_update_hook_code:n {#1}
}
- { \msg_error:nnnnnn { hooks } { unknown-rule }
- {#1} {#2} {#3} {#4} }
+ {
+ \msg_error:nnnnnn { hooks } { unknown-rule }
+ {#1} {#2} {#3} {#4}
+ }
+ \s_@@_mark
}
% \end{macrocode}
+%
+% \begin{macrocode}
+%<latexrelease>\EndIncludeInRelease
+%<latexrelease>\IncludeInRelease{2020/10/01}{\@@_gset_rule:nnnn}
+%<latexrelease> {Refuse~setting~rule~for~one-time~hooks}
+%<latexrelease>\cs_new_protected:Npn \@@_gset_rule:nnnn #1#2#3#4
+%<latexrelease> {
+%<latexrelease> \@@_if_deprecated_generic:nT {#1}
+%<latexrelease> {
+%<latexrelease> \@@_deprecated_generic_warn:n {#1}
+%<latexrelease> \@@_do_deprecated_generic:Nn \@@_gset_rule:nnnn {#1}
+%<latexrelease> {#2} {#3} {#4}
+%<latexrelease> \exp_after:wN \use_none:nnnnnnnnn \use_none:n
+%<latexrelease> }
+%<latexrelease> \@@_init_structure:n {#1}
+%<latexrelease> \@@_rule_gclear:nnn {#1} {#2} {#4}
+%<latexrelease> \cs_if_exist_use:cTF { @@_rule_#3_gset:nnn }
+%<latexrelease> {
+%<latexrelease> {#1} {#2} {#4}
+%<latexrelease> \@@_update_hook_code:n {#1}
+%<latexrelease> }
+%<latexrelease> {
+%<latexrelease> \msg_error:nnnnnn { hooks } { unknown-rule }
+%<latexrelease> {#1} {#2} {#3} {#4}
+%<latexrelease> }
+%<latexrelease> }
+%<latexrelease>\EndIncludeInRelease
+% \end{macrocode}
% \end{macro}
% \end{macro}
%
@@ -3831,7 +3875,6 @@
% \end{macro}
%
%
-%
% \begin{macro}{\@@_initialize_hook_code:n}
% Initializing or reinitializing the fast execution hook code. In
% the preamble this is selectively done in case a hook gets used
@@ -3840,8 +3883,8 @@
% \begin{macrocode}
\cs_new_protected:Npn \@@_initialize_hook_code:n #1
{
- \@@_debug:n{ \iow_term:x{^^JUpdate~ code~ for~ hook~
- '#1' \on@line :^^J} }
+ \@@_debug:n
+ { \iow_term:x { ^^J Update~code~for~hook~'#1' \on@line :^^J } }
% \end{macrocode}
% This does the sorting and the updates.
% First thing we do is to check if a legacy hook macro exists and
@@ -3859,6 +3902,7 @@
% \cs{@@_initialize_single:NNn} and pass to it ready made csnames
% as they are needed several times inside. This way we save a bit
% on processing time if we do that up front.
+% \changes{v1.0u}{2022/05/17}{Refuse sorting one-time hooks (gh/818).}
% \begin{macrocode}
\@@_if_usable:nT {#1}
{
@@ -3873,7 +3917,7 @@
{
% \end{macrocode}
% By default the algorithm sorts the code chunks and then saves the
-% result in a token list for fast execution; this is done by adding the code chunks
+% result in a token list for fast execution; this is done by adding the code chunks
% one after another, using \cs{tl_gput_right:NV}. When we sort code for
% a reversed hook, all we have to do is to add the code chunks in
% the opposite order into the token list. So all we have to do
@@ -3902,8 +3946,8 @@
% i.e., we are only interested in storing the keys and the value is
% arbitrary.
% \begin{macrocode}
- \@@_debug:n{ \exp_args:NNx \prop_gput:Nnn
- \g_@@_used_prop {#1}{} }
+ \@@_debug:n
+ { \exp_args:NNx \prop_gput:Nnn \g_@@_used_prop {#1} { } }
}
}
}
@@ -4169,7 +4213,7 @@
% \meta{hook-code-plist}. We are about to apply the next rule and
% enter it into the data structure. \cs{@@_apply_label_pair:nnn} will
% just call \cs{@@_label_if_exist_apply:nnnF} for the \meta{hook}, and
-% if no rule is found, also try the \meta{hook} name \verb=??=
+% if no rule is found, also try the \meta{hook} name \texttt{??}
% denoting a default hook rule.
%
% \cs{@@_label_if_exist_apply:nnnF} will check if the rule exists for
@@ -4286,7 +4330,7 @@
% out to be a real issue, we can improve the code.
%
% Here the code is removed from \cs{l_@@_cur_hook_tl} rather than
-% \verb=#3= because the latter may be \verb=??=, and the default
+% \verb=#3= because the latter may be \texttt{??}, and the default
% hook doesn't store any code. Removing it instead from \cs{l_@@_cur_hook_tl}
% makes the default rules \verb=->= and \verb=<-= work properly.
% \begin{macrocode}
@@ -4320,16 +4364,17 @@
% \@@_apply_-rule_>:nnn,
% \@@_apply_-rule_<-:nnn,
% \@@_apply_-rule_->:nnn,
-% \@@_apply_-rule_x:nnn,
+% \@@_apply_-rule_xW:nnn,
+% \@@_apply_-rule_xE:nnn,
% }
% Reversed rules.
% \begin{macrocode}
-\cs_new_eq:cc { @@_apply_-rule_<:nnn } { @@_apply_rule_>:nnn }
-\cs_new_eq:cc { @@_apply_-rule_>:nnn } { @@_apply_rule_<:nnn }
+\cs_new_eq:cc { @@_apply_-rule_<:nnn } { @@_apply_rule_>:nnn }
+\cs_new_eq:cc { @@_apply_-rule_>:nnn } { @@_apply_rule_<:nnn }
\cs_new_eq:cc { @@_apply_-rule_<-:nnn } { @@_apply_rule_<-:nnn }
\cs_new_eq:cc { @@_apply_-rule_->:nnn } { @@_apply_rule_->:nnn }
-\cs_new_eq:cc { @@_apply_-rule_xE:nnn } { @@_apply_rule_xE:nnn }
-\cs_new_eq:cc { @@_apply_-rule_xW:nnn } { @@_apply_rule_xW:nnn }
+\cs_new_eq:cc { @@_apply_-rule_xE:nnn } { @@_apply_rule_xE:nnn }
+\cs_new_eq:cc { @@_apply_-rule_xW:nnn } { @@_apply_rule_xW:nnn }
% \end{macrocode}
% \end{macro}
%
@@ -4535,7 +4580,7 @@
% \meta{inline function} is executed with |#1|${}={}$\meta{relation},
% |#2|${}={}$\meta{label_1}\verb=|=\meta{label_2},
% and |#3|${}={}$\meta{hook} (the latter may be the argument |#1| to
-% \cs{@@_list_rules:nn}, or |??| if it is a default rule).
+% \cs{@@_list_rules:nn}, or \texttt{??} if it is a default rule).
% \begin{macrocode}
\cs_new_protected:Npn \@@_list_rules:nn #1 #2
{
@@ -4847,6 +4892,7 @@
% clears the hook so that any further call to \cs{hook_use:n} or
% \cs{hook_use_once:n} will expand to nothing.
% \changes{v1.0r}{2021/09/06}{Clean up after \cs{UseOneTimeHook} (gh/606)}
+% \changes{v1.0u}{2022/05/13}{Check if prop exists to avoid l3debug error}
% \begin{macrocode}
\cs_new_protected:Npn \@@_use_once_set:n #1
{ \@@_tl_gset:cn { g_@@_#1_reversed_tl } { I } }
@@ -4855,7 +4901,7 @@
\@@_tl_gclear:c { @@~#1 }
\@@_tl_gclear:c { @@_next~#1 }
\@@_tl_gclear:c { @@_toplevel~#1 }
- \prop_gclear:c { g_@@_#1_code_prop }
+ \prop_gclear_new:c { g_@@_#1_code_prop }
}
% \end{macrocode}
% \end{macro}
@@ -4872,7 +4918,7 @@
% empty.
% \changes{v1.0r}{2021/09/06}{Macro added (gh/606)}
% \begin{macrocode}
-\prg_new_conditional:Npnn \@@_if_execute_immediately:n #1 { F, TF }
+\prg_new_conditional:Npnn \@@_if_execute_immediately:n #1 { T, F, TF }
{
\@@_if_usable:nTF {#1}
{
@@ -5113,7 +5159,8 @@
%
% \begin{macrocode}
\msg_new:nnnn { hooks } { unknown-rule }
- { Unknown~ relationship~ '#3'~
+ {
+ Unknown~ relationship~ '#3'~
between~ labels~ '#2'~ and~ '#4'~
\str_if_eq:nnF {#1} {??} { ~in~hook~'#1' }. ~
Perhaps~ a~ misspelling?
@@ -5130,6 +5177,22 @@
% \end{macrocode}
%
% \begin{macrocode}
+\msg_new:nnnn { hooks } { rule-too-late }
+ {
+ Sorting~rule~for~'#1'~hook~applied~too~late.\\
+ Try~setting~this~rule~earlier.
+ }
+ {
+ You~tried~to~set~the~ordering~of~hook~'#1'~using\\
+ \ \ \iow_char:N\\DeclareHookRule{#1}{#2}{#3}{#4}\\
+ but~hook~'#1'~was~already~used~as~a~one-time~hook,~
+ thus~sorting~is\\
+ no~longer~possible.~Declare~the~rule~
+ before~the~hook~is~used.
+ }
+% \end{macrocode}
+%
+% \begin{macrocode}
\msg_new:nnnn { hooks } { misused-top-level }
{
Illegal~use~of~\iow_char:N \\AddToHook{#1}[top-level]{...}.\\
@@ -5596,4 +5659,10 @@
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\endinput
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+^^A Needed for emacs
+^^A
+^^A Local Variables:
+^^A mode: latex
+^^A coding: utf-8-unix
+^^A End: