Update to include v4.1 options, accessibility changes, and other fixes

Author: dpvc

advanced/model.rst

@@ -20,13 +20,13 @@ processors are called `jax`, and are described in more detail
 below.
 
 When MathJax runs, it looks through the page for special markers that
-delimit/indicate mathematics; for each such marker, it locates an
-appropriate input jax, which it uses to convert the mathematics into
-an internal form (a MathML tree as javascript objects), and then calls
-an output jax to transform the internal format into HTML content that
-displays the mathematics within the page.  The page author configures
-MathJax by indicating which input and output jax are to be used, and
-which extensions should be included.
+indicate mathematics; for each such marker, it locates an appropriate
+input jax, which it uses to convert the mathematics into an internal
+form (a MathML tree as javascript objects), and then calls an output
+jax to transform the internal format into HTML content that displays
+the mathematics within the page.  The page author configures MathJax
+by indicating which input and output jax are to be used, and which
+extensions should be included.
 
 While MathML notation is an XML format that consists of tags like
 those that make up the HTML language, it is not a format that is easy

basic/accessibility.rst

@@ -68,12 +68,24 @@ browser/os/screen-reader combinations to ensure that the user
 experience is an seamless as possible.
 
 In version 4, the extensions for generating speech and exploring
-expressions are included an enabled in all the :ref:`combined
+expressions are included and enabled in all the :ref:`combined
 components <combined-components>` so that your pages should be
 accessible to users with screen or Braille readers automatically in
 that case. (In version 3, the user had to activate the accessibility
 features to turn them on.)
 
+.. note::
+
+   Support for tactile Braille output devices varies across screen
+   readers, operative systems, and browsers.  Users of Braille output
+   devices may need to select the "Combine with Speech" option in the
+   MathJax contextual menu's Braille submenu in order to obtain Nemeth
+   or Euro Braille output rather than the speech text on their Braille
+   device (this can also be accomplished by pressing the |bkey| b
+   |ekey| key while exploring an expression interactively).  NVDA
+   users in Windows will want to do this, though JAWS users should be
+   fine with the default settings.
+
 If you are making a custom configuration, you can include ``ui/menu``
 to enable the contextual menu, or you can include any of the
 :ref:`a11y extensions <accessibility-components>` explicitly.  In
@@ -90,8 +102,8 @@ configure the extensions.
    in the combined components.  That is no longer the case in v4,
    which now uses the speech and explorer components instead.  Users
    can still use the MathJax contextual menu to turn on the hidden
-   MathML and turn off the semantic enrichment that underlies the
-   speech and explorer components if they want to have a similar
+   MathML, which will turn off the speech and Braille generation that
+   underlies the explorer component, if they want to have a similar
    experience to the one from v3.
 
 
@@ -104,16 +116,19 @@ Screen reader support in Mathjax v3 was based on the
 :ref:`assistive-mml-component` component, which embedded a MathML
 representation of each expression that was visually hidden, but
 available to screen readers, in addition to its typeset version that
-was visible for sighted users, but hidden from screen readers.
-The quality of MathML support in screenreaders varies greatly, with
+was visible for sighted users, but hidden from screen readers.  The
+quality of MathML support in screenreaders varies greatly, with
 different levels of MathML feature support, different speech rule
 sets, and different voicing technologies.
 
-This approach only worked with those screen readers that understand
-MathML, and even then, the experience was different depending on the
-screen reader and browser that was being used.  As screen-reader and
-browser versions changed, they sometimes failed to work properly with
-the hidden MathML, and it was difficult to maintain this feature.
+Using hidden MAthML only worked with those screen readers that
+understand MathML, and even then, the experience was different
+depending on the screen reader and browser that was being used.  As
+screen-reader and browser versions changed, they sometimes failed to
+work properly with the hidden MathML; for example, some screen readers
+skip the math entirely when reading the page as a whole, even when
+they voice the math while stepping through the page in smaller units.
+This makes it difficult to maintain this feature.
 
 In version 4, screen reader support is now being handled through the
 :ref:`explorer-component` and :ref:`speech-component` components of

basic/explorer-commands.rst

@@ -106,6 +106,13 @@ Advanced Keys
     without a screen reader.  This mode remains in effect until turned
     off.  It can also be controlled via the MathJax contextual menu.
 
+|bkey| B |ekey|
+    Toggle the "Combine with Speech" menu item, which tells MathJax
+    whether to include the Braille rendering within the
+    :attr:`aria-label` attribute along with the speech text or whether
+    to put it in the :attr:`aria-braillelabel` attribute.  See the
+    notes below.
+
 |bkey| D |ekey|
     Get positional information; i.e., the current level in the
     sub-expression tree as well as collapsibility/expandability of the
@@ -179,4 +186,17 @@ manually when you are done exploring the expression.  How that is done
 depends on the screen reader, so consult the reader's documentation
 for details on how to accomplish that.
 
+For users of tactile Braille devices, MathJax handles the Braille
+notation using the :attr:`aria-braillelabel` attribute (part of the
+ARIA specification), but not all screen readers process this attribute
+properly.  To help accommodate this limitation, MathJax provides an
+option that will put the Braille into the :attr:`aria-label` attribute
+instead, along with the generated speech, as some screen readers will
+pass the Braille on to the Braille device that way.  NVDA users will
+want to enable this feature, for example.
+
+This feature can be enabled by selecting the "Combine with Speech"
+item in the Braille submenu of the MathJax contextual menu, or by
+pressing the |bkey| b |ekey| key while exploring an expression.
+
 |-----|

options/accessibility.rst

@@ -341,6 +341,7 @@ The Configuration Block
    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
@@ -388,6 +389,20 @@ Option Descriptions
    `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

options/output/index.rst

@@ -55,6 +55,7 @@ The options are given here with their default values.
         },
         font: '',                      // the font component to load
         fontPath: FONTPATH,            // The path to the font definitions
+        fontExtensions: [],            // The font extensions to load
         htmlHDW: 'auto',               // 'use', 'force', or 'ignore' data-mjx-hdw attributes
         preFilters: [],                // A list of pre-filters to add to the output jax
         postFilters: [],               // A list of post-filters to add to the output jax
@@ -284,6 +285,13 @@ Option Descriptions
    in node applications.  Any occurrences of ``%%FONT%%`` in the path
    will be replaced by the font name when the font is accessed.
 
+.. _output-fontExtensions:
+.. describe:: fontExtensions: []
+
+   This gives a list of font extensions to load when the output jax is
+   loaded.  For example, setting this to ``['mathjax-euler']`` would
+   load the euler font extension.
+
 .. _output-htmlHDW:
 .. describe:: htmlHDW: 'auto'
 

options/startup/loader.rst

@@ -27,7 +27,12 @@ In the example below, :data:`Loader` represents the
         failed: function (error) {                   // function to call if a component fails to load
           console.log(`MathJax(${error.package || '?'}): ${error.message}`);
         },
-        paths: {mathjax: Loader.getRoot()},          // the path prefixes for use in specifying components
+        paths: {                                     // the path prefixes for use in specifying components
+          mathjax: Loader.getRoot(),
+          fonts: (typeof window === 'undefined'
+                   ? '@mathjax'
+                   : 'https:cdn.jsdelivr.net/npm/@mathjax')
+        },
         source: {},                                  // the URLs for components, when defaults aren't right
         dependencies: {},                            // arrays of dependencies for each component
         provides: {},                                // components provided by each component
@@ -75,7 +80,7 @@ Option Descriptions
    section below for how to trap individual component errors.
 
 .. _loader-paths:
-.. describe:: paths: {mathjax: Loader.getRoot()}
+.. describe:: paths: {mathjax: Loader.getRoot(), fonts: ...}
 
    This object links path prefixes to their actual locations.  By
    default, the ``mathjax`` prefix is predefined to be the location
@@ -85,11 +90,22 @@ Option Descriptions
    prefix.  For example, ``input/tex`` will become
    ``[mathjax]/input/jax`` automatically.
 
+   The ``fonts`` path is predefined to point to the location where
+   MathJax will load fonts.  For node applications, it is set to
+   ``@mathjax`` so that fonts are taken from the
+   ``node_modules/@mathjax`` directory.  For web applications, it is
+   set to ``https://cdn.jsdelivr.net/npm/@mathjax`` so that fonts are
+   loaded from that CDN.
+
    When the TeX :ref:`tex-require` extension is loaded, an additional
    ``tex`` path is created in order to be able to load the various TeX
-   extensions.
+   extensions.  Other paths that may be predefined include ``sre`` and
+   ``mathmaps`` for the locations of the speech-rule-engine files,
+   ``mml`` for MathML extensions, and font-specific paths like
+   ``mathjax-newcm`` for the locations of the files needed by the
+   fonts.
 
-   You can define your own prefixes, for example,
+   You can define your own prefixes; for example,
 
    .. code-block:: javascript
 
@@ -100,10 +116,10 @@ Option Descriptions
         }
       };
 
-   which defines a ``custom`` prefix that you can used to access
-   custom extensions.  The URL can even be to a different server than
-   where you loaded the main MathJax code, so you can host your own
-   custom extensions and still use a CDN for the main MathJax code.
+   defines a ``custom`` prefix that you can used to access custom
+   extensions.  The URL can even be to a different server than where
+   you loaded the main MathJax code, so you can host your own custom
+   extensions and still use a CDN for the main MathJax code.
 
    You can define as many different paths as you need.  Note that
    paths can refer to other paths, so you could do

options/startup/startup.rst

@@ -32,7 +32,9 @@ In the example below, :data:`Startup` represents the
         input: [],               // The names of the input jax to use from among those loaded
         output: null,            // The name for the output jax to use from among those loaded
         handler: null,           // The name of the handler to register from among those loaded
-        adaptor: null            // The name for the DOM adaptor to use from among those loaded
+        adaptor: null,           // The name for the DOM adaptor to use from among those loaded
+        polyfillHasOwn: true,    // True if a polyfill for Object.hasOwn should be used when
+                                 //   it is not available natively
       }
     };
 
@@ -149,4 +151,14 @@ Option Descriptions
    do, it will set this value so that it will be used automatically.
    There are several other DOM adaptors for use in `node`, as well.
 
+.. _startup-polyfillHasOwn:
+.. describe:: polyfillHasOwn: true
+
+   This indicates whether MathJax should provide a polyfill for the
+   :meth:`Object.hasOwn()` method when it is not available natively in
+   the browser.  It is defined in all modern browsers, but some
+   browsers that are several years old may not have an implementation
+   for it, so MathJax will provide one when needed unless this option
+   is set to ``false``.
+
 |-----|

output/fonts.rst

@@ -64,27 +64,50 @@ font via
 
    npm install @mathjax/mathjax-stix2-font
 
-(add ``-font`` to the name of whichever font you want, and obtain it
-from the ``@mathjax`` scope); MathJax should find the font in your
-:file:`node_modules/@mathjax` folder.  It is also possible to
-configure the path to the fonts using the :data:`fontPath` option of
-the :data:`output` block.  This should be set to a string that
-indicates where the font can be found; that string should include
-``%%FONT%%`` in any part of the path where the font name needs to
-appear.  For example,
+(add ``-font`` to the name of whichever font you want, or
+``-font-extension`` for a font extension, and obtain it from the
+``@mathjax`` scope); MathJax should find the font in your
+:file:`node_modules/@mathjax` folder.
+
+By default, MathJax components use the predefined ``fonts`` path to
+locate the fonts.  That is, when the font is specified as
+``mathjax-stix2``, for example, MathJax will use
+``[fonts]/mathjax-stix2-font`` as the path to the font.  This path is
+set to ``https://cdn.jsdelivr.net/npm/@mathjax`` for web applications
+and ``@mathjax`` for node applications.  If you host your own copy of
+MathJax and its fonts, you can set this path to the location where the
+fonts are stored.  For example,
+
+.. code-block:: javascript
+
+    MathJax = {
+      loader: {
+        paths: {
+          font: '/mathjax-fonts',
+      }
+    };
+
+would tell MathJax to obtain fonts from the top-level
+``mathjax-fonts`` directory on the server where web page came from.
+
+It is also possible to configure the path to the fonts using the
+:data:`fontPath` option of the :data:`output` block.  This should be
+set to a string that indicates where the font can be found; that
+string should include ``%%FONT%%`` in any part of the path where the
+font name needs to appear.  For example,
 
 .. code-block:: javascript
 
     MathJax = {
       output: {
-        fontPath: '@mathjax/%%FONT%%-font'
+        fontPath: '[fonts]/%%FONT%%-font'
       }
     };
 
-is the default path in node applications.
+is the default path for MathJax components.
 
-It is also possible to specify an explicit URL as the font name in the
-configuration:
+Finally, you can specify an explicit URL to a font as the font name in
+the configuration:
 
 .. code-block:: javascript
 
@@ -144,15 +167,15 @@ a separate *pseudo-variant* used internally by MathJax, so are
 available only through the macros provided by the corresponding TeX
 extension.
 
-For ``mathjax-euler``, configure MathJax to load the given extension.
-For example,
+For ``mathjax-euler``, configure MathJax to load the given extension
+using the :data:`fontExtensions` array of the :data:`output` block of
+your configuration.  For example,
 
 .. code-block:: javascript
 
    MathJax = {
-     loader: {
-       paths: {font: 'https://cdn.jsdelivr.net/npm/@mathjax'},
-       load: ['[font]/mathjax-euler-font']
+     output: {
+       fontExtensions: ['mathjax-euler']
      }
    };
 

upgrading/earlier/whats-new-2.0.rst

@@ -26,7 +26,7 @@ recommended).
 
 
 Reduced flickering during typesetting
-====================================
+=====================================
 
 In the past, each expression was displayed as soon as it was typeset,
 which caused a lot of visual flickering as MathJax processed the page.