[latex3-commits] [git/LaTeX3-latex3-latex2e] gh963: Code documentation (1c239dc6)

[PhelypeOleinik]

Repository : https://github.com/latex3/latex2e
On branch  : gh963
Link       : https://github.com/latex3/latex2e/commit/1c239dc641ee9728a5b7dc565950171fef7dde30

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

commit 1c239dc641ee9728a5b7dc565950171fef7dde30
Author: PhelypeOleinik <phelype.oleinik at latex-project.org>
Date:   Tue Nov 29 01:03:26 2022 -0300

    Code documentation


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

1c239dc641ee9728a5b7dc565950171fef7dde30
 base/ltdefns.dtx | 53 ++++++++++++++++++++++++++++++++++++++---------------
 1 file changed, 38 insertions(+), 15 deletions(-)

diff --git a/base/ltdefns.dtx b/base/ltdefns.dtx
index db7436b3..1a4d3f58 100644
--- a/base/ltdefns.dtx
+++ b/base/ltdefns.dtx
@@ -1811,6 +1811,12 @@
 %    \end{macrocode}
 % \end{macro}
 %
+%
+% \subsubsection{Showing environments}
+%
+% \begin{macro}{\ShowEnvironment}
+% \changes{v1.5s}{2022/11/24}{Added \cs{ShowEnvironment}}
+%
 %    \begin{macrocode}
 %</2ekernel>
 %<latexrelease>\IncludeInRelease{2023-06-01}{\ShowEnvironment}
@@ -1818,8 +1824,10 @@
 %<*2ekernel|latexrelease>
 %    \end{macrocode}
 %
-% \begin{macro}{\ShowEnvironment}
-%  \changes{v1.5s}{2022/11/24}{Add \cs{ShowEnvironment}}
+%   \cs{ShowEnvironment} is quite similar to \cs{ShowCommand}.  We will
+%   pass the environment \meta{env} around as the macro
+%   \cs[no-index]{env}, because \cs{robust at command@act} expects a single
+%   token.
 %    \begin{macrocode}
 \def\ShowEnvironment#1{%
   \expandafter\@show at environment\csname #1\endcsname}
@@ -1830,10 +1838,8 @@
 %    \end{macrocode}
 %
 % \begin{macro}{\@showenvironmentlisthook}
-%   The initial definition of \cs{@showenvironmentlisthook} contains the same tests
-%   as used for copying, but \cs{@show at ...} commands instead of \cs{@copy at ..}.
-%   Same as before, it is initialized to cope with \cs{DeclareRobustCommand} and
-%   \cs{newcommand} with optional arguments.
+%   This is similar to \cs{@showcommandlisthook}, but uses the dedicated
+%   versions for environments.
 %    \begin{macrocode}
 \def\@showenvironmentlisthook{%
   {\@if at DeclareRobustCommand \@show at DeclareRobustCommand@env}%
@@ -1841,11 +1847,11 @@
 %    \end{macrocode}
 % \end{macro}
 %
-% \begin{macro}{\@showenvironmentlisthook}
-%   The initial definition of \cs{@showenvironmentlisthook} contains the same tests
-%   as used for copying, but \cs{@show at ...} commands instead of \cs{@copy at ..}.
-%   Same as before, it is initialized to cope with \cs{DeclareRobustCommand} and
-%   \cs{newcommand} with optional arguments.
+% \begin{macro}{\@show at newcommand@env}
+% \begin{macro}{\@show at DeclareRobustCommand@env}
+%   These are similar to the command versions below, except they say
+%   \enquote{environment} and call \cs{@show at environment@end} to print
+%   the \cs{end} part.
 %    \begin{macrocode}
 \long\def\@show at newcommand@env#1{%
   \typeout{> \string\begin{\@expl at cs@to at str@@N#1}=environment:}%
@@ -1860,6 +1866,21 @@
   \expandafter\show at kernel@robust at command
     \csname\@expl at cs@to at str@@N#1 \endcsname
   \@show at environment@end#1}
+%    \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\@show at normalenv}
+% \begin{macro}{\@show at environment@end}
+%   A \enquote{normal} environment is straightforward.
+%   \cs{@show at environment@end} needs to check if the \cs{end} part is
+%   defined and show it accordingly, otherwise the output would show
+%   gibberish.
+%    \begin{macrocode}
+\long\def\@show at normalenv#1{%
+  \@show at normalenv@meaning#1%
+    {\string\begin{\@expl at cs@to at str@@N#1}=environment}%
+  \@show at environment@end#1}
 \long\def\@show at environment@end#1{%
   \@ifundefined{end\@expl at cs@to at str@@N#1}%
     {\@show at normalenv@undefined}%
@@ -1868,12 +1889,12 @@
       {\string\end{\@expl at cs@to at str@@N#1}}}
 %    \end{macrocode}
 % \end{macro}
+% \end{macro}
 %
+% \begin{macro}{\@show at normalenv@meaning}
+% \begin{macro}{\@show at normalenv@undefined}
+%   And here the auxiliaries that do the actual printing.
 %    \begin{macrocode}
-\long\def\@show at normalenv#1{%
-  \@show at normalenv@meaning#1%
-    {\string\begin{\@expl at cs@to at str@@N#1}=environment}%
-  \@show at environment@end#1}
 \def\@show at normalenv@meaning#1#2{%
   \edef\reserved at a{#2:^^J%
     \@expl at cs@argument at spec@@N#1->\@expl at cs@replacement at spec@@N#1}%
@@ -1882,6 +1903,8 @@
   \edef\reserved at a{#1=undefined}%
   \showtokens\expandafter\expandafter\expandafter{\expandafter\reserved at a}}
 %    \end{macrocode}
+% \end{macro}
+% \end{macro}
 %
 %   Now the rollback code.
 %    \begin{macrocode}