Skip to content

Commit 7374822

Browse files
dpvcdpvc
committed
Update accessibility pages
1 parent fcf0d5a commit 7374822

File tree

3 files changed

+408
-295
lines changed

3 files changed

+408
-295
lines changed

‎basic/a11y-extensions.rst‎

Lines changed: 159 additions & 137 deletions
Original file line numberDiff line numberDiff line change
@@ -1,188 +1,180 @@
1-
.. |bkey| raw:: html
2-
3-
<kbd>
4-
5-
.. |ekey| raw:: html
6-
7-
</kbd>
81

9-
.. raw:: html
10-
11-
<style>
12-
kbd {
13-
display: inline-block;
14-
padding: 3px 5px;
15-
font-size: 11px;
16-
line-height: 10px;
17-
color: #444d56;
18-
vertical-align: middle;
19-
background-color: #fafbfc;
20-
border: solid 1px #c6cbd1;
21-
border-bottom-color: #959da5;
22-
border-radius: 3px;
23-
box-shadow: inset 0 -1px 0 #959da5;
24-
}
25-
</style>
26-
<br/>
2+
.. _a11y-extensions:
273

4+
########################
5+
Accessibility Extensions
6+
########################
287

29-
.. _a11y-extensions:
8+
MathJax offers accessibility support via its own built-in extensions
9+
that provide a choice of support options as well as a high degree of
10+
personalization. The extensions can be activated either via the
11+
context menu, which itself is fully accessible, or a page author can
12+
control the default settings using the Mathjax configuration object.
13+
When the menu component is available, configuration should be done
14+
using the :ref:`MathJax menu options <menu-options>`, otherwise use
15+
the :ref:`accessibility options <accessibility-options>`.
3016

31-
#######################
32-
Accessibility Extension
33-
#######################
17+
Most features of the accessibility extensions are based on technology
18+
provided by the `Speech Rule Engine <https://speechruleengine.org>`__,
19+
a powerful tool for enhancing MathML expressions with additional
20+
structural information, and for converting the enriched MathML into
21+
speech text that can be read by a screen reader.
3422

35-
MathJax offers accessibility support via its own built-in extension that
36-
provides a choice of support options as well as a high degree of
37-
personalization. The extension can be activated either via the context menu,
38-
which itself is fully accessible, or by default using configuration
39-
options. Similarly its various features and options are best selected via the
40-
:ref:`MathJax Menu <menu-options>` or programmatically using the
41-
:ref:`accessibility options <accessibility-options>`. We discuss
42-
the different features of the accessibility tool at the hand of the context
43-
menu, roughly in the order in which they appear.
23+
The accessibility features are controlled via the MathJax contextual
24+
menu. In version 3, these were in an `Accessibility` sub-menu, but in
25+
v4, there is a new `Accessibility` section in the main menu, with sub
26+
menus for speech, Braille, the explorer, and other options.
4427

45-
Most features of the Accessibility extensions are based on technology provided by
46-
the `Speech Rule Engine <https://speechruleengine.org>`__. For some more details
47-
and information please also see there.
4828

49-
MathJax's supports the widest selection of browsers, operating systems, and
50-
assistive technologies as they only require the use of well-supported web
51-
standards such as WAI-ARIA, in particular labels and live regions.
29+
.. _explorer-interaction:
5230

5331
Interactive Exploration
5432
=======================
5533

56-
The main feature is an interactive exploration mode that allows a reader to
57-
traverse and explore sub-expressions step-by-step. The explorer is activated in
58-
the context menu by checking the `Activate` item in the `Accessibility`
59-
sub-menu.
34+
The main feature is an interactive exploration mode that allows a
35+
reader to traverse and explore sub-expressions step-by-step.
36+
Expressions typeset by MathJax are focusable, and when the user tabs
37+
to or clicks on an expression, that starts the explorer, either on the
38+
expression as a whole, or on the clicked sub-expression.
39+
Double-clicking starts the explorer at the top level, just like
40+
tabbing.
6041

42+
Exploration of the expression is performed using keyboard commands.
43+
These are described in the :ref:`explorer-commands` section. During
44+
traversal, focused sub-expressions are highlighted and optionally
45+
magnified; an aural rendering is pushed to a screen reader, and a
46+
tactile rendering can be presented on a Braille display, if one is
47+
connected, as described in the next section.
6148

62-
Once a math expression is focused, the explorer can be started by pressing the
63-
|bkey| Enter |ekey| key. The cursor keys then allow traversal of the expression.
49+
The `Explorer` sub-menu controls how the highlighting of the selected
50+
sub-expression is performed. Its `Highlight` sub-menu allows you to
51+
select the background and foreground colors and their opacities.
52+
Several other options are described in the :ref:`explorer-highlighting`
53+
section. The `Magnification` sub-menu is described below in the
54+
:ref:`explorer-zoom` section.
6455

65-
66-
.. toctree::
67-
:maxdepth: 1
68-
69-
Available keyboard commands <explorer-commands>
56+
The `Describe Math as` sub-menu lets you pick the phrase that will be
57+
used when the screen reader voices a typeset expression, while `Help
58+
message on focus` determines whether the "Press H for help" message is
59+
read when the math is first focused.
7060

7161

72-
During traversal, focused sub-expressions are highlighted and optionally
73-
magnified. In addition, an aural rendering is pushed to a screen reader, if one
74-
is available, and a tactile rendering can be read on a Braille display, if one
75-
is connected.
76-
62+
.. _explorer-speech-and-braille:
7763

7864
Speech & Braille Support
7965
========================
8066

81-
Both aural and tactile rendering can be controlled via the options in the
82-
`Speech` sub-menu. `Speech Output` and `Braille Output`, respectively,
83-
control whether or not speech or Braille output is generated. If speech is
84-
generated, it is by default also displayed in `Speech Subtitles`, which can be
85-
switched off and hidden. Braille on the other hand is by default hidden but can
86-
be displayed by switching on the `Braille Subtitles`.
87-
88-
Speech is generally generated with respect to the currently chosen locale (if it
89-
is available). In addition, there are a number of different rule sets that can
90-
be chosen for translating math to text, where each can have a number of
91-
different preferences for how a particular expression is spoken. By default, MathJax
92-
uses the `MathSpeak` rule set in `Verbose` mode; however, the menu allows this
93-
to be changed to either the `ClearSpeak` or `ChromeVox`. Each rule set has
94-
several different preference settings; three in the case of MathSpeak, for example,
95-
which primarily influence the length of produced text. `ClearSpeak
96-
<https://docs.wiris.com/en/mathtype/mathtype_desktop/accessibility/clearspeak>`__
97-
on the other hand has a large number of preferences that allow very fine-tuned
98-
control over how different types of expressions are spoken. The MathJax menu
99-
allows a smart choice of preferences by only displaying the preferences that
100-
are currently relevant for the sub-expression that is currently explored.
101-
The `Select Preferences` option opens a selection box for all possible
102-
ClearSpeak preference choices.
103-
104-
Some rule-set and preference settings can also be controlled by keyboard
105-
commands. This allows the user to have the same expression read in different
106-
variants without having to leave the exploration mode. The |bkey| > |ekey| key
107-
switches rule sets between MathSpeak and ClearSpeak if both are available for
108-
the current locale. The |bkey| < |ekey| key cycles preferences for the currently
109-
active rule set. For ClearSpeak rules, preference cycling depends on the type
110-
of the currently explored sub-expression, similar to smart selection of menu
111-
entries.
11267

113-
The speech language can be adjusted in the `Language` sub-menu in the
114-
`Speech` options. MathJax currently only supports speech in English,
115-
French, German, and Spanish. The only available Braille output is
116-
Nemeth. We are hoping to add more in the future.
68+
Both aural and tactile rendering can be controlled via the options in
69+
the `Speech` and `Braille` sub-menus. The `Generate` item in each
70+
menu tells MathJax whether to include that format in its output, so
71+
you can enable each form separately. The `Show subtitles` item
72+
determines whether the speech and/or Braille are shown on screen below
73+
the expression as it is being explored. This can even help sighted readers
74+
to know how an expression should be pronounced.
75+
76+
The `Speech` sub-menu includes an option for `Auto Voicing` the
77+
expression as it is navigated. When this is selected, the expression
78+
will be read by the browser's speech synthesis API, rather than a
79+
screen reader, and the terms will be highlightes as they are read.
80+
This is useful, for example, for dyslexic users who benefit from the
81+
synchronized highlighting.
82+
83+
There are a number of different rule sets that can be chosen for
84+
translating math to text, where each can have a number of different
85+
preferences for how a particular expression is spoken. By default,
86+
MathJax uses the `ClearSpeak`, however, the `Speech` sub-menu allows
87+
also provides the `MathSpeak` option.
88+
89+
Each rule set has several different preference settings; three in the
90+
case of MathSpeak, for example, which primarily influence the length
91+
of produced text. `ClearSpeak
92+
<https://docs.wiris.com/en/mathtype/mathtype_desktop/accessibility/clearspeak>`__,
93+
on the other hand, has a large number of preferences that allow very
94+
fine-tuned control over how different types of expressions are
95+
spoken. The MathJax menu allows a smart choice of preferences by only
96+
displaying the preferences that are relevant for the sub-expression
97+
that is currently selected. The `Select Preferences` option opens a
98+
selection box for all possible ClearSpeak preference choices.
99+
100+
Some rule-set and preference settings can be controlled by keyboard
101+
commands. This allows the user to have the same expression read in
102+
different variants without having to leave the exploration mode. The
103+
|bkey| > |ekey| key switches rule sets between MathSpeak and
104+
ClearSpeak if both are available for the current locale. The |bkey| <
105+
|ekey| key cycles preferences for the currently active rule set. For
106+
ClearSpeak rules, preference cycling depends on the type of the
107+
currently explored sub-expression, similar to smart selection of menu
108+
entries.
117109

118-
In addition to voicing expressions, the explorer allows for queries on
119-
sub-expression, such as getting positional information with respect to the
120-
context, as well as summaries of the sub-expression currently explored.
110+
The language can be selected via the `Language` sub-menu in the
111+
`Speech` menu. MathJax currently supports speech in more than a dozen
112+
languages, including English, French, German, Hindi, Spanish and
113+
Korean. Braille output is available in two forms: Nemeth and what we
114+
call Eruo Braille. The latter uses 8-dot Braille to represent the
115+
underlying LaTeX expressions, when available, as is currently being
116+
taught in gradeschools in a number of European countries.
117+
118+
In addition to voicing the sub-expressions during exploration, the
119+
explorer allows for queries on sub-expression, such as getting
120+
positional information with respect to the context, as well as
121+
summaries of the sub-expression currently being explored. See the
122+
:ref:`explorer-commands` section for details.
121123

122124

125+
.. _explorer-highlighting:
123126

124-
Abstraction
125-
===========
126-
127-
In addition to textual summaries of expressions, MathJax offers the
128-
possibility to abstract certain sub-expressions so that the entire
129-
sub-expression is visually replaced by a placeholder symbol and
130-
interactive traversal treats it as a single element. This allows the
131-
reader to abstract away details and to better observe the overall
132-
structure of a formula.
133-
134-
Abstraction can be triggered either via mouse click on a collapsible
135-
expression or via pressing the |bkey| Enter |ekey| key during keyboard
136-
exploration. Expressions that can be abstracted can also be discovered
137-
using some of the highlighting features.
138-
139-
140-
Highlight
141-
=========
127+
Highlighting
128+
============
142129

143-
During interactive exploration, the sub-expression that is explorered is
144-
automatically highlighted, by default with a blue background color. The
145-
highlighting can be customized by changing `Background` or `Foreground`
146-
colors in in the `Highlight` sub-menu of the MathJax contextual menu.
147-
In addition, the opacity of both `Background` and `Foreground` can be
148-
adjusted by two slider bars underneath the respective sub-menus.
130+
During interactive exploration, the sub-expression that is being
131+
explorered is automatically highlighted, by default with a blue
132+
background color. The highlighting can be customized by changing
133+
`Background` or `Foreground` colors in in the `Highlight` sub-menu of
134+
the `Explorer` section of the MathJax contextual menu. In addition,
135+
the opacity of both `Background` and `Foreground` can be adjusted by
136+
two slider bars underneath the respective sub-menus.
149137

150138
The `Highlight` sub-menu also provides a choice of highlighters for
151-
marking collapsible sub-expressions: The `Flame` highlighter permanently
152-
colors collapsible sub-expressions while successively darkening the
153-
background for nested collapsible expressions. The `Hover` highlighter
154-
colors each collapsible sub-expression only when hovering over it with
155-
the mouse pointer.
139+
marking collapsible sub-expressions: the `Flame` highlighter
140+
permanently colors collapsible sub-expressions while successively
141+
darkening the background for nested collapsible expressions. The
142+
`Hover` highlighter colors each collapsible sub-expression only when
143+
the mouse pointer is hovering over it.
156144

157145
A final highlighting feature is `Tree Coloring`, in which expressions are
158146
visually distinguished by giving neighbouring symbols different, ideally
159147
contrasting foreground colors.
160148

161149

150+
.. _explorer-zoom:
151+
162152
Magnification
163153
=============
164154

165-
During exploration, the accessibility extension can optionally magnify
166-
the sub-expression that is currently explored. The zoomed version of
167-
the expression is overlaid on the original one when traversing the
155+
During expression exploration, the explorer can optionally magnify the
156+
sub-expression that is currently selected. The zoomed version of the
157+
expression is overlaid above the original one when traversing the
168158
formula. For keyboard exploration, this can be switched on in the
169-
`Magnification` sub-menu by selecting the `Keyboard` option.
159+
`Magnification` sub-menu of the `Explorer` menu by selecting the
160+
`Keyboard` option.
170161

171-
A similar effect can be achieved by exploring an expression with the mouse.
172-
When using the `Mouse` option in the `Magnification` sub-menu, the
173-
sub-expression over which the mouse pointer hovers is zoomed.
162+
A similar effect can be achieved by exploring an expression with the
163+
mouse. When using the `Mouse` option in the `Magnification` sub-menu,
164+
the sub-expression where the mouse is pointering is zoomed.
174165

175166
The zoom factor of the magnification can also be adjusted. The values
176-
available in the context menu are `200%`, `300%`, `400%`, and
177-
`500%`.
167+
available in the context menu are `200%`, `300%`, `400%`, and `500%`.
168+
178169

170+
.. _explorer-semantic-info:
179171

180172
Semantic Info
181173
=============
182174

183175
The `Semantic Info` sub-menu contains a number of options that allow the reader to see
184176
the semantic classifications MathJax applies to a particular sub-expression, by
185-
hovering over it with the mouse pointer. The choices here are
177+
hovering over it with the mouse pointer. The choices here are:
186178

187179

188180
* `Type`
@@ -199,3 +191,33 @@ hovering over it with the mouse pointer. The choices here are
199191
For more details on all of these concepts, see also the documentation of the
200192
`Speech Rule Engine <https://speechruleengine.org>`__.
201193

194+
195+
.. _explorer-collapse:
196+
197+
Collapsible Expressions
198+
=======================
199+
200+
In addition to textual summaries of expressions, MathJax offers the
201+
possibility to abstract certain sub-expressions so that the entire
202+
sub-expression is visually replaced by a placeholder symbol and
203+
interactive traversal treats it as a single element. This allows the
204+
reader to abstract away details and to better observe the overall
205+
structure of a formula.
206+
207+
Sub-expressions can be collapsed in this way either by clicking on
208+
them with the mouse (the pointer should become a "pointing hand" when
209+
that is possible), or by using the explorer to navigate to the
210+
expression and then pressing the |bkey| Enter |ekey| or |bkey| Return
211+
|ekey| key. Clicking or pressing one of the these keys again will
212+
return the expression to its original form. Collapsible expressions
213+
can also be discovered using some of the highlighting features, as
214+
described above.
215+
216+
The ability to collapse sub-expressinos is controlled by the
217+
`Collapsible Math` setting in the `Options` sub-menu of the MathJax
218+
contextual menu. This feature is off by default, but can be selected
219+
by the user, or the default can be changed by the page author using
220+
the :ref:`contextual menu configuration options <menu-options>`.
221+
222+
|-----|
223+

0 commit comments

Comments
 (0)