Caution

A solution for MathML that works in all user agents does not currently exist. The techniques presented on this page will continue to be updated as new information becomes available.

Summary

Support for rendering of native MathML markup is increasing but workarounds may still be necessary in some support scenarios.

Techniques

Examples

Example 1 — Block-level MathML equation with a description in the alttext attribute
<math xmlns="http://www.w3.org/1998/Math/MathML"
      alttext="Frac Root a EndRoot Over b EndFrac">
   <mfrac>
      <msqrt>
         <mtext>a</mtext>
      </msqrt>
      <mi>b</mi>
   </mfrac>
</math>

Demo:

a b
Example 1 — Inline MathML equation with a description in the alttext attribute
In the Pythagorean Theorem,
   <math alttext="a squared plus b squared equals c squared">
      <mrow><msup><mi>a</mi><mn>2</mn></msup><mo>+</mo><msup><mi>b</mi><mn>2</mn></msup><mo>=</mo><msup><mi>c</mi><mn>2</mn></msup></mrow>
   </math>,
   the sum of the square of …

Demo:

In the Pythagorean Theorem, a2+b2=c2, the sum of the square …

Example 3 — Image with alternative text

Note that although an image might be the only output, if a publisher has source MathML markup, it can be kept together with the image in a (possibly hidden) div. Publishers could then choose which format to use in their published content (i.e., filtering out the less-supported alternative). It could also allow both forms to be published, with scripting used to determine which to render (note that a CSS fallback might also be needed for the hidden attribute if older user agents like IE11 have to be accounted for).


<div class="mathml-eq">
   <img src="squarerootab.jpg" alt="Frac Root a EndRoot Over b EndFrac"/>
   <div hidden="hidden">
      <math xmlns="http://www.w3.org/1998/Math/MathML"
            alttext="Frac Root a EndRoot Over b EndFrac">
         <mfrac>
            <msqrt>
               <mtext>a</mtext>
            </msqrt>
            <mi>b</mi>
         </mfrac>
      </math>
   </div>
</div>

Alternatively, to avoid any processing or rendering impact, the MathML markup could be hidden in an HTML comment (<!-- -->). This may pose re-processing challenges later.


<img src="squarerootab.jpg" alt="Frac Root a EndRoot Over b EndFrac"/>
<!-- <math xmlns="http://www.w3.org/1998/Math/MathML"
            alttext="Frac Root a EndRoot Over b EndFrac">
         <mfrac>
            <msqrt>
               <mtext>a</mtext>
            </msqrt>
            <mi>b</mi>
         </mfrac>
      </math> -->

Frequently Asked Questions

Should I prefix the MathML tags?

No, it is not recommended to use prefixes with math tags (e.g., m:math).

Not all combinations of assistive technologies and user agents are XML aware, so even if they support MathML markup they may not support prefixed markup.

The use of unprefixed tags is also recommended as it ensures compatibility between both HTML and XHTML syntaxes (XML prefixes are not supported in HTML).

Should I use the ARIA math role?

No, it is strongly advised not to use the math role with MathML markup. In many cases, using this role will cause the MathML markup not to be accessible to users.

Why aren't natural language descriptions advisable?

Consider the simple equation presented in Example 1 above. A reasonable natural language description might be "the square root of a over b". But consider that there are two ways that this statement could be interpreted:

  1. to take the square root of the value a and then divide the resulting value by b.
  2. to divide a by b and then take the square root of the resulting value.

A user who cannot see the visual presentation of the equation is not going to be able to determine which is the correct interpretation with only the description to go by. MathSpeak takes the ambiguity out of the equation by clearly breaking down the components of the equation in a way that doesn't leave ambiguity.

Is MathSpeak the only option for describing MathML?

No, but it is an openly documented format. Although some MathML applications take slightly different approaches to voicing equations, MathSpeak is a good reflection of the typical grammar.

Should I use the verbose, brief or super-brief syntaxes?

The different levels reflect the expected age and proficiency of the user. A math book geared towards younger users, or users new to the topic, would typically employ the verbose grammar. More advanced users already proficient in math and familiar with the grammar will likely find the verbose syntax a nuisance, so either the brief or super-brief grammars can be employed.

Explanation

Although a benefit of native MathML support in XHTML content documents is the ability to provide voicing based on the markup, user agents capable of such voicings are still not widespread. MathML still presents the most accessible option in user agents that do support it. (Recent testing from the DIAGRAM Center showed that only 7 of 25 EPUB reading systems were capable of rendering MathML markup.)

As MathML rendering support is expected to grow now that it is being re-integrated into the Chrome browser, the best option for providing accessible math equations is to use MathML markup. An alternative text description can be provided in the alttext attribute.

Alternatively, a less robust solution is to provide an image of the math with a sufficiently descriptive alternative text (and extended description for more complex equations). It is not required to include the MathML markup as shown in Example 3, but integrating the native markup can help transition to accessible MathML later when support improves.

Related Links