[latex3-commits] [git/LaTeX3-latex3-latex2e] clsguide-cleanup: Add details of \DeclareRobustCommand, etc. (fc9c205e)

[Joseph Wright]

Repository : https://github.com/latex3/latex2e
On branch  : clsguide-cleanup
Link       : https://github.com/latex3/latex2e/commit/fc9c205e49dca1f9fa266756c4e0b4a3dfcfa401

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

commit fc9c205e49dca1f9fa266756c4e0b4a3dfcfa401
Author: Joseph Wright <joseph.wright at morningstar2.co.uk>
Date:   Thu Jan 12 13:06:57 2023 +0000

    Add details of \DeclareRobustCommand, etc.


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

fc9c205e49dca1f9fa266756c4e0b4a3dfcfa401
 base/doc/clsguide.tex | 60 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 60 insertions(+)

diff --git a/base/doc/clsguide.tex b/base/doc/clsguide.tex
index c2fe499e..2589a3ee 100644
--- a/base/doc/clsguide.tex
+++ b/base/doc/clsguide.tex
@@ -1083,4 +1083,64 @@ command from expanding; |\MessageBreak| causes a line-break; and |\space|
 prints a space. Also, these should not end with a full stop as one is
 automatically added.
 
+\section{Deprecated commands in wide use}
+
+A small number of commands were introduced as part of \LaTeXe{} in the
+mid-1990s, are widely used but have been superseded by more modern methods.
+These are covered here as they are likely to be encountered routinely in
+existing classes and packages.
+
+\subsection{Defining commands}
+
+The \texttt{*}-forms of these commands should be used to define
+commands that are not, in \TeX{} terms, long.  This can be useful for
+error-trapping with commands whose arguments are not intended to
+contain whole paragraphs of text.
+
+\begin{decl}
+  |\DeclareRobustCommand| \arg{cmd} \oarg{num} \oarg{default}
+     \arg{definition}\\
+  |\DeclareRobustCommand*| \arg{cmd} \oarg{num} \oarg{default}
+     \arg{definition}
+\end{decl}
+This command takes the same arguments as |\newcommand| but it declares a robust
+command, even if some code within the \m{definition} is fragile. You can use
+this command to define new robust commands, or to redefine existing commands
+and make them robust. A log is put into the transcript file if a command is
+redefined.
+
+For example, if |\seq| is defined as follows:
+\begin{verbatim}
+   \DeclareRobustCommand{\seq}[2][n]{%
+     \ifmmode
+       #1_{1}\ldots#1_{#2}%
+     \else
+       \PackageWarning{fred}{You can't use \protect\seq\space in text}%
+     \fi
+   }
+\end{verbatim}
+Then the command |\seq| can be used in moving arguments, even though
+|\ifmmode| cannot, for example:
+\begin{verbatim}
+   \section{Stuff about sequences $\seq{x}$}
+\end{verbatim}
+
+Note also that there is no need to put a |\relax| before the |\ifmmode| at the
+beginning of the definition; this is because the protection given by this
+|\relax| against expansion at the wrong time will be provided internally.
+
+\begin{decl}
+  |\CheckCommand| \arg{cmd} \oarg{num} \oarg{default}
+     \arg{definition}\\
+  |\CheckCommand*| \arg{cmd} \oarg{num} \oarg{default}
+     \arg{definition}
+\end{decl}
+This takes the same arguments as |\newcommand| but, rather than define \m{cmd},
+it just checks that the current definition of \m{cmd} is exactly as given by
+\m{definition}. An error is raised if these definitions differ.
+
+This command is useful for checking the state of the system before your package
+starts altering the definitions of commands. It allows you to check, in
+particular, that no other package has redefined the same command.
+
 \end{document}