diff options
author | Karl Berry <karl@freefriends.org> | 2022-06-08 20:41:20 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2022-06-08 20:41:20 +0000 |
commit | 0525ef25305c7f48ef158ac19f68bae09c664d60 (patch) | |
tree | 30bec1f740b86109fd5c0e21b1337f7f563d9dee /Master/texmf-dist/source/latex/base/lthooks.dtx | |
parent | 1ad2a2e7d1e951099f662da861d573aa77eeedce (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.dtx | 165 |
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: |