[latex3-commits] [git/LaTeX3-latex3-latex2e] gh186: documentation (eb72860b)

[Frank Mittelbach]

Repository : https://github.com/latex3/latex2e
On branch  : gh186
Link       : https://github.com/latex3/latex2e/commit/eb72860b1dc9c84d7952b06ef1ddfffab6a7f6e6

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

commit eb72860b1dc9c84d7952b06ef1ddfffab6a7f6e6
Author: Frank Mittelbach <frank.mittelbach at latex-project.org>
Date:   Mon Apr 13 15:21:28 2020 +0200

    documentation


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

eb72860b1dc9c84d7952b06ef1ddfffab6a7f6e6
 base/doc/ltnews32.tex | 44 +++++++++++++++++++++++++++++++++++---------
 1 file changed, 35 insertions(+), 9 deletions(-)

diff --git a/base/doc/ltnews32.tex b/base/doc/ltnews32.tex
index b9f051e8..0a54a6e6 100644
--- a/base/doc/ltnews32.tex
+++ b/base/doc/ltnews32.tex
@@ -43,6 +43,7 @@
 \providecommand\meta[1]{$\langle$\textit{#1}$\rangle$}
 \providecommand\option[1]{\texttt{#1}}
 \providecommand\env[1]{\texttt{#1}}
+\providecommand\Arg[1]{\texttt\{\meta{#1}\texttt\}}
 
 
 \providecommand\XeTeX{\hologo{XeTeX}}
@@ -300,17 +301,38 @@ has finally be fixed.
 %
 \gnatsissue{latex}{3357}
 
-\subsection{Added test for format date}
 
-\emph{to write}
-
-	Add \cs{IfFormatAtLeastTF} to test if the current format is
-        equal or later than the given date.  Also add
-        \cs{IfClassAtLeastTF} and \cs{IfPackageAtLeastTF} as a
-        suggested alternative to \cs{@ifpackagelater} and
-        \cs{@ifclasslater} (which have a wrong name because it is
-        really ``later or equal'').
 
+\subsection{Added tests for format, package and class dates}
+
+To implement compatibility code or to ensure that certain features are
+available if is  helpful and often necessary to check the date of the
+format or that of a package or class and execute different code based
+on the result. For that \LaTeX\ only had some internal commands
+(\cs{@ifpackagelater} and \cs{@ifclasslater}) for testting package or
+class names but nothing really for testing the format date. For the
+latter one had to resort to some obscure command \cs{@ifl at t@r} that,
+given its cryptic name, was clearly never intended for use even in
+package or class code.  Furthermore, even the existing interface
+commands where defective as they are testing for \enquote{equal or
+  later} and not for \enquote{later} as their names indicate.
+
+We have therefore introduced three new CamelCase commands as the
+official interface for such tests
+\begin{flushleft}
+  \cs{IfFormatAtLeastTF}\Arg{date}\\
+  \hspace*{4em} \Arg{true code}\Arg{false code}
+\end{flushleft}
+and for package and class tests
+\begin{flushleft}
+  \cs{IfClassAtLeastTF}\Arg{class name}\Arg{date}\\
+  \hspace*{4em} \Arg{true code}\Arg{false code} \\
+  \cs{IfPackageAtLeastTF}\Arg{package name}\Arg{date}\\
+  \hspace*{4em} \Arg{true code}\Arg{false code}
+\end{flushleft}
+For compatibility reasons the legacy commands remain available, but we
+suggest to replace them over time and use the new interfaces in new
+code.
 %
 \githubissue{186}
 
@@ -405,6 +427,10 @@ processed as part of the formula.
   \emph{\LaTeX{} documentation on the \LaTeX{} Project Website}.\\
   \url{https://latex-project.org/help/documentation/}
 
+\bibitem{32:issue-tracker}
+  \emph{\LaTeX{} issue tracker}.
+  \url{https://github.com/latex3/latex2e/issues/}
+
 \end{thebibliography}