Skip to content

Integrate MathCAT into NVDA#18323

Merged
seanbudd merged 205 commits into
nvaccess:masterfrom
RyanMcCleary:mathcat-integration
Nov 17, 2025
Merged

Integrate MathCAT into NVDA#18323
seanbudd merged 205 commits into
nvaccess:masterfrom
RyanMcCleary:mathcat-integration

Conversation

@RyanMcCleary

@RyanMcCleary RyanMcCleary commented Jun 25, 2025

Copy link
Copy Markdown
Contributor

Link to issue number:

Closes #17667.

Summary of the issue:

The MathCAT add-on is not currently included in the core of NVDA. Integrating MathCAT into NVDA will give users access to mathematical content out of the box.

Description of user facing changes:

The core functionality of the add-on will remain the same, but MathCAT will be included without needing to install it as an add-on (replacing mathPlayer). An additional panel will be added in the NVDA preferences dialog containing the configuration that is currently handled in MathCAT's add-on configuration dialog. Additionally, the user docs will be updated to reflect the replacement of mathPlayer with MathCAT.

Description of developer facing changes:

The code from the MathCAT add-on has been refactored and cleaned up to conform to NVDA's coding standards, and that code is included in the mathPres/MathCAT directory with this PR. Dependencies have been added as a Git submodule in include/nvda-mathcat. Before this PR is ready for review, changes will also be made to the way MathCAT is initialized (currently, it is only set up to be loaded as an add-on), and YAML configuration will be replaced with configobj.

Description of development approach:

Developments will proceed in the following steps:

  • Update the initialization of MathCAT so that it is loading and running correctly in its current form.
  • Include MathCAT configuration into the NVDA preferences dialog.
  • Replace YAML configuration with configobj.
  • Add unit and system tests.

Testing strategy:

The add-on code after refactoring has been tested only by loading it into NVDA and testing it functionally. Discussion of more unit and system tests is ongoing.

Known issues with pull request:

  • Previously, libmathcat_py.pyd was included in that MathCAT directory. Now, it is located in include/assets, so it is not being imported correctly. This can be fixed by updating pyproject.toml with the new path.

Code Review Checklist:

  • Documentation:
    • Change log entry
    • User Documentation
    • Developer / Technical Documentation
    • Context sensitive help for GUI changes
  • Testing:
    • Unit tests
    • System (end to end) tests
    • Manual testing
  • UX of all users considered:
    • Speech
    • Braille
    • Low Vision
    • Different web browsers
    • Localization in other languages / culture than English
  • API is compatible with existing add-ons.
  • Security precautions taken.

@coderabbitai summary

@RyanMcCleary RyanMcCleary requested a review from a team as a code owner June 25, 2025 00:40
@RyanMcCleary RyanMcCleary requested a review from seanbudd June 25, 2025 00:40
@RyanMcCleary RyanMcCleary marked this pull request as draft June 25, 2025 00:45
@josephsl

josephsl commented Jun 25, 2025 via email

Copy link
Copy Markdown
Contributor

@AppVeyorBot

Copy link
Copy Markdown

See test results for failed build of commit 28d9c66976

@AppVeyorBot

Copy link
Copy Markdown
  • Build execution time has reached the maximum allowed time for your plan (60 minutes).

See test results for failed build of commit 4298ae7b2f

@AppVeyorBot

Copy link
Copy Markdown
  • Build execution time has reached the maximum allowed time for your plan (60 minutes).

See test results for failed build of commit 7445b8eba5

@AppVeyorBot

Copy link
Copy Markdown
  • Build execution time has reached the maximum allowed time for your plan (60 minutes).

See test results for failed build of commit 9427fd7aa8

@AppVeyorBot

Copy link
Copy Markdown
  • Build execution time has reached the maximum allowed time for your plan (60 minutes).

See test results for failed build of commit 4ba7a139a0

@NSoiffer

NSoiffer commented Nov 7, 2025

Copy link
Copy Markdown
Contributor

@seanbudd wrote:

Can we make 3.13 x64 builds?

Done.

Also, I'll move the highlighting to a new issue.

@seanbudd

seanbudd commented Nov 7, 2025

Copy link
Copy Markdown
Member

@NSoiffer - can you let us know when there's a release with 3.13 builds

@seanbudd seanbudd enabled auto-merge (squash) November 17, 2025 02:37
auto-merge was automatically disabled November 17, 2025 02:45

Head branch was pushed to by a user without write access

@seanbudd seanbudd merged commit 2037d74 into nvaccess:master Nov 17, 2025
41 checks passed
@CyrilleB79

Copy link
Copy Markdown
Contributor

@RyanMcCleary thanks for this work, it will be nice to have MathCAT out of the box.

What happens for people having MathCAT installed as an add-on when upgrading to last alpha?
And for people having another math provider installed (e.g. Access8Math)?

@codeofdusk codeofdusk mentioned this pull request Nov 17, 2025
5 tasks
seanbudd pushed a commit that referenced this pull request Nov 30, 2025
Closes #19014
Summary of the issue:

Since #18323, there has been LaTeX included in the User Guide. However, it was not parsed, just left as source.
Description of user facing changes:

The newly added LaTeX is now parsed to MathML, meaning it may be interacted with using MathCAT, and should be displayed in modern browsers.
Description of developer facing changes:

None
Description of development approach:

    Added l2m4m to as a dependency.
    Added its LaTeX2MathMLExtension to the extensions used when converting the user guide.
    Whitelisted the MathML tags that we currently use in the user guide.
    Allowed the display attribute on <math> tags.
    Added an attribute filter callable that strips the display attribute on <math> tags if its value is inline, as this is redundant.
Comment thread source/localesData.py
LANG_NAMES_TO_LOCALIZED_DESCS: Dict[str, str] = {
LANG_NAMES_TO_LOCALIZED_DESCS: dict[str, str] = {
# Translators: The name of a language supported by NVDA.
"aa": pgettext("languageName", "Afar"),

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@RyanMcCleary, why have all these languages been integrated in this PR?
Contrary to what the comment claims, they are not supported by NVDA. They are not supported by MathCAT either.

Or if they are not useful, could you please remove them?

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Note: Keeping them with for no use just makes more work for translators. Thanks.

@RyanMcCleary RyanMcCleary Dec 8, 2025

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wrote a script using pycountry to generate these language descriptions from the list of language codes in mathPres/MathCAT/localization.py. At the time, I wasn't aware that there was any downside to having more entries than necessary. Would you like me to open another PR to remove the unnecessary entries?

EDIT: I've added more context on how these language descriptions were generated. As @seanbudd mentioned, we got this list of languages from MathCATForPython. From there, we generated the English descriptions (as @NSoiffer mentioned, the original descriptions were already translated).

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's ask NV Access opinion before opening a working on this.
Cc @seanbudd or @SaschaCowley

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@CyrilleB79 - are you sure these are not supported in mathcat? we ripped these lists from a "supported languages" list in mathcat

@NSoiffer - is Cyrille right in saying these are unnecessary in NVDA?

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have not checked but I would be very surprised that MathCAT supports Church Slavic, Manx (language of Isle of Man) or Volapük (an international language created end 19th century less known than Esperanto). Or any language that have been added only 2 or 3 years ago in Google Translate, so not in the most common 130 languages (e.g. Ewe, Bambara, Sardinian).

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah that's frustrating, I don't see most of these languages in https://github.com/NSoiffer/MathCAT/tree/main/Rules/Languages . We migrated this list from https://github.com/NSoiffer/MathCATForPython/blob/9a3ceba991be84404868b391d03e3f6fc2ed561e/addon/globalPlugins/MathCAT/MathCATPreferences.py#L125

I think we can remove these given @NSoiffer 's comment here: #18323 (comment)

Can you create a separate issue/PR?

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Out of curiosity, is there a good reason to make translators translate these language names, rather than just using something like https://pypi.org/project/langcodes?

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Historically, NVDA has translated its language names directly from Windows information. This list only contained language names that Windows could not provide.

Now:

  • I do not know if the languages added here for MathCAT integration have been added here because some Windows platform could not translate them.
  • I do not even know if it has been tried to reduce this list when we dropped compatibility with Windows 7 and then Windows 8.1: it is quite likely that Windows 10 is able to provide more language names than Windows 7 did.

@NSoiffer

NSoiffer commented Dec 8, 2025

Copy link
Copy Markdown
Contributor

Some historical prospective: I have a long list of country codes and names to use in the languages menu. The idea was to get this out of the way. It avoids sync problems in the future where a language is added but it doesn't show up in the menu because the menu entry is "divorced" from the actual translation. MathCAT sees the language Rule directory and adds that to its supported language list. For what I did, that list (dictionary) was pre-translated (e.g., "es": "Español"), so no translator work was needed.

This design is useful for MathCAT translators who can just copy the directory into %APPDATA%/nvda/addons/MathCAT/... and try out there translations before it gets into a release. No need to modify separate python code.

I don't know if this makes sense for when MathCAT is builtin, but it has definitely been useful for MathCAT as an addon.

@SaschaCowley SaschaCowley mentioned this pull request Dec 12, 2025
5 tasks
SaschaCowley added a commit that referenced this pull request Dec 12, 2025
Fixup #18323

### Summary of the issue:

`mathCATDir` is a property of `NVDAState.WritePaths`, even though it is
not writable by non-elevated installed copies, and it doesn't seem like
we even want to write to it.

### Description of user facing changes:

None

### Description of developer facing changes:

`mathCATDir` is now a property of `NVDAState.ReadDirs`.

### Description of development approach:

Moved `mathCATDir` to `NVDAState._ReadDirs`.
Searched for usages of `mathCATDir` in `source/` and updated them.

### Testing strategy:

Ran from source and interacted with MathML in Firefox.

### Known issues with pull request:

None
seanbudd pushed a commit that referenced this pull request Jan 13, 2026
Follow-up of #18323.
Summary of the issue:

Some MathCAT options were unclear and hard to understand.
Description of how this pull request fixes the issue:

Cleanup UI and documentation.
Testing strategy:

Tested that settings changes appear as expected. Alpha testing.
seanbudd pushed a commit that referenced this pull request Jan 22, 2026
Summary of the issue:

When MathCAT has been integrated in NVDA (#18323), many translatable language names have been added. These language names are not used by MathCAT, nor by NVDA itself. Thus this addition only represents extra work for translators and unused code in the code base.
Description of user facing changes:

N/A
Description of developer facing changes:

No more unused languages to translate.
Description of development approach:

    Removed the languages added in Integrate MathCAT into NVDA #18323.
    Kept the most modern annotation style done in the same file.
SaschaCowley added a commit that referenced this pull request Feb 18, 2026
Follow-up to #18323, #19373 and #19613

### Summary of the issue:

Since the introduction of MathCAT into NVDA in #18323, NVDA has
persisted MathCAT settings to a YAML file . This is at odds with current
project configuration standards, which use either configobj ini files,
or JSON. This also duplicates settings, as they're also saved to
`nvda.ini`.
Originally, these were stored in `%AppData%\MathCAT\prefs.yaml`, but as
of #19373, they are saved to `mathcat.yaml` in NVDA's config directory.
In neither case was `shouldWriteToDisk` checked before saving the
preferences. Additionaly, [NV Access's Corporate & Government
page](https://www.nvaccess.org/corporate-government/) states "To prevent
NVDA users from modifying their configuration or add-ons directly, user
write access to [`%APPDATA%\nvda`] must also be restricted". If
implemented, this would have stopped users from changing their MathCAT
settings in memory, as they had to be saved to YAML to be loaded by
MathCAT.
In #19613, the logic was changed to programmatically apply these
settings with `libmathcat.SetPreference`, which should solve the problem
of users without write access to their NVDA config directory being able
to change their MathCAT preferences. However, the code that wrote the
settings to the YAML file was not removed, nor did it contain any error
handling.

### Description of user facing changes:

None, but may avoid some errors in the logs.

### Description of developer facing changes:

Pyyaml is no-longer a dependency.
`mathPres.MathCAT.preferences.MathCATUserPreferences.save` has been
renamed to `apply`, and no longer saves the settings to YAML. Settings
persistance is handled by NVDA's configuration system.

### Description of development approach:

Removed the code that wrote MathCAT preferences to YAML, and any code
that only it depended on. Renamed `save` to `apply` using VS Code's
refactoring tool. Searched the repo for `yaml` and after confirming that
we don't rely on `pyyaml` anywhere else, ran `uv remove pyyaml`.

### Testing strategy:

Tested by loading the [Wikipedia page on the quadratic
formula](https://en.wikipedia.org/wiki/Quadratic_formula) in firefox.
Located some math and read it. Changed settings one at a time and tested
that they were applied correctly. Restarted NVDA and ensured that the
new settings were still present.

### Known issues with pull request:

None known
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

conceptApproved Similar 'triaged' for issues, PR accepted in theory, implementation needs review. release/blocking this issue blocks the milestone release

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Version 2025.1.2 does not read the “Formula” tag. MathML is ignored by NVDA by default