[latex3-commits] [latex3/latex3] main: Clean up description about old deprecation policy (2cad1a5c9)

[github at latex-project.org]

Repository : https://github.com/latex3/latex3
On branch  : main
Link       : https://github.com/latex3/latex3/commit/2cad1a5c9e36e906bc841062c23d23c3a440c51d

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

commit 2cad1a5c9e36e906bc841062c23d23c3a440c51d
Author: Yukai Chou <muzimuzhi at gmail.com>
Date:   Wed Mar 20 03:21:56 2024 +0800

    Clean up description about old deprecation policy


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

2cad1a5c9e36e906bc841062c23d23c3a440c51d
 l3kernel/l3basics.dtx      |  9 ++++-----
 l3kernel/l3debug.dtx       |  7 +++----
 l3kernel/l3deprecation.dtx | 40 +++++++++++-----------------------------
 3 files changed, 18 insertions(+), 38 deletions(-)

diff --git a/l3kernel/l3basics.dtx b/l3kernel/l3basics.dtx
index 66e999fe6..eb24b55e1 100644
--- a/l3kernel/l3basics.dtx
+++ b/l3kernel/l3basics.dtx
@@ -1340,7 +1340,7 @@
 %       only locally/globally assigned;
 %     \item \texttt{check-expressions} that checks integer, dimension,
 %       skip, and muskip expressions are not terminated prematurely;
-%     \item \texttt{deprecation} that makes soon-to-be-deprecated commands produce errors;
+%     \item \texttt{deprecation} that makes deprecated commands produce errors;
 %     \item \texttt{log-functions} that logs function definitions;
 %     \item \texttt{all} that does all of the above.
 %   \end{itemize}
@@ -1355,7 +1355,7 @@
 %     \cs{debug_suspend:} \ldots{} \cs{debug_resume:}
 %   \end{syntax}
 %   Suppress (locally) errors and logging from \texttt{debug} commands,
-%   except for the \texttt{deprecation} errors or warnings.  These pairs
+%   except for the \texttt{deprecation} errors.  These pairs
 %   of commands can be nested.  This can be used around pieces of code
 %   that are known to fail checks, if such failures should be ignored.
 %   See for instance \pkg{l3coffins}.
@@ -1871,9 +1871,8 @@
 %
 % \begin{macro}{\__kernel_deprecation_code:nn}
 % \begin{variable}{\g_@@_deprecation_on_tl, \g_@@_deprecation_off_tl}
-%   Some commands were more recently deprecated and not yet removed;
-%   only make these into errors if the user requests it.  This relies on
-%   two token lists, filled up in \pkg{l3deprecation}.
+%   Make deprecated commands throw errors if the user requests it.
+%   This relies on two token lists, filled up in \pkg{l3deprecation}.
 %    \begin{macrocode}
 \cs_gset_nopar:Npn \g_@@_deprecation_on_tl { }
 \cs_gset_nopar:Npn \g_@@_deprecation_off_tl { }
diff --git a/l3kernel/l3debug.dtx b/l3kernel/l3debug.dtx
index 6654b6d4c..522d42bab 100644
--- a/l3kernel/l3debug.dtx
+++ b/l3kernel/l3debug.dtx
@@ -389,10 +389,9 @@
 % \end{macro}
 %
 % \begin{macro}{\@@_deprecation_on:, \@@_deprecation_off:}
-%   Some commands were more recently deprecated and not yet removed;
-%   only make these into errors if the user requests it.  This relies on
-%   two token lists, filled up in \pkg{l3deprecation} by calls to
-%   \cs{__kernel_deprecation_code:nn}.
+%   Make deprecated commands throw errors if the user requests it.
+%   This relies on two token lists, filled up in \pkg{l3deprecation} by
+%   calls to \cs{__kernel_deprecation_code:nn}.
 %    \begin{macrocode}
 \cs_new_protected:Npn \@@_deprecation_on:
   { \g_@@_deprecation_on_tl }
diff --git a/l3kernel/l3deprecation.dtx b/l3kernel/l3deprecation.dtx
index 3906c6786..281a2f813 100644
--- a/l3kernel/l3deprecation.dtx
+++ b/l3kernel/l3deprecation.dtx
@@ -51,8 +51,10 @@
 %
 % \section{\pkg{l3deprecation} documentation}
 %
-% A few commands have had to be deprecated over the years.  This module
-% defines deprecated and deleted commands to produce an error.
+% A few commands have had to be deprecated over the years.
+% All commands deprecated before release 2022-01-12 were already
+% removed; commands deprecated since then will no longer be removed.
+% Instead, this module defines them to produce errors.
 %
 % \end{documentation}
 %
@@ -74,31 +76,12 @@
 %   \cs{__kernel_patch_deprecation:nnNNpn} \Arg{date} \Arg{replacement}
 %   \meta{definition} \meta{function} \meta{parameters} \Arg{code}
 % \end{quote}
-% defines the \meta{function} to produce a warning and run its
-% \meta{code}, or to produce an error and not run any \meta{code},
-% depending on the \pkg{expl3} date.
-% \begin{itemize}
-% \item If the \pkg{expl3} date is less than the \meta{date} (plus
-%   $6$~months in case \texttt{undo-recent-deprecations} is used) then
-%   we define the \meta{function} to produce a warning and run its code.
-%   The warning is actually suppressed in two cases:
-%   \begin{itemize}
-%   \item if neither \texttt{undo-recent-deprecations} nor
-%     \texttt{enable-debug} are in effect we may be in an end-user's
-%     document so it is suppressed;
-%   \item if the command is expandable then we cannot produce a warning.
-%   \end{itemize}
-% \item Otherwise, we define the \meta{function} to produce an error.
-% \end{itemize}
-% In both cases we additionally make \cs{debug_on:n} |{deprecation}|
-% turn the \meta{function} into an \tn{outer} error, and
-% \cs{debug_off:n} |{deprecation}| restore whatever the behaviour was
-% without \cs{debug_on:n} |{deprecation}|.
-%
-% In later sections we use the \pkg{l3doc} key \texttt{deprecated} with
-% a date equal to that \meta{date} plus $6$~months, so that \pkg{l3doc}
-% will complain if we forget to remove the stale \meta{parameters} and
-% \Arg{code}.
+% defines the \meta{function} to produce an error and run its
+% \meta{code}.
+%
+% We make \cs{debug_on:n} |{deprecation}| turn the \meta{function} into
+% an \tn{outer} error, and \cs{debug_off:n} |{deprecation}| restore
+% whatever the behaviour was without \cs{debug_on:n} |{deprecation}|.
 %
 % In the explanations below, \meta{definition} \meta{function}
 % \meta{parameters} \Arg{code} or assignments that only differ in the
@@ -183,8 +166,7 @@
 %
 % \begin{macro}{\__kernel_deprecation_error:Nnn}
 %   The \tn{outer} definition here ensures the command cannot appear
-%   in an argument.  Use this auxiliary on all commands that have been
-%   removed since 2015.
+%   in an argument.
 %    \begin{macrocode}
 \cs_new_protected:Npn \__kernel_deprecation_error:Nnn #1#2#3
   {