.. _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 assistive 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 loading 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 default tbehavior by providing a function that
   does whatever you want, such as recording the error, or replacing
   the original MathML with alterntiave MathML containing 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 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:

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
     }
   };


|-----|