<commit_before># MathJax Accessibility Extensions Documentation

* [Introduction](#introduction)
* [Quick Start](#quick-start)
* [Reader Guide](#reader-guide)
  * [Keyboard Exploration](#keyboard-exploration)
  * [Bookmarklet](#bookmarklet)
* [Configuration and use](#configuration-and-use)
  * [accessibility-menu.js](#accessibility-menu.js)
  * [explorer.js](#explorer.js)
  * [auto-collapse.js](#auto-collapse.js)
  * [collapsible.js](#collapsible.js)
  * [semantic-enrich.js](#semantic-enrich.js)
  * [mathjax-sre.js and its components](#mathjax-sre.js-and-its-components)
  * [Compatibility](#compatibility)
* [Support](#support)
  * [Browser support](#browser-support)
  * [Mobile support](#mobile-support)
  * [MathJax output support](#mathjax-output-support)
  * [Screenreader support](#screenreader-support)
    * [Using the explorer](#using-the-explorer)
    * [Browse and Focus mode](#browse-and-focus-mode)
    * [Missing and excessive voicing](#missing-and-excessive-voicing)
    * [Summary of test results](#summary-of-test-results)
* [Demos](#demos)
* [Videos](#videos)

## Introduction

The MathJax Accessibility Extensions provide several features for enabling accessible rendering of equations. These come in the form of several [MathJax extensions](http://docs.mathjax.org/en/latest/advanced/extension-writing.html):

* `accessibility-menu.js`, a lightweight (<1kb zipped) extension to extend the MathJax Menu with opt-in functionality for assistive features.
* `explorer.js`, an extension that provides speech-text generation as well as expression exploration and highlighting functionality.
* `auto-collapse.js`, an extension that provides a responsive rendering mode that collapses subexpressions to fit equations on smaller screens.
* `collapsible.js`, an extension that adds the ability to collapse expressions based on estimates of the complexity of the expressions and their subexpressions [used by `auto-collapse.js` and `explorer.js`].
* `semantic-enrich.js`, an extension that coordinates between MathJax and `mathjax-sre.js` to enrich MathJax's internal representations with semantic information about the expressions [used by all the extensions above].
* `mathjax-sre.js` (and its components), a custom build of [speech-rule-engine](https://github.com/zorkow/speech-rule-engine/), providing semantic enrichment and speech-text generation.

### Quick start

The easiest way to get started is by adding the Accessibility Menu Extension to your MathJax configuration. This adds very little load to your site while providing your visitors with an accessible opt-in for all features.

Version 2.7.0 included the Accessibility Menu Extension in its combined configuration files, so users of most websites that load MathJax will have access to the new menu automatically.

For MathJax v2.6, you need to load the extensions from a v2.7 distribution.

**Note**. The extensions require MathJax v2.6 or higher. 

To load the Accessibility Menu Extension, you set the custom configuration path and add the extensions to your configuration's `extensions` array, e.g., add

```html
<script type="text/x-mathjax-config">
MathJax.Ajax.config.path["a11y"] = "https://cdnjs.cloudflare.com/ajax/libs/mathjax/extensions/a11y";
MathJax.Hub.Config({
  // ...your configuration options...
  extensions: ["[a11y]/accessibility-menu.js"]
});
</script>
```

**before** you load `MathJax.js` itself.

By default, the Accessibility Menu will not load any of the other extensions, but merely extends the menu with options for users to opt-in to the other extensions.

Of course, you can activate the sub-extensions by loading them directly in the extensions array or by using the `menuSettings` configuration option, e.g.,

```html
<script type="text/x-mathjax-config">
MathJax.Ajax.config.path["a11y"] = "https://cdnjs.cloudflare.com/ajax/libs/mathjax/extensions/a11y";
MathJax.Hub.Config({
  // ...your other configuration options...
  extensions: ["[a11y]/accessibility-menu.js"]
  menuSettings: {
    collapsible: true,
    autocollapse: true,
    explorer: true
  }
});
</script>
```

### Local installation

The MathJax accessibility extensions require a more complex build process than other MathJax extensions. You can download pre-compiled packages from the [GitHub release page](https://github.com/mathjax/MathJax-a11y/releases) or  build your own copy using Grunt, see the [repository's README](https://github.com/mathjax/MathJax-a11y/)).

## Reader Guide

On a site that loads any of the MathJax Accessibility Extensions, you will find three additional items in the "Accessibility" submenu of the MathJax Menu. These items control the respective extensions:

* "Collapsible Math" (toggle)
* "Auto-Collapse" (toggle)
* "Explorer" (submenu)

![MathJax Menu with additional Accessibility Menu options](menu1.png)

If the Explorer Extension is not active, its submenu will only list one toggle "Activate" and a hint that more options will appear in this submenu when the Explorer Extension is active.

![MathJax Menu with inactive Explorer submenu](menu2.png)

If the Explorer Extension is active, you will see a submenu structure exposing all its options:

* Active (toggle)
* (separator)
* Walker (submenu of radio buttons)
  * No Walker
  * Syntax Walker (default)
  * Semantic Walker
* Highlight (submenu of radio buttons)
  * None (default)
  * hover
  * flame
* Background (submenu of radio buttons)
  * Blue (default)
  * Red
  * Green
  * Yellow
  * Cyan
  * Magenta
  * White
  * Black
* Foreground (submenu of radio buttons)
  * Black (default)
  * White
  * Magenta
  * Cyan
  * Yellow
  * Green
  * Red
  * Blue
* (separator)
* Speech Output (toggle)
* Generation (submenu of radio buttons)
  * Eager
  * Mixed
  * Lazy (default)
* (separator)
* MathSpeak Rules
  * Verbose (default)
  * Brief
  * Superbrief
* ChromeVox Rules
  * Verbose
  * Short
  * Alternative

![MathJax Menu with active Explorer submenu](menu3.png)

Let us quickly describe their function:

* "Walker": controls the style of exploration.
* "Highlight": adds a highlight to indicate the complexity measure for subexpressions (especially useful in combination with collapsed expressions)
* "Background/Foreground": set the color for Highlight which is also used when using the walker to explore an expression
* "Speech Output" activates the generation of speech-text in both top-level ARIA labels as well as synchronized speech-text when exploring
* "Generation" determines if the speech output on the outer element provides a short summary, a longer summary or a speech string for the entire expression
* "MathSpeak/ChromeVox Rules": allows you to choose between the different rule sets for speech-text generation.

### Keyboard Exploration

The Explorer's Walker option enables keyboard navigation for exploring sub-expressions simultaneously visually and aurally. The application uses the following keys bindings:

* <kbd>SHIFT+SPACE</kbd>: start application (requires focus)
  * **NOTE:** Depending on the implementation quality of the particular browser/screenreader/OS combination (especially Chrome and IE), users might have to disable screenreader reading modes (e.g., "browse mode" in NVDA, "virtual cursor" in JAWS) before being able to launch the application.
* <kbd>ESC</kbd>: stop application.
  * **NOTE:** When restarted, the application will continue where the user left off.
* <kbd>UP</kbd>/<kbd>DOWN</kbd>: move up or down the sub-expression tree.
  * When moving down, navigation will start at the left-most sub-expression of the level.
  * The application plays an aural indicator (earcon) if the user is at the bottom/top level of the tree.
* <kbd>LEFT</kbd>/<kbd>RIGHT</kbd>: navigate the current level in the sub-expression tree horizontally.
* <kbd>ENTER</kbd>:  switch collapsed state of the current sub-expression and regenerate speech-text to match (e.g., provide summary upon collapsing).
* <kbd>SPACE</kbd>: get positional information, i.e., the current level in the sub-expression tree as well as collapsibility/expandability of the current subexpression.

For information on the keyboard navigation of the Explorer's walker, please see the [configuration section]() and the [support section]() below.

### Bookmarklet

If you encounter a page without the Accessibility extension, you can sideload the extensions via a bookmarklet, e.g., the following would load the Accessibility Menu:

```javascript
if(window.MathJax){
  MathJax.Ajax.config.path["a11y"] = "https://cdn.mathjax.org/mathjax/contrib/a11y";
  MathJax.Ajax.Require("[a11y]/accessibility-menu.js");
}
```

Or simply <a href='javascript:if(window.MathJax){ MathJax.Ajax.config.path["a11y"] = "https://cdn.mathjax.org/mathjax/contrib/a11y"; MathJax.Ajax.Require("[a11y]/accessibility-menu.js"); }'> drag this link to your bookmarks</a>.

## Configuration and Use

### accessibility-menu.js

This extension has no configuration block of its own but is controlled via the MathJax Menu settings. Below are the options in their default setting.

```javascript
menuSettings: {
  collapsible: false,  // true, false
  autocollapse: false, // true, false
  explorer: false      // true, false
}
```

* `collapsible`: if set to `true`, this loads and enables the extension `collapsible.js` (cf. below)
* `autocollapse`: if set to `true`, this loads and enables the extension `auto-collapse.js` (cf. below).
* `explorer`: if set to `true`, this loads and enables the extension `explorer.js` (cf. below).

Note that all of these extensions will trigger a re-rendering of the output as the underlying MathML will be modified to reflect the semantic analysis. This can lead to small changes in visual rendering such as properly matching fence sizes.

### explorer.js

The Explorer extension provides exploration tools for sub-expressions. It is the largest piece of the accessibility extensions.<commit_msg>[docs] update cdn-related URLS Fixes #193<commit_after># MathJax Accessibility Extensions Documentation

* [Introduction](#introduction)
* [Quick Start](#quick-start)
* [Reader Guide](#reader-guide)
  * [Keyboard Exploration](#keyboard-exploration)
  * [Bookmarklet](#bookmarklet)
* [Configuration and use](#configuration-and-use)
  * [accessibility-menu.js](#accessibility-menu.js)
  * [explorer.js](#explorer.js)
  * [auto-collapse.js](#auto-collapse.js)
  * [collapsible.js](#collapsible.js)
  * [semantic-enrich.js](#semantic-enrich.js)
  * [mathjax-sre.js and its components](#mathjax-sre.js-and-its-components)
  * [Compatibility](#compatibility)
* [Support](#support)
  * [Browser support](#browser-support)
  * [Mobile support](#mobile-support)
  * [MathJax output support](#mathjax-output-support)
  * [Screenreader support](#screenreader-support)
    * [Using the explorer](#using-the-explorer)
    * [Browse and Focus mode](#browse-and-focus-mode)
    * [Missing and excessive voicing](#missing-and-excessive-voicing)
    * [Summary of test results](#summary-of-test-results)
* [Demos](#demos)
* [Videos](#videos)

## Introduction

The MathJax Accessibility Extensions provide several features for enabling accessible rendering of equations. These come in the form of several [MathJax extensions](http://docs.mathjax.org/en/latest/advanced/extension-writing.html):

* `accessibility-menu.js`, a lightweight (<1kb zipped) extension to extend the MathJax Menu with opt-in functionality for assistive features.
* `explorer.js`, an extension that provides speech-text generation as well as expression exploration and highlighting functionality.
* `auto-collapse.js`, an extension that provides a responsive rendering mode that collapses subexpressions to fit equations on smaller screens.
* `collapsible.js`, an extension that adds the ability to collapse expressions based on estimates of the complexity of the expressions and their subexpressions [used by `auto-collapse.js` and `explorer.js`].
* `semantic-enrich.js`, an extension that coordinates between MathJax and `mathjax-sre.js` to enrich MathJax's internal representations with semantic information about the expressions [used by all the extensions above].
* `mathjax-sre.js` (and its components), a custom build of [speech-rule-engine](https://github.com/zorkow/speech-rule-engine/), providing semantic enrichment and speech-text generation.

### Quick start

The easiest way to get started is by adding the Accessibility Menu Extension to your MathJax configuration. This adds very little load to your site while providing your visitors with an accessible opt-in for all features.

Version 2.7.0 included the Accessibility Menu Extension in its combined configuration files, so users of most websites that load MathJax will have access to the new menu automatically.

For MathJax v2.6, you need to load the extensions from a v2.7 distribution.

**Note**. The extensions require MathJax v2.6 or higher. 

To load the Accessibility Menu Extension, you set the custom configuration path and add the extensions to your configuration's `extensions` array, e.g., add

```html
<script type="text/x-mathjax-config">
MathJax.Ajax.config.path["a11y"] = "https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/extensions/a11y";
MathJax.Hub.Config({
  // ...your configuration options...
  extensions: ["[a11y]/accessibility-menu.js"]
});
</script>
```

**before** you load `MathJax.js` itself.

By default, the Accessibility Menu will not load any of the other extensions, but merely extends the menu with options for users to opt-in to the other extensions.

Of course, you can activate the sub-extensions by loading them directly in the extensions array or by using the `menuSettings` configuration option, e.g.,

```html
<script type="text/x-mathjax-config">
MathJax.Ajax.config.path["a11y"] = "https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/extensions/a11y";
MathJax.Hub.Config({
  // ...your other configuration options...
  extensions: ["[a11y]/accessibility-menu.js"]
  menuSettings: {
    collapsible: true,
    autocollapse: true,
    explorer: true
  }
});
</script>
```

### Local installation

The MathJax accessibility extensions require a more complex build process than other MathJax extensions. You can download pre-compiled packages from the [GitHub release page](https://github.com/mathjax/MathJax-a11y/releases) or  build your own copy using Grunt, see the [repository's README](https://github.com/mathjax/MathJax-a11y/)).

## Reader Guide

On a site that loads any of the MathJax Accessibility Extensions, you will find three additional items in the "Accessibility" submenu of the MathJax Menu. These items control the respective extensions:

* "Collapsible Math" (toggle)
* "Auto-Collapse" (toggle)
* "Explorer" (submenu)

![MathJax Menu with additional Accessibility Menu options](menu1.png)

If the Explorer Extension is not active, its submenu will only list one toggle "Activate" and a hint that more options will appear in this submenu when the Explorer Extension is active.

![MathJax Menu with inactive Explorer submenu](menu2.png)

If the Explorer Extension is active, you will see a submenu structure exposing all its options:

* Active (toggle)
* (separator)
* Walker (submenu of radio buttons)
  * No Walker
  * Syntax Walker (default)
  * Semantic Walker
* Highlight (submenu of radio buttons)
  * None (default)
  * hover
  * flame
* Background (submenu of radio buttons)
  * Blue (default)
  * Red
  * Green
  * Yellow
  * Cyan
  * Magenta
  * White
  * Black
* Foreground (submenu of radio buttons)
  * Black (default)
  * White
  * Magenta
  * Cyan
  * Yellow
  * Green
  * Red
  * Blue
* (separator)
* Speech Output (toggle)
* Generation (submenu of radio buttons)
  * Eager
  * Mixed
  * Lazy (default)
* (separator)
* MathSpeak Rules
  * Verbose (default)
  * Brief
  * Superbrief
* ChromeVox Rules
  * Verbose
  * Short
  * Alternative

![MathJax Menu with active Explorer submenu](menu3.png)

Let us quickly describe their function:

* "Walker": controls the style of exploration.
* "Highlight": adds a highlight to indicate the complexity measure for subexpressions (especially useful in combination with collapsed expressions)
* "Background/Foreground": set the color for Highlight which is also used when using the walker to explore an expression
* "Speech Output" activates the generation of speech-text in both top-level ARIA labels as well as synchronized speech-text when exploring
* "Generation" determines if the speech output on the outer element provides a short summary, a longer summary or a speech string for the entire expression
* "MathSpeak/ChromeVox Rules": allows you to choose between the different rule sets for speech-text generation.

### Keyboard Exploration

The Explorer's Walker option enables keyboard navigation for exploring sub-expressions simultaneously visually and aurally. The application uses the following keys bindings:

* <kbd>SHIFT+SPACE</kbd>: start application (requires focus)
  * **NOTE:** Depending on the implementation quality of the particular browser/screenreader/OS combination (especially Chrome and IE), users might have to disable screenreader reading modes (e.g., "browse mode" in NVDA, "virtual cursor" in JAWS) before being able to launch the application.
* <kbd>ESC</kbd>: stop application.
  * **NOTE:** When restarted, the application will continue where the user left off.
* <kbd>UP</kbd>/<kbd>DOWN</kbd>: move up or down the sub-expression tree.
  * When moving down, navigation will start at the left-most sub-expression of the level.
  * The application plays an aural indicator (earcon) if the user is at the bottom/top level of the tree.
* <kbd>LEFT</kbd>/<kbd>RIGHT</kbd>: navigate the current level in the sub-expression tree horizontally.
* <kbd>ENTER</kbd>:  switch collapsed state of the current sub-expression and regenerate speech-text to match (e.g., provide summary upon collapsing).
* <kbd>SPACE</kbd>: get positional information, i.e., the current level in the sub-expression tree as well as collapsibility/expandability of the current subexpression.

For information on the keyboard navigation of the Explorer's walker, please see the [configuration section]() and the [support section]() below.

### Bookmarklet

If you encounter a page without the Accessibility extension, you can sideload the extensions via a bookmarklet, e.g., the following would load the Accessibility Menu:

```javascript
if(window.MathJax){
  MathJax.Ajax.config.path["a11y"] = "https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/extensions/a11y";
  MathJax.Ajax.Require("[a11y]/accessibility-menu.js");
}
```

Or simply <a href='javascript:if(window.MathJax){ MathJax.Ajax.config.path["a11y"] = "https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/extensions/a11y"; MathJax.Ajax.Require("[a11y]/accessibility-menu.js"); }'> drag this link to your bookmarks</a>.

## Configuration and Use

### accessibility-menu.js

This extension has no configuration block of its own but is controlled via the MathJax Menu settings. Below are the options in their default setting.

```javascript
menuSettings: {
  collapsible: false,  // true, false
  autocollapse: false, // true, false
  explorer: false      // true, false
}
```

* `collapsible`: if set to `true`, this loads and enables the extension `collapsible.js` (cf. below)
* `autocollapse`: if set to `true`, this loads and enables the extension `auto-collapse.js` (cf. below).
* `explorer`: if set to `true`, this loads and enables the extension `explorer.js` (cf. below).

Note that all of these extensions will trigger a re-rendering of the output as the underlying MathML will be modified to reflect the semantic analysis. This can lead to small changes in visual rendering such as properly matching fence sizes.

### explorer.js

The Explorer extension provides exploration tools for sub-expressions. It is the largest piece of the accessibility extensions.
{'fraction_non_alphanumeric': 0.09965739621120516, 'fraction_numerical': 0.00488714228133817, 'mean_word_length': 4.738363688927436, 'pattern_counts': {'":': 8, '<': 49, '<?xml version=': 0, '>': 47, 'https://': 14, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5765971', 'n_tokens_mistral': 5741, 'n_tokens_neox': 5487, 'n_words': 2194}