Document Accessibility

---

MathJax, Semantics and Accessibility

Overview

• Rendering Mathematics on the Web
• A quick intro to MathJax
  • using and configuring
  • porting TeX features
• Math Accessibility
  • Basic features
  • Customisation
• Semantics

Understanding MathJax

• MathJax is a JavaScript library for rendering Mathematics in all browsers
• Can take LaTeX, AsciiMath, and MathML as input
• Generates browser output, e.g. HTML/CSS, SVG
• De facto rendering solution of (nearly) all Mathematics on the web
• Provides accessibility extension
• MathJax IS NOT MathML!

There are other rendering solutions out there: KaTeX, MathQuill, MathLive

Including MathJax

When running pandoc or make4ht with the appropriate options MathJax is generally included. If not, it is easy to add a script tag to the header of the HTML file:

<script type="text/javascript" id="MathJax-script" async
  src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js">
</script>

This loads a basic configuration, which finds LaTeX and MathML code in the page and translates it into HTML with CSS styling.

MathJax still might need some costomization.

Revisiting the Example

• Translate with pandoc or with make4ht

pandoc rademacher.tex -o rademacher.html --standalone --mathjax

make4ht rademacher.tex "mathjax"

This now should give nicely rendered math. The results are also available here:

• make4ht output
• pandoc output

Configuring MathJax

Configuration element can be added in script tag before MathJax is loaded.

Basic configuration

<script>
MathJax = {
  tex: {
    inlineMath: [['$', '$'], ['\\(', '\\)']]
  }
}
</scrip>

This allows the use of $ signs for inline mathematics.

See MathJax Documentation at http://docs.mathjax.org/ for details

Configuration example with Macros

• Adding macros is often important

MathJax = {
  tex: {
    inlineMath: [['$', '$'], ['\\(', '\\)']],
    macros: {
      RR: "{\\bf R}",
      bold: ["{\\bf #1}", 1]
    }
  }
}

A Macro Example

Download the example file

\documentclass{article}

\begin{document}

\section{Slash command}

\[A\slash B\]

\end{document}

Note that \slash is a new macro.

Translate the File

• Translate with pandoc

    pandoc slash.tex -o slash.html --standalone --mathjax

or with make4ht

make4ht slash.tex "mathjax"

• The \slash macro will lead to incorrect output in the browser.
• There are two ways to get rid of the slash problem.

1. Define the macro via a \newcommand as you would in the preamble of you LaTeX file.
2. Give it to MathJax in its configuration.

Using newcommand

• Edit the html file directly in a text editor (i.e., not in Word).

1. Add an invisible div with the \newcommand code before the first call of the macro:

    <div style="display:none">\(\newcommand{\slash}{\backslash}\)</div>

Note, that I gave the div a style that makes sure it is not displayed. Generally it is not necessary, but might make sense to avoid visual output in case there is an error in your macro definition.

Add macro to the configuration

2. Add the following code into your slash.html file, before the script tag loading MathJax.

    <script>
    MathJax = {
        tex: {
            macros: {
                slash: "\\backslash"
                }
            }
        }
    </script>

Make sure it is before the script tag that loads MathJax!

Difference between pandoc and make4ht

pandoc

• Include minimal MathJax configuration
• Tries to destructure macros as much as possible
• But that only works for simple macros

make4ht

• Includes complex MathJax configuration
• Loads packages explicitly
• Does not touch macros at all
• E.g., the newcommand is only available in the newcommand package
• We will observe that for the next command

Adding a New Environment

• Similar to adding macros via newcommand, we can add new environment via newenvironment
• Example:

\[
    \newenvironment{braced}{\left\{}{\right\}}
    \begin{braced}
        x = \frac{-b \pm \sqrt{b^2-4ac}}{2a}
    \end{braced}
\]

$$ \newenvironment{braced}{\left{}{\right}} \begin{braced} x = \frac{-b \pm \sqrt{b^2-4ac}}{2a} \end{braced} $$

• Make sure the newenvironment is in Math mode, otherwise MathJax cannot see it
• The the next MathJax version there will also be a configuration option for environment similar to macros:

MathJax = {
    tex: {
        environments: {
          braced: ["\\left\\{", "\\right\\}"]
        }
      }
    };

make4ht configuration

<script>
  window.MathJax = { 
      tex: { 
          tags: "ams", 
          inlineMath: [ ["\\\(","\\\)"] ], 
          displayMath: [ ['$$','$$'], ["\\[","\\]"] ], 
          processEscapes: true, 
          processEnvironments: true, 
          packages: ['base', 'color', 'ams'] }, 
          loader: { load: ['[tex]/color', '[tex]/ams'] 
          } 
  };
</script> 

We need to add newcommand to the packages list and ensure it is loaded:

          packages: ['base', 'color', 'ams', 'newcommand'] }, 
          loader: { load: ['[tex]/color', '[tex]/ams', '[tex]/newcommand'] 

Accessibility

Math rendered with MathJax is pretty much accessible out of the box

• MathJax has its own accessiblity extension
• In addition: Some screen readers detect it and make it accessible

Example: Interactivity and Screenreading

• Listen to the quadratic formula $$ x = \frac{-b \pm \sqrt{b^2-4ac}}{2a} $$
• Source in LaTeX
• Rendered with MathJax
  • Javascript library for rendering LaTeX, AsciiMath, MathML in all browsers
  • One extra line of HTML
• Accessibility "built-in"

Compute Speech

• Enrich Math using Speech Rule Engine
• Javascript library for translating XML into Speech (markup)
• Open source library available at github
• Only Math speech solution in JavaScript
• Runs in browser, command line, as node module.
• Initially implemented in the context of ChromeVox
• Speech solution for: ChromeVox, MathJax, EquatIO, MathLive, ...

Switching on Speech output

Speech output can be switched on via:

• MathJax context menu
  • Press activate
  • This will switch on basic speech output
  • Enable further customisation option in the menu
• Alternatively we can use configuration options

Forcing Speech output on a page

Add the following configuration in your example file or add the option part to the existing configuration.

MathJax = {
    options: {
      menuOptions: {
        settings: {
          explorer: true
        }
      }
   }
}

Note, that user selected options always overwrite developer selected options Note also, that in future version accessibility will be provided by default.

Alternative Formats for Math

• Tactile output, Abstraction, Summaries $$ \vec{\nabla} \times \vec{F} = \left( \frac{\partial F_z}{\partial y} - \frac{\partial F_y}{\partial z} \right) \mathbf{i} + \left( \frac{\partial F_x}{\partial z} - \frac{\partial F_z}{\partial x} \right) \mathbf{j} + \left( \frac{\partial F_y}{\partial x} - \frac{\partial F_x}{\partial y} \right) \mathbf{k} $$

Other Formats:

• General E-books, Epub3, etc.
• 3D printing and embossing
• Fulltext translation to Braille, e.g., PreText to Nemeth
• But also computational elements for JupyterLab, Sage, R, Maple, MatLab
• Subtitling, e.g., via automatic text generation

Customising Accessibility

There are multiple ways to customise accessibility

• Easiest way is via the context menu
• Providing configuration options on the page
• More elaborate programmatically via renderActions

We will look at configurations.

A11y Configuration

Add the following to the options block in your example file:

MathJax = {
  options: {
    renderActions: {
      addMenu: [0, '', '']
    },
    menuOptions: {
      settings: {
        explorer: true
      }
    },
    a11y: {
      backgroundColor: 'Green',
      braille: true,
      viewBraille: true
    }
  }
};

Reload the page. What can you observe?

Semantics

• Accessibility requires one or multiple alternative views
• Achieve this by adding semantic layers
• For regular text semantics is quite straight forward
• Semantics for math is quite different from its syntax
• In particular navigation has to be meaningful

Generate Semantics

• Math markup (e.g., LaTeX, MathML) are not very expressive

    ax^2+bx+c=0

<math>
  <mi>a</mi>
  <msup>
    <mi>x</mi>
    <mn>2</mn>
  </msup>
  <mo>+</mo>
  <mi>b</mi>
  <mi>x</mi>
  <mo>+</mo>
  <mi>c</mi>
  <mo>=</mo>
  <mn>0</mn>
</math>

Embedding Semantics

• SRE reinterprets the syntax
• Fully disassembles the symbol structure
• Reassembles a semantic intepretation bottom-up
• Applies a number of (partially selectable) heuristics
• Rewrite

<math><mi>a</mi><msup><mi>x</mi><mn>2</mn></msup>
  <mo>+</mo><mi>b</mi><mi>x</mi><mo>+</mo><mi>c</mi>
  <mo>=</mo><mn>0</mn></math>

internally into semantically improved term structure

Outlook

• Some general Math document issues
• Dive deeper into Semantics