[latex3-commits] [git/LaTeX3-latex3-latex2e] gh373: Add documentation on \robust at command@act (cc5beede)

[PhelypeOleinik]

Repository : https://github.com/latex3/latex2e
On branch  : gh373
Link       : https://github.com/latex3/latex2e/commit/cc5beedea657af8507ec120732dfe4d9884bad23

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

commit cc5beedea657af8507ec120732dfe4d9884bad23
Author: PhelypeOleinik <tex.phelype at gmail.com>
Date:   Wed Aug 19 15:18:39 2020 -0300

    Add documentation on \robust at command@act
    
    Mission statement, actually


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

cc5beedea657af8507ec120732dfe4d9884bad23
 base/ltdefns.dtx | 63 +++++++++++++++++++++++++++++++++++++-------------------
 1 file changed, 42 insertions(+), 21 deletions(-)

diff --git a/base/ltdefns.dtx b/base/ltdefns.dtx
index 5abe0387..8aabd24f 100644
--- a/base/ltdefns.dtx
+++ b/base/ltdefns.dtx
@@ -1286,11 +1286,7 @@
 %    \end{macrocode}
 % \end{macro}
 %
-%
-% \begin{macro}{\NewCommandCopy}
-% \begin{macro}{\RenewCommandCopy}
-% \begin{macro}{\DeclareCommandCopy}
-% \changes{v1.5j}{2020/05/09}{Added \cs{DeclareCommandCopy} (gh/239)}
+% \subsection{Acting on robust definitions}
 %
 %   With most document level commands being robust now there is more of a
 %   requirement to have a standard way of aliasing (or copying) a command to a
@@ -1305,22 +1301,35 @@
 %   other types of robust commands that are frequently used, which are not
 %   defined in the \LaTeXe{} kernel, like commands defined with
 %   \textsf{xparse}'s \cs{NewDocumentCommand} and \textsf{etoolbox}'s
-%   \cs{newrobustcmd}.  Here we will define a generic \cs{DeclareCommandCopy}
-%   that will check \LaTeXe's robust types out of the box, but that can be
-%   extended to work with other packages' robust commands.
-%
-%    \begin{macrocode}
-%</2ekernel>
-%<latexrelease>\IncludeInRelease{2020-10-01}{\DeclareCommandCopy}
-%<latexrelease>  {Add \NewCommandCopy, \RenewCommandCopy, and \DeclareCommandCopy}%
-%<*2ekernel|latexrelease>
-%    \end{macrocode}
-%
-%   \cs{DeclareCommandCopy} just calls \cs{declare at command@copy} with \cs{relax},
-%   which serves as a prefix for definitions.  Heiko Oberdiek's
-%   \textsf{letltxmacro} defines a global variant of \cs{LetLtxMacro}, but since
-%   none of our definition commands have a global version, this one won't either,
-%   for consistency.
+%   \cs{newrobustcmd}.
+%
+%   In this section we will define a generic extensible machinery to act on
+%   robust commands.  This code will then be used to test if a command is
+%   robust, considered the different types of robustness, and then either copy
+%   that definition, if \cs{DeclareCommandCopy} (or similar) is used, or show
+%   the definition of the command, if \cs{ShowCommmand} is used.
+%
+%   The looping machinery is generic and knows nothing about what is to be done
+%   for each case.  The syntax of the main macro \cs{robust at command@act} is:
+%   \begin{quote}
+%     |\robust at command@act|\meta{action-list}\meta{fallback-action}\\
+%       \meta{robust-cmd}\meta{act-arg}
+%   \end{quote}
+%   \meta{action-list} is a token list of the form:
+%   \begin{quote}
+%     |{|\meta{if-type-1} \meta{act-type-1}|}|\\
+%     |{|\meta{if-type-2} \meta{act-type-2}|}|\\
+%     \ldots
+%   \end{quote}
+%   \cs{robust at command@act} will iterate over the \meta{action-list}, evaluating
+%   each \meta{if-type-$n$}\meta{robust-cmd}{|\meta{true}|}{|\meta{false}|}|.
+%   If the \meta{if-type-$n$} conditional returns \meta{true}, then
+%   \meta{act-type-$n$}\meta{act-arg} is executed, and the loop ends.  If the
+%   conditional returns \meta{false}, then \meta{if-type-$n+1$} is executed in
+%   the same way, until either one of the conditionals return \meta{true}, or
+%   the end of the \meta{action-list} is reached.  If the end is reached, then
+%   \meta{fallback-action}\meta{act-arg} is executed before
+%   \cs{robust at command@act} exits.
 %
 %   \cs{NewCommandCopy} checks if \verb=#1= is already defined, and raises an
 %   error if so, otherwise the definition is carried out.
@@ -1437,6 +1446,18 @@
       {\@secondoftwo}}}
 %    \end{macrocode}
 %
+%
+%    \begin{macrocode}
+%</2ekernel>
+%<latexrelease>\IncludeInRelease{2020-10-01}{\DeclareCommandCopy}
+%<latexrelease>  {Add \NewCommandCopy, \RenewCommandCopy, and \DeclareCommandCopy}%
+%<*2ekernel|latexrelease>
+%    \end{macrocode}
+%
+% \begin{macro}{\NewCommandCopy}
+% \begin{macro}{\RenewCommandCopy}
+% \begin{macro}{\DeclareCommandCopy}
+% \changes{v1.5j}{2020/05/09}{Added \cs{DeclareCommandCopy} (gh/239)}
 %   The initial definition of \cs{@declarecommandcopylisthook} contains the
 %   tests for the two types of robust command in the kernel.
 %    \begin{macrocode}