[latex3-commits] [latex3/latex2e] If-X-TF: Document \IfPackageAtLeastTF, etc. (564abf3f)

[github at latex-project.org]

Repository : https://github.com/latex3/latex2e
On branch  : If-X-TF
Link       : https://github.com/latex3/latex2e/commit/564abf3f9691e4144526ebeb55101378803e843b

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

commit 564abf3f9691e4144526ebeb55101378803e843b
Author: Joseph Wright <joseph at texdev.net>
Date:   Mon Sep 2 08:21:46 2024 +0100

    Document \IfPackageAtLeastTF, etc.


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

564abf3f9691e4144526ebeb55101378803e843b
 base/changes.txt      |  5 ++++
 base/doc/clsguide.tex | 77 +++++++++++++++++++++++++++++++++++++++++++++------
 2 files changed, 73 insertions(+), 9 deletions(-)

diff --git a/base/changes.txt b/base/changes.txt
index e758eeba..4244b12c 100644
--- a/base/changes.txt
+++ b/base/changes.txt
@@ -6,6 +6,11 @@ to completeness or accuracy and it contains some references to files that are
 not part of the distribution.
 ================================================================================
 
+2024-09-02  Joseph Wright  <Joseph.Wright at latex-project.org>
+
+	* clsguide.tex:
+	Document \IfPackageAtLeastTF, etc.
+
 2024-08-12  Joseph Wright  <Joseph.Wright at latex-project.org>
 
 	* ltluatex.dtx:
diff --git a/base/doc/clsguide.tex b/base/doc/clsguide.tex
index c7c2ac5e..5447922f 100644
--- a/base/doc/clsguide.tex
+++ b/base/doc/clsguide.tex
@@ -42,7 +42,7 @@
     \texttt{clsguide.tex} for full details.}%
 }
 
-\date{2024-06-19}
+\date{2024-09-02}
 
 \NewDocumentCommand\cs{m}{\texttt{\textbackslash\detokenize{#1}}}
 \NewDocumentCommand\marg{m}{\arg{#1}}
@@ -366,7 +366,8 @@ The outline of a class or package file is:
    declaring new variables, commands and fonts; and loading other files.
 \end{description}
 
-\subsection{Identification}
+\subsection{Identification%
+  \label{sec:ID}}
 
 The first thing a class or package file does is identify itself.
 Package files do this as follows:
@@ -389,12 +390,14 @@ For example:
    \NeedsTeXFormat{LaTeX2e}
    \ProvidesClass{article}[2022-06-01 Standard LaTeX class]
 \end{verbatim}
-The \m{date} should be given in the form `\textsc{yyyy-mm-dd}' and must be
-present if the optional argument is used (this is also true for the
-|\NeedsTeXFormat| command). Any derivation from this syntax will result in
-low-level \TeX{} errors---the commands expect a valid syntax to speed up the
-daily usage of the package or class and make no provision for the case that the
-developer made a mistake!
+The \m{date} should be given in the form `\textsc{yyyy-mm-dd}' or
+`\textsc{yyyy/mm/dd}' and must be present if the optional argument is used.
+Exactly four digits are required for the year and two each for the month and
+day. Where necessary, zeros should be added to pad the month and day
+appropriately. If digits or separators are missing, the date will likely be
+misinterpreted: the commands expect a valid syntax to speed up the daily usage
+of the package or class and make no provision for the case that the developer
+made a mistake!
 
 This date is checked whenever a user specifies a date in their |\documentclass|
 or |\usepackage| command. For example, if you wrote:
@@ -676,7 +679,8 @@ with name \m{format-name}. You can use the optional argument \m{release-date}
 to further specify the earliest release date of the format that is needed. When
 the release date of the format is older than the one specified a warning will
 be generated. The standard \m{format-name} is \texttt{LaTeX2e}. The date, if
-present, must be in the form \textsc{yyyy-mm-dd}.
+present, must be in the form `\textsc{yyyy-mm-dd}' or
+`\textsc{yyyy/mm/dd}'.
 
 Example:
 \begin{verbatim}
@@ -977,6 +981,61 @@ as in that case \textsf{article} is passed options only by the default option
 handler, but this handler is not used for |landscape| because that option is
 explicitly declared.
 
+\subsection{Useful status tests}
+
+A number of status tests are available which can be used by package and
+class authors to query the presence and date of other code, the current kernel
+release and other related ideas. Three forms of each test are provided, one
+requiring arguments for both \meta{true} and \meta{false} branches, one
+requiring only a \meta{true} branch and one requiring only a \meta{false}
+branch. These are indicated in their names as |TF|, |T| and |F|, respectively.
+Here, we document only the |TF| versions: the other forms are however
+available.
+
+\begin{decl}
+  |\IfPackageLoadedTF| \arg{package-name} \arg{true code} \arg{false code}\\
+  |\IfClassLoadedTF| \arg{class-name} \arg{true code} \arg{false code}\\
+  |\IfFileLoadedTF| \arg{file-name} \arg{true code} \arg{false code}
+\end{decl}
+These commands test whether the named package, class or file is loaded: this
+requires that this information is available in an appropriate |\Provides...|
+line, as described in Section~\ref{sec:ID}. In the case of \cs{IfFileLoadedTF},
+the full \meta{file-name} must be provided; in contrast, no extension should be
+given if testing for a package or class.
+
+\begin{decl}
+  |\IfPackageLoadedWithOptionsTF| \arg{package-name} \arg{options} \arg{true code} \arg{false code}\\
+  |\IfClassLoadedOptionsTF| \arg{class-name} \arg{options} \arg{true code} \arg{false code}
+\end{decl}
+These commands test if the named package or class was loaded with
+\emph{exactly} the \meta{options} specified. Thus the package or class must be
+loaded (giving a \texttt{true} result for \cs{If...LoadedT}) and the option
+list used when loading it must be identifical to the \meta{options}.
+
+\begin{decl}
+  |\IfPackageAtLeastTF| \arg{package-name} \arg{date} \arg{true code} \arg{false code}\\
+  |\IfClassAtLeastTF| \arg{class-name} \arg{date} \arg{true code} \arg{false code}\\
+  |\IfFileAtLeastTF| \arg{file-name} \arg{date} \arg{true code} \arg{false code}
+\end{decl}
+These tests are used to check wheteher the date information given in the
+|\Provides...| line of a package or class is least a given \meta{date}.
+The \meta{date} is compared with that in the
+optional argument to \cs{Provides...} (as described in Section~\ref{sec:ID});
+if \cs{Provides...} was missing or had no optional argument, the reference
+date is treated as |0000/00/00|.
+As for \cs{Provides...}, the \meta{date} should be given in the form
+`\textsc{yyyy-mm-dd}' or `\textsc{yyyy/mm/dd}'. If the package or class is not
+loaded, the \meta{false} branch will be taken; in contrast, if the \meta{date}
+is not of the required form, the behavior is formally undefined.
+
+\begin{decl}
+  |\IfFormatAtLeastTF| \arg{date} \arg{true code} \arg{false code}
+\end{decl}
+Tests the release \meta{date} of the \LaTeX{} format and selects the
+appropriate branch. The date used by the format is adjusted to incorporate any
+roll forward or back that has been applied to it, so that the the apparent date
+of the format will be that after roll back.
+
 \subsection{Safe file commands}
 
 These commands deal with file input; they ensure that the non-existence of a