[Tex/LaTex] When not to use \ensuremath for math macro

best practicesmacrosmath-mode

I have gotten into the habit of using \ensuremath around math components in every macro that I define, so that I can use the same macro inside and outside of math mode. But egreg's comments in \DeclareMathOperator won't take arguments has me thinking that perhaps I should not be doing this all the time:

It's not a good idea, in my opinion, to add \ensuremath; why should it be? Disclaimer: this is part of my \ensuremath-only-when-really-needed campaign. 🙂 – egreg

Why \ensuremath? Wouldn't $\scriptstyle#1$ be easier to read? – egreg

In this case it was required to use math mode as we were within a \makebox (i.e., text mode). So, out of habit I used \ensuremath but egreg was right that in this case using $...$ would have worked just as well and was certainly easier to read. But, even in this case I still prefer to use \ensuremath so that it is more obvious that this can be used in math and text mode without having to think about \makebox being in text mode.

So, is there really any harm in always using \ensuremath, at least for any of my personal macros? I realize that there is a slight extra overhead in processing, but is there something else to consider?

If there are other considerations when they macros are coming packages that are intended for general purpose use, I would be interested in those as well. The most obvious one is that we may want to make sure that the user of the macro knows that this macro requires math mode, so require them to only use the macro in math mode.

Since this references egreg's campaign, I felt I should include a MWE for new users as per my MWE-as-often-as-possible campaign:

\documentclass{article}

\newcommand{\FunctionF}{\ensuremath{x^2}}%

\begin{document}
Text mode: \FunctionF

Math mode: $G(x) = x^3 - \FunctionF$
\end{document}

Best Answer

Two objections come to mind:

If you don't know you will be entering math mode, then you may write something "semantically" correct that breaks.

For example:

\documentclass{article}
\newcommand\mathmacro[1][A]{\ensuremath{{#1}_1}}
\begin{document}
 \mathmacro[$x^2$] % The dollar signs *leave* math mode
\end{document}

What's going on here is that \mathmacro[$x^2$] expands to

\ensuremath{{$x^2$}_1}

which expands to (effectively)

\ifmmode
 {$x^2$}_1
\else
 ${$x^2$}_1$
\fi

and you can see that if you write it outside of math mode, the second branch is taken, so the first dollar sign brings you into math mode and the one at the front of $x^2$ takes you out of it, with the reverse operation happening afterwards. This gives an error.

Of course, you aren't supposed to do that, since \mathmacro is actually a "math macro usable in text mode", so you should think of the thing between the brackets of its argument as being in math mode. Alas, this confuses both the author and the text editor's syntax highlighting, since it is a nonstandard assumption.

Edit: I would define this macro as:

\newcommand\mathmacro[1][A]{{#1}_1}

and use it as:

$x^2$ sub one: $\mathmacro[x^2]$.

This way, the parts that are math are clearly math.

In the unlikely event that you or some package sets \everymath, you will be very surprised when your apparently text-mode macros start to look different.

On the subject of semantics, though, the issue is clear: \ensuremath breaks the separation between math and text, which are two very different things. TeX even has the distinction built in: different fonts, different spacing rules, different parsing rules. You can probably construct a lot more counterexamples by exploiting these.

What I mean by this is that in the following situation:

\documentclass{article}
\newcommand\mathmacro[1][A]{\ensuremath{{#1}_1}}
\begin{document}
 A sub one: \mathmacro

 \bfseries A sub one: \mathmacro
\end{document}

you may be surprised that the bold text does not extend to the contents of the apparently text-mode \mathmacro.

What I'm saying is not so much that \ensuremath actually breaks anything as that it violates your expectations to the point that it makes things harder rather than easier.

Tokenization stage

The general rule is that spaces after control words (\par, for instance) are ignored, while after control symbols (\!, for instance) are retained; spaces at the beginning of a line are ignored altogether. Consecutive spaces are transformed into one space token but two consecutive end-of-lines become a \par (this statement is not fully correct, but not too incorrect for the purposes of this answer).

After the tokenization stage

There is an obvious intermix between tokenization stage and subsequent processing. In what follows "space" will mean "space token" and I won't care about spaces that have already disappeared, such as those after a control word).

It's now important to know that spaces in the input don't always produce spacing in the output. To understand why, it's necessary to learn some theory.

TeX is always in one of three modes: horizontal, vertical or math.

_{(The above paragraph tells a lie, strictly speaking: there is a circumstance in which it's not in one of these modes, but it's irrelevant for the discussion.)}

Under normal circumstances spaces do not produce output in vertical and math mode (let's not discuss the very special settings that make them appear).

It's quite easy to tell when TeX enters math mode: as soon as it sees $ or $$ (which, in LaTeX parlance, are, respectively \( and all the display math environments, initiated by \[, \begin{equation}, \begin{align} and so on). It exits math mode, returning to the previous mode when it sees the closing $ or $$ (with similar remarks as before for LaTeX).

Roughly speaking, TeX is in vertical mode at the start of a job or after a \par or when it's beginning a \vbox or \vtop or \vcenter; these are started, in LaTeX, by \parbox and \begin{minipage}. However, spaces in vertical and math mode are not suppressed: they are there, but produce no output. This is a cause for some misunderstandings. TeX starts horizontal mode when it sees a character to be typeset, \noindent, \indent or some other commands, notably \leavevmode (this is not an exhaustive list) or when it's starting an \hbox (for LaTeX it's \mbox, \makebox, \fbox, \colorbox, ... or the lrbox environment). In horizontal mode every space that's not absorbed by other rules (see later) produces output.

When TeX is absorbing the preamble of a LaTeX document it is in vertical mode. But a definition such as
```
\newcommand{\foo}{
  bar
}
```
will produce spaces in the output: the above is equivalent to
```
\newcommand{\foo}{ bar }
```
If \foo is seen at the beginning of a paragraph, the first space will not produce output (TeX is still in vertical mode), but the second will, as the b will trigger horizontal mode. Conversely
```
\newcommand{\baz}[1]{\parbox{10cm}{
  #1
}}
```
won't show spurious spaces. The first one, before #1 does nothing because it's seen in vertical mode; the final one, after #1 is suppressed because of the final implicit \par that ends the \parbox.
A definition such as
```
\newcommand{\myop}{
  \overset{t }{=}
}
```
will not need % to protect end-of-lines (translated into spaces), because it will be used in math mode (or will give an error anyway).

The most important (but easy) rule that should be considered is that tokens in the body of a definition are simply stored and not executed (they can be expanded in a \edef or \xdef, but still not executed). The execution is performed (after expansion) when the defined macro is used. The execution of a space token in vertical or math mode does nothing, in horizontal mode it produces a spacing in the output.

Numbers and dimensions

There is a place where space tokens have a peculiar behavior. When TeX is looking for a number or a dimension in order to perform an assignment or when expanding \number and \romannumeral, it expands tokens until an unexpandable token appears or a space token is found. In this case, the space is swallowed as part of the process.

This is one aspect to be kept in mind when writing macros. Let's see an example: we want to make a "monthly to-do list". Just a \parbox with twelve lines labelled by year and month; a loop seems the best approach, with the year given as argument:

\documentclass{article}
\newcount\monthlycount
\newcommand{\monthlytodo}[1]{\par%
  \fbox{%
    \parbox{10cm}{%
      \monthlycount=1%
      \loop\ifnum\monthlycount<13%
        #1--\number\monthlycount\hrulefill\par%
        \advance\monthlycount by 1%
      \repeat%
    }%
  }%
}
\begin{document}
\monthlytodo{2013}
\end{document}

Try it; this will surprise you with

! TeX capacity exceeded, sorry [main memory size=3000000].

Oh, boy! We've made sure that no spurious spaces were inserted by our macro! Why is TeX betraying us? Simple: the input can be written equivalently as

\loop\ifnum\monthlycount<13#1--\number\monthlycount

and #1 is replaced by 2013. So our loop checks whether the current value of \monthlycount is less than 132013 and stores tokens for the \parbox until TeX runs out of memory.

Let's try an amended version:

\newcommand{\monthlytodo}[1]{\par
  \fbox{%
    \parbox{10cm}{
      \monthlycount=1
      \loop\ifnum\monthlycount<13
        #1--\number\monthlycount\hrulefill\par
        \advance\monthlycount by 1
      \repeat
    }%
  }%
}

Look, ma! No spurious spaces!

enter image description here

Exercise 1 Why some lines end with % and other lines don't? We now know that % is harmful after 13 (and also after the 1 in the preceding line).

Technicality: space tokens are looked for but then swallowed also after keywords (such as by in the example and the unit names mm, pt and so on). There are also a few other places, but this answer is already too long. I'll show only how some of the problems can arise also when using LaTeX functions in this context:

\newcounter{monthlycount}
\newcommand{\monthlytodo}[1]{\par
  \fbox{%
    \parbox{10cm}{
      \setcounter{monthlycount}{1}
      \loop\ifnum\value{monthlycount}<13
        #1--\arabic{monthlycount}\hrulefill\par
        \stepcounter{monthlycount}
      \repeat
    }%
  }%
}

Exercise 2 Why isn't % necessary in lines 4–9 of the code above?

Best Answer

Related Solutions

[Tex/LaTex] Proper way to use \ensuremath to define a macro useable in and out of math mode

[Tex/LaTex] When is it harmful to add percent character at end of lines in a \newcommand, or similar

Tokenization stage

After the tokenization stage

Numbers and dimensions

Related Question