[latex3-commits] [git/LaTeX3-latex3-latex3] gh795: Add intro documentation (feec52d54)

[PhelypeOleinik]

Repository : https://github.com/latex3/latex3
On branch  : gh795
Link       : https://github.com/latex3/latex3/commit/feec52d54f5f4a9b57e48654313020e9db52a1b2

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

commit feec52d54f5f4a9b57e48654313020e9db52a1b2
Author: PhelypeOleinik <phelype.oleinik at latex-project.org>
Date:   Thu Jan 14 15:28:36 2021 -0300

    Add intro documentation
    
    part of #795


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

feec52d54f5f4a9b57e48654313020e9db52a1b2
 l3packages/xparse/xparse.dtx | 34 ++++++++++++++++++++++++++++++++++
 1 file changed, 34 insertions(+)

diff --git a/l3packages/xparse/xparse.dtx b/l3packages/xparse/xparse.dtx
index eeae7fdf2..be204b65b 100644
--- a/l3packages/xparse/xparse.dtx
+++ b/l3packages/xparse/xparse.dtx
@@ -4197,6 +4197,40 @@
 %    \end{macrocode}
 % \end{macro}
 %
+% \subsection{Copying commands}
+%
+% Since the 2020-10-01 release, the \LaTeXe{} kernel provides
+% \cs{NewCommandCopy} for copying robust commands (a fancy \cs{let}) and
+% \cs{ShowCommand} for showing the definition of robust commands
+% (a fancy \cs{show}).  The machinery for that is extensible, and we can
+% add \pkg{xparse} support to that.  We need to define three commands:
+% \begin{itemize}
+%   \item a conditional to check if a command is an \pkg{xparse} command;
+%   \item a command to copy an \pkg{xparse} command;
+%   \item a command to show an \pkg{xparse} command.
+% \end{itemize}
+%
+% The easiest solution would be to just extract the argument
+% specification and the replacement text of the command and define it
+% again with the proper \pkg{xparse} command.  The problem with that is
+% that if the command has any issue that raises a warning, that would be
+% raised again for the copy, which is a bit awkward, so we go for the
+% long route of dissecting the command's internal structure and copying
+% it bit by bit.
+%
+% There are generally four possible types of \pkg{xparse} commands, by
+% their internal structure:
+% \begin{itemize}
+%   \item robust commands defined with \cs{NewDocumentCommand};
+%   \item expandable commands defined with \cs{NewExpandableDocumentCommand};
+%   \item begin environment commands defined with \cs{NewDocumentEnvironment}
+%     (structurally very similar to \cs{NewDocumentCommand}); and
+%   \item end environment commands, also defined with \cs{NewDocumentEnvironment}.
+% \end{itemize}
+% The plan here is to detect which type of command we're dealing with
+% (if any of the above), and use a dedicated macro that knows how to
+% copy or show such command.
+%
 % \subsection{Argument processors}
 %
 % \begin{macro}{\@@_bool_reverse:N}