[latex3-commits] [l3svn] r6674 - l3doc: add key "deprecated" for function environment

[noreply at latex-project.org]

Author: bruno
Date: 2016-08-18 16:07:23 +0200 (Thu, 18 Aug 2016)
New Revision: 6674

Modified:
   trunk/l3kernel/l3doc.dtx
Log:
l3doc: add key "deprecated" for function environment

This key raises an error if the given date is past.
Presumably that will make sure we remember to delete
deprecated functions.


Modified: trunk/l3kernel/l3doc.dtx
===================================================================
--- trunk/l3kernel/l3doc.dtx	2016-08-18 13:21:28 UTC (rev 6673)
+++ trunk/l3kernel/l3doc.dtx	2016-08-18 14:07:23 UTC (rev 6674)
@@ -862,6 +862,22 @@
 %    \end{macrocode}
 % \end{variable}
 %
+% \begin{variable}[int]{\l_@@_date_added_tl, \l_@@_date_updated_tl}
+%   Values of some options of the \env{function} environment.
+%    \begin{macrocode}
+\tl_new:N \l_@@_date_added_tl
+\tl_new:N \l_@@_date_updated_tl
+%    \end{macrocode}
+% \end{variable}
+%
+% \begin{variable}[int]{\l_@@_function_argument_tl}
+%   Save the argument of a \env{function} environment for use in error
+%   messages.
+%    \begin{macrocode}
+\tl_new:N \l_@@_function_argument_tl
+%    \end{macrocode}
+% \end{variable}
+%
 % ^^A Bruno: what does the next line do?
 %    \begin{macrocode}
 % \int_new:N \c at CodelineNo
@@ -1187,6 +1203,48 @@
 % \end{macro}
 % \end{macro}
 %
+% \begin{macro}[int, pTF]{\@@_date_compare:nNn}
+% \begin{macro}[aux]{\@@_date_compare_aux:nnnNnnn, \@@_date_compare_aux:w}
+%    \begin{macrocode}
+\prg_new_conditional:Npnn \@@_date_compare:nNn #1#2#3 { TF , T , F , p }
+  { \@@_date_compare_aux:w #1/// \q_mark #2 #3/// \q_stop }
+\cs_new:Npn \@@_date_compare_aux:w
+    #1 / #2 / #3 / #4 \q_mark #5 #6 / #7 / #8 / #9 \q_stop
+  {
+    \@@_date_compare_aux:nnnNnnn
+      { \tl_if_empty:nTF {#1} { 0 } {#1} }
+      { \tl_if_empty:nTF {#2} { 0 } {#2} }
+      { \tl_if_empty:nTF {#3} { 0 } {#3} }
+      #5
+      { \tl_if_empty:nTF {#6} { 0 } {#6} }
+      { \tl_if_empty:nTF {#7} { 0 } {#7} }
+      { \tl_if_empty:nTF {#8} { 0 } {#8} }
+  }
+\cs_new:Npn \@@_date_compare_aux:nnnNnnn #1#2#3#4#5#6#7
+  {
+    \int_compare:nNnTF {#1} = {#5}
+      {
+        \int_compare:nNnTF {#2} = {#6}
+          {
+            \int_compare:nNnTF {#3} #4 {#7}
+              { \prg_return_true: } { \prg_return_false: }
+          }
+          {
+            \int_compare:nNnTF {#2} #4 {#6}
+              { \prg_return_true: } { \prg_return_false: }
+          }
+      }
+      {
+        \int_compare:nNnTF {#1} #4 {#5}
+          { \prg_return_true: } { \prg_return_false: }
+      }
+    \use_none:n
+    \q_stop
+  }
+%    \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
 % \subsection{Messages}
 %
 %    \begin{macrocode}
@@ -1198,6 +1256,8 @@
     ':'~hence~it~is~not~clear~where~to~add~'_p'~or~'TF'.~
     Please~follow~expl3~naming~conventions.
   }
+\msg_new:nnn { l3doc } { deprecated-function }
+  { The~deprecated~function(s)~'#1'~should~have~been~removed~on~#2. }
 %    \end{macrocode}
 %
 % \subsection{Options and configuration}
@@ -2044,6 +2104,7 @@
       } ,
     added .tl_set:N = \l_@@_date_added_tl ,
     updated .tl_set:N = \l_@@_date_updated_tl ,
+    deprecated .code:n = { \@@_deprecated_on:n {#1} } ,
     tested .code:n = { } ,
     no-label .bool_set:N = \l_@@_no_label_bool ,
     verb .value_forbidden:n = true ,
@@ -2051,6 +2112,19 @@
   }
 %    \end{macrocode}
 %
+% \begin{macro}[aux]{\@@_deprecated_on:n}
+%   Complain if a deprecated function should have been removed earlier.
+%    \begin{macrocode}
+\cs_new_protected:Npn \@@_deprecated_on:n #1
+  {
+    \@@_date_compare:nNnT {#1} < { \tex_year:D / \tex_month:D / \tex_day:D }
+      {
+        \msg_error:nnxx { l3doc } { deprecated-function }
+          { \tl_to_str:N \l_@@_function_argument_tl } {#1}
+      }
+  }
+%    \end{macrocode}
+% \end{macro}
 %
 % \begin{macro}[int]{\@@_function:nnw}
 %   \begin{arguments}
@@ -2073,6 +2147,7 @@
   {
     \@@_function_typeset_start:
     \@@_function_init:
+    \tl_set:Nn \l_@@_function_argument_tl {#2}
     \keys_set:nn { l3doc/function } {#1}
     \@@_names_get_seq:nN {#2} \l_@@_names_seq
     \@@_names_parse: