##
Section 4.9 Mathematics

As mentioned in the overview,

Section 3.6, we use

LaTeX syntax for mathematics. In order to allow for quality display in

HTML, and other electronic formats, this limits us to the subset of

LaTeX supported by the very capable

MathJax Javascript library. Generally this looks like the

`amsmath`

package maintained by the American Mathematical Society at their

AMS-LaTeX page. For a complete and precise list of what MathJax supports, see MathJax’s

Supported TeX/LaTeX commands. Once you have digested this more general section, be sure to also consult

Section 4.10 for some very specific suggestions.

###
Subsection 4.9.1 Inline Mathematics

Use the `<m>`

to place variables or very short expressions within a sentence of a paragraph, the content of a `<title>`

, a `<cell>`

of a table, a footnote, or other similar locations of sentence-like text. You can’t cross-reference this text, nor make a knowl with it. Though you can typically cross-reference a containing element.

Do not use LaTeX-isms like `\displaystyle`

to try to end-run the inline nature. It will just lead to poor results.

###
Subsection 4.9.2 One-Line Display Mathematics

The `<me>`

element can be used for longer expressions or a single equation. Typically you will get vertical separation above and below, and the contents will be centered. See below about concluding periods (and other punctuation), and alignment. The `<men>`

variant will produce a numbered equation, and therefore with a provided `@xml:id`

attribute, can be the target of a cross-reference (`<xref>`

).

###
Subsection 4.9.3 Multi-line Display Mathematics

We begin with a pure container, either `<md>`

or `<mdn>`

. The former numbers no lines, the latter numbers every line. Within the container, content, on a per-line basis, goes into a `<mrow>`

element. You can think of `<mrow>`

as being very similar to `<me>`

. In a LaTeX `align`

the `\\`

mark the end of a displayed line. In PreTeXt each `<mrow>`

delimits a displayed line, and there are no `\\`

s. Use `\amp`

to mark the alignment point.

On any given `<mrow>`

you can place the `@number`

attribute, with allowable values of `yes`

and `no`

. These will typically be used to override the behavior inherited by the container, but there is no harm if they are redundant. A given line of the display may be the target of a cross-reference, though the numbering flexibility means you can try (and fail) to target an unnumbered equation.

An `<mrow>`

may have a `@tag`

attribute in place of a `@number`

attribute. This will create a “number” on the equation which is just a symbol. This is meant for situations where you do not want to use numbers, and the resulting cross-reference is “local.” In other words, the `<xref>`

and its target are not far apart, such as maybe within the same `<example>`

or the same `<proof>`

. Allowable values for the attribute are:

star, dstar, tstar,
dagger, ddagger, tdagger,
daggerdbl, ddaggerdbl, tdaggerdbl,
hash, dhash, thash,
maltese, dmaltese, tmaltese

These are the names of symbols, with prefixes where the prefix

`d`

means “double”, and the prefix

`t`

means “triple”. Cross-references to these tagged equations happens in the usual way and should behave as expected. See

Section 3.4 and

Section 4.5 for more on cross-references.

###
Subsection 4.9.4 Exceptional Characters

The

LaTeX macros,

`\amp`

,

`\lt`

, and

`\gt`

are always available within these mathematics elements, so that you can avoid the exceptional XML characters

`&`

,

`<`

and

`>`

. See

Section 3.14 for this same information, but in the broader context of your entire document.

###
Subsection 4.9.5 Text in Mathematics

Once in a while, you need a little bit of “regular” text within an expression and you do not want it to look like a product of a bunch of one-letter variables. Use the `\text{}`

macro for these. Only. Other ways of switching out of math-mode and into some sort of “regular” text will appear inferior, and can raise errors in certain conversions.

Do place surrounding spaces inside the `\text{}`

macro.

Do not place any mathematics inside the `\text{}`

macro.

Do not use the `\mbox{}`

macro as a substitute.

Do not use font-changing commands (e.g. `\rm`

) as a substitute.

For example,

<me>f(x) = \begin{cases} x^2 \amp \text{if } x\gt 0\\
-7 \amp \text{otherwise} \end{cases}</me>

produces

\begin{equation*}
f(x) = \begin{cases}x^2\amp\text{if }x\gt 0\\-7\amp\text{otherwise}\end{cases}\text{.}
\end{equation*}

This example amply illustrates the use of macros for XML exceptional characters (twice), appropriate use of the `\text{}`

macro (twice), spaces in the `\text{}`

macro (once), sentence-ending punctuation (see the source, the period is *not* inside the `<me>`

element) and yes, we did think twice about the `\\`

(an exception to the rule).

###
Subsection 4.9.6 Color in Mathematics

There is a temptation to use color to indicate or highlight portions of mathematics, especially for electronic outputs where color is easy and cheap. But before you leap, how will this work in black-and-white printed output? How will it work for a blind reader using a screen-reader or a braille version?

With careful use of TeX grouping (`{...}`

) you can make the two behaviors of `\color`

effective. For example, go:

{\color{blue}{x^2}}

###
Subsection 4.9.7 Cross-References in Display Mathematics

A cross-reference is achieved with the

`<xref>`

element, see

Section 3.4. You can place an

`<xref>`

inside a

`<mrow>`

, and remarkably, it will do the right thing. This is one of only two

XML elements you can mix-in with

LaTeX syntax. A typical use is to provide a justification or explanation for a step in a proof, derivation, or simplification. And it works best with alignment, see below.

###
Subsection 4.9.8 Alignment in Display Mathematics

Displayed mathematics is implemented with the AMS-LaTeX `align`

environment. Ampersands are used to control this, so use the `\amp`

macro for these. The first ampersand in a line or row is an alignment point, typically a symbol, like an equality. The next ampersand is a column separator, then the next is an alignment point, then a column separator, then… The moral of the story is you should have \(n\) alignment points, with \(n-1\) column separators, for a total of \(2n-1\) ampersands—always an odd number.

For example,

<md>
<mrow>A \amp = B \amp D \amp = E \amp \amp \text{Because}</mrow>
<mrow> \amp = C \amp \amp = F \amp \amp <xref ref="txo" /></mrow>
</md>

produces

\begin{align*}
A \amp = B \amp D \amp = E \amp \amp\text{Because}\\
\amp = C \amp \amp = F \amp \amp\knowl{./knowl/xref/txo.html}{\text{Table 4.5.3}}\text{.}
\end{align*}

Sometimes you want several short equations on one line. Do not use `<me>`

. Instead use a single `<mrow>`

inside an `<md>`

, and use alignment to spread them out evenly.

For multi-line display mathematics with no ampersands present, each line will be centered. This is implemented with the AMS-LaTeX `gather`

environment.

You can fool the alignment behavior by hiding all your ampersands in macro definitions, so there is the optional `@alignment`

attribute for the `<md>`

or `<mdn>`

element, in order to force the right kind of alignment. Allowable values are `gather`

, `align`

, and `alignat`

. The latter is similar to `align`

, but no space is automatically provided between columns. You can leave it that way, or explicitly add your own. For example, this allows you to precisely arrange individual terms of a system of linear equations, especially when terms with zero coefficients are omitted. When using the `alignat`

option PreTeXt tries to count ampersands to see how many columns you intend, since LaTeX needs this number (we are not sure why). This detection can be fooled too, especially if you have something like a matrix with lots of ampersands for other purposes. So set the `@alignat-columns`

attribute to the *number of intended columns*, if necessary.

###
Subsection 4.9.9 Commutative Diagrams

Commutative diagrams may be authored using the

AMS LaTeX `amscd`

package. While restricted in some ways, such as the lack of sloped or curved arrows, it has one important advantage over more general drawing tools. Support for

HTML output comes from MathJax, and hence has accessible versions included in the output.

Typical use would be within an `<me>`

element, so starting with `\begin{CD}`

. Despite this being multi-line output, we have not chosen to integrate it within the more general `md/mrow`

structure, but that decision can be revisited.

###
Subsection 4.9.10 Fill-In Blanks in Mathematics

The other mix-in

XML element is

`<fillin>`

. It may use a

`@fill`

attribute with some math string to determine width, height, and depth of the blank. Or it may use a

`@characters`

attribute that takes an integer value to hint at the width.

###
Subsection 4.9.11 Page Breaks for Tall Display Mathematics

For print output, do nothing additional and LaTeX will do its best to break your display between lines. You can turn this behavior off by setting the `@break`

attribute on the `<md>`

or `<mdn>`

to the value `no`

. Once you do this, you can then selectively allow a page break after a given `<mrow>`

by setting the `@break`

attribute on the `<mrow>`

to the value `yes`

.

###
Subsection 4.9.12 Your Macros

These go in the `<docinfo>`

section, wrapped in a `<macros>`

element. Keep them simple—one or two arguments, and one-line definitions. This is not the place to be fancy, and not the place to try to end-run the structural aspects of PreTeXt. The idea is to define something like `\adjoint{A}`

for the matrix `A`

to be a superscript asterisk, and later you can change your mind and use a superscript dagger instead. Keep in the spirit of PreTeXt and use readable, semantic macros. For example, do not use `\a{A}`

for the adjoint of `A`

. Repeating: keep your LaTeX macros simmple, and to a single line.

PreTeXt will use your macros correctly for print and for

HTML, after erasing whitespace from the left margin, and stripping

LaTeX comments.

The name of your macros also cannot contain any numbers, otherwise MathJax will “silently” fail and may not read any subsequent macros you might have. This is important because PreTeXt will place custom macros for you at the end of your own, defined at

Subsection 4.9.4, to be used. Those would fail to be processed by MathJax if your own macros caused it to stop reading.

###
Subsection 4.9.13 Semantic Macros

We have resisted using overly-verbose MathML for mathematics, or worse, inventing our own

XML vocabulary for mathematics.

LaTeX syntax generally works great, but to work even better within PreTeXt an author needs to take a few extra steps. Your work will translate better to a variety of formats, and will be easier to maintain, with well-designed macros. A well-designed macro will convey the mathematical

*meaning* of the object to a reader of your source, without them looking at your

*definition* of the macro. In situations where a mathematical object might be written with different notation, it should be trivial to change the macro’s definition and preserve the mathematical meaning. For example, consider two versions of a binomial coefficient:

\begin{align*}
&{n\choose r} & &\operatorname{C}(n,r)
\end{align*}

which could both equally well be the realization of `\binomial{n}{r}`

.

Here we describe some notation which often carries multiple mathematical meanings and/or may be created with LaTeX in multiple ways.

####
Subsubsection 4.9.13.1 Vertical Bars

Vertical bars are used for a variety of mathematical objects. Paired to create functions of expressions: absolute value, \(\left\lvert x-1\right\rvert\text{;}\) norm of a vector, \(\left\lVert \mathbf{v}\right\rVert\text{;}\) cardinality of a set, \(\left\lvert X\right\rvert\text{;}\) and the determinant of a matrix, \(\left\lvert A^k\right\rvert\text{.}\) As relations: division, \(a\mid b\text{;}\) parallel lines \(L_1\parallel L_2\text{.}\) Sets are another use: \(E=\left\{x\in{\mathbb Z}\,\middle\vert\, x\equiv 0\pmod 2\right\}\text{.}\)

LaTeX `\vert`

, `\Vert`

, `\lvert`

, `\rvert`

, `\lVert`

, `\rVert`

are the delimiters, where `l`

and `r`

refer to left and right, and the capitalized versions are a pair of vertical lines. The qualifiers `\left`

and `\right`

can be used to have the length of the bar grow to match what it encloses. Note that there is a `\middle`

that we have used above with `\vert`

for the set \(E\text{,}\) and we have added space on either side. `\mid`

and `\parallel`

are relations, used above to indicate divisibility and parallel lines, and so automatically get an extra bit of spacing on either side.

When using `\left`

or `\right`

in isolation, `\left.`

or `\right.`

can be used to define a group that only has a bar on one end. For example:

\begin{gather*}
\int_0^1\,\sin^{-1}(x)\,dx = \left.\frac{1}{\sqrt{1-x^2}}\right\rvert_{x=0}^{x=1}\text{.}
\end{gather*}

####
Subsubsection 4.9.13.2 Times

The “times” symbol sees many uses that are different: dimensions, multiplication, and more complicated products (such as a Cartesian product of two sets). Macros `\product`

, `\times`

, and `by`

could carry different meanings, even if each one is defined by the `\times`

symbol, \(\times\text{.}\) For example:

Chess is played on an <m>8 \by 8</m> grid, which
contains <m>8 \times 8 = 64</m> little squares.

If <m>G</m> and <m>H</m> are finite groups, then
<m>\card(G \product H) = \card(G) \times \card(H)</m>.

###
Subsection 4.9.14 Punctuation After Display Math

If a chunk of displayed math concludes a sentence, then the sentence-ending punctuation should appear at the conclusion of the display. (And certainly not at the start of the first line after the display!) But do not author the punctuation within the mathematics element, put it afterwards, where it logically belongs.

More specifically, place a sentence-ending period (say)

*immediately* after the closing of an

`<me>`

,

`<men>`

,

`<md>`

, or

`<mdn>`

element. PreTeXt will place the period in your output in the right place and in the right way. (By using

LaTeX’s

`\text{}`

macro, if you are curious to know the details.) Here is an example. The

XML source

<md>
<mrow>(a+b)^2</mrow>
</md>. Now...

will render as

\begin{gather*}
(a+b)^2\text{.}
\end{gather*}

Now…

This all applies more generally to clause-ending punctuation, such as a comma. Take notice of the requirement that the punctuation must be

*immediately* after the closing tag of the math element, otherwise it will not migrate properly. For example, do not interrupt the flow with whitespace, or an

XML comment, or anything else.

For inline mathematics (the `<m>`

element) the same authoring principle holds, though you would likely do this naturally. Author the punctuation *outside* the element, where it will remain.

Here is a technical subtlety that will demonstrate some of the inner machinery of PreTeXt and our conversions. In your work, locate a theorem that has some numbered display mathematics (

`mdn`

) which is at the end of a sentence, and which you have authored as described above. In

HTML output, test a cross-reference (

`xref`

) to the theorem and you will see the period for the end of the sentence at the end of the display, where it should be. Now test a cross-reference (

`xref`

) to one of the numbered equations. First, the knowl will contain the entire display, to provide context, but it also will not contain the period, since the rest of the sentence is not in the knowl and so the period is not necessary.

###
Subsection 4.9.15 Lists of Mathematical Expressions

It is common to make lists of expressions, equations, or identities. Think of the definitions of trigonometric functions, a collection of antiderivatives, or a compendium of generating functions.

In these situations, author a list item, `<li>`

, within an `<ol>`

or `<ul>`

, by using *only* the necessary `<m>`

element. Do not use an intervening `<p>`

, and do not include any adjacent text. Whitespace is OK. Then PreTeXt will add LaTeX’s `\displaystyle`

command to improve the visual appearance of the mathematics, and so you do not need to.

If you prefer to not have this behavior, insert an intervening `<p>`

, and output will be identical, but without the `\displaystyle`

.

Note that

*any* text, other than whitespace, outside the

`<m>`

tag will disable this feature,

*including punctuation*. However, according to the

Chicago Manual of Style [1, 6.127], “Items carry no closing punctuation unless they consist of complete sentences.” So that comma at the end of your equation probably doesn’t belong there anyway.

###
Subsection 4.9.16 LaTeX Packages, MathJax Extensions

LaTeX, which we use as the syntax for mathematics, allows extensive customization through packages, which are enabled through a `\usepackage{}`

macro. Packages also provide extensive customization or control over the document structure. Thus, PreTeXt provides support for additional packages *to enhance mathematical content*, but does not have any facility beyond this (e.g. to influence or support document structure).

We use

LaTeX to create

PDF and print output. For most other electronic formats, we use MathJax to embed mathematics onto a web page or to make images of mathematics used in EPUB, and so on. MathJax has

extensions, which mimic certain

LaTeX packages. For a list of supported extensions see MathJax’s

TeX/LaTeX Extension List. Note that some of these extensions are technical (not supporting mathematical syntax) and some we load already as part of setting up MathJax, so carefully evaluate how a given package is selected to support certain macros.

Suppose there is a

LaTeX math-mode macro you would like to use. We will illustrate with the

`\cancelto`

macro that is part of the fairly standard

`cancel`

package. It will draw an arrow through a mathematical formula, with a replacement value. Conveniently, MathJax has a

`cancel`

extension, and this extension

*also* defines the

`\cancelto`

macro. You need to check this, as a

LaTeX package and a MathJax extension are not guaranteed to define the same collection of macros. Nor are the two guaranteed to have the same name (though this is best practice).

To make the `\cancelto`

macro available and active in your mathematical elements (`<m>`

, `<me>`

, etc.) add the following to your `<docinfo>`

element:

<math-package latex-name="cancel" mathjax-name="cancel"/>

Now you may freely use the `\cancelto`

macro in your mathematics, confident that it will render correctly in all output formats.

Note that both attributes

`@latex-name`

and

`@mathjax-name`

must be present. They may be identical (as above, and typical) or they may be different (rare). There are situations where one might be empty. Of course, you can use these macros in other definitions of mathematics macros you might make (

Subsection 4.9.12). However, we do not guarantee the absence of conflicts with other packages in use, even if employed by PreTeXt. Nor do we support debugging such conflicts.

If there are

LaTeX macros you desire, but without a MathJax implementation, then there is not much we can do, short of suggesting you write your own extension (not recommended, see

A Custom Extension). There are some workarounds which we may document shortly.

###
Subsection 4.9.17 Mathematics in Titles

Titles are a key feature of PreTeXt, and migrate to various places in different conversions, where they might be mixed with bold text, or where they do not render properly. Please report any substandard situations. A good example of this phenomenon is mathematics in division titles, where we provide a

`<plaintitle>`

alternate. See

Section 4.8 for a complete discussion.

###
Subsection 4.9.18 Extras

We were once in the business of supporting “extra” macros for mathematics, but have discontinued that practice (in a mostly backward-compatible way).

We are moving away from built-in automatic support for the

`\sfrac{}{}`

macro. As of 2023-10-18 you may use this macro, but results will just look like regular inline fractions. However, you can get superior typesetting in

PDF output by loading the

`xfrac`

LaTeX package with the following in

`<docinfo>`

:

<math-package latex-name="xfrac" mathjax-name=""/>

Historically, we provided good internal support for the LaTeX `extpfeil`

package of extensible arrows, even though the LaTeX version has some severe shortcomings. As of 2023-10-19, it is now an author’s responsibility to *elect* this package, along with the reliable MathJax extension of the same name. Add to `<docinfo>`

:

<math-package latex-name="extpfeil" mathjax-name="extpfeil"/>

###
Subsection 4.9.19 Notes

As mentioned at the start of this section, your use of

LaTeX needs to also be supported by MathJax so that it may be rendered as part of an

HTML page displayed in a web broswer. In addition to the information at the start of

Section 4.9, this subsection has some notes that may help you navigate this situation.

Generally, MathJax supports commands available in the `amsmath`

package.

You can construct, and use, your own macros,

*but only for mathematics*, not for document structure or document management. See

Subsection 4.9.12.

The `\matrix{}`

command, and its friends (such as `\pmatrix{}`

) are not supported by LaTeX, despite being recognized by MathJax. So use environments like `\begin{matrix}`

and `\begin{pmatrix}`

(with their corresponding `\end{}`

, of course) and you will get accurate results for both formats.