decker-edu / decker

A markdown based tool for slide deck creation.
GNU General Public License v3.0
60 stars 15 forks source link

Update MathJax to 4.0.0-beta4 for better accessibility features #88

Open salbeira opened 10 months ago

salbeira commented 10 months ago

This PR includes:

An upgrade of MathJax from 3.2.2 to the current 4.0.0-beta4.

The Accessibility Menu of MathJax seems very much broken right now in the version 3.2.2: Activating Accessibility features by hand simply crashes MathJax (removing all math from the page) or - at least - doesn't crash but does not add any exploration meta-data to the math containers for the accessibility exploration feature to work with. In the "better" case, a page reload was required to let the menu change take effect.

Update: I just got confirmation that it actually IS broken: https://github.com/mathjax/MathJax/issues/3124

This can even be witnessed in their demo page: https://www.mathjax.org/#demo (Just rightclick a typeset formula, go to "Accessibility" and click "Activate" to see all the math disappear (what a magic trick!)).

This SEEMS to be fixed in 4.0.0. I took the files required from the official repo tag 4.0.0-beta4 and put them into our vendor directory. Check if your browser chached any old files as that might throw unexplainable errors like "can not get a document handle", but without chaning anything related in the code after several retries it fixed itself.

In addition I added a way to link to a deck with the ?a11y search parameter, similar to how reveal wants its ?print-pdf search parameter for printing. This simply activates handout mode, a11y color mode and tells MathJax on load to enable the math exploration by default.

I also removed our "throwing away" of the MathJax-Menu-Settings so the user can save their MathJax settings.

One thing that 4.0.0 also changes is the math default font. Right now the font repository of MathJax is private until 4.0.0 officially releases. @kno10 you already played around with the new Font feature, maybe you can give some input about how to include better looking fonts.

The eLearning deck of @mbotsch works for me in all the usual ways, except the look of the formulas.

Please check how this branch works out for you. This is by no way "done" and needs some more review and tinkering but it seems to work without any changes to our custom post-mathjax adjustments.

@monofon in addition the test "math-deck.md" in the repo is currently rendering but the tests inside are not consistent with what is even tested in the first place. Can you review what is actually supposed to be listed there so I have some point of reference what I should even test when touching the math plugin?

kno10 commented 10 months ago

If you use the standard CDN, fonts should "just work" by setting

MathJax = { output: { font: 'mathjax-fira' } };

for self-hosted fonts (which is what I use), set MathJax.output.fontPath.

A popular (and powerful) sans-serif font is Fira. I do not like all of the math symbols in standalone (e.g., \prod is ugly), but within slides that use the Fira font they integrate very well. A MWE is this:

<html>
<script>
MathJax = { output: { font: 'mathjax-fira' } };
</script>
<script src="https://cdn.jsdelivr.net/npm/mathjax@4.0.0-beta.4/tex-svg-nofont.js"></script>
$$ \int x \sum y \prod z \frac{\text{Banana}}{\text{Oranges}} $$
</html>

In the fiddle, modify the "mathjax-fira" line to try out the different fonts. There are

Font Name Original Source
mathjax-modern A version of Latin-Modern (the new default font in MathJax)
mathjax-asana A version of the Asana-Math font
mathjax-bonum A version of the Gyre Bonum font
mathjax-dejavu A version of the Gyre DejaVu font
mathjax-pagella A version of the Gyre Pagella font
mathjax-schola A version of the Gyre Schola font
mathjax-termes A version of the Gyre Termes font
mathjax-stix2 A version of the STIX2 font
mathjax-fira A version of the Fira and Fira-Math fonts
mathjax-euler A version of the Neo Euler font as an extension to mathjax-modern
mathjax-tex The original MathJax TeX font

Apparently, mathjax-tex should be closer to the looks of mathjax 2/3, if that is what you want.

For some unknown reason, the -nofont version does not work in my local installation, while the tex-svg.js version works. There is also a pre-bundled combination in the CDN of each font, so the user can choose the math font simply by selecting a different URL for MathJax (note that the URL changes in both the package name and in the file name):

<html>
<script src="https://cdn.jsdelivr.net/npm/mathjax-fira-font@4.0.0-beta.4/tex-mml-svg-mathjax-fira.js"></script>
$$ \int x \sum y \prod z \frac{\text{Banana}}{\text{Oranges}} $$
</html>

To see MathJax with Fira math in action, here is an example (beamer slides converted to markdown, then pandoc to HTML): https://dm.cs.tu-dortmund.de/mlbits/class-svm-optimization/. You will probably agree that matching the text font with the math font looks smooth, in particular with inline math.

mbotsch commented 10 months ago

Somehow it doesn't work for my elearning slides... Screenshot 2023-11-10 at 11 57 36

salbeira commented 10 months ago

How strange ...

grafik

WARNING: You are running a development build of decker (version: 0.14.0, branch: math-a11y, commit: 3ed201551b7c8a0615118bfd8f5634c143f5ed0c, tag: undefined, build date: 2023-11-09). Please be sure that you know what you're doing.

I also had inconsistent macro expansion when I tested this in the math-deck.md from the repo but as I already said this fixed itself after a few reloads so I made the browser cache responsible ... a mystery ... but if it is completely inconsistent and not a cache issue that is indeed a point against upgrading right now and waiting for an official release.

mbotsch commented 10 months ago

The above problem is caused by the HTML mathjax extension not being autoloaded in v4 (but it was in v3).

MathJax v4 also changed the startup behavior, such that our math fixes are not executed properly after typesetting. As a consequence, incremental multi-line equations are not properly handled.

With that, two of the two equation in my example deck (i.e. 100%) fail.

Let's wait until MathJax 4 is out of beta phase and then try again.

salbeira commented 10 months ago

I would not throw in the towel so quickly, as there are definetly more options for us to get our custom adjustments into the mathjax pipeline. I changed the adjustemts into renderActions that work directly on the nodes passed around the mathjax rendering pipeline.

mjx4

salbeira commented 10 months ago

To document the remaining issue with MathJax 4.0.0:

The MathJax.startup.promise is resolved too soon, causing the typeset not to be actually done before we resolve our Reveal promise. I had to turn all our adjustments into renderActions anyway so later re-renders of math formulas triggerd by interactions with the Accessibility-Menu also contain our adjustments, so they do happen if math is typeset and a usual presentation should be unaffected by this bug. What we can not guarantee is that the typeset happens before the page is printed if we run it in headless mode though.

This bug will be addressed in the next beta release if I understand the developer's comment about the issue: https://github.com/mathjax/MathJax/issues/3131

kno10 commented 10 months ago

I did not notice this, as I do not use fragments with math equations currently.

mbotsch commented 7 months ago

Still does not work, unfortunately even less than before. In the math slides of my example deck now first all non-math fragments are shown, followed by all math fragments. Can you confirm this?

salbeira commented 7 months ago

I can confirm this happening in Chrome ... I can not confirm this happening in Firefox ...

It sees that Chrome is very quick to run reveal's routine to set the data-fragment-index attributes on fragments where for some reason in Firefox doesnt happen until the math is rendered. The behaviour of Firefox is what is supposed to happen. The developers of MathJax confirmed to me in one of my issues related to this that their roadmap to 4.0.0's release got delayed and they have not released any new version of MathJax that might fix the "promise resolves too soon" error. I need to dig around and see if I had implemented the workaround proposed there or if I removed it with the render actions. Will update this soon.

kno10 commented 7 months ago

I came across another issue in the current mathjax beta related to line breaking (workaround: disable inline line breaking), supposedly fixed in the next beta/release. If merging beta4, maybe also add this workaround. https://github.com/mathjax/MathJax/issues/3135

salbeira commented 7 months ago

OK I re-added the startup code that should have been part of MathJax's next beta release (the one that didn't happen yet) to the plugin that is supposed to fix the "loads too quick" issue and that resolves it on initial load in both browsers for me.

On a re-render of the mathjax formulas their data-fragment-index of course gets removed as they are new DOM elements though. Because all other elements on the same slide keep their data-fragment-index, reveal then rearranges the order to the one where first all non-math is revealed, followed by the math.

This can be fixed by also removing all data-fragment-indices from elements on the same page that is rerendered but it is no longer identifyable if the author of the slides put the data-fragment-index on the element by hand or if it was put there by reveal after loading.

EDIT: Now this rerendering of the forumlas happens when activating the Accessibility features of the Math Menu, something that should also come with disabling the fragment system anyway.