System package information and spkg-configure for mathjax

[mkoeppe]

After #31035, our mathjax spkg is only used in our sphinx documentation. We currently ship a "stripped" version of mathjax 2.7.4 (see build/pkgs/mathjax/spkg-src; #25032, #18596); #25833 proposes an upgrade to 3.x.

We add an spkg-configure.m4 script for the standard package mathjax, as well as corresponding system package information in build/pkgs/mathjax/distros/ using ​https://repology.org/projects/?search=mathjax

---

Random references:

py-mathjax/pypi/py-mathjax at master · kiwi0fruit/py-mathjax ​https://github.com/kiwi0fruit/py-mathjax/tree/master/pypi/py-mathjax

Debian JavaScript Maintainers / mathjax · GitLab ​https://salsa.debian.org/js-team/mathjax

sphinx/setup.py at 3.x · sphinx-doc/sphinx ​https://github.com/sphinx-doc/sphinx/blob/3.x/setup.py

Math support for HTML outputs in Sphinx — Sphinx 4.0.0+ documentation ​https://www.sphinx-doc.org/en/master/usage/extensions/math.html#module-sphinx.ext.mathjax

sphinx-ext-mathjax - Google Search ​https://www.google.com/search?safe=off&sxsrf=ALeKk03spVlQ9ALPLJJCbNfF9EIdC_LYuQ%3A1596929073175&ei=MTQvX8mUCuKU0PEPu-yOiAE&q=sphinx-ext-mathjax&oq=sphinx-ext-mathjax&gs_lcp=CgZwc3ktYWIQAzIFCAAQzQIyBQgAEM0CMggIABDNAhCLAzIICAAQzQIQiwMyCAgAEM0CEIsDOgQIABBHOgcIIxCwAhAnOgcIIRAKEKABOgUIIRCgAToFCCEQqwJQmyhY4UVgtFBoAHABeACAAWqIAeUHkgEDOS4ymAEAoAEBqgEHZ3dzLXdpergBA8ABAQ&sclient=psy-ab&ved=0ahUKEwiJ8Yyx4IzrAhViCjQIHTu2AxEQ4dUDCAw&uact=5

Math support for HTML outputs in Sphinx — Sphinx 4.0.0+ documentation ​https://www.sphinx-doc.org/en/master/usage/extensions/math.html#module-sphinx.ext.mathjax

sphinx/mathjax.py at 3.x · sphinx-doc/sphinx ​https://github.com/sphinx-doc/sphinx/blob/3.x/sphinx/ext/mathjax.py

[mkoeppe]

There are numerous unresolved tickets regarding mathjax...

#30296 (System package information and spkg-configure for mathjax) – Sage ​https://trac.sagemath.org/ticket/30296#modify

#30226 (Allow LaTeX in text3d) – Sage ​https://trac.sagemath.org/ticket/30226

#30030 (Prevent JSmol from phoning home) – Sage ​https://trac.sagemath.org/ticket/30030

#29993 (Enable MathJax? in the TOC of Sage reference manual) – Sage ​https://trac.sagemath.org/ticket/29993#comment:9

#28547 (Remove hardcoded mathjax path in docs/conf.py) – Sage ​https://trac.sagemath.org/ticket/28547

#28257 (MathJax? causing unusual hanging in large notebooks) – Sage ​https://trac.sagemath.org/ticket/28257

#26612 (Remove bad mathjax symlink and bad mathjax directories) – Sage ​https://trac.sagemath.org/ticket/26612

#25833 (Upgrade to MathJax? 3) – Sage ​https://trac.sagemath.org/ticket/25833

#24024 (Meta-ticket: Update other packages to using the sage-dist-helpers functions + DESTDIR where applicable) – Sage ​https://trac.sagemath.org/ticket/24024

#24367 (Confusing documentation on MathJax? in light of use in Jupyter notebook) – Sage ​https://trac.sagemath.org/ticket/24367

#25015 (Improve introspection capabilities of Sage Jupyter Kernel) – Sage ​https://trac.sagemath.org/ticket/25015

#25111 (In the built documentation, replace duplicate files by symlinks) – Sage ​https://trac.sagemath.org/ticket/25111

#22394 (MathJax? javascript loaded more than once) – Sage ​https://trac.sagemath.org/ticket/22394

#18596 (Don't strip MathJax? fonts) – Sage ​https://trac.sagemath.org/ticket/18596

[mkoeppe]

For availability of mathjax in distributions, see ​https://repology.org/project/mathjax/versions

[mkoeppe]

The commit only indicates where the system directory should be inserted.

I don't plan to work on this ticket.

Hoping that people knowledgeable about the Jupyter notebook and/or documentation building will be interesting in working on it.

---

New commits:

​68a0dda

build/pkgs/sage_conf/src/sage_conf.py.in: Add MATHJAX_DIR

[mkoeppe]

There is also a pip-installable package ​https://pypi.org/project/py-mathjax/, but I think using it has not benefits for us.

[mkoeppe]

Also notebook bundles mathjax ... why do we install another copy?

[jhpalmieri]

Replying to mkoeppe:

Also notebook bundles mathjax ... why do we install another copy?

The change

build/make/Makefile.in

@@ -289 +289 @@
 # produce plots.
 DOC_DEPENDENCIES = sagelib $(inst_sphinx) \
        | $(SAGERUNTIME) $(inst_maxima) $(inst_networkx) $(inst_scipy) $(inst_sympy) \
-       $(inst_matplotlib) $(inst_pillow) $(inst_mathjax) $(inst_mpmath) \
+       $(inst_matplotlib) $(inst_pillow) $(inst_mpmath) \
        $(inst_ipykernel) $(inst_jupyter_client) $(inst_conway_polynomials) \
        $(inst_tachyon) $(inst_jmol) $(inst_thebe) $(inst_ipywidgets)
 

build/pkgs/mathjax/type

@@ -1 @@
-standard
+optional

avoids building mathjax, but then Sphinx doesn't find it when building the documentation. So if we want to use the version bundled with notebook, we need to make sure that Sphinx knows where to find it.

[mkoeppe]

src/sage/docs/conf.py expects sage.env.MATHJAX_DIR to be set to the location. This is what we'd have to configure if we take mathjax either from a system installation, or some other source.

[slelievre]

Replying to mkoeppe:

Also notebook bundles mathjax ... why do we install another copy?

See

• ​Stack Overflow question 28909747: How do I configure mathjax for iPython notebooks?

and the various answers there, including

• ​StackOverflow answer 58866858

which states

Jupyter ships with its own (smaller) version of MathJax. This is why it is not able to find the (Computer Modern) 'TeX' font -- there only is the STIX font.

So it's possible that the smaller version of MathJax shipped by Jupyter Notebook is not enough for our Sphinx use.

Configuring Jupyter Notebook to use Sage's fuller MathJax might have benefits (ability to typeset more math?) and/or drawbacks (performance?).

[mkoeppe]

Replying to slelievre:

Configuring Jupyter Notebook to use Sage's fuller MathJax might have benefits (ability to typeset more math?)

This should be investigated.

[mkoeppe]

Hoping we can make progress on this ticket this week - ​https://wiki.sagemath.org/days111

[arojas]

FWIW: On Arch we're unbundling mathjax from Jupyter and using the system one:

​https://github.com/archlinux/svntogit-community/blob/packages/jupyter-notebook/trunk/PKGBUILD#L40

Everything works fine, even without the /usr/share/jupyter/nbextensions/mathjax symlink installed by sage.

[mkoeppe]

Thanks. I have created #31035 (Remove mathjax configuration/symlink from jupyter notebook), as it seems what Sage is doing is simply not necessary any more after various updates of Jupyter.

[mkoeppe]

Setting new milestone based on a cursory review of ticket status, priority, and last modification date.

[slelievre]

Here is distro info to hopefully restart things here.

---

New commits:

​5c624ab

30296: Add distro info for mathjax

[mkoeppe]

Setting a new milestone for this ticket based on a cursory review.

[mkoeppe]

See also #33600: Configure mathjax in sphinx config and upgrade to Mathjax v3

[klee]

Still no spkg-configure.m4?

This script just needs to rewrite sage.env.MATHJAX_DIR to the system mathjax2 directory (/usr/share/mathjax?) if found in the system.

Perhaps it also needs to decide if it is really mathjax2 or mathjax3...

I am ready to duplicate it to #25833.

[klee]

Replying to klee:

This script just needs to rewrite sage.env.MATHJAX_DIR to the system mathjax2 directory (/usr/share/mathjax?) if found in the system.

This may not be true since the system mathjax2 would have all fonts and be too large to use for sage documentation. Sphinx will copy the whole to each _static directory of every documentation (reference, tutorial, ...).

Then the conclusion would be that we should not try to use the system mathjax???

[arojas]

Replying to klee:

This may not be true since the system mathjax2 would have all fonts and be too large to use for sage documentation. Sphinx will copy the whole to each _static directory of every documentation (reference, tutorial, ...).

Then the conclusion would be that we should not try to use the system mathjax???

On Arch (and Gentoo, which is where I got the idea from) distro packages we replace all _static copies with a symlink to the one in html/en/_static post-installation. Perhaps that sould be done on install by default?

[klee]

Replying to arojas:

On Arch (and Gentoo, which is where I got the idea from) distro packages we replace all _static copies with a symlink to the one in html/en/_static post-installation. Perhaps that should be done on install by default?

I guess that could be done for sage, independent of this ticket. Then it would reduce the number of times to copy $SAGE_SHARE/mathjax to _static/.

Nonetheless, spkg-configure.m4 needs to copy the reduced set of files from the system mathjax to $SAGE_SHARE/mathjax.

[arojas]

Replying to klee:

Replying to arojas:

On Arch (and Gentoo, which is where I got the idea from) distro packages we replace all _static copies with a symlink to the one in html/en/_static post-installation. Perhaps that should be done on install by default?

I guess that could be done for sage, independent of this ticket. Then it would reduce the number of times to copy $SAGE_SHARE/mathjax to _static/.

Nonetheless, spkg-configure.m4 needs to copy the reduced set of files from the system mathjax to $SAGE_SHARE/mathjax.

Well, my point is that once there is just one copy of _static, then maybe it's not *that* bad to just copy over the entire contents of the system mathjax dir.

[klee]

Replying to arojas:

Well, my point is that once there is just one copy of _static, then maybe it's not *that* bad to just copy over the entire contents of the system mathjax dir.

It would not be just one copy, because you have _static directory for each of languages.

[klee]

Replying to arojas:

Well, my point is that once there is just one copy of _static, then maybe it's not *that* bad to just copy over the entire contents of the system mathjax dir.

One copy to html/_static might suffice.

Other question: the location of the system mathjax is /usr/share/mathjax on all linux platforms? Or does it vary?

[klee]

The mathjax3 tarball is around 5Mb. I think this is not so big. Then is it worth while to detect the system mathjax and copy it instead of downloading the tarball?

[arojas]

Replying to klee:

Other question: the location of the system mathjax is /usr/share/mathjax on all linux platforms? Or does it vary?

mathjax doesn't provide an install script, so unfortunately there's no standard location and it's up to each distro to decide where to install it. On Arch we use /usr/share/mathjax, other distros may use mathjax3 instead if they also ship v2. (But, according to ​https://repology.org/project/mathjax/versions, no other distro is shipping mathjax 3 yet)

[klee]

Replying to arojas:

Replying to klee:

Other question: the location of the system mathjax is /usr/share/mathjax on all linux platforms? Or does it vary?

mathjax doesn't provide an install script, so unfortunately there's no standard location and it's up to each distro to decide where to install it.

mathjax is a javascript library, and perhaps unique in that among sage spkgs. I doubt if spkg-configure.m4 script is relevant with mathjax.

@matthias: would you comment?

[mkoeppe]

Given that the spread of mathjax 3 in distributions is so low, I don't think that there is a need to support system packages providing it. If this changes in the future, spkg-configure.m4 would be the correct mechanism though.

[mjo]

Replying to klee:

mathjax is a javascript library, and perhaps unique in that among sage spkgs. I doubt if spkg-configure.m4 script is relevant with mathjax.

It is kind of an awkward fit, since there's no reliable way of detecting via spkg-configure.m4 where the the html/js files might live. But we can at the very least check a list of known locations. The gp2c package does that for lack of a better strategy.

[mkoeppe]

One would probably only want to search for the system library when also system node is installed, which would give discoverability.

[klee]

Replying to mjo:

Replying to klee:

mathjax is a javascript library, and perhaps unique in that among sage spkgs. I doubt if spkg-configure.m4 script is relevant with mathjax.

It is kind of an awkward fit, since there's no reliable way of detecting via spkg-configure.m4 where the the html/js files might live. But we can at the very least check a list of known locations. The gp2c package does that for lack of a better strategy.

I agree. Still as this mathjax package is not big and does not take time to install, I doubt if it would ever be worth while to put necessary efforts for this package.

Hence I suggest closing this ticket as "won't fix".

[mjo]

Replying to klee:

Hence I suggest closing this ticket as "won't fix".

Sage's mathjax has "never" worked for me. This is probably due to font stripping (​https://trac.sagemath.org/ticket/18596#comment:4), but undoing that would make the package larger.

So I'd quite like the ability to use the unbroken copy my distro provides, regardless of any time/bandwidth savings. Ultimately I can write the spkg-configure if no one else does it. I'll probably wait until the mathjax-3.x upgrade is done though.

[klee]

Replying to mjo:

Replying to klee:

Hence I suggest closing this ticket as "won't fix".

Sage's mathjax has "never" worked for me. This is probably due to font stripping (​https://trac.sagemath.org/ticket/18596#comment:4), but undoing that would make the package larger.

So I'd quite like the ability to use the unbroken copy my distro provides, regardless of any time/bandwidth savings. Ultimately I can write the spkg-configure if no one else does it. I'll probably wait until the mathjax-3.x upgrade is done though.

Okay. Thanks. Does mathjax3 (#25833) work for you?

[mjo]

Replying to klee:

Okay. Thanks. Does mathjax3 (#25833) work for you?

Yes, thanks, replied there.