tsengwoody / Access8Math

Allows access math content written by MathML ; Assist writing math content by LaTeX
GNU General Public License v2.0
32 stars 15 forks source link
nvda-addon

Access8Math Introduction

Access8Math is an NVDA add-on that enhances the user experience when reading and writing mathematical content.

Access8Math offers text-to-speech/Braille functionality for MathML content. MathML is the standard language for describing math structure and content on the web, which enables visually readable math content through a web browser.

Access8Math can also assist in writing and converting LaTeX to MathML. LaTex is a typesetting system which is easy to write and learn. It’s commonly used for representing math formulas.

With Access8Math's reading, writing, and conversion features, visually impaired users can read and write math content with ease. Based on MathML and LaTeX, two common math markups, Access8Math significantly reduces the difficulty of two-way communication between visually impaired and sighted users.

Reading Features Overview

Interaction Features Overview

Writing Features Overview

Access8Math Description

The Access8Math add-on provides comprehensive math content reading and writing capabilities.

Access8Math offers customizable speech and braille output, and an Interactive Mode to access and understand math content. In Interactive Mode, users can read math content in smaller segments, as well as choosing the size of the segments through keyboard shortcuts. In this way, they can understand the structure and hierarchical relationships of long math content more easily.

Access8Math also provides a command menu to make writing LaTeX easier. Instead of memorizing complex LaTeX syntaxes, users can navigate through the command menu to input math markups..

In addition, users can preview their inputs while editing, which helps users to find and fix syntax errors as soon as possible.

Finally, Access8Math converts text and math content written in LaTeX into visually readable HTML files. Since both text and math content can be displayed together visually, it makes math discussion between visually impaired and sighted people more fluid.

MathML Examples

Math contents on Wikipedia are written in MathML:

Access8Math User Guide

Reading Features

Language Setting

Select the language in which the math content in Access8Math will be converted in Settings > Reading. If your language is not supported by the system, see the "Adding a new language" paragraph in the "Localization" section of this document.

Reading Experience Settings

Mathematical Structure Analysis

These rules are designed to enhance the reading experience of commonly used mathematical structures. The system analyzes the content according to the MathML structure and mathematical rules, so that the speech outputs and Braille outputs are more consistent with the mathematical meaning. For example, "x^2" will be read as "square of x" instead of "x super 2".

Enable or disable this functionality by checking the "Analyze mathematical meaning of contents" checkbox in Settings > Reading. Uncheck this option to view the original MathML structure.

This option also changes the given additional information of the mathematical meaning when navigating between math segments in Interactive Mode.

Simplified Speech Outputs

When the system analyzes mathematical rules, it will read them out in a simplified way. If there is only one single item in the math content, it can omit the markups before and after while reading, so that it can be understood more efficiently. For example, "(\frac{1}{2})" will be read as "1 over 2" instead of "fraction with numerator 1 and denominator 2 end fraction".

Enable or disable a simplified rule from the list of checkboxes in Settings > Rules.

Pauses Between Segments

Access8Math reads math content with a pause between items to make the math content easier to understand.

To adjust the pause time between items, set a value from 1 to 100 in Settings > Reading. A smaller value means a shorter pause time and a larger value means a longer pause time.

Math Reader Settings

Select the source of the math reader in Settings > Math Reader.

Customize Math Symbol Speech Outputs and Braille Outputs

In the "Localization" menu, it’s possible to edit the table of math symbols and the table of mathematical rules. For more details, please refer to the "Localization" section of this document.

Interaction Features

How to Activate NVDA Interactive Mode?

For speech-oriented users, it is often preferable to listen to a math equation in smaller segments rather than hearing the whole equation at once. If currently in Browse mode, move the cursor over the math content and press the Space or Enter key.

If not in Browse mode:

  1. Move the review cursor to the location of the math content. By default, the review cursor follows the system caret so the system cursor can be moved to the math content.
  2. Execute the following shortcut: NVDA + Alt + M to interact with the math content.

Once in Interactive Mode, use commands such as the arrow keys to explore an equation. For example, use the left and right arrow to move within an equation, and use the down arrow to explore a segment of the equation.

When finished reading, simply press Esc to return to the document. For more information about reading and navigating in Math Content, see the next section.

Available Keyboard Controls in Access8Math Interactive Mode

Adjust Additional Information for Outputs in Interactive Mode

Writing Features

Access8Math Editor

Access8Math editor allows users to write Markdown documents and add resources (such as images, links, etc.) to the editor’s workspace for referencing them in a document.

When exporting documents, Access8Math editor converts Markdown files into HTML files which displays both the text and the math content. The resources in the document will be archived into the output zip file. This allows the exported HTML file to display various types of contents (such as text, math, images, videos, and audios).

For more information on how to use the import and export features, please refer to the "Import and Export'' section of this document.

Separators

When writing, special characters are used to separate text content from math content. In other words, the content inside the separators is math content written in a specific math markup, while the content outside is general text content.

Category Staring Separator Ending Separator
LaTeX (Parentheses) ( )
LaTeX (Dollar sign) $ $
Nemeth (UEB) _% _:
Nemeth (at) @ @

Note: It’s possible to change the separators used in LaTeX/Nemeth in the Settings > Document.

Mixed Content Examples

Command Gestures (Toggle: NVDA + Alt + C)

Note: Enable or disable command gestures at startup in Settings > Writing. Press NVDA + Alt + C in the editing area to enable or disable the command gesture. The shortcut can be changed in the NVDA input gestures.

Shortcut Gestures (Toggle: NVDA + Alt + S)

When the editing cursor is in the LaTeX block, press A ~ Z or F1 ~ F12 to quickly insert the bound LaTeX, and press Shift + Alphabets, Shift + F1 ~ F12 to read out the bound LaTeX of the shortcut gesture (it’s necessary to set up the shortcut gesture in the LaTeX Command Menu first).

Note: Enable or disable shortcut gestures at startup in Settings > Writing. Press NVDA + Alt + S in the editor to enable or disable shortcut gestures. The shortcut can be changed in the NVDA input gestures.

Greek Alphabets Gestures (Toggle: NVDA + Alt + G)

When the editing cursor is in the LaTeX block, press a letter key to quickly insert the LaTeX markup of the corresponding Greek letter. See the "Appendix" of this document for Alphabet to Greek Alphabet Table.

Editing and Navigating Between Blocks

In Access8Math editor, content separated by separators is treated as different blocks, such as text blocks and math content blocks. The editing cursor can be quickly moved between different blocks using the block navigation.

Take the content "The solution of the quadratic equation (ax^2+bx+c=0) is (x=\frac{-b\pm\sqrt{b^2-4ac}}{2a})" as an example, there are two main math content blocks and two text blocks, which can be labeled as Block A, Block B, Block C and Block D:

Block Navigation Gestures (Toggle: NVDA + Alt + N)

Note: Enable or disable block navigation gestures at startup in Settings > Writing. Press NVDA + Alt + N in the editor to enable or disable block navigation gestures. The shortcut can be changed in the NVDA input gestures.

Block Browse Mode (Toggle: NVDA + Space)

When using the Block Browsing mode, the system will output the mathematical meaning of the content instead of the original math markup of the current block. For example, “(\frac{1}{2}) as a decimal is 0.5” will output as "1 over 2 as a decimal is 0.5" instead of “(\frac{1}{2}) as a decimal is 0.5”.

Use the following gestures to move the editing cursor and enter the Interactive Mode:

Press Shift with the above keys to select the text.

If pressing the following keys only, the editing cursor will jump to the next block of that type. If pressing Shift + the key at the same time, the editing cursor will jump to the previous block of that type:

Use the following gestures to edit the document:

Import and Export

Export a Document

For the “preview” feature in the Access8Math editor's View menu, it allows users to convert the Markdown document to an HTML document for previewing.

The math content in the Markdown document will be converted to MathML, which allows different users to view it easily (visually or through speech or Braille). As for resources (such as images, videos or audios), they will be converted into appropriate HTML elements and reference the correct resource files. Therefore, the output HTML document can display various types of contents.

For the “export” feature in the Access8Math editor's View menu, it allows users to save and share the document. Two types of documents will be exported:

Import a Document

There are two ways to open an Access8Math Document:

Note: Configure whether or not the math objects in the exported HTML are independant blocks with the “HTML Math Display'' setting in Settings > File. This setting will affect whether the math objects are read independently or mixed with normal text when navigating with arrow keys to read the whole line in the Browse Mode.

Virtual Menus

Virtual menus will be presented only as speech and braille outputs. There is no actual visual menu. Select an item in the list by using the up/down arrow. If the menu item has a sub-menu, use the right key to enter the sub-menu; use the left key to exit the sub-menu.

Localisation

Adding a New Language

By clicking this option in the “Localisation” menu, languages that are not originally supported by the system can be added. Once added, the newly added language will appear in the "Settings" > "Reading" > "Language" menu. However, the added language is only a copy of the English language template. The speech and Braille outputs need to be defined through "Symbol Dictionary" and "Math Rules" to achieve customized localization.

Customizing Speech and Braille Outputs for Math Symbols

In the "Tools" > "Access8Math" > "Localization" menu, speech and Braille outputs can be customized. Both speech and Braille outputs are divided into two parts: "Symbol Dictionary" and "Math Rules."

Editing Symbol Dictionary

Access8Math maps specific symbols to corresponding text/ braille outputs through a dictionary file to solve issues where rare symbols cannot be read by speech synthesizers or where symbols have different meanings between mathematical contexts and general text.

For example, "!" means "factorial" in mathematical content, while in general text it represents emotion. By editing the dictionary file, symbols can be mapped to new alternative texts or Braille outputs to update incorrect outputs..

Editing Math Rules

Access8Math establishes corresponding mathematical rules for the MathML structure of commonly used math content. When encountering MathML structures that match the rules, the system will read out and display them according to the content defined in the mathematical rules. The speech outputs and Braille outputs can be customized according to the habits of different regions.

If you are interested in localizing symbol dictionaries and mathematical rules, edit them through these two windows, and use the export function to obtain edited files. Then, you can provide these files to the development team through Access8Math GitHub Pull requests or Email (tsengwoody.tw@gmail.com). We would be happy to include your translation in Access8Math.

Appendix

LaTeX Menu

id latex category order label
matrix2X2 \left [ \begin{matrix} {} &{} \ {} &{} \end{matrix} \right ] 2-dimension 0 matrix (2X2)
matrix3X3 \left [ \begin{matrix} {} &{} &{} \ {} &{} &{} \ {} &{} &{} \end{matrix} \right ] 2-dimension 1 matrix (3X3)
determinant2X2 \left \begin{array} {cc} {} &{} \ {} &{} \end{array} \right 2-dimension 2 determinant (2X2)
determinant3X3 \left \begin{array} {ccc} {} &{} &{} \ {} &{} &{} \ {} &{} &{} \end{array} \right 2-dimension 3 determinant (3X3)
leftarrow \leftarrow arrow 0 left arrow
rightarrow \rightarrow arrow 1 right arrow
leftrightarrow \leftrightarrow arrow 2 left right arrow
uparrow \uparrow arrow 3 up arrow
downarrow \downarrow arrow 4 down arrow
updownarrow \updownarrow arrow 5 up down arrow
dotproduct \cdot calculus 5 dot product
integral \int_{}^{}{} \mathrm d calculus 1 integral
nabla \nabla calculus 2 nabla
partial \partial calculus 4 partial derivative
prime \prime calculus 3 derivative
differential \mathrm{d} calculus 0 differential
combination C_{}^{} combinatorics 0 combination
permutation P_{}^{} combinatorics 1 permutation
combination-with-repetition H_{}^{} combinatorics 2 combination with repetition
unordered-selection U_{}^{} combinatorics 3 unordered selection
frac \frac{}{} common 0 fractions
sqrt \sqrt{} common 1 square root
root \sqrt[]{} common 2 root
sumupdown \sum_{}^{} common 3 summation
vector \vec{} common 4 vector
limit \lim_{{} \to {}} common 5 limit
logarithm \log_{} common 6 logarithm
arc \overset{\frown}{} geometry 0 arc
triangle \triangle{} geometry 1 triangle
angle \angle{} geometry 2 angle
degree ^{\circ} geometry 3 degree
circ \circ geometry 4 circle
parallel \parallel geometry 5 parallel
perp \perp geometry 6 perpendicular
square \square{} geometry 7 square
small-diamond \diamond{} geometry 8 small diamond
large-diamond \Diamond{} geometry 9 large diamond
because \because logic 0 because
therefore \therefore logic 1 therefore
iff \iff logic 2 if and only if
implies \implies logic 3 implies
impliedby \impliedby logic 4 implied by
times \times operator 0 times
div \div operator 1 divide
pm \pm operator 2 plus-minus sign
modulus \bmod operator 3 modulus
overline \overline{} other 0 line segment
overleftrightarrow \overleftrightarrow{} other 1 line
overrightarrow \overrightarrow{} other 2 ray
binom \binom{}{} other 3 binomial coefficient
simultaneous-equations \begin{cases} {} &{} \ {} &{} \end{cases} other 4 simultaneous equations
infty \infty other 5 infty
repeating-decimal 0.\overline{} other 6 repeating decimal
ge \ge relation 0 greater than or equal to
le \le relation 1 less than or equal to
ne \ne relation 2 not equal to
approx \approx relation 3 approximate
cong \cong relation 5 full equal
sim \sim relation 6 similar
doteqdot \doteqdot relation 4 approximately equal to
propto \propto relation 7 proportional to
in \in set 0 belong to
notin \not\in set 1 not belong to
ni \ni set 2 include element
notni \not\ni set 3 not include element
subset \subset set 4 lie in
subsetneqq \subsetneqq set 5 properly lie in
not-subset \not\subset set 6 not lie in
supset \supset set 7 include
supsetneqq \supsetneqq set 8 properly include
not-supset \not\supset set 9 not include
cap \cap set 10 intersection set
cup \cup set 11 union set
setminus \setminus set 12 difference set
complement \complement_{} set 13 complement
emptyset \emptyset set 14 empty set
natural-number \mathbb{N} set 15 natural number
real-number \mathbb{R} set 16 real number
forall \forall set 17 for all
exists \exists set 18 exists
sine \sin{} trigonometric 0 sine
cosine \cos{} trigonometric 1 cosine
tangent \tan{} trigonometric 2 tangent
cotangent \cot{} trigonometric 3 cotangent
secant \sec{} trigonometric 4 secant
cosecant \csc{} trigonometric 5 cosecant
arcsine \arcsin{} trigonometric 6 arcsine
arccosine \arccos{} trigonometric 7 arccosine
arctangent \arctan{} trigonometric 8 arctangent
hyperbolic-sine \sinh{} trigonometric 9 hyperbolic sine
hyperbolic-cosine \cosh{} trigonometric 10 hyperbolic cosine
hyperbolic-tangent \tanh{} trigonometric 11 hyperbolic tangent
hyperbolic-cotangent \coth{} trigonometric 12 hyperbolic cotangent
floor \lfloor \rfloor other 7 floor
ceil \lceil \rceil other 8 ceil

English Alphabets to Greek Alphabets Table

English Alphabet Greek Alphabet LaTeX
a α \alpha
b β \beta
c θ \theta
d δ \delta
e ε \epsilon
f φ \phi
g γ \gamma
h η \eta
i ι \iota
k κ \kappa
l λ \lambda
m μ \mu
n ν \nu
o ο \omicron
p π \pi
r ρ \rho
s σ \sigma
t τ \tau
u υ \upsilon
v φ \psi
w ω \omega
x χ \chi
y ξ \xi
z ζ \zeta

Access8Math update log

Access8Math v4.2 Update

Access8Math v4.1 Update

Access8Math v4.0 Update

Access8Math v3.8 Update

Access8Math v3.7 Update

Access8Math v3.6 Update

Access8Math v3.5 Update

Access8Math v3.4 Update

Access8Math v3.3 Update

Access8Math v3.2 Update

Access8Math v3.1 Update

Access8Math v3.0 Update

Access8Math v2.6 Update

Access8Math v2.5 Update

Access8Math v2.3 Update

Access8Math v2.3 Update

Access8Math v2.2 Update

*fix bug incorrect speech when a single node has more characters.

Access8Math v2.1 Update

Access8Math v2.0 Update

Access8Math v1.5 update log

Access8Math v1.4 update log

Access8Math v1.3 update log

Access8Math v1.2 update log

Access8Math v1.1 update log