Using the `explain` command of 657851 for text AND equations

Question

This is a followup question to yesterdays question here.

I want to be able to generate my document in two different levels of detail.

1. (When draft is not set): normal version
2. (When draft option is used): more detailed version. Some additional explanation text is given. Some calculations include extra steps to make it more easy to follow. The additions should be colored differently (gray).

@JasperHabicht Gave a nice solution if the only additions are lines in the aligned environment.

Now I want my additions to be more flexible, i.e., insert text and equations. I already admitted that I did not understand the solution of @Jasper Habicht in the older question and that is why I cannot modify it to work as I want.

I modified the MWE to include the "old" solution:

\documentclass[
   draft,
]{article}

\usepackage{amsmath}
\usepackage{ifdraft}
\usepackage{xcolor}

\ExplSyntaxOn
\NewDocumentCommand{\insertexplaincolor} { m } {
    \tl_set:Nn \l__myexplcol_explcolbody_tl { #1 }
    \regex_replace_all:nnN { \& } { \& \c{explaincolor} } \l__myexplcol_explcolbody_tl
    \regex_replace_all:nnN { \c{\\} } { \c{\\} \c{explaincolor} } \l__myexplcol_explcolbody_tl
    \tl_use:N \l__myexplcol_explcolbody_tl
}
\ExplSyntaxOff

\newcommand{\explaincolor}{\color{gray}}

\newcommand{\explain}[1]{%
    \ifdraft{\insertexplaincolor{#1}}{}%
}

\begin{document}
    \begin{equation}
        \begin{aligned}
            {(a + b)}^2
            \explain{
                & = (a + b)(a + b) \\
                & = a^2 + ab + ba + b^2 \\
            }
            & = a^2 + 2ab + b^2
        \end{aligned}
    \end{equation}

    It follows
    \explain{%
        using \(-b\) in the place of \(b\)
    }
    that
    \begin{equation}
        {(a - b)}^2 = a^2 - 2ab + b^2.
    \end{equation}

    \explain{%
        There is also the third version
        \begin{equation}
            (a + b)(a - b) = a^2 - b^2.
        \end{equation}
    }
\end{document}

The insertions are made correctly depending on the draft option. The color however is only correct within the first aligned.

Ty once more for your help. Franz

Answer 1

The original code in my answer does the following: Read everything that is put as argument of \explain and essentially add \color{gray} after each occurance of & or \\. This way, the following

{(a + b)}^2
\explain{
    & = (a + b)(a + b) \\
    & = a^2 + ab + ba + b^2 \\
}
& = a^2 + 2ab + b^2

will become something like

{(a + b)}^2
\explain{ \color{gray}
    & \color{gray} = (a + b)(a + b) \\ \color{gray}
    & \color{gray} = a^2 + ab + ba + b^2 \\ 
}
& = a^2 + 2ab + b^2

Now, if you feed the \explain macro an argument that does not contain any & or \\, it won't insert the \color macro, and therefore the text won't be printed in gray.

We are lucky that placing a \color macro just somewhere is very unlikely to break the code. Even if no text follows, it won't do any harm. So, we can just add another \color{gray} in front of the argument of the \explain macro and reset the color at the end. To make this work, we need to grab the default color (stored in . at the beginning of the document) beforehand and save it as the color default which we can later access.

If you use the macro inside a sentence, you should place a space at the end of the argument. Otherwise this space won't show in draft mode.

\documentclass[
   draft,
]{article}

\usepackage{amsmath}
\usepackage{ifdraft}
\usepackage{xcolor}

\colorlet{explain}{gray}   % this is just to make it easier to change the color of the explanations 

\AtBeginDocument{\colorlet{default}{.}}

\ExplSyntaxOn
\NewDocumentCommand{\insertexplaincolor} { m } {
    \tl_set:Nn \l__myexplcol_explcolbody_tl { \color{explain} #1 \color{default} }
    % add \color{explain} after every occurance of &
    \regex_replace_all:nnN { \& } { \& \c{color}\{explain\} } \l__myexplcol_explcolbody_tl    
    % add \color{explain} after every \\
    \regex_replace_all:nnN { \c{\\} } { \c{\\} \c{color}\{explain\} } \l__myexplcol_explcolbody_tl    
    \tl_use:N \l__myexplcol_explcolbody_tl
}
\ExplSyntaxOff

\newcommand{\explain}[1]{%
    \ifdraft{\insertexplaincolor{#1}}{}\ignorespaces%
}

\begin{document}
    \begin{equation}
        \begin{aligned}
            {(a + b)}^2
            \explain{ 
                & = (a + b)(a + b) \\
                & = a^2 + ab + ba + b^2 \\
            }
            & = a^2 + 2ab + b^2
        \end{aligned}
    \end{equation}

    It follows
    \explain{
        using \(-b\) in the place of \(b\)
    }
    that
    \begin{equation}
        {(a - b)}^2 = a^2 - 2ab + b^2.
    \end{equation}

    \explain{
        There is also the third version
        \begin{equation}
            (a + b)(a - b) = a^2 - b^2.
        \end{equation}
    }
    
    \explain{
        Even this works
        \begin{equation}
            \begin{aligned}
                {(a + b)}^2
                    & = (a + b)(a + b) \\
                    & = a^2 + ab + ba + b^2 \\
                & = a^2 + 2ab + b^2
            \end{aligned}
        \end{equation}
    }

    Using the macro \explain{inside } a sentence.  % <-- space at the end of argument
\end{document}