options/accessibility.rst
.. _accessibility-options:
################################ Accessibility Extensions Options ################################
MathJax contains several extensions meant to support those who need
assistive technology, such as screen readers. See the
:ref:accessibility-components page for more details. The options
that control these extensions are listed below.
|btight|
semantic-enrich-optionsspeech-optionscomplexity-optionsexplorer-optionsassistive-mml-options|etight|
Because the accessibility extensions are controlled by the settings of
the MathJax contextual menu, when the :ref:menu-component is loaded,
you use the :ref:menu-options to determine whether they are
enabled or not. There are settings below that can be used to
disable the extensions, in case they are loaded automatically, but
these are not the settings that control whether the extensions
themselves are loaded. That is controlled by the menu settings:
.. code-block:: javascript
MathJax = { options: { menuOptions: { settings: { enrich: true, // true to enable semantic-enrichment collapsible: false, // true to enable collapsible math speech: true, // true to enable speech generation braille: true, // true to enable Braille generation assistiveMml: false, // true to enable assistive MathML } } } };
.. note::
The :data:explorer option has been removed in v4, and is replaced
by the :data:speech and :data:braille options, which determine
whether the explorer is active (either one will activate the
explorer). The semantic-enrichment is controlled by the new
:data:enrich option, and is required for both the complexity
computations and the speech and Braille generation; disabling
enrichment effectively disables nearly all the accessibility tools
at once.
In version 3, the accessibility tools were off and the assistive MathML was on by default, meaning users had to enable to explorer by hand if they wanted to use it. In version 4, the reverse is true: the accessibility extensions are included and enabled in all the combined components, and the assistive MathML is off. This means users will be able to explore expressions immediately without the need to change menu settings.
If you are not using a combined component, you can load the extensions
explicitly using the :ref:loader-options, but it is probably better to
use the menu options above, so that if a user turns the extensions
off, they will not incur the network and startup costs of loading the
extensions they will not be using.
.. note::
In version 4, the MathJax contextual menu has been redesigned to give more prominence to the accessibility tools, and they are now at the top level of the menu rather than hidden in a submenu.
.. _semantic-enrich-options:
This extension coordinates the creation and embedding of semantic
information generated by the enrichment process within the MathJax
output for use by the other extensions. The semantic-enrich
extension adds an enrich action to the document's default
:ref:renderActions <document-renderActions> object.
.. code-block:: javascript
MathJax = { options: { enableEnrichment: true, // false to disable enrichment enrichError: (doc, math, err) => doc.enrichError(doc, math, err), // function to call if enrichment fails } };
.. _semantic-enrich-enableEnrichment: .. describe:: enableEnrichment: true
This setting controls whether semantic enrichment is applied to the
internal MathML representation of the mathematics in the page when
the semantic-enrich extension is loaded. This is controlled
automatically by the settings of the context menu, so you should
use those to control semantic-enrichment if the menu component is
present. If not, you can use it to disable semantic enrichment if
the semantic-enrich component has been loaded automatically and
you don't need it.
.. _semantic-enrich-error: .. describe:: enrichError: (doc, math, err) => doc.enrichError(doc, math, err)
This setting provides a function that gets called when the semantic
enrichment process fails for some reason. The default is to call
the MathDocument's enrichError() method, which simply prints a
warning message in the browser console window. The original
(unenriched) MathML will be used for the output of the expression.
You can override the default behavior by providing a function that
does whatever you want, such as recording the error, or replacing
the original MathML with alternative MathML containing an error
message.
.. note::
In version 3, the semantic-enrich extension handled both
enrichment and speech generation. These two functions have been
separated in version 4, and speech is now processed in the new
speech extension described below. The sre block that was
listed here in v3 has been moved to the speech extension.
.. _speech-options:
This extension coordinates the generation of speech strings Braille
notation that are added to the HTML or SVG nodes within the page where
they can be used by screen readers, or by the
:ref:explorer-component. The speech extension adds an
attachSpeech action to the document's default :ref:renderActions <document-renderActions> object.
.. code-block:: javascript
MathJax = { options: { enableSpeech: true, // false to disable speech strings enableBraille: true, // false to disable Braille notation speechError: (doc, math, err) => doc.speechError(doc, math, err), // called if speech generation fails sre: { domain: 'mathspeak', // speech rules domain style: 'default', // speech rules style locale: 'en' // the language to use (en, fr, es, de, it) }, a11y: { speech: true, // switch on speech output when enabled braille: true, // switch on Braille output when enabled }, worker: { path: 'path-to-bundle/a11y/sre', // full path to bundle/a11y/sre (set automatically) maps: 'path-to-sre/lib/mathmaps', // full path to sre's speech rules worker: 'speech-worker.js', // name of worker script to load as a webworker debug: false, // true to include debugging messages in the browser console about // the communications between the page, worker pool, and workers. }, } };
.. _speech-enableSpeech: .. describe:: enableSpeech: true
This setting controls whether speech strings are generated and
attached to the DOM elements within the page when the speech
extension is loaded. This is controlled automatically by the
settings of the context menu, so you should use those to control
speech generation if the menu component is present. If not, you
can use it to disable speech generation if the speech component
has been loaded automatically and you don't need it.
.. _speech-enableBraille: .. describe:: enableBraille: true
This setting controls whether Braille labels are generated and
attached to the DOM elements within the page when the speech
extension is loaded. This is controlled automatically by the
settings of the context menu, so you should use those to control
Braille labels if the menu component is present. If not, you can
use it to disable Braille generation if the speech component has
been loaded automatically and you don't need it.
.. _speech-error: .. describe:: enrichError: (doc, math, err) => doc.enrichError(doc, math, err)
This setting provides a function that gets called when the speech
or Braille generation fails for some reason. The default is to
call the MathDocument's speechError() method, which simply
prints a warning message in the browser console window. You can
override the default behavior by providing a function that does
whatever you want, such as recording the error.
.. _speech-sre: .. describe:: sre: {...}
This block sets configuration values for the Speech-Rule Engine
(SRE) that underlies MathJax's speech and Braille features. See
the SRE documentation <https://github.com/zorkow/speech-rule-engine/tree/master#options-to-control-speech-output>__
for more details.
.. _speech-a11y: .. describe:: a11y: {...}
This block gives boolean values that essentially duplicate the
:data:enableSpeech and :data:enableBraille values above.
.. _speech-worker: .. describe:: worker: {...}
This block gives parameters that control the speech generation, which is performed using webworkers so that this time-consuming process will not interfere with the responsiveness of the page. You should not need to change these.
.. _complexity-options:
This extension generates a complexity metric and inserts elements that
allow the expressions to be collapsed by the user by clicking on the
expression based on that metric. The complexity extension adds a
complexity action to the document's default :ref:renderActions <document-renderActions> object.
.. code-block:: javascript
MathJax = { options: { enableComplexity: true, // set to false to disable complexity computations makeCollapsible: true // insert mactions to allow collapsing } };
.. _complexity-enableComplexity: .. describe:: enableComplexity: true
This setting controls whether the complexity extension is to run
or not when it is loaded. The value is controlled automatically by
the settings of the context menu, so you should use those to
control the complexity computations if the menu component is
present. If not, you can use it to disable the computations if the
complexity component has been loaded automatically and you don't
need it.
.. _complexity-makeCollapsible: .. describe:: makeCollapsible: true
This setting determines whether the extension will insert
<maction> elements to allow complex expressions to be
"collapsed" so that they take up less space, and produce condensed
speech strings that are simpler to listen to. When false, the
expression is not altered, but elements are marked (internally) if
they would be collapsible.
.. _complexity-identifyCollapsible: .. describe:: identifyCollapsible: true
This setting determines whether the complexity numbers computed for each element in the expression should take collapsing into account. If true, parents of collapsible elements will get complexities that reflect the collapsible elements being collapsed. When false, the complexities assume no collapsing will take place.
.. _complexity-Collapse: .. describe:: Collapse: Collapse
The Collapse object class to use for creating the <maction>
elements needed for collapsing complex expressions. This allows
you to create a subclass of Collapse and pass that to the
document.
.. _complexity-ComplexityVisitor: .. describe:: ComplexityVisitor: ComplexityVisitor
The ComplexityVisitor object class to use for managing the
computations of complexity values. This allows you to create a
subclass of ComplexityVisitor and pass that to the document.
.. _explorer-options:
This extension provides support for interactive exploration of
expressions within the page. See the :ref:accessibility page for
details about how this works.
The explorer extension adds an explorable action to the
document's default :ref:renderActions <document-renderActions>
object.
.. code-block:: javascript
MathJax = { options: { enableExplorer: true, // set to false to disable the explorer enableExplorerHelp: true, // set to false to disable the help icon and dialog a11y: { speech: true, // switch on speech output braille: true, // switch on Braille output subtitles: true, // show speech as a subtitle viewBraille: false, // display Braille output as subtitles help: true, // include "press h for help" messages on focus roleDescription: 'math', // the role description to use for math expressions voicing: false, // switch on speech output
backgroundColor: 'Blue', // color for background of selected sub-expression
backgroundOpacity: .2, // opacity for background of selected sub-expression
foregroundColor: 'Black', // color to use for text of selected sub-expression
foregroundOpacity: 1, // opacity for text of selected sub-expression
highlight: 'None', // type of highlighting for collapsible sub-expressions
flame: false, // color collapsible sub-expressions
hover: false, // show collapsible sub-expression on mouse hovering
treeColoring: false, // tree color expression
magnification: 'None', // type of magnification
magnify: '400%', // percentage of magnification of zoomed expressions
keyMagnifier: false, // switch on magnification via key exploration
mouseMagnifier: false, // switch on magnification via mouse hovering
align: 'top', // placement of magnified expression
infoType: false, // show semantic type on mouse hovering
infoRole: false, // show semantic role on mouse hovering
infoPrefix: false, // show speech prefixes on mouse hovering
}
}
};
.. _explorer-enableExplorer: .. describe:: enableExplorer: true
This setting controls whether the explorer extension is to run or
not when it is loaded. The value is controlled automatically by
the settings of the context menu, so you should use those to
control whether expressions are explorable if the menu component is
present. If not, you can use it to disable the explorer if the
explorer component has been loaded automatically and you don't
need it.
.. _explorer-enableExplorerHelp: .. describe:: enableExplorerHelp: true
This controls whether the small "info" icon is displayed at the
upper right-hand corner of an expression when it is focused.
Setting it to false will prevent the icon from appearing, will
disable the "press H for help" message from being spoken when an
expression is first focused, and disables the help dialog when the
"h" key is pressed during expression exploration. This means that
users of assistive technology will be unable to obtain help on how
to use MathJax's assistive features, so you should not set this to
false if your pages may be viewed by users with accessibility
needs.
The :data:a11y options are all controlled by the MathJax contextual
menu, when the menu component is present, so you should use the
corresponding menu options to set these values in that case. If the
menu component is not loaded, you can use the options below to control
the explorer directly.
The options belong roughly to one of the following four categories:
Speech Options ^^^^^^^^^^^^^^
.. _explorer-speech: .. describe:: speech: true
Determines whether speech output is produced. By default, speech is computed for every expression on the page, and will be voiced by a screen reader when the page is read, or when the explorer is started.
.. _explorer-braille: .. describe:: braille: true
Determines whether Braille output is produced. By default, Braille is computed for every expression on the page, and will be sent to a Braille output device when the page is read, or when the explorer is started.
.. _explorer-subtitles: .. describe:: subtitles: true
This option specifies whether the speech string for the selected sub-expression will be shown as a subtitle under the expression as it is explored.
.. _explorer-viewBraille: .. describe:: viewBraille: false
This option specifies whether Braille output will be displayed under the expression as it is explored.
.. _explorer-help: .. describe:: help: true
This option specifies whether the explorer should voice "press h for help" when an expression becomes focused. This helps new users to realize that help is available, but experienced users may wish to disable this feature.
.. _explorer-roleDescription: .. describe:: roleDescription: 'math'
This option specifies what description should be voiced by screen
readers when reading a MathJax expression; for example, the
expression E = mc^2 might be read as "E equals m c squared,
math". The value to use can be set using the MathJax contextual
menu to one of several options, including no description.
.. _explorer-voicing: .. describe:: voicing: true
This option determines whether MathJax will read expressions using the Browser's voice API during expression exploration. That can be useful for people who are not using a screen reader, but still want to hear the spoken expression.
.. note::
As of version 3.1.3, the speechRules option has been broken
into two separate options, domain and style, in the sre
block of the configuration. See the :ref:speech-options
above for more.
Highlighting Options ^^^^^^^^^^^^^^^^^^^^
.. _explorer-foregroundColor: .. describe:: foregroundColor: 'Black'
This specifies the color to use for the text of the selected
sub-expression during expression exploration. The color should be
chosen from among the following: 'Blue', 'Red',
'Green', 'Yellow', 'Cyan', 'Magenta', 'White',
and 'Black'.
.. _explorer-foregroundOpacity: .. describe:: foregroundOpacity: 1
This indicates the opacity to use for the text of the selected sub-expression, with 1 begin fully opaque, and 0 being totally transparent.
.. _explorer-backgroundColor: .. describe:: backgroundColor: 'Blue'
This specifies the background color to use for the selected
sub-expression during expression exploration. The color should be
chosen from among the following: 'Blue', 'Red',
'Green', 'Yellow', 'Cyan', 'Magenta', 'White',
and 'Black'.
.. _explorer-backgroundOpacity: .. describe:: backgroundOpacity: .2
This indicates the opacity to use for the background color of the selected sub-expression, with 1 begin fully opaque, and 0 being totally transparent.
.. _explorer-highlight: .. describe:: highlight: 'None'
Chooses a particular highlighter for showing collapsible
sub-expressions. Choices are 'None', 'Flame', and 'Hover'.
.. _explorer-flame: .. describe:: flame: false
This flag switches on the Flame highlighter, which permanently highlights collapsible sub-expressions, with successively darkening background for nested collapsible expressions.
.. _explorer-hover: .. describe:: hover: false
This switches on the Hover highlighter that highlights collapsible sub-expression when hovering over them with a the mouse pointer.
Note, that having both 'hover' and 'flame' set to true can lead to
unexpected side-effects.
.. _explorer-treeColoring: .. describe:: treeColoring: false
This setting enables tree coloring, by which expressions are visually distinguished by giving neighbouring symbols different, ideally contrasting foreground colors.
Magnification Options ^^^^^^^^^^^^^^^^^^^^^
.. _explorer-magnification: .. describe:: magnification: 'None'
This option specifies a particular magnifier for enlarging
sub-expressions. Choices are 'None', 'Keyboard', and 'Mouse'.
.. _explorer-magnify: .. describe:: magnify: '400%'
This gives the magnification factor (as a percent) to use for the zoomed sub-expression when zoomed sub-expressions are being displayed during expression exploration. The default is 400%.
.. _explorer-keyMagnifier: .. describe:: keyMagnifier: false
Switches on zooming of sub-expressions during keyboard exploration of an expression.
.. _explorer-mouseMagnifier: .. describe:: mouseMagnifier: false
Switches on zooming of sub-expressions by hovering with the mouse pointer.
Note, using both 'keyMagnifier' and 'mouseMagnifier together can lead
to unwanted side-effect.
.. _explorer-align: .. describe:: align: 'top'
This setting tells where to place the zoomed version of the selected sub-expression, when zoomed sub-expressions are being displayed during expression exploration.
Semantic Info Options ^^^^^^^^^^^^^^^^^^^^^
Semantic information explorers are a feature that displays some semantic information of a sub-expression when hovering over it with the mouse pointer. Note, multiple information explorers work well together.
.. _explorer-infoType: .. describe:: infoType: false
Activates an explorer that investigates the semantic type of sub-expressions. The type is an immutable property of an expression, that is independent of its particular position in a formula. Note, however that types can change depending on subject area of a document.
.. _explorer-infoRole: .. describe:: infoRole: false
Activates an explorer to present the semantic role of a sub-expression, which is dependent on its context in the overall expression.
.. _explorer-infoPrefix: .. describe:: infoPrefix: false
Activates explorer for prefix information, which pertains to the position of
a sub-expression. Examples are 'exponent', 'radicand', etc. These
would also be announced during interactive exploration with speech output.
For more details on these concepts, see also the documentation of the
Speech Rule Engine <https://speechruleengine.org>__.
.. note::
While multiple keyboard-based exploration techniques work well together and can be easily employed simultaneously, switching on multiple mouse-based exploration tools can lead to unexpected interactions of the tools and often unpredictable side effects.
.. _assistive-mml-options:
This extension adds visually hidden MathML to MathJax's output that
can be voiced by some screen readers. See the
:ref:screenreader-support section for more details on how this
works. The extension adds an action to the document's default
:ref:renderActions <document-renderActions> object that does the
MathML insertion. You can disable that by using the following
configuration.
.. note::
In version 3, the assistive-mml extension was included in all
the combined components, and was active by default. That is no
longer the case in v4, where the other accessibility tools are
included and enabled by default. Users who prefer the assistive
MathML can turn off the semantic enrichment (which will disable the
other tools), and turn on the assistive MathML using the MathJax
contextual menu (in the Options submenu in the Accessibility
section of the main menu.
.. code-block:: javascript
MathJax = { options: { enableAssistiveMml: false } };
.. _assistiveMml-enableAssistiveMml: .. describe:: enableAssistiveMml: false
This setting controls whether the assistive-mml extension is to
run or not when it is loaded. The value is controlled
automatically by the settings of the context menu, so when the menu
component is present, you should use those to control whether
assistive MathML is inserted. If the menu is not available, you
can use this option to disable the assistive MathML if the
assistive-mml component has been loaded automatically and you
don't need it.
|-----|