Revised:

MathML Best Practices

Introduction

This guide is an overview of best practices that Hawkes uses for the construction of our math content via MathML and MathJax in all areas of the Web Platform. This document makes frequent use of examples and includes the most recent version of the MathJax library as accessed through the MathJax CDN.

Best Practices

The foundation of this document is based on standards created by the W3C in the MathML specification (specifically Chapter 3: Presentation MathML) and by the MathML in DAISY (Digital Accessible Information SYstem) Structure Guidelines. Some of the DAISY standards are DAISY specific and have been specifically omitted from this document. Rather than simply referring others to both of these guidelines, a condensed version is provided in this guide. The simpler elements will not be explained in detail nor will a detailed overview of the attributes that can be applied to those elements be given. Please note that this is a living document that will be updated as the best practices are refined.

What Is MathML?

MathML is a markup language similar to HTML that is used for encoding and display of mathematical equations. The base element for MathML expressions is the math element and this is used to start every MathML expression. Writing well-formed MathML expressions is important because it allows user agents (web browsers, screen readers, etc.) to determine the structure of math expressions in a machine-readable way.

Accessible mathematics on the web has had a rocky history. In previous versions of Internet Explorer (IE), assistive technology users could utilize the MathPlayer plug-in to provide an audio rendering of MathML expressions. With support for plug-ins dropped from IE10, and IE11 only recently supporting enterprise mode, which enables plug-in use, assistive technology users have had a lot of difficulty with mathematics on the web. The screen reader JAWS only recently gained the ability to read MathML rendered through MathJax (a JavaScript rendering engine), providing access for users once again.

The Importance of Well-Formed MathML and MathML Cloud

Having well-formed MathML is important for a number of reasons. First, it makes the code more maintainable, since standardized code allows content developers to easily make improvements as the technology evolves. Secondly, any person looking at the code will know exactly what the expression means, or will have the ability to gain understanding through existing references. Well-formed MathML code also provides a distinct hierarchy for assistive technology to travel through. This hierarchy is the structure of the mathematical expression and allows assistive technology users to better understand the expression. Lastly, having well-formed MathML means that a service for generating alternative text for math equations can be used with the understanding that since our equations conform to guidelines, similar equations should receive similar alternative text. This consistency provides predictability for users.

Alternative Text Using MathML Cloud

MathML Cloud is a service that uses the structure of MathML to create alternative text. Hawkes uses MathML cloud to generate alternative text for MathML expressions, which provides a fallback mechanism for any assistive technology that cannot read MathML markup.

To use MathML Cloud, follow this link to www.mathmlcloud.org.

Once on the landing page, select Convert Multiple Equations and then select MathML.
Select the browse button and navigate to the HTML page you would like to upload.
After you have selected the document, select Process and wait for the page to finish processing.
Next, you will be presented with a list of MathML expressions found in the HTML document and the descriptions that were added. You can look through the descriptions in this view to make sure they are correct or look through them later. You also have the option to leave feedback for the description or the way that the MathML was output.
Then select the output file link towards the top of the page. This will prompt a dialog. Save the document.

Once the document has been saved you can open it up in a browser or text editor and look through the alternative text (called description by MathML Cloud). Alternative text will be added in the MathML expressions through the alttext attribute. It will look like the following.

$0 division-sign 23 equals 0$

Alttext added through MathML Cloud

<!--https://mathmlcloud.org/equation/55c4ee8c9e28dbb8d64d4b81-->
<math xmlns="http://www.w3.org/1998/Math/MathML" id="55c4ee8c9e28dbb8d64d4b81" alttext="0 division-sign 23 equals 0">
    <mrow>
        <mn>0</mn>
        <mo>÷</mo>
        <mn>23</mn>
    </mrow>
    <mo>=</mo>
    <mn>0</mn>
</math>

When MathML is used in a desc element within an SVG, MathML Cloud will still add alternative text to that expression. You can see the MathML within the desc element from your browser using the developer tools built into most modern browsers.

Lastly, you can use MathML Cloud alternative text to help with proofing MathML equations. If something reads strangely in the MathML Cloud alternative text, it is usually an issue with the MathML formatting.

Updating Equations in MathML Cloud

Should an equation change that already has alternative text from MathML Cloud this equation should be updated in MathML Cloud. In the example above note that there is a URL in a comment https://mathmlcloud.org/equation/55c4ee8c9e28dbb8d64d4b81. Go to the URL and paste the new MathML equation. Click update and copy and paste the equation and alternative text into the document that you are working on.

When We Use MathML

In the Hawkes Web Platform, mathematical expressions are presented either as MathML or as SVG images with embedded markup. For most mathematical elements, simply using MathML that is well marked up should be sufficient, and places where images are more appropriate are covered in the MathML Content Best Practices.

When We Do Not Use MathML

There are several places within the Web Platform where we choose not use MathML. The JavaScript renderer that Hawkes uses, MathJax, to display the MathML can cause longer page load times when there is a lot of math on the page. To reduce page load times we use standard HTML elements whenever possible.

For variables that appear by themselves within the content we use the var element to denote that the text represents a variable. Since var is a native HTML element there will be no need to calculate its position on the page. In order to keep headings, including table headings as consistent looking as possible we only use MathML when a complex math expression appears in the heading, such as $\frac{x - 1}{3}$ .

Another area that MathML should not be used is when numbers are not being referred to mathematically. Some examples of this kind of situation are dates, times, figure numbers, example numbers, table numbers, decades, etc. One example that requires specific markup is ordinal numbers such as 1^st, 2^nd, and 3^rd. These numbers are written in plain text with the sup element used to superscript the text.