[latex3-commits] [git/LaTeX3-latex3-latex2e] lthooks-doc-updates: Add deprecation commands (db7dc4e3)

[PhelypeOleinik]

Repository : https://github.com/latex3/latex2e
On branch  : lthooks-doc-updates
Link       : https://github.com/latex3/latex2e/commit/db7dc4e3e0055dcc8d158cc5d2cf57dae202a2c7

>---------------------------------------------------------------

commit db7dc4e3e0055dcc8d158cc5d2cf57dae202a2c7
Author: PhelypeOleinik <phelype.oleinik at latex-project.org>
Date:   Thu Aug 5 23:14:04 2021 -0300

    Add deprecation commands


>---------------------------------------------------------------

db7dc4e3e0055dcc8d158cc5d2cf57dae202a2c7
 base/lthooks.dtx                                   | 104 +++++++++++++++++----
 base/testfiles-lthooks/lthooks-029-deprecated.tlg  |  12 +++
 .../lthooks-errors-deprecated.tlg                  |   4 +
 3 files changed, 101 insertions(+), 19 deletions(-)

diff --git a/base/lthooks.dtx b/base/lthooks.dtx
index ad12d42f..7fd8a7a4 100644
--- a/base/lthooks.dtx
+++ b/base/lthooks.dtx
@@ -5138,37 +5138,103 @@
 %
 % \fmiinline{these should give a deprecation warning now}
 %
-% \begin{macro}{\@@_activate_generic_reversed:n}
-%    Deprecated.
+% \begin{macro}{%
+%     \hook_disable:n,
+%¨    \hook_provide:n,
+%     \hook_provide_reversed:n,
+%     \hook_provide_pair:nn,
+%     \@@_activate_generic_reversed:n,
+%     \@@_activate_generic_pair:nn,
+%   }
+%   Deprecated.
 %    \begin{macrocode}
+\cs_new_protected:Npn \hook_disable:n
+  {
+    \@@_deprecated_warn:nn
+      { hook_disable:n }
+      { hook_disable_generic:n }
+    \hook_disable_generic:n
+  }
+\cs_new_protected:Npn \hook_provide:n
+  {
+    \@@_deprecated_warn:nn
+      { hook_provide:n }
+      { hook_activate_generic:n }
+    \hook_activate_generic:n
+  }
+\cs_new_protected:Npn \hook_provide_reversed:n
+  {
+    \@@_deprecated_warn:nn
+      { hook_provide_reversed:n }
+      { hook_activate_generic:n }
+    \@@_activate_generic_reversed:n
+  }
+\cs_new_protected:Npn \hook_provide_pair:nn
+  {
+    \@@_deprecated_warn:nn
+      { hook_provide_pair:nn }
+      { hook_activate_generic:n }
+    \@@_activate_generic_pair:nn
+  }
 \cs_new_protected:Npn \@@_activate_generic_reversed:n #1
   { \@@_normalize_hook_args:Nn \@@_activate_generic:nn {#1} { - } }
+\cs_new_protected:Npn \@@_activate_generic_pair:nn #1#2
+  { \hook_activate_generic:n {#1} \@@_activate_generic_reversed:n {#2} }
 %    \end{macrocode}
 % \end{macro}
 %
-%
-% \begin{macro}{\@@_activate_generic_pair:nn}
-%    Deprecated.
+% \begin{macro}{
+%     \DisableHook,
+%     \ProvideHook,
+%     \ProvideReversedHook,
+%     \ProvideMirroredHookPair,
+%   }
+%   Deprecated.
 %    \begin{macrocode}
-\cs_new_protected:Npn \@@_activate_generic_pair:nn #1#2
-  { \hook_activate_generic:n {#1} \@@_activate_generic_reversed:n {#2} }
+\cs_new_protected:Npn \DisableHook
+  {
+    \@@_deprecated_warn:nn
+      { DisableHook }
+      { DisableGenericHook }
+    \hook_disable_generic:n
+  }
+\cs_new_protected:Npn \ProvideHook
+  {
+    \@@_deprecated_warn:nn
+      { ProvideHook }
+      { ActivateGenericHook }
+    \hook_activate_generic:n
+  }
+\cs_new_protected:Npn \ProvideReversedHook
+  {
+    \@@_deprecated_warn:nn
+      { ProvideReversedHook }
+      { ActivateGenericHook }
+    \@@_activate_generic_reversed:n
+  }
+\cs_new_protected:Npn \ProvideMirroredHookPair
+  {
+    \@@_deprecated_warn:nn
+      { ProvideMirroredHookPair }
+      { ActivateGenericHook }
+    \@@_activate_generic_pair:nn
+  }
 %    \end{macrocode}
 % \end{macro}
 %
-%
-%  \begin{macro}{\ProvideReversedHook,\ProvideMirroredHookPair}
-%    Deprecated.
+% \begin{macro}{\@@_deprecated_warn:nn}
+%   Warns about a deprecation, telling what should be used instead.
 %    \begin{macrocode}
-\NewDocumentCommand \ProvideReversedHook { m }{ \@@_activate_generic_reversed:n {#1} }
-\NewDocumentCommand \ProvideMirroredHookPair { mm }{ \@@_activate_generic_pair:nn {#1}{#2} }
+\cs_new_protected:Npn \@@_deprecated_warn:nn #1 #2
+  { \msg_warning:nnnn { hooks } { deprecated } {#1} {#2} }
+\msg_new:nnn { hooks } { deprecated }
+  {
+    Command~\iow_char:N\\#1~is~deprecated~and~will~be~removed~in~a~
+    future~release. \\ \\
+    Use~\iow_char:N\\#2~instead.
+  }
 %    \end{macrocode}
-%  \end{macro}
-%
-%
-%
-%
-%
-%
+% \end{macro}
 %
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 %
diff --git a/base/testfiles-lthooks/lthooks-029-deprecated.tlg b/base/testfiles-lthooks/lthooks-029-deprecated.tlg
index 8faac2a3..7c050942 100644
--- a/base/testfiles-lthooks/lthooks-029-deprecated.tlg
+++ b/base/testfiles-lthooks/lthooks-029-deprecated.tlg
@@ -72,11 +72,19 @@ l. ...\ShowHook{bbb}
 <recently read> }
 l. ...\ShowHook{ccc}
 ------------ provide an known reversed hook --------------
+LaTeX hooks Warning: Command \ProvideReversedHook is deprecated and will be
+(hooks)              removed in a future release.
+(hooks)              
+(hooks)              Use \ActivateGenericHook instead.
 -> The hook 'ccc':
 > The hook is empty.
 <recently read> }
 l. ...\ShowHook{ccc}
 ------------ provide an known reversed hook with data --------------
+LaTeX hooks Warning: Command \ProvideReversedHook is deprecated and will be
+(hooks)              removed in a future release.
+(hooks)              
+(hooks)              Use \ActivateGenericHook instead.
 -> The hook 'ccc':
 > Code chunks:
 >     Z -> Z1
@@ -91,6 +99,10 @@ l. ...\ShowHook{ccc}
 <recently read> }
 l. ...\ShowHook{ccc}
 ------------ provide an reversed hook on an existing normal hook --------------
+LaTeX hooks Warning: Command \ProvideReversedHook is deprecated and will be
+(hooks)              removed in a future release.
+(hooks)              
+(hooks)              Use \ActivateGenericHook instead.
 ! LaTeX hooks Error: Hook 'aaa' already declared as a normal hook!
 For immediate help type H <return>.
  ...                                              
diff --git a/base/testfiles-lthooks/lthooks-errors-deprecated.tlg b/base/testfiles-lthooks/lthooks-errors-deprecated.tlg
index 1cc79916..1a5fafd9 100644
--- a/base/testfiles-lthooks/lthooks-errors-deprecated.tlg
+++ b/base/testfiles-lthooks/lthooks-errors-deprecated.tlg
@@ -6,6 +6,10 @@ For immediate help type H <return>.
 l. ...\NewHook{xxx}
 There already exists a hook declaration with this name.
 Please use a different name for your hook.
+LaTeX hooks Warning: Command \ProvideReversedHook is deprecated and will be
+(hooks)              removed in a future release.
+(hooks)              
+(hooks)              Use \ActivateGenericHook instead.
 ! LaTeX hooks Error: Hook 'xxx' already declared as a normal hook!
 For immediate help type H <return>.
  ...