What is \mathchoice?

Question

Can someone give me a detailed starters' guide to \mathchoice? I was trying to define commands for underscript and overscript (which I have found out to exist and be called \underset and \overset), and up till now I've been using scaled arrays (matrices) for that, i.e. compressing a column vector containing the line of text and the overscript/underscript stuff to avoid the matrix expanding and leaving space between itself and the surrounding environment, and rescaling its contents to normal size or to a smaller size for the overscript/underscript.

Problem is, as soon as the height of a "cell" of this column vector is altered, my text starts flying above the rest of the text or sinking below it. So I have to work on the scalings and it's often boring to find the exactly right scaling factors to align the text with overscript/underscript with nearby text. Working on this, I tried to define a command \lower, and bumped into a Command \lower already defined error. I looked \lower up, and found out about the existence of something called \mathchoice. Problem is, what I found seems to be only troubleshooting, and to require a minimal knowledge of what \mathchoice is, or at least of what certain lines of code (as \def\xfb#1#2{\fbox{$#1#2$}}) do, which I don't have; or maybe what I've found (i.e. Proper use of \mathchoice) is meant to only give practical advice, i.e. to give you code that works, rather than explaining what one is doing with the recommended code.

To make an example unrelated to \mathchoice, what I mean is what I found seems to either require the reader to know \newcommand{\norm}[1]{\left\|#1\right\|} is defining a new command, which is invocated by \norm, has one parameter, and places it between \left\| and \right\|, which are automatically resized double vertical bars, or to only give the reader the code without any intention of explaining it does that. \mathpalette seems to be closely related to \mathchoice, so it wouldn't be inappropriate to ask for help on both, I presume.

Answer 1

\mathchoice aims to solve the problem of defining commands for math mode that behave differently in the four main math styles, that is, display, text, script and scriptscript. I'll gloss over the four secondary (or “cramped”) styles, which are not of a concern with \mathchoice.

When TeX is in a display it uses display style; in an inline formula it uses text style. But subscripts or superscripts use, at the first level, script style, and from the second level up, scriptscript style.

However, when typesetting a fraction in display style, TeX uses text style for the numerator and the denominator. But it will use script style when the fraction starts out in text style.

Let's make an example. In amsmath there is \iint that typesets a double integral; it is built by typesetting two integral signs, but they must be closer to each other than what would result by \int\int. However, the amount of back up must be bigger in display style than in the other styles, so amsmath uses

\mkern-7mu\mathchoice{\mkern-2mu}{}{}{}

which means that the back up will be -9mu in display style, but only -7mu in the other styles.

Another important example is \text@, which is amsmath internal for \text:

\def\text@#1{{\mathchoice
  {\textdef@\displaystyle\f@size{#1}}%
  {\textdef@\textstyle\f@size{\firstchoice@false #1}}%
  {\textdef@\textstyle\sf@size{\firstchoice@false #1}}%
  {\textdef@\textstyle \ssf@size{\firstchoice@false #1}}%
  \check@mathfonts
  }%
}

Apart from minor details, this achieves the purpose by typesetting four boxes using different fonts: \f@size is LaTeX internal for the current font size, \sf@size and \ssf@size are the internals for the font sizes corresponding to sub/superscripts of first and second level. When finally TeX makes a decision to what style the subformula containing \text is to be typeset, it will use one of the four boxes.

Those boxes are constructed before TeX know which one it has to use, because of what's perhaps the biggest flaw in TeX's design, which is how it manages fractions. But describing this would take too far.

The primitive \mathchoice has four arguments that should by math material; they are typeset in the corresponding style and stored away:

\mathchoice{<material for display style>}
           {<material for text style>}
           {<material for script style>}
           {<material for scriptscript style>}

(in the definition of \text@ we see \textdef@ that calls \hbox to switch back to text mode).

The most frequent use of \mathchoice is through \mathpalette, of which you can find a description in The mysteries of \mathpalette

Answer 2

The best answer to this question (and many other questions) is TeX By Topic by Victor Eijkhout. Try texdoc texbytopic for a free copy of this great book.

Anyway, it tells you that there are eight math modes in TeX:

Math formulas are set in any of eight styles: D display style, T text style, S script style, SS scriptscript style, and the four ‘cramped’ variants D', T', S', SS' of these. The cramped styles differ mainly in the fact that superscripts are not raised as far as in the original styles.

and further.

The primitive command

  \mathchoice{D}{T}{S}{SS}

lets the user specify four variants of a formula for the four styles. TEX constructs all four and inserts the appropriate one.