User guide: Update the section on reading math to recommend MathCAT, and also clarify some information about MathPlayer.

[michaelDCurran]

Link to issue number:

Fixes #16036
Fixes #15352

Summary of the issue:

When reading the section of the User guide about Math support, and then the MathPlayer page from Wiris, it is unclear as to whether MathPlayer is actually needed for NvDA unless you are using an older browser such as Internet Explorer 8.
Also, Nthe User Guide does not recommend let alone mention, MathCAT, which is now the replacement for the older and unmaintained MathPlayer.

Description of user facing changes

Update the math section in the User guide to mention and recommend MathCAT, and clarify that MathPlayer is still relevant on newer browsers.

Description of development approach

n/a

Testing strategy:

Built the user guide as html.

Known issues with pull request:

None known.

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.

[nvdaes]

@michaelDCurran , I don't see a mention to Neil to notify about this PR.
I love MathCAT and when needed I help to make smoke testing and to submit the add-on to the store if Neil ask me to do it, so let's mention @NSoiffer
I'll strongly recommend MathCAT for languages like spanish, since CMU braille is supported and used in certain countries, and I found difficulties to navigate with MathPlayer.

[CyrilleB79]

These changes generally look good to me.

I have just one point to discuss.
Only MathCAT and MathPlayer are mentioned as a possibility to access math content with NVDA. Though, using Access8Math is another real-life and quite popular alternative. It is specifically relevant for languages that are not (yet) available in MathCAT: fr, pt_BR, ru, tr, as well as zh_CN and zh_TW (considering that zh without country code is available in MathCAT instead).

It seems that NV Access wants to promote MathCAT and not Access8Math. Could you list in this issue (not in the User Guide) all the reasons for this choice and if it is likely to change in the future or not? This would encourage translators to put effort where it is more useful. Thanks.

Even if MathCAT is recommended in the User Guide, I think that mentioning Access8Math too would be useful, indicating that there are different supported languages with respect to MathCAT. Thanks.

[lukaszgo1]

Isn't this Pr also a fix for #15352?

[Adriani90]

@lukaszgo1 actually yes it fixes that issue as well. Thank you Mick for taking this up. :-)

[Qchristensen]

Changes look good so far. One small change: Line 932 reads: "this is only referring to using mathPlayer to display mathematical content visually, and can be ignored by those using it to read or navigate math with NvDA." - there should be a capital at the start of the line and the "v" in NVDA should be capitalised.

@CyrilleB79 Not speaking for @michaelDCurran but I suspect the original intention was to encourage use of MathCat over Mathplayer, rather than specifically excluding Access8Math. Would you like to propose an amended wording to include Access8Math for the use cases it is best suited to?

[michaelDCurran]

@CyrilleB79 To be completely honest, I was completely unaware of Access8math. But having now tested it a bit, it is definitely worthy of being included in the user guide. Thus I have rewritten the section to mention both MathCAT and Access8math. And to Generally recommend one of those newer NVDA add-ons, over the older MathPlayer, rather than the section generally recommending MathCAT specifically. Does this read better now?

[CyrilleB79]

@CyrilleB79 To be completely honest, I was completely unaware of Access8math. But having now tested it a bit, it is definitely worthy of being included in the user guide. Thus I have rewritten the section to mention both MathCAT and Access8math. And to Generally recommend one of those newer NVDA add-ons, over the older MathPlayer, rather than the section generally recommending MathCAT specifically. Does this read better now?

Yes, very nice. Thanks.

I have one last question: The URL for Access8Math is https://addons.nvda-project.org/addons/access8math.en.html.
For now the community website cannot be updated due to translation system being paused. Moreover,
Additionally, in the medium term, this website may be removed; some add-on authors have already changed the documentation URL to their GitHub repository.

@michaelDCurran, any update regarding the community website? Can add-on authors rely on it for NVDA 2024.1? Or do you already recommend to use an alternative URL?

@tseng Woody, do you plann to change the documentation URL for the next release of Access8Math? You may wait for Mick's answer to decide.

[michaelDCurran]

I would recommend that add-on authors move their home page URLs away from the old add-on website at this stage. Message ID: ***@***.***>

[Qchristensen]

That all reads well, good work everyone.

[CyrilleB79]

I would recommend that add-on authors move their home page URLs away from the old add-on website at this stage. Message ID: @.***>

Sorry, I remember now why I have kept the link on the community website rather than a link to GitHub for my own add-ons. The GitHub's page has the same content as the English readme. However, the community website has translated content for non-English users.

For now, we can keep the link on GitHub, given the lack of visibility on the community website.
However, for add-on authors and users, a solution to have translated content is still requested.
In this message two months ago, @michaelDCurran you wrote:

• The webhook and cron jobs will be re-enabled, again allowing add-on translations and add-on website updates to occur.

I have not seen any notification that it has happened since then. When will this happen? Since authors will update their add-ons for NVDA 2024.1 compatibility, I hope this happens before 2024.1rc1, i.e. before add-on authors are able to release stable add-ons compatible with NVDA 2024.1. Thanks.

[tsengwoody]

I am sorry for my delayed response to this discussion regarding the inclusion of Access8Math in the NVDA User Guide. It was only today, as I began updating Access8Math for compatibility with NVDA 2024.1, that I stumbled upon the updated User Guide and this discussion.
First and foremost, I would like to express my sincerest gratitude to @CyrilleB79 for advocating for Access8Math's inclusion in the User Guide. thank your support for our efforts.
I am also immensely glad to @michaelDCurran for your openness to include Access8Math in the User Guide upon learning about it. The inclusion significantly enhances the visibility of Access8Math, benefiting users who can leverage it to its full potential. It is truly heartening to see our work acknowledged.
The mission of Access8Math has always been to offer a comprehensive and accessible solution for mathematical content. Beyond striving to provide accessible mathematical reading solution, Access8Math is equally dedicated to offering a more accessible mathematical writing solution. This two aspects ensures that Access8Math addresses the full spectrum of mathematical accessibility needs.
We are committed to the ongoing development of Access8Math, ensuring it remains a valuable tool for the NVDA community in future.