Upgrade to MathJax 3 and configure Sage

[slel]

Mathjax v3.2.0 was released on 2021-06-17, see https://github.com/mathjax/MathJax.

This will be done in three steps:

• Step 1: Fix Sage to be compatible with MathJax3. Done in Make Sage output MathJax3 compatible htmls #31517.
• Step 2: Provide mathjax spkg upgraded to MathJax3.
• Step 3: Configure Sage to use MathJax3.

This ticket focuses on the Steps 2 and 3.

To install mathjax, you can download the tarball from a temporary URL:

https://drive.google.com/file/d/1-tMjjIwftzoGngFh549_kUO3Chmy3qhI/view?usp=sharing

and place the tarball in upstream/ and make, or you can just do make since the tarball will be automatically downloaded from the attachment of this ticket after unsuccessful attempts to download from sage mirrors.

We can now choose whether to use mathjax CDN or not. The default is not to. To use CDN, do

export SAGE_DOCBUILD_OPTS="--use-cdns"

before make online doc.

Related tickets:

• System package information and spkg-configure for mathjax #30296 System package information and spkg-configure for mathjax

• Configure mathjax in sphinx config and upgrade to Mathjax v3 #33600 Configure mathjax in sphinx config and upgrade to Mathjax v3

Depends on #33763

CC: @antonio-rojas @egourgoulhon @embray @kiwifb @timokau @jdemeyer @jhpalmieri @kcrisman @miguelmarco @novoselt @haraldschilly @slel @sagetrac-tmonteil @vbraun @orlitzky

Component: packages: standard

Keywords: upgrade, mathjax

Author: Tobias Diez, Kwankyu Lee

Branch: 2535a91

Reviewer: Tobias Diez, Kwankyu Lee

Issue created by migration from https://trac.sagemath.org/ticket/25833

[slel]

comment:1

The second public beta release for MathJax v3 was released.

• announcement on the MathJax Users list

The announcement ends with this note:

MathJax v3 is in beta release. Do not use this in production,
but please test it and report issues on the MathJax v3 issue tracker!

We are continuing to add more functionality to version 3, and will be
releasing additional beta versions as new features become available.
So watch this site for more news to come!

[sagetrac-tmonteil]

comment:2

Do you know how light it will be compared to https://katex.org/ ?

[slel]

comment:3

Replying to @sagetrac-tmonteil:

Do you know how light it will be compared to https://katex.org/ ?

No. This might be a good question to ask on the mathjax-users mailing list.

Meanwhile the third public beta for MathJax 3 was announced on 28 Nov 2018.

[slel]

comment:4

MathJax v3 beta.4 released 2019-05-21.

[slel]

comment:5

MathJax 3.0.5 was released (2020-04).

[williamstein]

comment:9

It's worth paying attention to the fact that Mathjax 3 is missing a significant feature that might be really critical for Sage, which is "automatic line breaking". See the discussion here:

mathjax/MathJax#2312 (comment)

E.g., "So line breaking and other features will most likely have to wait until next year." "That's the reason why nearly nobody is using MathJax 3." etc.

I think this is very important to be aware of, and it's one reason why CoCalc doesn't use MathJax 3, and uses KaTeX by default. For some applications automatic line breaking probably isn't so important, but it might be very important for Sage, due to people often printing out polynomials and big formulas.

[kwankyu]

comment:10

Replying to @williamstein:

It's worth paying attention to the fact that Mathjax 3 is missing a significant feature that might be really critical for Sage, which is "automatic line breaking".

It is jupyter people who decides what math rendering web engine is used in jupyter, which is the official frontend of Sage. I think whether Sage will be moving to MathJax3 or something else is dependent on what they do.

[williamstein]

comment:11

Replying to @kwankyu:

Replying to @williamstein:

It's worth paying attention to the fact that Mathjax 3 is missing a significant feature that might be really critical for Sage, which is "automatic line breaking".

It is jupyter people who decides what math rendering web engine is used in jupyter, which is the official frontend of Sage. I think whether Sage will be moving to MathJax3 or something else is dependent on what they do.

Thanks. Here's their plan regarding this issue: jupyterlab/jupyterlab#7218 (comment)

[kcrisman]

comment:12

It's worth paying attention to the fact that Mathjax 3 is missing a significant feature that might be really critical for Sage, which is "automatic line breaking". See the discussion here:

Thanks, William, I'll pass that on upstream to PreTeXt.

[kwankyu]

Branch: public/25833

[kwankyu]

Author: Kwankyu Lee

[sagetrac-git]

Branch pushed to git repo; I updated commit sha1. New commits:

46d0d69

Add sage package mathjax3

[sagetrac-git]

Commit: 46d0d69

[kwankyu]

comment:15

To support #33600, I prepared a new package for mathjax3.

I've never done creating a spkg before and don't understand everything about this business. So please help. This is a public branch!

I used the mathjax2 spkg as a template, and managed to place a tarball in upstream/ directory and install from it to local/share/mathjax3 by sage -i mathjax3.

[sagetrac-git]

Branch pushed to git repo; I updated commit sha1. New commits:

6da197e

Remove garbage files

[sagetrac-git]

Changed commit from 46d0d69 to 6da197e

[kwankyu]

comment:17

Fixed first mistake.

[kwankyu]

comment:20

To the uninitiated (like me):

First

cd build/pkgs/mathjax3/
spkg-src 

to make the tarball upstream/mathjax-3.2.0.tar.gz.

[sagetrac-git]

Branch pushed to git repo; I updated commit sha1. New commits:

bd60742

Put into mathjax subdirectory

[sagetrac-git]

Changed commit from 6da197e to bd60742

[tobiasdiez]

comment:88

Thanks!

For the performance issues, there are a few things not related to mathjax that could be improved: https://pagespeed.web.dev/report?url=https%3A%2F%2F7b43a317c103400d467a6c8d65fb6d6181d4ee37--sagemath-tobias.netlify.app%2Freference%2Fmanifolds%2Fsage%2Fmanifolds%2Fdifferentiable%2Fvectorfield.html

Notably, the require script is quite expensive to load.

[kwankyu]

comment:89

Replying to @tobiasdiez:

Notably, the require script is quite expensive to load.

Yes. I noticed that. See #33320 comment:82.

[kwankyu]

Changed dependencies from #33724 to #33763

[sagetrac-git]

Branch pushed to git repo; I updated commit sha1. This was a forced push. New commits:

8511370	Refactor sage/docs
4b0fae4	Some obvious edits
6517de2	More edits
d8a645f	Added instancedoc.py to sagemath-objects/MANIFEST.in
8b28eea	Upgrade to MathJax3
c34be8e	Fix mathjax3 bug in website/templates/index.html
e0a5d39	Remove commented-out lines
1cd2b49	Add upstream_url
a72a8e3	Fix to make the reference main page less flickering

[sagetrac-git]

Changed commit from 7b43a31 to a72a8e3

[kwankyu]

comment:92

Rebased on the dependency #33763.

[sagetrac-git]

Changed commit from a72a8e3 to 2535a91

[sagetrac-git]

Branch pushed to git repo; I updated commit sha1. New commits:

2535a91

Restore changes to conf.py

[kwankyu]

comment:94

The dependency got positive review.

[vbraun]

Changed branch from public/25833 to 2535a91

[antonio-rojas]

Changed commit from 2535a91 to none

[antonio-rojas]

comment:96

Why the double mathjax/mathjax subdir in the installation path? This looks weird and it will break using distro packages (so far only Arch seems to be shipping mathjax 3, but I doubt any distro will install it to /usr/share/mathjax/mathjax)

[kwankyu]

comment:97

Replying to @antonio-rojas:

Why the double mathjax/mathjax subdir in the installation path? This looks weird

If I remember correctly, that was the result of wishing to put the (second) mathjax directory into _static so that all mathjax files are kept in _static/mathjax and not mixed with other static files (unlike the situation with mathjax2), while not touching the spkg installation procedure (specifically build/pkgs/mathjax/spkg-install.in). Hence the tarball of spkg mathjax consists of a single directory mathjax.

and it will break using distro packages (so far only Arch seems to be shipping mathjax 3, but I doubt any distro will install it to /usr/share/mathjax/mathjax)

I don't know how the distro package works. Can't they change the installation script to install the package as they want, that is, into /usr/share/mathjax?

If they can't, would it solve the problem that the spkg tarball consists of mathjax files instead of the single directory? If we do so, then we need to touch the spkg installation procedure.

[antonio-rojas]

comment:98

Replying to @kwankyu:

I don't know how the distro package works. Can't they change the installation script to install the package as they want, that is, into /usr/share/mathjax?

If they can't, would it solve the problem that the spkg tarball consists of mathjax files instead of the single directory? If we do so, then we need to touch the spkg installation procedure.

OK, I see. The problem is that, if mathjax is installed in /usr/share/mathjax (as it is on Arch, and I assume other distros once they upgrade), sphinx will copy its content to _static, which is not what Sage expects, so mathjax won't work in docs. And setting MATHJAX_DIR=/usr/share is not an option, as this would copy the entire contents of /usr/share into _static.

It's unfortunate that sphinx doesn't allow to specify a single dir to be copied into _static, this would allow the issue to be solved cleanly. I've opened a ticket upstream for this sphinx-doc/sphinx#10499 so we can have a reasonable solution eventually.

For now, if we can't come up with a better solution, I guess I can just copy the mathjax dir to some temporary location at build time and set that as MATHJAX_DIR

[kwankyu]

comment:99

Replying to @antonio-rojas:

It's unfortunate that sphinx doesn't allow to specify a single dir to be copied into _static, this would allow the issue to be solved cleanly. I've opened a ticket upstream for this sphinx-doc/sphinx#10499 so we can have a reasonable solution eventually.

True. Thanks.

For now, if we can't come up with a better solution, I guess I can just copy the mathjax dir to some temporary location at build time and set that as MATHJAX_DIR

I experimented with the idea of using a symbolic link instead of copying, but it didn't work. Still no better solution. Thanks.