Skip to main content

Section 6.8 Mathematics

As mentioned in the overview, Section 3.5, we use syntax for mathematics. In order to allow for quality display in HTML, and other electronic formats, this limits us to the subsset of 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 the MathJax Supported LaTeX commands page.

Subsection 6.8.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 -isms like \displaystyle to try to end-run the inline nature. It will just lead to poor results.

Subsection 6.8.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 6.8.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>. If you are tempted to put a \\ into an <mrow>, think twice.

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, 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.3 and Section 6.6 for more on cross-references.

Subsection 6.8.4 Special Characters

The macros, \amp, \lt, and \gt are always available within these mathematics elements, so that you can avoid the special XML characters &, < and >. See Section 3.13 for this same information, but in the broader context of your entire document.

Subsection 6.8.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>


\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 special 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 6.8.6 Cross-References in Display Mathematics

A cross-reference is achieved with the <xref> element, see Section 3.3. 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 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 6.8.7 Alignment in Display Mathematics

Displayed mathematics is implemented with the AMS- 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,

  <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>


\begin{align*} A \amp = B \amp D \amp = E \amp \amp\text{Because}\\ \amp = C \amp \amp = F \amp \amp\knowl{./knowl/txo.html}{\text{Table 6.6.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- 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 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 6.8.8 Fill-In Blanks in Mathematics

The other mix-in XML element is <fillin> with an optional @characters attribute that takes an integer value. You will get a thin horizontal line, on the baseline, which can suggest to a reader that they should supply something within the surrounding mathematics. The attribute suggests the length of the line—experiment a bit, since it is not super-precise.

Subsection 6.8.9 Page Breaks for Tall Display Mathematics

For print output, do nothing additional and 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 6.8.10 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.

PreTeXt will use your macros correctly for print and for HTML, after erasing whitespace from the left margin, and stripping comments.

Subsection 6.8.11 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 's \text{} macro, if you are curious to know the details.) Here is an example. The XML source

</md>.  Now...

will render as

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


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.

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 6.8.12 Additional Packages

Generally, you cannot add additional packages for use within mathematics. The exception is a package with support available optionally within MathJax. And it must have the same name as its normal version. Then set a docinfo/latex-preamble/package element to be the common name of the package. (The cancel package is one such example.)

Then the supported macros of the package will be available with your mathematics elements, and you can use them within other macro definitions. 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.

Subsection 6.8.13 Extras

There are two existing additional options, which we might want to remove some day for technical reasons. Macros from the extpfeil extensible arrows package are availble by default, and an \sfrac{}{} macro is available for appealing inline “slanted fractions.”