|
| 1 | +.. _v4-api-changes: |
| 2 | + |
| 3 | +=================== |
| 4 | +MathJax API Changes |
| 5 | +=================== |
| 6 | + |
| 7 | +There are several MathJax API changes in this release, though most |
| 8 | +should not be breaking changes, as described below. |
| 9 | + |
| 10 | + |
| 11 | +.. _v4-api-promises: |
| 12 | + |
| 13 | +New Promise-Based Functions |
| 14 | +=========================== |
| 15 | + |
| 16 | +Some actions in MathJax require loading extra code from an extension, |
| 17 | +which is an asynchronous action, as the browser must wait for the file |
| 18 | +to be loaded before it can use it. In MathJax v3, such asynchronous |
| 19 | +actions were mostly associated with loading TeX extension packages, |
| 20 | +and that could be avoided by pre-loading the extensions that are |
| 21 | +needed, so that typesetting could be performed synchronously. In v4, |
| 22 | +with fonts that have much greater coverage than in v3, some font data |
| 23 | +may need to be loaded asynchronously as well, and that means that |
| 24 | +typesetting may be asynchronous even if all the needed TeX extensions |
| 25 | +are pre-loaded. As a result, the :js:meth:`MathJax.typesetPromise()` |
| 26 | +function is more likely to be needed, and :js:meth:`MathJax.typeset()` |
| 27 | +will only work if no font data needs to be loaded. This is discussed |
| 28 | +in more detail in the :ref:`v4-promises` section. |
| 29 | + |
| 30 | +Because of this greater need to handle asynchronous file loading, |
| 31 | +several new functions have been added to the :data:`MathDocument` |
| 32 | +class to provide promise-based versions of the corresponding |
| 33 | +synchronous calls. These include |
| 34 | +:js:meth:`mathDocument.convertPromise()`, |
| 35 | +:js:meth:`mathDocument.renderPromise()`, and |
| 36 | +:js:meth:`mathDocument.rerenderPromise()`, which wrap the |
| 37 | +:js:meth:`mathDocument.convert()`, :js:meth:`mathDocument.render()`, |
| 38 | +and :js:meth:`mathDocument.rerender()` methods in the needed |
| 39 | +:js:meth:`mathjax.handleRetriesFor()` call and return its promise. |
| 40 | +This makes it easier to perform these actions when font data or TeX |
| 41 | +extensions need to be loaded than having to use |
| 42 | +:js:meth:`mathjax.handlerRetriesFor()` yourself. |
| 43 | + |
| 44 | +In the past, promise-based functions, like |
| 45 | +:js:meth:`MathJax.typesetPromise()`, |
| 46 | +:js:meth:`MathJax.tex2chtmlPromise()`, etc., could not be called while |
| 47 | +another one was currently in effect. That is, you needed to wait for |
| 48 | +the promise from one such call to resolve before you could do the next |
| 49 | +call, and the documentation encouraged you to use |
| 50 | +:data:`MathJax.startup.promise` to help chain these calls together. |
| 51 | +In v4, these functions now use an internal promise (associated with |
| 52 | +the :data:`MathDocument`) to prevent more than one from running |
| 53 | +concurrently, so these calls chain automatically. In particular, you |
| 54 | +should no longer use :data:`MathJax.startup.promise` yourself to |
| 55 | +serialize your calls to these functions. |
| 56 | + |
| 57 | +You may wish to use the new :data:`MathDocument` promise to |
| 58 | +synchronize other code with MathJax's typesetting operations without |
| 59 | +having to keep track of the promises returned by the various |
| 60 | +promise-based functions. For this reason, MathJax provides a new |
| 61 | +:js:meth:`mathDocument.whenReady()` method of the :data:`MathDocument` |
| 62 | +class. It takes a function as its argument, and performs that action |
| 63 | +when its internal promise is resolved; that is, when any previous |
| 64 | +promise-based typesetting or conversion actions complete. You can |
| 65 | +think of :js:meth:`mathDocument.whenReady()` as queuing your action to |
| 66 | +be performed whenever MathJax has finished anything that has been |
| 67 | +queued previously. |
| 68 | + |
| 69 | +The function you pass to :js:meth:`mathDocument.whenReady()` can |
| 70 | +return a promise (if it starts any asynchronous actions of its own, |
| 71 | +for example), in which case that promise must be fulfilled before any |
| 72 | +further :js:meth:`mathDocument.whenReady()` actions will be |
| 73 | +performed. For example |
| 74 | + |
| 75 | +.. code-block:: js |
| 76 | +
|
| 77 | + const doc = mathjax.document('', {}); |
| 78 | + doc.whenReady(() => console.log('A')); |
| 79 | + doc.whenReady(() => { |
| 80 | + return new Promise((ok, fail) => { |
| 81 | + setTimeout(() => { |
| 82 | + console.log('B'); |
| 83 | + ok(); |
| 84 | + }, 1000); |
| 85 | + }); |
| 86 | + }); |
| 87 | + doc.whenReady(() => console.log('C')); |
| 88 | +
|
| 89 | +would print ``A`` to the developer console, then a second later print |
| 90 | +``B`` followed by ``C``. |
| 91 | + |
| 92 | + |
| 93 | +.. _v4-api-speech: |
| 94 | + |
| 95 | +Changes to Speech Generation |
| 96 | +============================ |
| 97 | + |
| 98 | +In v3, the speech generation was performed within the |
| 99 | +:ref:`semantic-enrich-component` component along with the semantic |
| 100 | +enrichment of the internal MathML representation of the mathematical |
| 101 | +expressions that it processes. In v4, these two functions have been |
| 102 | +separated from each other, and the speech-generation functionality is |
| 103 | +performed in a new :ref:`speech-component` component. This is |
| 104 | +included in all the combined components, but can be loaded |
| 105 | +individually by including ``a11y/speech`` in the :data:`load` array of |
| 106 | +the :data:`loader` block of your MathJax configuration. |
| 107 | + |
| 108 | +The section on :ref:`v4-explorer-details` already mentions the new |
| 109 | +:meth:`MathJax.done()` function that is used to shut down the |
| 110 | +web-worker or node worker-thread that is created for speech |
| 111 | +production. There is a corresponding new |
| 112 | +:js:meth:`mathDocument.done()` method for the :data:`MathDocument` |
| 113 | +class that can be used in applications that don't use the MathJax |
| 114 | +Component framework, but rather call on MathJax modules directly. |
| 115 | + |
| 116 | + |
| 117 | +.. _v4-api-input-jax: |
| 118 | + |
| 119 | +Named Access to Input Jax |
| 120 | +========================= |
| 121 | + |
| 122 | +A MathDocument's :data:`inputJax` array included any input jax that |
| 123 | +you have loaded. E.g., in the ``tex-mml-svg.js`` combined component, |
| 124 | +it would contain entries for both the TeX and MathML input jax. |
| 125 | +Because this is an array, it was not obvious in v3 which of the two |
| 126 | +entries was which (you would need to check each entry's :data:`name` |
| 127 | +property to see if it is the one you want). In this release, the |
| 128 | +:data:`inputJax` array also includes properties that point to the |
| 129 | +input jax by name. That is, :data:`mathDocument.inputJax.tex` will |
| 130 | +point to the TeX input jax, if any, and similarly for |
| 131 | +:data:`mathDocument.inputJax.mathml`. |
| 132 | + |
| 133 | + |
| 134 | +.. _v4-api-modules: |
| 135 | + |
| 136 | +Change to ES6 Modules |
| 137 | +===================== |
| 138 | + |
| 139 | +The fact that the webpacked components are now ES6 files (see the |
| 140 | +section on :ref:`v4-es6-modules`) means that MathJax will no longer |
| 141 | +run in IE11, so you should no longer include the ``polyfill.io`` |
| 142 | +script that was recommended in the documentation for IE11 support. |
| 143 | + |
| 144 | +The ``es5`` directory has been removed from the MathJax distribution, |
| 145 | +so the ``/es5`` should be removed from the URL used to access |
| 146 | +MathJax's components. In the ``mathjax`` npm package, the files from |
| 147 | +the ``es5`` directory are now in the main directory, and for |
| 148 | +``mathjax-full`` (now called ``@mathjax/src``), they are in the |
| 149 | +generic ``bundle`` directory. |
| 150 | + |
| 151 | + |
| 152 | +.. _v4-api-options: |
| 153 | + |
| 154 | +Changes to Configuration Options |
| 155 | +================================ |
| 156 | + |
| 157 | +The :data:`tex.skipHtmlTags` configuration property now includes |
| 158 | +``select`` and ``option`` tags, since pop-up menu items can only |
| 159 | +contain textual content, not other HTML tags. |
| 160 | + |
| 161 | +In addition to the new configuration options discussed in other |
| 162 | +sections, there are several additional options available in this |
| 163 | +release: |
| 164 | + |
| 165 | +* Two new settings in the :data:`options.menuOptions.settings` |
| 166 | + configuration object: :data:`showSRE` and :data:`showLatex`, which |
| 167 | + control whether to include the data attributes generated by the |
| 168 | + speech-rule-engine or the :attr:`data-latex` attributes in MathML |
| 169 | + and SVG output in the `Show Math As` and `Copy to Clipboard` menus. |
| 170 | + |
| 171 | +.. |
| 172 | +
|
| 173 | +* :data:`mathml.verify.checkMathvariants`, which controls whether the |
| 174 | + MathML input jax will check that :attr:`mathvariant` attribute |
| 175 | + values are valid math variants and report an error if not. Invalid |
| 176 | + :attr:`mathvariant` values can cause MathJax to crash under some |
| 177 | + circumstances, so the default value of this option is ``true``, but |
| 178 | + this may cause current expressions with invalid math variant values |
| 179 | + that used to render to now show those nodes as having errors. |
| 180 | + |
| 181 | +The :data:`lineWidth` property of the :data:`Metrics` object (used to |
| 182 | +store information about the font metrics of the container surrounding |
| 183 | +an expression) has been removed, as the line-breaking algorithm ended |
| 184 | +up using the :data:`containerWidth` property directly. That affects |
| 185 | +functions that accept metric data as their inputs (such as |
| 186 | +:js:meth:`mathDocument.convert()` and :js:meth:`MathJax.tex2chtml()`), |
| 187 | +as these will no longer accept :data:`lineWidth` in the options passed |
| 188 | +to them. |
| 189 | + |
| 190 | +Some backward-compatibility code in v3 has been removed; e.g., when |
| 191 | +the :data:`tex.multlineWidth` configuration option was moved to |
| 192 | +:data:`tex.ams.multlineWidth` in an earlier version, there was code to move |
| 193 | +the old value to the new location, but that code has been removed in |
| 194 | +v4. |
| 195 | + |
| 196 | + |
| 197 | +.. _v4-api-code: |
| 198 | + |
| 199 | +Changes to the Code Base |
| 200 | +======================== |
| 201 | + |
| 202 | +The MathJax code base has undergone a major cleanup effort for this |
| 203 | +release, using ``eslint`` and ``prettier`` to format the code |
| 204 | +consistently, and new life-cycle scripts to perform these actions have |
| 205 | +been added to the ``package.json`` file. Other modernizations, like |
| 206 | +moving from :meth:`String.substr()` to :meth:`String.substring()` were |
| 207 | +also performed. |
| 208 | + |
| 209 | +A number of object name changes are listed in the |
| 210 | +:ref:`v4-breaking-changes` section. |
| 211 | + |
| 212 | +Finally, MathJax's test suite has been expanded to include more than |
| 213 | +3,000 tests. We have full coverage for the TeX input jax and the |
| 214 | +``ts/util`` directories, but more tests need to be written for other |
| 215 | +sections of the code base. This is an ongoing project that will take |
| 216 | +time to complete. |
| 217 | + |
| 218 | +|-----| |
0 commit comments