.. _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.
* :ref:`semantic-enrich-options`
* :ref:`complexity-options`
* :ref:`explorer-options`
* :ref:`assistive-mml-options`
Because the accessibility extensions are controlled by the settings of
the MathJax contextual menu, you may use the :ref:`menu-options` to
control 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: {
assistiveMml: true; // true to enable assitive MathML
collapsible: false; // true to enable collapsible math
explorer: false; // true to enable the expression explorer
}
}
}
};
Note that there is no control for the semantic enrichment *per se*,
but it is enabled automatically by enabling the collapsible math or
the expression explorer.
Although you can load the extensions explicitly using the
:ref:`loader-options`, it is probably better to use the men u options
above, so that if a user turns the extensions off, they will not incur
the network and startup costs of laoding the extensions they will not
be using.
-----
.. _semantic-enrich-options:
Semantic-Enrich Extension 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 two actions to the document's
default :ref:`renderActions <document-renderActions>` object: an
``enrich`` action to perform the semantic enrichment, and an
``attachSpeech`` action to attach speech (if it is being generated) to
the output.
The Configuration Block
-----------------------
.. code-block:: javascript
MathJax = {
options: {
enableEnrichment: true, // false to disable enrichment
sre: {
speech: 'none', // or 'shallow', or 'deep'
domain: 'mathspeak', // speech rules domain
style: 'default', // speech rules style
locale: 'en' // the language to use (en, fr, es, de, it)
},
enrichError: (doc, math, err) => doc.enrichError(doc, math, err), // function to call if enrichment fails
}
};
Option Descriptions
-------------------
.. _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.
This is controlled automatically by the settings of the context
menu, so you should not need to adjust it yourself. You can,
however, use it to disable semantic enrichment if the
`semantic-enrich` component has been loaded automatically and you
don't need that.
.. _semantic-sre:
.. describe:: sre: {...}
This block sets configuration values for the Speech-Rule Engine
(SRE) that underlies MathJax's semantic enrichment features. See
the `SRE documentation
<https://github.com/zorkow/speech-rule-engine/tree/master#options-to-control-speech-output>`__
for more details.
.. _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 defaul tbehavior by providing a function that
does whatever you want, such as recording the error, or replacing
the original MathML with alterntiave MathML contianing an error
message.
.. note::
As of version 3.1.3, the ``enrichSpeech`` option has been renamed
as ``speech`` in the ``sre`` block of the configuration.
-----
.. _complexity-options:
Complexity Extension 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. Use the ``'a11y/complexity'``
block of your MathJax configuration to configure the extension.
The `complexity` extension adds a ``complexity`` action to the
document's default :ref:`renderActions <document-renderActions>`
object.
The Configuration Block
-----------------------
.. code-block:: javascript
MathJax = {
options: {
enableComplexity: true, // set to false to disable complexity computations
makeCollapsible: true // insert mactions to allow collapsing
}
};
Option Descriptions
-------------------
.. _complexity-enableComplexity:
.. describe:: enableComplexity: true
This setting controls whether the `complexity` extension is to run
or not. The value is controlled automatically by the settings of
the context menu, so you should not need to adjust it yourself.
You can, however, use it to disable it 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.
Developer Options
-----------------
.. _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:
Explorer Extension 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.
The Configuration Block
-----------------------
.. code-block:: javascript
MathJax = {
options: {
enableExplorer: true, // set to false to disable the explorer
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
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
}
}
};
Option Descriptions
-------------------
.. _explorer-enableExplorer:
.. describe:: enableExplorer: true
This setting controls whether the `explorer` extension is to run
or not. The value is controlled automatically by the settings of
the context menu, so you should not need to adjust it yourself.
You can, however, use it to disable it if the `explorer`
component has been loaded automatically and you don't need it.
The a11y options belong roughly to one of the following four categories:
Speech Options
^^^^^^^^^^^^^^
.. _explorer-speech:
.. describe:: speech: true
Sets if speech output is produced. By default speech is computed for every
expression on the page and output once the explorer is started.
.. _explorer-braille:
.. describe:: braille: true
Sets whether or not Braille is produced and output for an expression.
.. _explorer-subtitles:
.. describe:: subtitles: true
This option indicates 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 indicates whether Braille output will be displayed under the
expression as it is explored.
.. 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:`semantic-enrich-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.
.. _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.
.. _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 highligher, 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:
Assisitve-MML Extension 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 `assisitive-mml` extension is included in all the combined
components, and is active by default, so screen reader users will not
need to do anything to activate it. There is a menu item that
controls whether to insert the assistive MathML, so visual users can
turn it off if they wish.
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.
.. code-block:: javascript
MathJax = {
options: {
enableAssistiveMml: false
}
};
|-----|