latex-lab-mathcapture.dtx

% \iffalse meta-comment
%
%% File: latex-lab-mathcapture.dtx
%
% 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
% license or (at your option) any later version.  The latest version
% of this license is in the file
%
%    https://www.latex-project.org/lppl.txt
%
%
% The development version of the bundle can be found below
%
%    https://github.com/latex3/latex2e/required/latex-lab
%
% for those people who are interested or want to report an issue.
%
%<*driver>
\documentclass{l3doc}
\EnableCrossrefs
\CodelineIndex
\begin{document}
  \DocInput{latex-lab-mathcapture.dtx}
\end{document}
%</driver>
%
% \fi
%
%
% \title{The \texttt{latex-lab-mathcapture} code\thanks{}}
% \author{\LaTeX{} Project}
%
% \maketitle
%
% \newcommand\fmi[1]{\begin{quote} TODO: \itshape #1\end{quote}}
% \newcommand\NEW[1]{\marginpar{\mbox{}\hfill\fbox{New: #1}}}
% \providecommand\class[1]{\texttt{#1.cls}}
% \providecommand\pkg[1]{\texttt{#1}}
% \providecommand\hook[1]{\texttt{#1}}
%
% \begin{abstract}
% \end{abstract}
%
% \tableofcontents
%
% \section{Introduction}
%
% 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
% blocks (possibly containing further math) absorbed as part of the
% formula. For example,
%\begin{verbatim}
%      \[ a \in A \text{ for all $a<5$}  \]
%\end{verbatim}
% would only result in a single capture of the tokens
% ``\verb*/a \in A \text{ for all $a<5$}/''.
%
% \subsection{Code level interfaces}
%
% \begin{function}{\math_register_env:n}
%   \begin{syntax}
%     \cs{math_register_env:n} \Arg{env}
%   \end{syntax}
%   Registers the \meta{env} as a math environment which should be captured
%   and made available. This is necessary for all top-level math mode
%   environments: low-level errors may result if these are not correct
%   set up.
% \end{function}
%
% \begin{function}{\math_processor:n}
%   \begin{syntax}
%     \cs{math_processor:n} \Arg{tokens}
%   \end{syntax}
%   Declares that the captured math content should be passed to the
%   \meta{tokens}, which will receive the environment type as |#1| and
%   the content as |#2|.
% \end{function}
%
% \subsection{Document level interfaces}
%
% \begin{function}{\RegisterMathEnvironment}
%   \begin{syntax}
%     \cs{RegisterMathEnvironment} \Arg{env}
%   \end{syntax}
%   Registers the \meta{env} as a math environment which should be captured
%   and made available. This is necessary for all top-level math mode
%   environments: low-level errors may result if these are not correct
%   set up.
% \end{function}
%
% \MaybeStop{\setlength\IndexMin{200pt}  \PrintIndex  }
%
% \section{The Implementation}
%
%    \begin{macrocode}
%<@@=math>
%    \end{macrocode}
%
%    \begin{macrocode}
%<*kernel>
%    \end{macrocode}
%
% \subsection{File declaration}
%    \begin{macrocode}
\ProvidesFile{latex-lab-mathcapture.ltx}
        [2023-01-06 v0.1a Grab all the math(s)]
%    \end{macrocode}
%
%    \begin{macrocode}
\ExplSyntaxOn
%    \end{macrocode}
%
% \subsection{Setup}
%
% Loading \pkg{amsmath} is an absolute requirement: this avoids needing to
% have conditional definitions and deals with how to define \cs{[}/\cs{]}
% neatly.
%    \begin{macrocode}
\tl_gput_right:Nn \@kernel@before@begindocument
  { \RequirePackage { amsmath } }
%    \end{macrocode} 
%
% \subsection{Data structures}
%
% \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}
%
% \subsection{Interface commands}
%
% \begin{macro}
%   {\@@_process:nn, \@@_process:Vn, \@@_process_auxi:nn, \@@_process_auxii:nn}
%   A no-op place-holder; the internal wrapper means that it does not need to
%   be concerned with internals.
%    \begin{macrocode}
\cs_new_protected:Npn \@@_process:nn #1#2
  {
    \legacy_if:nF { measuring@ }
      { \tl_trim_spaces_apply:nN {#2} \@@_process_auxi:nn {#1} }
  }
\cs_generate_variant:Nn \@@_process:nn { V }
\cs_new_protected:Npn \@@_process_auxi:nn #1#2
  { \@@_process_auxii:nn {#2} {#1} }
\cs_new_protected:Npn \@@_process_auxii:nn #1#2 { }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\math_processor:n}
%   A simple installer
%    \begin{macrocode}
\cs_new_protected:Npn \math_processor:n #1
  { \cs_set_protected:Npn \@@_process_auxii:nn ##1##2 {#1} }
%    \end{macrocode}
% \end{macro}
%
% \subsection{Content grabbing}
%
% \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}.
%    \begin{macrocode}
\cs_new_protected:Npn \@@_grab_dollar:w % $
  #1 $
  {
    \tl_if_head_eq_meaning:nNF {#1} \m@th
      { \@@_process:nn { math } {#1} } % $
    #1 $
  }
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\@@_grab_dollardollar:w}
%   And for the classical \TeX{} display structure.
%    \begin{macrocode}
\cs_new_protected:Npn \@@_grab_dollardollar:w % $$
  #1 $$
  {
    \@@_process:nn { equation* } {#1} % $$
    #1 $$
  }
%    \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}
\cs_new_protected:Npn \@@_grab_inline:w % \(
  #1 \)
  {
    \@@_process:nn { math } {#1}
    $ #1 $
    \bool_set_false:N \l_@@_collected_bool
  }
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\@@_grab_eqn:w}
%   For the most common use of \cs{[}/\cs{]}: turn into an environment.
%    \begin{macrocode}
\cs_new_protected:Npn \@@_grab_eqn:w % \[
  #1 \]
  { \begin { equation* } #1 \end { equation* } }
%    \end{macrocode}
% \end{macro}
%
% \subsection{Marking math environments}
%
% A general mechanism for math mode environments that do no grab their
% content (\emph{cf.}~most \pkg{amsmath} environments).
%
% \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:n #1
  {
    \cs_gset_eq:cc { @@_env_ #1 _begin: } {#1}
    \cs_gset_eq:cc { @@_env_ #1 _end: } { end #1 }
    \ExpandArgs { nnx } \RenewDocumentEnvironment {#1} { b }
      {
        \bool_set_true:N \exp_not:N \l_@@_collected_bool
        \exp_not:N \@@_process:nn {#1} {####1}
        \exp_not:c { @@_env_ #1 _begin: }
        ####1
        \exp_not:c { @@_env_ #1 _end: }
      }
      { }
  }
\NewDocumentCommand \RegisterMathEnvironment { m }
  { \math_register_env:n {#1} }
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \subsection{Document commands}
%
% \begin{macro}
%   {\equation, \@@_equation_begin:, \equation*, \@@_equation_star_begin:}
% \begin{macro}
%   {\endequation, \@@_equation_end:, \endequation*, \@@_equation_star_end:}
%   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.
%    \begin{macrocode}
\tl_gput_right:Nn \@kernel@before@begindocument
  {
    \math_register_env:n { equation }
    \math_register_env:n { equation* }
  }
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\(, \)}
%  If math mode has not been collected, we need to  do that; otherwise, worry
%  about whether we are in math mode or not. The closing command here can only
%  occur inside a collected math block: otherwise it will be simply used as
%  a delimiter.
%    \begin{macrocode}
\cs_gset_protected:Npn \( % \)
  {
    \bool_if:NTF \l_@@_collected_bool
      {
        \mode_if_math:TF
          { \@badmath }
          { $ }
      }
      {
        \bool_set_true:N \l_@@_collected_bool
        \@@_grab_inline:w
      }
  } % \(
\cs_gset_protected:Npn \)
  {
    \mode_if_math:TF
      { $ }
      { \@badmath }
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\[, \]}
%   Again, we need to watch for when \pkg{amsmath} is loaded after this code.
%   The flag usage here is to cover the case where \cs{[}/\cs{]} is nested
%   inside another environment.
%    \begin{macrocode}
\tl_gput_right:Nn \@kernel@before@begindocument
  {
    \cs_gset_protected:Npn \[ % \]
      {
        \bool_if:NTF \l_@@_collected_bool
          { \begin { equation* } }
          { \@@_grab_eqn:w }
      } % \[
    \cs_gset_protected:Npn \]
      {
        \bool_if:NTF \l_@@_collected_bool
          { \end{ equation* } }
          { \@badmath }
      }
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\ensuremath}
%   A bit of nesting fun to make sure we collect only if required.
%    \begin{macrocode}
\cs_gset_protected:Npn \ensuremath #1
  {
    \mode_if_math:TF
      {#1}
      {
        \bool_if:NTF \l_@@_collected_bool
          { \@ensuredmath {#1} }
          {
            \bool_set_true:N \l_@@_collected_bool
            \@@_process:nn { math } {#1}
            \@ensuredmath {#1}
            \bool_set_false:N \l_@@_collected_bool
          }
      }
  }
%    \end{macrocode}
% \end{macro}
%
% \subsection{\cs{everymath} and \cs{everydisplay}}
%
% The business end for grabbing inline math and \enquote{raw} \TeX{}
% display. Most display math mode is actually handled elsewhere, as we
% have macro control.
%    \begin{macrocode}
\exp_args:No \tex_everymath:D
  {
    \tex_the:D \tex_everymath:D
    \bool_if:NF \l_@@_collected_bool
      {
        \bool_set_true:N \l_@@_collected_bool
        \@@_grab_dollar:w
      }
  }
\exp_args:No \tex_everydisplay:D
  {
    \tex_the:D \tex_everydisplay:D
    \bool_if:NF \l_@@_collected_bool
      {
        \bool_set_true:N \l_@@_collected_bool
        \@@_grab_dollardollar:w
      }
  }
%    \end{macrocode}
%
% \subsection{Modifying kernel environments}
%
%   We need to cover this even though it is of course not encouraged.
%    \begin{macrocode}
\math_register_env:n { eqnarray }
%    \end{macrocode}
%
% Places where math mode is (ab)used.
%    \begin{macrocode}
\clist_map_inline:nn
  { tabular }
  {
    \AddToHook{ env / #1 / begin }
      { \bool_set_true:N \l_@@_collected_bool }
  }
%    \end{macrocode}
%
% \begin{macro}{\@@_m@th:, \m@th}
%   Handle non-math use of math mode. At present nesting isn't supported as
%   \cs{m@th} pops up in a few places that \emph{are} math mode!
%    \begin{macrocode}
\cs_new_eq:NN \@@_m@th: \m@th
\cs_gset_protected:Npn \m@th
  {
    \bool_set_true:N \l_@@_collected_bool
    \@@_m@th:
  }
%    \end{macrocode}
% \end{macro}
%
% \subsection{Modifying \pkg{amsmath}}
%
% \begin{macro}{\@@_amsmath_align@:nn}
% \begin{macro}
%   {
%     \@@_amsmath_gather@:n ,
%     \@@_amsmath_multline@:n
%   }
% \begin{macro}{\align@}
% \begin{macro}{\gather@, \multline@}
%   Mark up all of the display environments as the content is captured anyway.
%   We then use the internal for each environment type to insert the processing
%   code. Each of these is slightly different, so we cannot use a simple loop
%   here. The test for \cs{split@tag} is required as the \texttt{split}
%   environment internally uses \texttt{gather} \emph{when not within an
%   \pkg{amsmath}} environment, for example inside \texttt{equation}. Without
%   the precaution, we'd get two copies of the grabbed math, the second of
%   which would start with \cs{split@tag}.
%    \begin{macrocode}
\clist_map_inline:nn
  { align , gather , multline }
  {
    \AddToHook{ env / #1 / begin }
      { \bool_set_true:N \l_@@_collected_bool }
    \AddToHook{ env / #1* / begin }
      { \bool_set_true:N \l_@@_collected_bool }
  }
\tl_gput_right:Nn \@kernel@before@begindocument
  {
    \cs_new_eq:NN \@@_amsmath_align@:nn \align@
    \cs_gset_protected:Npn \align@ #1#2
      {
        \@@_process:Vn \@currenvir {#2}
        \@@_amsmath_align@:nn {#1} {#2}
      }
    \cs_new_eq:NN \@@_amsmath_gather@:n \gather@
    \cs_gset_protected:Npn \gather@ #1
      {
        \tl_if_head_eq_meaning:nNF {#1} { \split@tag }
          { \@@_process:Vn \@currenvir {#1} }
        \@@_amsmath_gather@:n {#1}
      }
    \cs_new_eq:NN \@@_amsmath_multline@:n \multline@
    \cs_gset_protected:Npn \multline@ #1
      {
        \@@_process:Vn \@currenvir {#1}
        \@@_amsmath_multline@:n {#1}
      }
  }
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
%
%    \begin{macrocode}
\ExplSyntaxOff
%    \end{macrocode}
%
%    \begin{macrocode}
%</kernel>
%    \end{macrocode}
%
% \Finale
%