addversion with comments by Chris

required/latex-lab/latex-lab-mathcapture.dtx

@@ -1,8 +1,8 @@
 % \iffalse meta-comment
 %
 %% File: latex-lab-mathcapture.dtx
-%
-% Copyright (C) 2022-2023 The LaTeX Project
+% 
+% Copyright (C) 2022-2023 The LaTeX Project 
 %
 % It may be distributed and/or modified under the conditions of the
 % LaTeX Project Public License (LPPL), either version 1.3c of this
@@ -21,7 +21,7 @@
 %<*driver>
 \documentclass{l3doc}
 \EnableCrossrefs
-\CodelineIndex
+\CodelineIndex 
 
 \usepackage{todonotes}
 
@@ -62,6 +62,8 @@
 % \tableofcontents
 %
 % \section{Introduction}
+% \car*{Todo: update all the documentation! Both here and 
+%   (what little there is!) in the implementation section.}
 %
 % This file implements capture of all math mode material at the outer
 % level, i.e., a formula is captured in its entirety with inner text
@@ -116,8 +118,62 @@
 %       material.
 %   \end{itemize}
 % \end{function}
+% 
+% \section{Known current bugs, etc.}
+%     \car*{New Section, now with subsections.\\
+%      As indicated, these lists are probably incomplete.\\
+%      Some of these have been addressed in a more recent branch.} 
+%
+% \subsection{Capture/grabbing problems}
+% 
+% \begin{enumerate}
+%   \item Incorrect grabbing of |$|-math when there is also 
+%      explicit |$|-math within a \textit{text environment} 
+%      that is itself within the math that should all be grabbed.
+%   \item Similar incorrect grabbing with |$$| also.
+%   \item The grabbing, for all the display environments (and |\) \]|), needs
+%       to deal with nesting: \pkg{amsmath} contains code for this. 
+%   \item 
+% \end{enumerate} 
+%
+% \subsection{Other problems}
+% 
+% \begin{enumerate} 
+%   \item 
+%      The presence of \cs{m@th} in association with \cs{ensuremath} 
+%      does not necessarily indicate fakemath.  This is because  
+%      wanting mathsurround to be zero is very reasonable and common, 
+%      \emph{even when the math is genuine} (and hence needs to be collected).
+%   \item User-defined environments can create problems; but this area, of 
+%      new, copied and changed environments, has not yet been developed. 
+% 
+%  \car*{Joseph wrote, inter alia:\\
+%      My thinking [regarding] \cs{RegisterMathEnvironment}\\
+%    - (New) Math environments should not be created-then-patched, but only
+%    generated by a [(future)] dedicated command (\cs{DeclareMathEnviornment}, 
+%    presumably)\\
+%    - Math environments created with \pkg{ltcmd} [commands] should not be copied, . . .\\
+%    - Package authors should be able to manually set up math environments with a public boolean.}
+%
+%   \item 
+% \end{enumerate} 
+%
 %
-% \MaybeStop{\setlength\IndexMin{200pt}  \PrintIndex  }
+% \subsection{Other ToDos}
+%
+% \begin{enumerate}
+%  \item Add (some of) the math display commands that were \enquote{lifted from 
+%    plain}, e.g., \cs{displaylines} \cs{eqalign}(??).
+   \item 
+% \end{enumerate}
+%
+%
+% \car*{\cs{MaybeStop} (temporarily) not executed, as it is unknown on Chris' system.}
+% \iffalse
+%  \MaybeStop{\setlength\IndexMin{200pt}  \PrintIndex  }
+% \else
+%  \StopEventually{\setlength\IndexMin{200pt}  \PrintIndex  }
+% \fi
 %
 % \section{The Implementation}
 %
@@ -130,6 +186,8 @@
 %    \end{macrocode}
 %
 % \subsection{File declaration}
+%
+%    \car{Change description here?}
 %    \begin{macrocode}
 \ProvidesFile{latex-lab-mathcapture.ltx}
         [2023-01-31 v0.2a Grab all the math(s)]
@@ -149,15 +207,24 @@
   { \RequirePackage { amsmath } }
 %    \end{macrocode} 
 %
+%
 % \subsection{Data structures}
 %
-% \begin{variable}{\l_@@_collected_bool}
+%
+% \car{if $=>$ whether, below}
+%
+% \begin{variable}{\l_@@_collected_bool} 
 %   Tracks if math mode material has been collected, which happens inside
 %   \pkg{amsmath} environments as well as those handled directly here.
+%
+%
 %    \begin{macrocode}
 \bool_new:N \l_@@_collected_bool
 %    \end{macrocode}
 % \end{variable}
+% 
+%  \car{Change first tl name below: `env' $=>$ `info'?\\
+%        Or do we need an extra storage tl?}
 %
 % \begin{variable}{\g_@@_grabbed_env_tl, \g_@@_grabbed_math_tl}
 %    \begin{macrocode}
@@ -205,6 +272,17 @@
 % \begin{macro}{\@@_grab_dollar:w}
 %   Grab up to a single |$|, for inline math mode, suppressing
 %   any processing if the first token is \tn{m@th}.
+%
+%    \fmi{what's that test doing?} 
+%
+%    \car{It is some kind of fix, to avoid the remote 
+%      possibility that the math is empty, making the code 
+%      produce an unwanted \texttt{\$\$}.} 
+% 
+%\car{cf.~the code for this in \cs{@ensuredmath}} 
+
+%\car{It is harmless but unnecessary in the dollardollar grabbing below.}
+%
 %    \begin{macrocode}
 \cs_new_protected:Npn \@@_grab_dollar:w % $
   #1 $
@@ -232,6 +310,7 @@
 %    \end{macrocode}
 % \end{macro}
 %
+%
 % \begin{macro}{\@@_grab_inline:w}
 %   Collect inline math content and deal with the need to move to math mode.
 %    \begin{macrocode}
@@ -290,7 +369,9 @@
 % \begin{macro}{\math_register_env:n}
 % \begin{macro}{\RegisterMathEnvironment}
 %   Set up to capture environment content and make available.
+% 
 %    \begin{macrocode}
+%
 \cs_new_protected:Npn \math_register_env:nn #1#2
   {
     \tl_set:Nn \l_@@_env_name_tl {#1}
@@ -328,7 +409,12 @@
 %    \end{macrocode}
 % \end{macro}
 % 
-% \subsection{Document commands}
+% \subsection{Document commands} 
+%
+% \car*{Add one more here: \texttt{displaymath}, which
+%        is equivalent to \cs{[} , \cs{]}\\
+%        and hence to the basic \texttt{equation*}.\\
+%       Added in more recent branch.}
 %
 % \begin{macro}
 %   {\equation, \@@_equation_begin:, \equation*, \@@_equation_star_begin:}
@@ -337,6 +423,11 @@
 %   These environments are not set up by \pkg{amsmath} to collect their body,
 %   so we do that here. This has to be done \emph{after} we can be sure
 %   \pkg{amsmath} is loaded.
+%
+% \car*{Note that with \pkg{amsmath} loaded, \texttt{equation*} and \texttt{equation}\\
+%        are the two basics: they are used to define the other single-row\\
+%        display environments, etc.}
+%
 %    \begin{macrocode}
 \tl_gput_right:Nn \@kernel@before@begindocument
   {
@@ -398,9 +489,16 @@
   }
 %    \end{macrocode}
 % \end{macro}
+% 
 %
 % \begin{macro}{\ensuremath}
 %   A bit of nesting fun to make sure we collect only if required.
+%   \fmi{why does ensuremath need handling at all?}
+% 
+%   \car{Indeed!  Currently, this is setup to process the math that 
+%     it has anyways already captured as its argument; thus it is more 
+%     efficient than leaving the capture to be repeated by the \cs{everymath}}
+% 
 %    \begin{macrocode}
 \cs_gset_protected:Npn \ensuremath #1
   {
@@ -541,3 +639,5 @@
 %
 % \Finale
 %
+% 
+