Opened 22 months ago

Last modified 6 weeks ago

#30296 needs_work enhancement

System package information and spkg-configure for mathjax

Reported by: mkoeppe Owned by:
Priority: major Milestone: sage-9.7
Component: packages: standard Keywords: spkg-configure, mathjax, sd111
Cc: gh-jcamp0x2a, paulmasson, slelievre, egourgoulhon, mjo, klee, jhpalmieri, nthiery, enriqueartal, fbissey, arojas, thansen, etn40ff, gh-tobiasdiez Merged in:
Authors: Samuel Lelièvre, ... Reviewers:
Report Upstream: N/A Work issues:
Branch: public/30296 (Commits, GitHub, GitLab) Commit: 5c624abfd948829125163f91f4bd4b24d0ecb797
Dependencies: Stopgaps:

Status badges

Description (last modified by 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

Change History (51)

comment:1 Changed 22 months ago by mkoeppe

  • Cc klee added

comment:2 Changed 22 months ago by mkoeppe

  • Cc jhpalmieri nthiery added

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

comment:3 Changed 22 months ago by mkoeppe

  • Priority changed from major to critical

comment:4 Changed 22 months ago by mkoeppe

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

comment:5 Changed 22 months ago by mkoeppe

  • Branch set to u/mkoeppe/system_package_information_and_spkg_configure_for_mathjax

comment:6 Changed 22 months ago by mkoeppe

  • Commit set to 68a0dda07f50a127891eee45cb0dbe5852788210

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:

68a0ddabuild/pkgs/sage_conf/src/sage_conf.py.in: Add MATHJAX_DIR

comment:7 Changed 22 months ago by mkoeppe

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

comment:8 follow-ups: Changed 22 months ago by mkoeppe

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

comment:9 Changed 22 months ago by mkoeppe

  • Status changed from new to needs_info

comment:10 in reply to: ↑ 8 Changed 22 months ago by jhpalmieri

Replying to mkoeppe:

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

The change

  • build/make/Makefile.in

    diff --git a/build/make/Makefile.in b/build/make/Makefile.in
    index ed5294cc4e..3d65767bf7 100644
    a b base: $(inst_patch) $(inst_pkgconf) 
    289289# produce plots.
    290290DOC_DEPENDENCIES = sagelib $(inst_sphinx) \
    291291       | $(SAGERUNTIME) $(inst_maxima) $(inst_networkx) $(inst_scipy) $(inst_sympy) \
    292        $(inst_matplotlib) $(inst_pillow) $(inst_mathjax) $(inst_mpmath) \
     292       $(inst_matplotlib) $(inst_pillow) $(inst_mpmath) \
    293293       $(inst_ipykernel) $(inst_jupyter_client) $(inst_conway_polynomials) \
    294294       $(inst_tachyon) $(inst_jmol) $(inst_thebe) $(inst_ipywidgets)
    295295
  • build/pkgs/mathjax/type

    diff --git a/build/pkgs/mathjax/type b/build/pkgs/mathjax/type
    index a6a7b9cd72..134d9bc32d 100644
    a b  
    1 standard
     1optional

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.

comment:11 Changed 22 months ago by 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.

comment:12 Changed 22 months ago by mkoeppe

  • Description modified (diff)

comment:13 Changed 22 months ago by mkoeppe

  • Branch u/mkoeppe/system_package_information_and_spkg_configure_for_mathjax deleted
  • Commit 68a0dda07f50a127891eee45cb0dbe5852788210 deleted

comment:14 Changed 21 months ago by slelievre

  • Description modified (diff)
  • Keywords spkg-configure mathjax added

comment:15 Changed 21 months ago by mkoeppe

  • Milestone changed from sage-9.2 to sage-9.3
  • Priority changed from critical to major

comment:16 in reply to: ↑ 8 ; follow-up: Changed 21 months ago by slelievre

Replying to mkoeppe:

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

See

and the various answers there, including

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?).

comment:17 in reply to: ↑ 16 Changed 18 months ago by 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.

comment:18 Changed 18 months ago by mkoeppe

  • Cc enriqueartal added
  • Description modified (diff)

comment:19 Changed 18 months ago by mkoeppe

  • Keywords sd111 added

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

comment:20 Changed 18 months ago by mkoeppe

  • Cc fbissey arojas thansen added

comment:21 Changed 18 months ago by mkoeppe

  • Cc etn40ff added

comment:22 Changed 18 months ago by 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.

comment:23 Changed 18 months ago by 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.

comment:24 Changed 18 months ago by mkoeppe

  • Description modified (diff)

comment:25 Changed 18 months ago by mkoeppe

  • Dependencies set to #31035
  • Status changed from needs_info to needs_work

comment:26 Changed 18 months ago by mkoeppe

  • Description modified (diff)

comment:27 Changed 18 months ago by mkoeppe

  • Description modified (diff)

comment:28 Changed 16 months ago by mkoeppe

  • Milestone changed from sage-9.3 to sage-9.4

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

comment:29 Changed 14 months ago by slelievre

  • Authors set to Samuel Lelièvre, ...
  • Branch set to public/30296
  • Commit set to 5c624abfd948829125163f91f4bd4b24d0ecb797
  • Dependencies #31035 deleted

Here is distro info to hopefully restart things here.


New commits:

5c624ab30296: Add distro info for mathjax

comment:30 Changed 10 months ago by mkoeppe

  • Milestone changed from sage-9.4 to sage-9.5

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

comment:31 Changed 5 months ago by mkoeppe

  • Milestone changed from sage-9.5 to sage-9.6

comment:32 Changed 8 weeks ago by mkoeppe

  • Cc gh-tobiasdiez added

comment:33 Changed 8 weeks ago by mkoeppe

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

comment:34 Changed 7 weeks ago by mkoeppe

  • Milestone changed from sage-9.6 to sage-9.7

comment:35 follow-up: Changed 7 weeks ago by 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.

comment:36 in reply to: ↑ 35 ; follow-up: Changed 7 weeks ago by 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???

comment:37 in reply to: ↑ 36 ; follow-up: Changed 7 weeks ago by 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?

comment:38 in reply to: ↑ 37 ; follow-up: Changed 7 weeks ago by 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.

comment:39 in reply to: ↑ 38 ; follow-ups: Changed 7 weeks ago by 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.

comment:40 in reply to: ↑ 39 Changed 7 weeks ago by 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.

comment:41 in reply to: ↑ 39 ; follow-up: Changed 7 weeks ago by 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?

Last edited 7 weeks ago by klee (previous) (diff)

comment:42 Changed 7 weeks ago by 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?

comment:43 in reply to: ↑ 41 ; follow-up: Changed 7 weeks ago by 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)

comment:44 in reply to: ↑ 43 ; follow-up: Changed 7 weeks ago by 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?

comment:45 Changed 7 weeks ago by 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.

comment:46 in reply to: ↑ 44 ; follow-up: Changed 6 weeks ago by 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.

comment:47 Changed 6 weeks ago by mkoeppe

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

comment:48 in reply to: ↑ 46 ; follow-up: Changed 6 weeks ago by 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".

comment:49 in reply to: ↑ 48 ; follow-up: Changed 6 weeks ago by 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.

comment:50 in reply to: ↑ 49 ; follow-up: Changed 6 weeks ago by 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?

comment:51 in reply to: ↑ 50 Changed 6 weeks ago by mjo

Replying to klee:

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

Yes, thanks, replied there.

Note: See TracTickets for help on using tickets.