Amsmath – How `\Aboxed` Works?

amsmathmathtools

As a requirement in a homework I was asked to enclose my answers with a red box, so I imported mathtools and xcolor and tried with:

\color{red}\Aboxed{\color{black}#1}

where #1 is the equation, but it doesn't work. So I decided to watch the implementation of mathtools and I found the definition of \Aboxed{} that is:

\newcommand\Aboxed[1]{\let\bgroup{\romannumeral-`}\@Aboxed#1&&\ENDDNE}

\def\@Aboxed#1&#2&#3\ENDDNE{%
  \ifnum0=`{}\fi \setbox \z@
    \hbox{$\displaystyle#1{}\m@th$\kern\fboxsep \kern\fboxrule }%
    \edef\@tempa {\kern  \wd\z@ &\kern -\the\wd\z@ \fboxsep
        \the\fboxsep \fboxrule \the\fboxrule }\@tempa \boxed {#1#2}%
}

I think that I understand \setbox and a part of \@tempa.
I made a little drawing about what I think is happening there, \setbox creates a box with width of what will be on the left side of the equation accessible by \wd\z@. Then \@tempa puts that kerning on the left side, after that the alignment symbol, but I have no idea about the negative kerning on the right side.
tikz example of the kern
But I can't find anything about \let\bgroup{\romannumeral-`}, or the command \ENDDNE or the if statement \ifnum0=`{}\fi. I'm asking a lot but if someone can explain me that or give me any good place to start I would be grateful.

Best Answer

First things first: if you want a coloured version of \Aboxed, here is a quick fix:

\documentclass{article}

\usepackage{mathtools}
\usepackage{xcolor}

\makeatletter
\newcommand*\Acolorboxed[2][red]{%
   \let\bgroup{\romannumeral-`}%
   \@Acolorboxed{#1}#2&&\ENDDNE
}
\def\@Acolorboxed#1#2&#3&#4\ENDDNE{%
  \ifnum0=`{}\fi
  \setbox\z@\hbox{$\displaystyle#2{}\m@th$\kern\fboxsep \kern\fboxrule}%
  \edef\@tempa{\kern\wd\z@ & \kern-\the\wd\z@ \fboxsep\the\fboxsep \fboxrule\the\fboxrule}%
  \@tempa
  \fcolorbox{#1}{white}{\m@th$\displaystyle#2#3$}%
} 
\makeatother

\begin{document}

\begin{align*}
\Aboxed{a&=b} \\
\Acolorboxed{a&=b} \\
\Acolorboxed[green]{a&=b}
\end{align*}

\end{document}

enter image description here

Explaining \Aboxed

This is trickier: let me first "simplify" the definition by removing the two brace tricks (see later for that), i.e. let us assume the definitions were simply

\newcommand\Aboxed[1]{\@Aboxed#1&&\ENDDNE}
\def\@Aboxed#1&#2&#3\ENDDNE{%
  \setbox0=\hbox{$\displaystyle#1{}\m@th$\kern\fboxsep \kern\fboxrule}%
  \edef\@tempa{\kern\wd0 & \kern-\the\wd0 \fboxsep=\the\fboxsep \fboxrule=\the\fboxrule}%
  \@tempa
  \boxed {#1#2}%
}

The definition

\def\@Aboxed#1&#2&#3\ENDDNE{...}

means that \@Aboxed expects delimited arguments. Everything up to the first & is the first argument; everything between the first and second & is the second argument; everything between the second & and \ENDDNE is the third argument. The macro \ENDDNE is just some dummy delimiter. However, these two & and this \ENDDNE must be there: TeX will keep scanning the file until it finds them, and they're not there you'll get trouble, and that's why \Aboxed puts it there. You could have defined

\def\Aboxed#1&#2&#3\MaryPoppins{...}

and that would not have changed a thing, provided of course you correspondingly used

\newcommand\Aboxed[1]{\@Aboxed#1&&\MaryPoppins}

The fact that \Aboxed puts two & after its argument is a safety measure, which I presume was not present in first versions of mathtools (see ! Argument of \@Aboxed has an extra }). It allows you to (ab)use it and write \Aboxed{a} with no & without raising errors (though you should simply use \boxed for that).

Let us make an example: TeX expands macros, and when it finds

\Aboxed{E&=mc^2}

this is expanded to

% remember:
% \def\@Aboxed#1&#2&#3\ENDDNE
\@Aboxed E&=mc^2&&\ENDDNE

so that here E is the first argument, =mc^2 is the second argument, and a stray & is the third one. By the definition of \@Aboxed this becomes now

\setbox0=\hbox{$\displaystyle E{}\m@th$\kern\fboxsep \kern\fboxrule}%
\edef\@tempa{\kern\wd0 & \kern-\the\wd0 \fboxsep=\the\fboxsep \fboxrule=\the\fboxrule}%
\@tempa
\boxed {E=mc^2}%

The box register \box0 contains then the E plus the width of the \fbox and the separation. The idea is now to

  1. insert invisible horizontal space equal to the width of \box0,
  2. go to the next column,
  3. go back the width of \box0,
  4. print the \boxed equation.

Why the \edef? Cells act like groups, and the \box0 is set in a cell. If we had written

kern\wd0 & \kern-\wd0 \boxed {E=mc^2}

then the negative \kern would've been wrong. The \edef makes sure that \the is expanded such that we have the correct value. (Question: Why not using \global\setbox\@ne?)

The brace tricks, i.e. the two bits \let\bgroup{\romannumeral-`} and \ifnum0=`{}\fi, are rather tricky. You can read something e.g. in Showcase of brace tricks: }, \egroup, \iffalse{\fi}, etc.. My grasp of brace tricks is limited but I think it boils down to the fact that TeX does not increase/decrease the master counter when it scans `{ and `}. I assume they are there for some safety reason but honestly my tests haven't shown any difference without them. Hopefully someone with more TeX knowledge than me will shed light on this point.

Related Question