[latex3-commits] [git/LaTeX3-latex3-latex2e] gh818: some documentation changes (03102577)
Frank Mittelbach
frank.mittelbach at latex-project.org
Thu May 19 09:24:48 CEST 2022
Repository : https://github.com/latex3/latex2e
On branch : gh818
Link : https://github.com/latex3/latex2e/commit/03102577f759bf350db4b431086587d7322d3275
>---------------------------------------------------------------
commit 03102577f759bf350db4b431086587d7322d3275
Author: Frank Mittelbach <frank.mittelbach at latex-project.org>
Date: Thu May 19 09:24:48 2022 +0200
some documentation changes
>---------------------------------------------------------------
03102577f759bf350db4b431086587d7322d3275
base/doc/ltnews35.tex | 33 ++++--
base/lthooks.dtx | 9 +-
base/testfiles-lthooks/github-0606.tlg | 6 +-
base/testfiles-lthooks/github-0818.tlg | 7 +-
base/testfiles-lthooks/lthooks-031.lvt | 40 ++++++++
.../{filehook-003.tlg => lthooks-031.tlg} | 113 +++++++++++----------
base/update-lthooks-tests.sh | 4 +-
7 files changed, 138 insertions(+), 74 deletions(-)
diff --git a/base/doc/ltnews35.tex b/base/doc/ltnews35.tex
index 8f468a6a..32ab31e9 100644
--- a/base/doc/ltnews35.tex
+++ b/base/doc/ltnews35.tex
@@ -787,22 +787,33 @@ The old behavior can be restored by adding
to a document.
-\subsection{Fixed bug when setting a hook rule during a one-time hook code}
-
-In the particular case of a one-time hook used in or after
-\verb|\begin{document}| with at least two code labels, where one of them
-contains the declaration of a hook ordering rule for that one hook (such
-that the sorting mechanism kicks in while running the hook code), a bug
-existed which would cause the spurious typesetting of the code labels
-and the hook name. This was caused because the sorting mechanism was
-incorrectly called for a one-time hook. The bug is now fixed and an
-error is now raised when a new sorting rule is added to an already used
-one-time hook.
+\subsection{Fixed bug when setting hook rules for one-time hooks}
+
+If a \cs{DeclareHookRule} command is used for a on-time hook it has to
+come \emph{before} the hook gets used, because otherwise it never
+applies\Dash after all, the hook is used only once. There was a bug in
+the implementation in that the sorting mechanism was still applied if
+the \cs{DeclareHookRule} declaration appeared while the one-time hook was
+executed, causing the spurious typesetting of the code labels and the
+hook name. This bug is now fixed and an error is raised when a new
+sorting rule is added to an already used one-time hook.
+
+A possible scenario in which this new error is raised is the following:
+package \pkg{AAA} declares a hook rule for \hook{begindocument} (i.e.,
+\cs{AtBeginDocument}) to sort out the behavior between itself and some
+other package. Package \pkg{BBB} wants to load package \pkg{AAA} but
+only if it hasn't been loaded in the preamble, so delays the loading to
+\hook{begindocument}. In that case the hook rule declared by \pkg{AAA}
+can no longer be applied and you get the error. If that happens the
+solution is to load the package in \hook{begindocument/before}, which
+is executed at the very end of the preamble but before
+\hook{begindocument} is processed.
%
\githubissue{818}
+
\section{Changes to packages in the \pkg{amsmath} category}
diff --git a/base/lthooks.dtx b/base/lthooks.dtx
index 3d8eb903..e39ebd6b 100644
--- a/base/lthooks.dtx
+++ b/base/lthooks.dtx
@@ -32,7 +32,7 @@
%
% \begin{macrocode}
\def\lthooksversion{v1.0u}
-\def\lthooksdate{2022/05/17}
+\def\lthooksdate{2022/05/19}
% \end{macrocode}
%
%<*driver>
@@ -5179,15 +5179,16 @@
% \begin{macrocode}
\msg_new:nnnn { hooks } { rule-too-late }
{
- Cannot~set~a~sorting~rule~for~the~already~used~hook~'#1'.\\
+ 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.~Try~using~this~
- command~before~the~hook~is~used.
+ thus~sorting~is\\
+ no~longer~possible.~Declare~the~rule~
+ before~the~hook~is~used.
}
% \end{macrocode}
%
diff --git a/base/testfiles-lthooks/github-0606.tlg b/base/testfiles-lthooks/github-0606.tlg
index 3ef2fb16..42cced6a 100644
--- a/base/testfiles-lthooks/github-0606.tlg
+++ b/base/testfiles-lthooks/github-0606.tlg
@@ -10,15 +10,15 @@ l. ...\NewHook{A}
There already exists a hook declaration with this name.
Please use a different name for your hook.
B
-! LaTeX hooks Error: Cannot set a sorting rule for the already used hook 'A'.
+! LaTeX hooks Error: Sorting rule for 'A' hook applied too late.
(hooks) Try setting this rule earlier.
For immediate help type H <return>.
...
l. ...\DeclareHookRule{A}{b}{after}{c}
You tried to set the ordering of hook 'A' using
\DeclareHookRule{A}{b}{after}{c}
-but hook 'A' was already used as a one-time hook, thus sorting is no longer
-possible. Try using this command before the hook is used.
+but hook 'A' was already used as a one-time hook, thus sorting is
+no longer possible. Declare the rule before the hook is used.
-> The hook 'A':
> Code chunks:
> ---
diff --git a/base/testfiles-lthooks/github-0818.tlg b/base/testfiles-lthooks/github-0818.tlg
index faefacf4..8cd8102e 100644
--- a/base/testfiles-lthooks/github-0818.tlg
+++ b/base/testfiles-lthooks/github-0818.tlg
@@ -1,12 +1,11 @@
This is a generated file for the l3build validation system.
Don't change this file in any respect.
-! LaTeX hooks Error: Cannot set a sorting rule for the already used hook
-(hooks) 'aaaa'.
+! LaTeX hooks Error: Sorting rule for 'aaaa' hook applied too late.
(hooks) Try setting this rule earlier.
For immediate help type H <return>.
...
l. ...\hook_use_once:n {aaaa}
You tried to set the ordering of hook 'aaaa' using
\DeclareHookRule{aaaa}{A}{before}{B}
-but hook 'aaaa' was already used as a one-time hook, thus sorting is no longer
-possible. Try using this command before the hook is used.
+but hook 'aaaa' was already used as a one-time hook, thus sorting is
+no longer possible. Declare the rule before the hook is used.
diff --git a/base/testfiles-lthooks/lthooks-031.lvt b/base/testfiles-lthooks/lthooks-031.lvt
new file mode 100644
index 00000000..d5ec14be
--- /dev/null
+++ b/base/testfiles-lthooks/lthooks-031.lvt
@@ -0,0 +1,40 @@
+
+\RequirePackage[enable-debug]{expl3}
+\ExplSyntaxOn
+\debug_on:n { check-declarations , deprecation }
+\ExplSyntaxOff
+
+\documentclass{article}
+
+\input{regression-test}
+
+\START
+
+\NewHook{foo}
+
+\AddToHook{include/foo/after}[A]{\typeout{A1}}
+\AddToHook{include/foo/after}[B]{\typeout{B1}}
+\AddToHook{begindocument}[A]{\typeout{A2}}
+\AddToHook{begindocument}[B]{\typeout{B2}}
+
+\ShowHook{include/foo/after}
+\ShowHook{begindocument}
+
+\AddToHook{begindocument}[X]{\DeclareHookRule{include/foo/after}{B}{before}{A}}
+\AddToHook{begindocument}[Y]{\DeclareHookRule{begindocument}{B}{before}{A}}
+
+\begin{document}
+
+\ShowHook{include/foo/after}
+\ShowHook{begindocument}
+
+Test
+
+\include{foo}
+
+\ShowHook{include/foo/after}
+
+\AddToHook{include/foo/after}[C]{\typeout{C1}}
+
+
+\END
diff --git a/base/testfiles-lthooks/filehook-003.tlg b/base/testfiles-lthooks/lthooks-031.tlg
similarity index 52%
copy from base/testfiles-lthooks/filehook-003.tlg
copy to base/testfiles-lthooks/lthooks-031.tlg
index a64b8732..2e2f54c7 100644
--- a/base/testfiles-lthooks/filehook-003.tlg
+++ b/base/testfiles-lthooks/lthooks-031.tlg
@@ -1,23 +1,34 @@
This is a generated file for the l3build validation system.
Don't change this file in any respect.
-(article.cls
-Document Class: article ....-..-.. v... Standard LaTeX document class
-(size10.clo
-File: size10.clo ....-..-.. v... Standard LaTeX file (size option)
-)
-\c at part=\count...
-\c at section=\count...
-\c at subsection=\count...
-\c at subsubsection=\count...
-\c at paragraph=\count...
-\c at subparagraph=\count...
-\c at figure=\count...
-\c at table=\count...
-\abovecaptionskip=\skip...
-\belowcaptionskip=\skip...
-\bibindent=\dimen...
-)
-No file filehook-003.aux.
+-> The generic hook 'include/foo/after':
+> Code chunks:
+> A -> \typeout {A1}
+> B -> \typeout {B1}
+> Document-level (top-level) code (executed first):
+> ---
+> Extra code for next invocation:
+> ---
+> Rules:
+> ---
+> Execution order (after reversal):
+> B, A.
+<recently read> }
+l. ...\ShowHook{include/foo/after}
+-> The hook 'begindocument':
+> Code chunks:
+> A -> \typeout {A2}
+> B -> \typeout {B2}
+> Document-level (top-level) code (executed last):
+> ---
+> Extra code for next invocation:
+> ---
+> Rules:
+> ---
+> Execution order:
+> A, B.
+<recently read> }
+l. ...\ShowHook{begindocument}
+No file lthooks-031.aux.
LaTeX Font Info: Checking defaults for OML/cmm/m/it on input line ....
LaTeX Font Info: ... okay on input line ....
LaTeX Font Info: Checking defaults for OMS/cmsy/m/n on input line ....
@@ -32,42 +43,42 @@ LaTeX Font Info: Checking defaults for OMX/cmex/m/n on input line ....
LaTeX Font Info: ... okay on input line ....
LaTeX Font Info: Checking defaults for U/cmr/m/n on input line ....
LaTeX Font Info: ... okay on input line ....
--> The hook 'include/before':
-> Code chunks:
-> A -> \typeout {A}
-> B -> \typeout {B}
-> C -> \typeout {C}
-> Document-level (top-level) code (executed last):
-> ---
-> Extra code for next invocation:
-> ---
-> Rules:
-> ---
-> Execution order:
-> A, B, C.
--> The hook 'include/after':
+A2
+B2
+! LaTeX hooks Error: Sorting rule for 'begindocument' hook applied too late.
+(hooks) Try setting this rule earlier.
+For immediate help type H <return>.
+ ...
+l. ...\begin{document}
+You tried to set the ordering of hook 'begindocument' using
+ \DeclareHookRule{begindocument}{B}{before}{A}
+but hook 'begindocument' was already used as a one-time hook, thus sorting is
+no longer possible. Declare the rule before the hook is used.
+-> The generic hook 'include/foo/after':
> Code chunks:
-> A -> \typeout {A}
-> B -> \typeout {B}
-> C -> \typeout {C}
+> A -> \typeout {A1}
+> B -> \typeout {B1}
> Document-level (top-level) code (executed first):
> ---
> Extra code for next invocation:
> ---
> Rules:
-> ---
-> Execution order (after reversal):
-> C, B, A.
--> The hook 'include/end':
-> Code chunks:
-> A -> \typeout {A}
-> B -> \typeout {B}
-> C -> \typeout {C}
-> Document-level (top-level) code (executed first):
-> ---
-> Extra code for next invocation:
-> ---
-> Rules:
-> ---
-> Execution order (after reversal):
-> C, B, A.
+> B|A with relation <
+> Execution order (after reversal and applying rules):
+> B, A.
+<recently read> }
+l. ...\ShowHook{include/foo/after}
+-> The hook 'begindocument':
+> The hook is empty.
+<recently read> }
+l. ...\ShowHook{begindocument}
+[1
+]
+No file foo.tex.
+B1
+A1
+-> The generic hook 'include/foo/after':
+> The hook is empty.
+<recently read> }
+l. ...\ShowHook{include/foo/after}
+C1
diff --git a/base/update-lthooks-tests.sh b/base/update-lthooks-tests.sh
index 493f2fcb..aed91e18 100755
--- a/base/update-lthooks-tests.sh
+++ b/base/update-lthooks-tests.sh
@@ -85,6 +85,7 @@ l3build save -cconfig-lthooks \
lthooks-029 \
lthooks-029-deprecated \
lthooks-030 \
+ lthooks-031 \
lthooks-errors \
lthooks-errors-deprecated \
lthooks-etoolbox \
@@ -101,7 +102,8 @@ l3build save -cconfig-lthooks \
github-0565 \
github-0606 \
github-0648 \
- github-0648b
+ github-0648b \
+ github-0818
More information about the latex3-commits
mailing list.