Performance issues with semantic enrichment

[rossberg]

Issue Summary

With semantic enrichment turned on, pages of the WebAssembly spec take 4x the time to render, with up to 10 or 20 s for some users; see issue WebAssembly/spec#1972.

MathJax 4 apparently turns on semantic enrichment by default. Given the performance hit, this should be considered a breaking change, as we had to turn it off manually.

Steps to Reproduce:

1. Follow the link in Loading instruction reference in a browser takes 10-20 seconds to render WebAssembly/spec#1972 OP.
2. Manually turn Semantic Enrichment on again through the MathJax context menu — I see the page freeze for approximately 10 s on my machine.

Technical details:

• MathJax Version: 4.0
• Client OS: (e.g., Mac OS X 15.6.1)
• Browser: (e.g., Safari 18.6)
• Hardware: MacBook Air M2, 16 GB RAM

I am using the following MathJax configuration:

    window.MathJax = {
        "tex": {
            "maxBuffer": 30720,
            "macros": {
                "multicolumn": ["", 2]
            }
        },
        "options": {
            "menuOptions": {
                "settings": {
                    "enrich": false
                }
            }
        }
    }

and loading MathJax via

    <script defer="defer" src="https://cdn.jsdelivr.net/npm/mathjax@4/tex-mml-chtml.js"></script>

Supporting information:

• For live link please see above.

[dpvc]

Although MathJax can be used to typeset non-mathematical material, its mission is to handle mathematical layout, and its semantic enrichment is based around the expressions being actual mathematics, so it has to work hard to analyze things like the tables you are presenting.

MathJax converts the TeX input into MathML trees internally, and your tables generate very large trees. For example, the second one in the page you link to has over 1700 nodes in its tree, and that means the semantic analysis has a lot of work to do. Andit is not even the largest table on the page, in a page that contains more than a dozen similar tables. You are pushing MathJax limits (as you probably know, since you had to increase its buffer size just to lay out these tables).

One of the things that is making the semantic analysis more difficult is the total number of nodes in the tables, and the way the table is coded contributes to that. For example, the table uses things like \mathtt{0x0A}, which is telling MathJax to treat 0x0A as mathematics, which is parsed as the number 0 followed by a variable x followed by a number 0 followed by a variable A. (MathJax doesn't know about hexadecimal numbers, though you could configure its number pattern to recognize them if you wished.) That means that \mathtt{0x0A} produces four nodes in the MathML tree. It would be better to use \texttt{0x0A}, which produces a single node instead. Similarly, \mathsf{catch\_all\_ref} produces catch followed by _ followed by all followed by ref, so 5 nodes, while \textfs{catch\_all\_ref} produces only one node containing catch_all_ref.

Changing from the \math macros to \text ones reduces the number of nodes in that table by over 360 nodes. Your original table takes about 445 milliseconds for the semantic-enhancement on my computer, but with the \text macros rather than \math ones, that is reduced to about 290 ms, a savings of 155 ms, or roughly 1/3, from just that one change.

Another source of extra complication is actually the use of ~~ for spacing, as the semantic-enrichment has to try to figure out what the meaning of those two spaces is. It is better to use a single spacing command, like \hspace{.66em}, which would produce the same amount of space with only one node instead of two. That saves you an additional 20 ms.

There are a few other simplifications that can be made as well. For example, there are extra braces that are not needed, as in {\mathtt{0x0A}}, where the outer braces produce an extra nesting node that is not needed. Removing those gets you another 15 to 20 ms. There is also an extra column that is entirely blank. That can be removed, for a savings of an additional 25 to 30ms.

Taken all together, the changes that I've listed above reduce the semantic processing for this table from 445 down to about 225 ms, a savings of 220 ms, or nearly 50%. That is strictly from improving the structure of the table.

Of course, I suspect you are generating this from an original LaTeX document using some layout package for the syntax tables, and you may not have control over the output. In that case you can still realize much of the savings by making definitions equivalent to

\def\mathtt#1{\texttt{#1}}
\def\mathsf#1{\textsf{#1}}
\def\mathit#1{\textit{#1}}

in your configuration, via

 window.MathJax = {
    "tex": {
        "maxBuffer": 30720,
        "macros": {
            "multicolumn": ["", 2],
            "mathtt": ["\\texttt{#1}", 1],
            "mathit": ["\\textit{#1}", 1],
            "mathsf": ["\\texsf{#1}", 1]
        }
    },
    "options": {
        "menuOptions": {
            "settings": {
                "enrich": false
            }
        }
    }
}

to get the initial 1/3 savings.

You could add a TeX input pre-filter to convert ~~ to \hspace{.66em}, and perhaps you could remove the unwanted column if it is in your original source. Otherwise the pre-filter might be able to remove it (and the array template entry for that column). That would get you most of the savings described above.

The semantic enrichment is required for the speech-text generation (and is also useful for line breaking, which you aren't using here). We need the speech generation to be on by default in order to support users with assistive needs. Expecting those who already have special needs to (a) realize that they can turn on assistive tools in MathJax, (b) know how to do so, and (c) be willing to turn on a feature that can be used to identify them as having special needs (which many such users are rightly hesitant to do) is asking the community that needs the most support to do the most work. We want to make it as easy for them as possible.

In your case, you need to consider how you want your page to be presented for those with assistive needs. Having the entire table read out as a formula is probably not the best solution, so I think you are right to turn off the assistive tools, even if the speed were not an issue for you. These are the kinds of decisions that need to be considered when deciding how to display tables like these.

The real issue, of course, is that you are using MathJax basically for formatting a textual table that has a small amount of math in it. The table would be better handled as an HTML table with embedded math at the locations where it is actually used. I made a rough conversion of that one table to HTML with MathJax only for the math (and a few other things like arrows and the vertical bars and dots), which produced this output

compared to your original of

In this case even though there are over 100 math expressions within this HTML table, the semantic-enrichment only took 25 ms! This is an order of magnitude better than even the best time for your all-in-one-expression table (and your original is over 17 times longer).

This would be the best solution, should it be possible, as it makes the table part of the document (not the math), and allows MathJax to handle just the mathematical part of the table. This will work better with screen readers, as well as being more performant.

As for whether this is a "breaking change", one of the reasons we moved to v4.0 rather that calling it v3.3 is that there are a number of potentially breaking changes, and so you need to opt in to using it by switching to v4 explicitly. We did document that the assistive tools are on by default in v4, but not in the breaking changes section, as I don't consider it a breaking change. Your usage of mathJax to format tables is an outlier, and does push the semantic enrichment to the limit. Most expressions will not have quite the impact that yours have.