% \iffalse meta-comment
%
%% File: mathcolor.dtx (C) Copyright 2021-2022
% Frank Mittelbach, LaTeX Team
%
% 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
%
%
%%% From File: mathcolor.dtx
%
% \begin{macrocode}
\def\mathcolorversion{v1.0c}
\def\mathcolordate{2022/07/25}
% \end{macrocode}
%<*driver>
\documentclass{l3doc}
%\makeatletter \input{mathcolor.ltx} \makeatother
\usepackage{color}
% Fixing footnotes in functions and variables: this should be in l3doc!
\newcommand\fixfootnote[2]{\footnotemark
\AddToHookNext{env/#1/after}{\footnotetext{#2}}}
\AddToHook{env/function/begin}{\def\footnote{\fixfootnote{function}}}
\AddToHook{env/variable/begin}{\def\footnote{\fixfootnote{variable}}}
\EnableCrossrefs
\CodelineIndex
\begin{document}
\DocInput{mathcolor.dtx}
\end{document}
%</driver>
%
% \fi
%
% \title{Providing color in math\thanks{This file has version
% \mathcolorversion\ dated \mathcolordate, \copyright\ \LaTeX\
% Project.}}
% \author{Frank Mittelbach}
%
% \maketitle
%
%
% \section{Introduction}
%
% It is possible to use the \cs{color} command in math formulas but
% doing that has a number of restrictions and often leads to rather
% unreadable input. For example, to color the summation sign in red
% in the following formula
% \[
% X = \color{red} \sum_{{\color{black} i=1}}^{{\color{black} n}} \color{black} x_i
% \]
% A total of four color commands and a number of seemingly
% unnecessary extra braces in the sub and superscript are needed:
%\begin{verbatim}
% \[ X = \color{red} \sum
% _{{\color{black} i=1}} % without {{ the superscript is misplaced
% ^{{\color{black} n}} % without {{ the \sum is black
% \color{black} % without the x_i is red
% x_i \]
%\end{verbatim}
% While this is ugly but at least works, other things are simply
% impossible, e.g.,
% \[ \left\{ \frac{1}{2} \mathcolor{red}{\right\}} \]
% are not achievable at all because of the fact that \cs{left} and
% \cs{right} form a group. Thus, a \cs{color} command immediately
% before the \cs{right} has no effect and \verb=\}= remains black.
% Putting the color change before the \cs{left} and then resetting
% the color inside would work if you want to color both braces, but
% the above combination or the attempt to color only the left brace
% fails always.
%
% Using \cs{textcolor} in formulas appears to work on first glance,
% but it produces spacing problems that are not easy to overcome
% either, because it generates a single \cs{mathord} and no
% longer reflects its input, thus
% \verb/\[ a = b \textcolor{red}{\neq} c \]/
% produces
% \[ a = b \textcolor{red}{\neq} c \]
% This is a case one could mend by wrapping the
% \cs{textcolor} and its arguments in a \cs{mathrel}, but even when
% that is possible, the resulting formula source is difficult to
% maintain and in other situations the solutions are even more
% complicated or there is no solution at all.
%
% We therefore offer now a dedicated math coloring command named
% \cs{mathcolor}.
%
% \begin{function}{\mathcolor}
% \begin{syntax}
% \cs{mathcolor} \oarg{model} \Arg{color-spec} \Arg{math material}
% \end{syntax}
% It has the same arguments as \cs{textcolor} but is intended for
% use in formulas. The command does not generate a group and the
% \meta{math material} retains its math atom states and it correctly
% handles sub and superscripts that follow.
% \end{function}
%
% The command can also be used to color a single opening or closing
% symbol, e.g., the correct input to our earlier example is
%\begin{verbatim}
% \[ \left\{ \frac{1}{2} \mathcolor{red}{\right\}} \]
%\end{verbatim}
% which is how it was produced.
%
% If you attempt to color large operators that use explicit
% \cs{limits}, \cs{nolimits}, or \cs{displaylimits}, then these
% limit controls need to immediately follow the operator. However,
% \cs{mathcolor} is written in a way that it is possible write
%\begin{verbatim}
% \[ \mathcolor{red}{\int}\limits_0^1 \textrm{ or }
% \mathcolor{red}{\int\limits}_0^1 \]
%\end{verbatim}
% and achieve the same effect:
% \[ \mathcolor{red}{\int}\limits_0^1 \textrm{ or }
% \mathcolor{red}{\int\limits}_0^1 \]
%
%
% \MaybeStop{\setlength\IndexMin{200pt} \PrintIndex }
%
%
% \section{The Implementation}
%
% The code is called inside of the \pkg{color} or \pkg{xcolor}
% packages, so \texttt{@} is already a letter, but the
% coding here is done in the L3 programming layer, so we need to
% activate that. But first we check if this file was loaded before,
% e.g., when both \pkg{color} and \pkg{xcolor} are in the preamble
% and in that case we stop immediately.
% \begin{macrocode}
%<*code>
\ifcsname mathcolor\endcsname \endinput \fi
% \end{macrocode}
%
% \begin{macrocode}
\ExplSyntaxOn
%<@@=mathcolor>
% \end{macrocode}
%
% \begin{macro}{\g_@@_seq}
% We need to keep our own stack of color commands, so we allocate a
% sequence for that.
% \begin{macrocode}
\seq_new:N \g_@@_seq
% \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{\mathcolor}
% The document-level command which expects a color (if unnamed then
% the optional argument is the model) and colors the content of the
% second argument (like \cs{textcolor}, but without spacing
% problems in math).
% \begin{macrocode}
\DeclareDocumentCommand \mathcolor { o m m }
{
% \end{macrocode}
% The \cs{mathcolor} is only supported in math mode because in text
% mode it has problems scanning away a space after it, for example.
% We therefore raise an error if it executes
% anywhere else. The \LaTeXe{} error command is a
% bit strangely named, because in the kernel it is only used for
% math alphabets, but the message it gives is fine.
% \changes{v1.0b}{2022/01/28}{Restrict command to math mode}
% \begin{macrocode}
\mode_if_math:F { \non@alpherr {\mathcolor\space} }
% \end{macrocode}
% First real action is to save the current color value on a stack
% (needed if the command is nested or contains some further color
% changes with \cs{color} inside).
% \begin{macrocode}
\seq_gpush:No \g_@@_seq \current@color
% \end{macrocode}
% Then we switch to the new color, but we do not want to reset the
% color after the group (which is done by \cs{color} using
% \cs{aftergroup}\cs{reset@color}). The best solution here would be
% if the color packages would provide a command doing just the
% color switching, but for now we simply undo that part by pushing
% \cs{use_none:n} which gobbles the \cs{reset@color} added by
% \cs{color} with \cs{aftergroup}.
% \begin{macrocode}
\group_insert_after:N \use_none:n
% \end{macrocode}
% Switching the color is also slightly suboptimal, because
% depending on whether or not we have a \meta{model} argument, we
% have to call \cs{color} with or without the optional argument. But
% going low-level here is not an option as we need to support
% different color packages and their internals are not identical.
% \begin{macrocode}
\IfValueTF {#1} { \color[#1]{#2} } { \color{#2} }
% \end{macrocode}
% Then comes the math material we want to see colored:
% \begin{macrocode}
#3
% \end{macrocode}
% After that we need to reset the color ourselves (without a group
% that does it for us), i.e., popping the saved color from our
% stack, but there are some twists to that so we do this in a
% separate command (which in fact needs to be called several times,
% so inlining the code wouldn't be possible.
% \begin{macrocode}
\@@_scan_for_scripts:w
}
% \end{macrocode}
% \end{macro}
%
%
%
% \begin{macro}{\@@_scan_for_scripts:w}
% The complication when changing the color back is due to the fact
% that the \cs{mathcolor} may be followed by \verb=^= or \verb=_=
% or the hidden superscript \texttt{'} and its argument may end in a
% \cs{mathop} in which case the sub and superscripts may be
% attached as \cs{limits} instead of after the material. All cases
% need separate treatment.
% And we need to watch out for an upcoming \verb=&= and avoid
% prematurely triggering the end of an alignment cell.
% \changes{v1.0c}{2022/07/25}{Avoid ending an alignment cell
% prematurely when hitting an \texttt{\&} during
% scanning (gh/901)}
% \begin{macrocode}
\cs_new_protected:Npn \@@_scan_for_scripts:w
{
% \end{macrocode}
% We need to look at what follows \cs{mathcolor}, and we need to do
% that ignoring (and dropping) any spaces and \cs{relax} as \TeX{}
% would do in normal math processing (for example before a subscript
% token). We do this with expansion so that hidden sub or superscripts
% in macros are still found as long as the macros are expandable.
% \begin{macrocode}
\peek_remove_filler:n
{
% \end{macrocode}
% To avoid problems hitting on \verb=&= we start with a
% \cs{group_align_safe_begin:}. That has to be ended with
% \cs{group_align_safe_end:} when the
% danger (aka scanning) is over, which, due to the branching below, happens at
% four different points, i.e., when the \cs{mathcolor} is
% \begin{enumerate}
% \item
% followed by a \enquote{normal} token;
% \item
% followed by a braced sub/superscript;
% \item
% followed by an unbraced sub/superscript;
% \item
% followed by one of the \cs{limits} primitives.
% \end{enumerate}
% In each case we have to end the align safe group and we mark the
% points below in the code for easy reference.
% \begin{macrocode}
\group_align_safe_begin:
% \end{macrocode}
% We first parse for \cs{c_math_subscript_token} or
% \cs{c_math_superscript_token}.
% After \cs{peek_remove_filler:n} is done, it sets \cs{l_peek_token}
% equal to the next non-filler token, so we can avoid unnecessary
% work and just compare that. If either of the tokens is found, call
% \cs{@@_handle_scripts:Nw}:
% \begin{macrocode}
\token_case_catcode:NnTF \l_peek_token
{
\c_math_subscript_token { }
\c_math_superscript_token { }
}
{ \@@_handle_scripts:Nw }
% \end{macrocode}
% Otherwise we check if it was any of the limit operation
% primitives. If that is the case, e.g., if we have a situation
% such as
%\begin{verbatim}
% \mathcolor{red}{\int}\limits_1
%\end{verbatim}
% we have to move it directly after the \cs{int} to ensure there
% is no color reset between the operator and the \cs{limits} command.
% \begin{macrocode}
{
\token_case_meaning:NnTF \l_peek_token
{
\limits { \limits }
\nolimits { \nolimits }
\displaylimits { \displaylimits }
}
% \end{macrocode}
% Once that is done, we have to get rid of the token we peeked at
% and then restart scanning for sub or superscripts. Given that
% \cs{@@_scan_for_scripts:w} expands while scanning the simplest
% solution is to add \cs{use_none:n} in front of the peeked at
% token.
%
% Here we end the align safe group and
% \cs{@@_scan_for_scripts:w} will start a new one.
% \begin{macrocode}
{
\group_align_safe_end: % case 4
\@@_scan_for_scripts:w \use_none:n
}
% \end{macrocode}
% If it was not one of these we look for a \texttt{'} and if found remove it and
% replace it by its expansion. The reason we have to do this (and
% not rely on the earlier peeking to expand for us is the fact
% that \texttt{'} is only ``math active'' and that doesn't expand
% under \cs{expanded} or \cs{expandafter}.
% \begin{macrocode}
{
\token_if_eq_meaning:NNTF \l_peek_token '
{
\@@_handle_scripts:Nw ^
\c_group_begin_token
\exp_after:wN \prim@s \use_none:n
}
% \end{macrocode}
% If it is anything else we finish off which means we reset the
% color (because we prevented that before to happen automatically
% after the next group) and pop the color stack setting \cs{current@color}.
% \begin{macrocode}
{
\group_align_safe_end: % case 1
\reset@color
\seq_gpop:NN \g_@@_seq \current@color
}
}
}
}
}
% \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{\@@_handle_scripts:Nw}
% The tricky part of handling sub and superscripts is that we have
% to reset color to the one that is on the stack but reset it back
% to what it was before to allow for cases like
%\begin{verbatim}
% \[ \mathcolor{red}{a+\sum}_{i=1}^n \]
%\end{verbatim}
% Here, \TeX{} constructs a \cs{vbox} stacking subscript, summation
% sign, and superscript. So technically the superscript comes first
% and the \cs{sum} that should get colored red is the middle.
% \begin{macrocode}
\cs_new_protected:Npn \@@_handle_scripts:Nw #1
{
% \end{macrocode}
% The argument is either \verb=^= or \verb=_=, so we execute it and
% explicitly open two \verb={= groups. We need two because color
% resets are always done after a group, so the first group is for
% script material (in case it was just something like \verb=_i=)
% and the second is needed for the color reset to keep it within
% the super or subscript. If that reset would happen after it then
% the color \cs{special} would interfere with \TeX{} math spacing.
% \begin{macrocode}
#1 \c_group_begin_token \c_group_begin_token
% \end{macrocode}
% Now it is time to change the color back to the one on the stack.
% \begin{macrocode}
\seq_get:NN \g_@@_seq \current@color
\set@color
% \end{macrocode}
% \cs{set@color} adds \cs{aftergroup}\cs{reset@color}. We now a add
% bit more so that the code executed after the current (inner) group
% looks like this:
%\begin{verbatim}
% \reset@color } \@@_scan_for_scripts:w
%\end{verbatim}
% The \cs{@@_scan_for_scripts:w} then retakes control and initiates
% parsing for another sub or superscript.
% \begin{macrocode}
\group_insert_after:N \c_group_end_token
\group_insert_after:N \@@_scan_for_scripts:w
% \end{macrocode}
% Before we give control to \TeX{} to process the sub or
% superscript some final adjustment is necessary: if the input was
% \verb=^{...}= then we have one \verb={= too many, because we
% already supplied the outer one already. In that case we drop
% it. Otherwise we have an unbraced single token sub or superscript
% which means we are missing a closing \verb=}= at the end and need
% to account for that: this is done in false branch by
% \cs{use_ii_i:nn}.
%
% After scanning for a brace all scanning is done, so here are the
% other two points where we have to end the align safe group (in
% the true and false case).
% \begin{macrocode}
\peek_remove_filler:n
{
\token_if_eq_meaning:NNTF \l_peek_token \c_group_begin_token
{
\group_align_safe_end: % case 2
\peek_catcode_remove:NT \c_group_begin_token { }
}
{
\exp_after:wN \group_align_safe_end: % case 3
\use_ii_i:nn \c_group_end_token
}
}
}
% \end{macrocode}
% \end{macro}
%
% \begin{macrocode}
%<@@=>
% \end{macrocode}
%
% \begin{macrocode}
\ExplSyntaxOff
%</code>
% \end{macrocode}
%
% \Finale
%
%
%%%%%%%%%%%%%%%%
\endinput
%%%%%%%%%%%%%%%%