# MathML 3

## Why MathML 3?

MathML 2 was first adopted in 2001. Experience with MathML has accumulated over the years and the web environment has changed somewhat since then. Released in 2010 and updated in 2014, MathML 3 includes several requested features and some changes to update the recommendation to the current and emerging standards. MathML 3 also contains lots of smaller changes to clarify the spec and unify attribute values so that compatibility between implementations is more likely. With the exception of a few very minor changes for features not widely implemented, MathML 3 is backward compatible with MathML 2.

The big changes are:

- control over linebreaking and indentation
- elementary math notation support (2D math, long division, ...)
- support for bi-directional languages (eg, Arabic languages)

Some of the smaller changes are:

## The big changes

### Linebreaking and indentation

MathML 3 introduces several attributes for controlling line breaks and indentation after line breaks. The new controls can be used for both automatic line breaks when the renderer determines that there is not enough room to display an expression in a given width and for manual (forced) line breaks. In MathML 3, linebreaking and indentation are specified on operators (`mo`

). The controls include:

- whether a line break should or should not happen at an operator;
- whether the break should be before or after the operator;
- what character to use (if any) in place of an "⁢" character at a line break
- the amount of vertical space to be used after the line break

MathML 3 offers a good deal of control over how to indent after a line break. This allows for many different styles of linebreaking and also makes it possible to align the new line with a previous point in the expression (e.g., at an "="). Alignment at a particular point is done by marking the element you want to align to with an `id`

attribute and then telling MathML to indent to that id value.

The indenting controls include:

- alignment -- left/center/right/automatic/id
- shift amount -- amount to shift it from the aligned point

These options can be set for all of the lines or specifically for either the first or last line to override the indentation behavior for those lines. This flexibility accommodates many different styles of indenting.

For some examples, see Linebreaking of Expressions. For details, see Section 3.2.5.2.2 and Section 3.2.5.2.3 of the MathML 3 recommendation.

### Elementary math

MathML has long been useful for notations used in algebra and higher math, but describing the two-dimensional layout used in elementary math required tedious layout using `mtable`

, with each digit in its own column and clever tricks to get the lines to come out correctly. This was both difficult to do and the result was inaccessible. MathML 3 adds support for a wide variety of notations used in lower grade math for:

- addition, subtraction, and multiplication (with carries/borrows)
- long division
- repeating digits in decimal numbers

Here are some examples:

subtraction with borrows | long division (US, etc., style) | repeating decimal |

The support for these notations is very flexible in MathML 3 to handle the wide variety of notations that are used around the world. The flexibility allows for:

- different positions for the operator in addition, subtraction, and multiplication problems
- different positions for the carries
- different styles of cross-outs
- control over the length, position, and thickness of lines
- different notations for long division
- different notations for showing repeating decimals

For more examples, including a video showing how MathPlayer will speak these for accessibility, see our elementary math examples page. For complete details about the elements and attributes used for elementary math, see Section 3.6 of the MathML 3 recommendation.

### Bidirectional layout support

Mathematical notation is mostly consistent around the world. However, there are some notations that differ depending upon the language/locale such as "." versus "," for a decimal separator and "tan" (English) versus "tg" (French) for the tangent function. For people who want to produce language-independent MathML, content MathML smoothes over these differences and presentation MathML allows these specific notations to be encoded.

In Arabic countries, mathematical notation is written right-to-left using the same alphabetic characters. MathML 3 now makes it possible to encode right-to-left notations in presentation MathML. MathML 3 adds a `dir`

attribute to control whether layout is left-to-right or right-to-left (see Section 3.1.5 of the MathML 3 recommendation for details). MathML 3 also introduces some `mathvariant`

values for handling different styles of Arabic characters (see Section 3.2.2).

Here are two examples of Arabic math that use right-to-left notation (note: numbers are still left-to-right in Arabic math notation):

Square root | Long division |

### Content MathML

The chapter on content MathML was completely rewritten for MathML 3. Content MathML is used when the semantics of the math are more important than the visual display (the presentation) of the math. In MathML 3, a subset of content MathML is defined with semantics specified by OpenMath. This subset of content MathML is called Strict Content MathML and each element in strict content MathML is associated with a specific OpenMath Content Dictionary entry. OpenMath Content Dictionaries are extensible and permit a more precise definition of the semantics of each element. The meaning of most content MathML elements remains basically unchanged, although a mapping for each element into strict content MathML is given.

In order to accomplish alignment with OpenMath, the following changes were made to the elements:

- New content elements were added:
`bind`

,`share`

,`cerror`

,`cs`

, and`cbytes`

- Deprecated content elements:
`reln`

,`fn`

, and`declare`

## The little changes

### New attributes for ‹math›

Additional attributes were added to the `math`

element. Probably the biggest difference is that any attribute that can be specified for `mstyle`

can now be specified for `math`

. Other additions include the ability to set the width for linebreaking, control over the `altimg`

size and alignment, and the ability to set the `cdgroup`

(used for content MathML). See Section 2.2.1 of the MathML 3 recommendation for full details.

### Linking

In MathML 2, linking was done via XLink. However, XLink did not catch on and HTML5 doesn't use it. In MathML 3, all elements accept an `href`

attribute to allow for hypertext links. Note that what should happen for hypertext links depends on the environment in which the MathML resides. In MathPlayer, links cannot point to places inside of a MathML expression. See Section 2.1.6 and Section 6.4.3 of the MathML 3 recommendation for full details on linking and `href.`

### mglyph

`mglyph`

was extended to support general image inclusion (sort of like a `img`

element in HTML). In earlier versions of MathML, the idea was that `mglyph`

was a way of including characters from a non-standard font. This was not used much and the old usage of specifying a font and index into that font is deprecated in MathML 3. `mglyph`

now takes attributes to specify the source of the image, size, and alignment. For accessibility reasons, an `alt`

attribute value is required. For complete details on `mglyph`

, see Section 3.2.1.2 of the MathML 3 recommendation.

### mpadded

`mpadded`

is used to adjust the spacing around its children. The allowed attribute values have been extended and new attributes for positioning the children within the specified spacing have been added. See Section 3.3.6 of the MathML 3 recommendation for full details.

### semantics/annotation/annotation-xml

This element was previously grouped with content MathML, but properly spans both presentation and content MathML and should be implemented by any system that implements only content or only presentation MathML. It is now in Chapter 5, which discusses mixing content and presentation MathML. `annotation`

and `annotation-xml`

both take the content MathML attributes `cd`

and `name`

, and also take a `src`

attribute to specify the location of an external source for semantic information.

### Interactions with the host environment

MathML 3 adds a new Chapter 6 that discusses how MathML should interact with its host environment. There is an emphasis on MathML in web pages, but there is a discussion with embedding MathML in other environments. Among the topics covered are:

- names and "flavors" to use for encodings on the clipboard and the format to use for data in those encodings
- how MathML can be mixed with other markup, including embedding SVG in MathML
- using CSS with MathML

### New schema

In a step forward into today's web environment, the normative version of the grammar is now expressed in Relax NG, not as a DTD. A DTD and XSD version still exist and are derived from the Relax NG grammar.

### New operator dictionary

The Operator Dictionary table has been greatly expanded (and cleaned up) to include lots of new characters and attributes. The format is new and includes the ability to sort on different columns.

### Entities

Most of the information about entities has been moved from chapter 6 and is now its own recommendation: XML Entity Definitions for Characters. That new recommendation includes changes made to Unicode characters along with a discussion of some problematic characters.

## MathML and HTML5

HTML5 updated HTML4 to help meet the needs of modern web architecture. One of those updates brought math support into HTML5 via MathML. Most MathML will work just fine in HTML5, but here are a few things to watch out for:

HTML5 normally doesn't care about namespaces and puts all of the elements in the HTML namespace; MathML and SVG are the two exceptions to this rule. For compatibility with XTHML 1.x and XHTML5, the math tag should include the MathML namespace as shown below:

<math xmlns="http://www.w3.org/1998/Math/MathML"> … </math>

Another namespace issue arises with the use of `annotation-xml`

inside of `semantics`

. Inside of MathML, all elements are placed in the MathML namespace with two exceptions: inside some `annotation-xml`

elements and inside of `mtext`

elements.

The first exception allows you to include an HTML alternative encoding inside of a `semantics`

elements. The exception happens when the encoding attribute for `annotation-xml`

is either "text/html" or "application/xhtml+xml". In these cases, the elements are placed inside the HTML namespace and can be manipulated by script or styled by CSS if made visible. For other encodings, the non-HTML5 elements are placed in the MathML namespace even if they are declared to be in another namespace (eg, http://www.openmath.org/OpenMath ). If you use XHTML5 which is namespace aware, namespaces inside of MathML should be handled properly.

The second exception is inside of `mtext`

. HTML5 extends MathML by allowing HTML5 elements inside of mtext. These elements are placed in the HTML namespace. It is not recommended that you make use of this extension because it is unlikely to work in other environments.

If HTML tags occur elsewhere inside of a MathML element (with the two exceptions above), the MathML element is terminated (closed off) by the HTML5 parser at that point. That is almost certainly not what most authors intend, so care should be taken when adding HTML5 in MathML.

## Trying MathML 3

Other than MathPlayer, there are still very few complete implementations of MathML 3. Many other implementations, such as Firefox and MathJax have implemented some of MathML 3; we expect more and more of the features of MathML 3 will be implemented in those and other applications.