[latex3-commits] [git/LaTeX3-latex3-latex2e] gh648: Add deprecation warning and auto-correction (dcd155b0)
PhelypeOleinik
phelype.oleinik at latex-project.org
Tue Aug 24 04:13:48 CEST 2021
Repository : https://github.com/latex3/latex2e
On branch : gh648
Link : https://github.com/latex3/latex2e/commit/dcd155b047fab29df98d368539c414303de94551
>---------------------------------------------------------------
commit dcd155b047fab29df98d368539c414303de94551
Author: PhelypeOleinik <phelype.oleinik at latex-project.org>
Date: Mon Aug 23 23:13:48 2021 -0300
Add deprecation warning and auto-correction
>---------------------------------------------------------------
dcd155b047fab29df98d368539c414303de94551
base/lthooks.dtx | 138 +++++++++++++++++++++++++++++++--
base/testfiles-lthooks/github-0648.lvt | 64 +++++++++++++++
base/testfiles-lthooks/github-0648.tlg | 62 +++++++++++++++
3 files changed, 257 insertions(+), 7 deletions(-)
diff --git a/base/lthooks.dtx b/base/lthooks.dtx
index 2545a9cc..41a64c71 100644
--- a/base/lthooks.dtx
+++ b/base/lthooks.dtx
@@ -3005,10 +3005,84 @@
{ \tl_gset:cn { g_@@_#5_reversed_tl } { - } }
\prg_return_true:
}
- { \prg_return_false: }
+ {
+% \end{macrocode}
+%
+% Generic hooks are all named \meta{type}/\meta{name}/\meta{place},
+% where \meta{type} and \meta{place} are predefined
+% (\cs{c_@@_generic_\meta{type}/./\meta{place}_tl}), and \meta{name}
+% is the variable component. Older releases had some hooks with the
+% \meta{name} in the third part, so the code below supports that
+% syntax for a while, with a warning.
+%
+% The \cs{exp_after:wN} |...| \cs{exp:w} trick is there to remove the
+% conditional structure inserted by
+% \cs{@@_try_declaring_generic_hook:wnTF} to allow access to the
+% tokens that follow it, needed to keep things going.
+%
+% When the deprecation cycle ends, the lines below should all be
+% replaced by \cs{prg_return_false:}.
+% \begin{macrocode}
+ \@@_if_deprecated_generic:nTF {#5}
+ {
+ \@@_deprecated_generic_warn:n {#5}
+ \exp_after:wN \@@_declare_deprecated_generic:NNn
+ \exp:w % \exp_end:
+ }
+ { \prg_return_false: }
+ }
+ }
+% \end{macrocode}
+%
+% \begin{macro}{
+% \@@_deprecated_generic_warn:Nn,
+% \@@_deprecated_generic_warn:Nw,
+% }
+% \cs{@@_deprecated_generic_warn:n} will issue a deprecation warning
+% for a given hook, and mark that hook such that the warning will not
+% be issued again (multiple warnings can be issued, but only once per
+% hook).
+% \begin{macrocode}
+\cs_new_protected:Npn \@@_deprecated_generic_warn:n #1
+ { \@@_deprecated_generic_warn:w #1 \s_@@_mark }
+\cs_new_protected:Npn \@@_deprecated_generic_warn:w
+ #1 / #2 / #3 \s_@@_mark
+ {
+ \if_cs_exist:w @@~#1/#2/#3 \cs_end: \else:
+ \msg_warning:nnnnn { hooks } { generic-deprecated } {#1} {#2} {#3}
+ \fi:
+ \cs_gset_eq:cN { @@~#1/#2/#3 } \scan_stop:
+ }
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{
+% \@@_do_deprecated_generic:Nn,
+% \@@_do_deprecated_generic:Nw,
+% \@@_declare_deprecated_generic:NNw,
+% \@@_declare_deprecated_generic:NNw,
+% }
+% Now that the user was told about the deprecation, proceed by
+% swapping \meta{name} and \meta{place} and add the code to the
+% correct hook.
+% \begin{macrocode}
+\cs_new_protected:Npn \@@_do_deprecated_generic:Nn #1 #2
+ { \@@_do_deprecated_generic:Nw #1 #2 \s_@@_mark }
+\cs_new_protected:Npn \@@_do_deprecated_generic:Nw #1
+ #2 / #3 / #4 \s_@@_mark
+ { #1 { #2 / #4 / #3 } }
+\cs_new_protected:Npn \@@_declare_deprecated_generic:NNn #1 #2 #3
+ { \@@_declare_deprecated_generic:NNw #1 #2 #3 \s_@@_mark }
+\cs_new_protected:Npn \@@_declare_deprecated_generic:NNw #1 #2
+ #3 / #4 / #5 \s_@@_mark
+ {
+ \@@_try_declaring_generic_hook:wnTF #3 / #5 / #4 / \scan_stop:
+ { #3 / #5 / #4 }
+ #1 #2 { #3 / #5 / #4 }
}
%<latexrelease>\EndIncludeInRelease
% \end{macrocode}
+% \end{macro}
%
% \begin{macrocode}
%<latexrelease>\IncludeInRelease{2021/06/01}{\@@_try_declaring_generic_hook:wn}
@@ -3156,7 +3230,16 @@
% \end{macro}
% \end{macro}
%
-% \begin{macro}{\c_@@_generics_prop}
+% \begin{macro}{
+% \c_@@_generic_cmd/./before_tl,\c_@@_generic_cmd/./after_tl,
+% \c_@@_generic_env/./before_tl,\c_@@_generic_env/./after_tl,
+% \c_@@_generic_file/./before_tl,\c_@@_generic_file/./after_tl,
+% \c_@@_generic_package/./before_tl,\c_@@_generic_package/./after_tl,
+% \c_@@_generic_class/./before_tl,\c_@@_generic_class/./after_tl,
+% \c_@@_generic_include/./before_tl,\c_@@_generic_include/./after_tl,
+% \c_@@_generic_env/./begin_tl,\c_@@_generic_env/./end_tl,
+% \c_@@_generic_include/./end_tl
+% }
% 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}
@@ -3268,7 +3351,14 @@
%
% If the code pool for this hook doesn't exist, show a warning:
% \begin{macrocode}
- { \msg_warning:nnnn { hooks } { cannot-remove } {#1} {#2} }
+ {
+ \@@_if_deprecated_generic:nTF {#1}
+ {
+ \@@_deprecated_generic_warn:n {#1}
+ \@@_do_deprecated_generic:Nn \@@_gremove_code:nn {#1} {#2}
+ }
+ { \msg_warning:nnnn { hooks } { cannot-remove } {#1} {#2} }
+ }
}
% \end{macrocode}
% \end{macro}
@@ -3329,6 +3419,13 @@
% \begin{macrocode}
\cs_new_protected:Npn \@@_gset_rule:nnnn #1#2#3#4
{
+ \@@_if_deprecated_generic:nT {#1}
+ {
+ \@@_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
+ }
% \end{macrocode}
% First we ensure the basic data structure of the hook exists:
% \begin{macrocode}
@@ -4091,6 +4188,12 @@
% \begin{macrocode}
\cs_new_protected:Npn \@@_log:nN #1 #2
{
+ \@@_if_deprecated_generic:nT {#1}
+ {
+ \@@_deprecated_generic_warn:n {#1}
+ \@@_do_deprecated_generic:Nn \@@_log:nN {#1} #2
+ \exp_after:wN \use_none:nnnnnnnnn \use_none:nnnnn
+ }
\@@_preamble_hook:n {#1}
\@@_log_cmd:x { ^^J ->~The~hook~'#1': }
% \end{macrocode}
@@ -4305,6 +4408,12 @@
% \begin{macrocode}
\cs_new_protected:Npn \@@_gput_next_code:nn #1 #2
{
+ \@@_if_deprecated_generic:nT {#1}
+ {
+ \@@_deprecated_generic_warn:n {#1}
+ \@@_do_deprecated_generic:Nn \@@_gput_next_code:nn {#1} {#2}
+ \use_none:nnnn
+ }
\@@_if_disabled:nTF {#1}
{ \msg_error:nnn { hooks } { hook-disabled } {#1} }
{
@@ -4641,19 +4750,29 @@
% \end{macro}
%
% \begin{macro}[pTF]{\@@_if_generic:n}
+% \begin{macro}[pTF]{\@@_if_deprecated_generic:n}
% An internal conditional that checks if a name belongs to a generic
% hook.
% \begin{macrocode}
\prg_new_conditional:Npnn \@@_if_generic:n #1 { TF }
- { \@@_if_generic:w #1 / / / \scan_stop: }
-\cs_new:Npn \@@_if_generic:w #1 / #2 / #3 / #4 \scan_stop:
+ { \@@_if_generic:w #1 / / / \s_@@_mark }
+\cs_new:Npn \@@_if_generic:w #1 / #2 / #3 / #4 \s_@@_mark
{
\cs_if_exist:cTF { c_@@_generic_#1/./#3_tl }
{ \prg_return_true: }
{ \prg_return_false: }
}
+\prg_new_conditional:Npnn \@@_if_deprecated_generic:n #1 { T, TF }
+ { \@@_if_deprecated_generic:w #1 / / / \s_@@_mark }
+\cs_new:Npn \@@_if_deprecated_generic:w #1 / #2 / #3 / #4 \s_@@_mark
+ {
+ \cs_if_exist:cTF { c_@@_generic_#1/./#2_tl }
+ { \prg_return_true: }
+ { \prg_return_false: }
+ }
% \end{macrocode}
% \end{macro}
+% \end{macro}
%
% \begin{macro}[pTF]{\@@_if_generic_reversed:n}
% An internal conditional that checks if a name belongs to a generic
@@ -4828,8 +4947,13 @@
}
% \end{macrocode}
%
-%
-%
+% \begin{macrocode}
+\msg_new:nnn { hooks } { generic-deprecated }
+ {
+ Generic~hook~'#1/#2/#3'~is~deprecated. \\
+ Use~hook~'#1/#3/#2'~instead.
+ }
+% \end{macrocode}
%
%
%
diff --git a/base/testfiles-lthooks/github-0648.lvt b/base/testfiles-lthooks/github-0648.lvt
new file mode 100644
index 00000000..779ca9b7
--- /dev/null
+++ b/base/testfiles-lthooks/github-0648.lvt
@@ -0,0 +1,64 @@
+
+\RequirePackage[enable-debug]{expl3}
+\ExplSyntaxOn
+\debug_on:n { check-declarations , deprecation }
+\ExplSyntaxOff
+
+\input{regression-test}
+
+\def\test#1/#2/#3;{%
+ % Using deprecated names for generic hooks:
+ \AddToHook{#1/#2/#3}{\typeout{Old #1/#2/#3}}%
+ % Using new names:
+ \AddToHook{#1/#3/#2}{\typeout{New #1/#3/#2}}}
+
+\begin{filecontents}{aaa.sty}
+\end{filecontents}
+\begin{filecontents}{bbb.tex}
+\end{filecontents}
+
+\START
+
+\test file/before/aaa.sty;
+\test file/after/aaa.sty;
+\test package/before/aaa;
+\test package/after/aaa;
+\test class/before/minimal;
+\test class/after/minimal;
+\test include/before/bbb;
+\test include/end/bbb;
+\test include/after/bbb;
+
+% try this hook again
+\test file/before/aaa.sty;
+
+\def\resethook#1{%
+ \expandafter\let
+ \csname __hook #1\endcsname\UNDEFINED}
+
+%%%
+\AddToHook{file/foo.tex/before}{code}
+
+\typeout{\string\RemoveFromHook:}
+\RemoveFromHook{file/before/foo.tex}[top-level]
+\resethook{file/before/foo.tex}
+
+\typeout{\string\ShowHook:}
+\ShowHook{file/before/foo.tex}
+\resethook{file/before/foo.tex}
+
+\typeout{\string\AddToHookNext:}
+\AddToHookNext{file/before/foo.tex}{code}
+\resethook{file/before/foo.tex}
+
+\typeout{\string\DeclareHookRule:}
+\DeclareHookRule{file/before/foo.tex}{a}{before}{b}
+\resethook{file/before/foo.tex}
+
+\documentclass{minimal}
+\usepackage{aaa}
+\OMIT
+\begin{document}
+\TIMO
+\include{bbb}
+\end{document}
diff --git a/base/testfiles-lthooks/github-0648.tlg b/base/testfiles-lthooks/github-0648.tlg
new file mode 100644
index 00000000..877d0f52
--- /dev/null
+++ b/base/testfiles-lthooks/github-0648.tlg
@@ -0,0 +1,62 @@
+This is a generated file for the l3build validation system.
+Don't change this file in any respect.
+LaTeX hooks Warning: Generic hook 'file/before/aaa.sty' is deprecated.
+(hooks) Use hook 'file/aaa.sty/before' instead.
+LaTeX hooks Warning: Generic hook 'file/after/aaa.sty' is deprecated.
+(hooks) Use hook 'file/aaa.sty/after' instead.
+LaTeX hooks Warning: Generic hook 'package/before/aaa' is deprecated.
+(hooks) Use hook 'package/aaa/before' instead.
+LaTeX hooks Warning: Generic hook 'package/after/aaa' is deprecated.
+(hooks) Use hook 'package/aaa/after' instead.
+LaTeX hooks Warning: Generic hook 'class/before/minimal' is deprecated.
+(hooks) Use hook 'class/minimal/before' instead.
+LaTeX hooks Warning: Generic hook 'class/after/minimal' is deprecated.
+(hooks) Use hook 'class/minimal/after' instead.
+LaTeX hooks Warning: Generic hook 'include/before/bbb' is deprecated.
+(hooks) Use hook 'include/bbb/before' instead.
+LaTeX hooks Warning: Generic hook 'include/end/bbb' is deprecated.
+(hooks) Use hook 'include/bbb/end' instead.
+LaTeX hooks Warning: Generic hook 'include/after/bbb' is deprecated.
+(hooks) Use hook 'include/bbb/after' instead.
+\RemoveFromHook:
+LaTeX hooks Warning: Generic hook 'file/before/foo.tex' is deprecated.
+(hooks) Use hook 'file/foo.tex/before' instead.
+\ShowHook:
+LaTeX hooks Warning: Generic hook 'file/before/foo.tex' is deprecated.
+(hooks) Use hook 'file/foo.tex/before' instead.
+-> The hook 'file/foo.tex/before':
+> The hook is empty.
+<recently read> }
+l. ...\ShowHook{file/before/foo.tex}
+\AddToHookNext:
+LaTeX hooks Warning: Generic hook 'file/before/foo.tex' is deprecated.
+(hooks) Use hook 'file/foo.tex/before' instead.
+\DeclareHookRule:
+LaTeX hooks Warning: Generic hook 'file/before/foo.tex' is deprecated.
+(hooks) Use hook 'file/foo.tex/before' instead.
+Old class/before/minimal
+New class/minimal/before
+(minimal.cls
+Document Class: minimal ....-..-.. Standard LaTeX minimal class
+)
+Old class/after/minimal
+New class/minimal/after
+Old package/before/aaa
+New package/aaa/before
+Old file/before/aaa.sty
+New file/aaa.sty/before
+Old file/before/aaa.sty
+New file/aaa.sty/before
+(aaa.sty)
+Old file/after/aaa.sty
+New file/aaa.sty/after
+Old package/after/aaa
+New package/aaa/after
+Old include/before/bbb
+New include/bbb/before
+(bbb.tex)
+Old include/end/bbb
+New include/bbb/end
+Old include/after/bbb
+New include/bbb/after
+(github-0648.aux (bbb.aux))
More information about the latex3-commits
mailing list.