diff --git a/docs/source/mathml.rst b/docs/source/mathml.rst index 13acda760..b14eb201c 100644 --- a/docs/source/mathml.rst +++ b/docs/source/mathml.rst @@ -5,7 +5,7 @@ MathJax MathML Support ********************** The support for :term:`MathML` in MathJax consists of three parts: the -`mml2jax` preprocessor, the MathML input processor, and the NativeMML +`mml2jax` preprocessor, the `MathML` input processor, and the `NativeMML` output processor. The first of these looks for ```` tags within your document and marks them for later processing by MathJax. The second converts the MathML to the internal format used by MathJax, and @@ -34,9 +34,9 @@ any of the other setup issues that make using native MathML difficult. MathJax handles the setup and properly marks the mathematics so that the browser will render it as MathML. In addition, MathJax provides its contextual menu for the MathML, which -lets the user zoom the mathematics for easier reading, get the copy +lets the user zoom the mathematics for easier reading, get and copy the source markup, and so on, so there is added value to using MathJax -even whith a pure MathML workflow. +even with a pure MathML workflow. MathML in HTML pages diff --git a/docs/source/output.rst b/docs/source/output.rst index 05705a4a6..b1efe1381 100644 --- a/docs/source/output.rst +++ b/docs/source/output.rst @@ -10,9 +10,18 @@ Currently, MathJax can render math in two ways: - Using a browser's native MathML support. These are implemented by the `HTML-CSS` and `NativeMML` output -processors. You select which one you want to use by including either -``"output/HTML-CSS"`` or ``"output/NativeMML"`` in the `jax` array of -your MathJax configuration. For example +processors. + +If you are using one of the combined configuration files, then this will +select one of these output processors for you. If the config file ends in +``_HTML``, then it is the HTML-CSS output processor, and if it ends in +``_HTMLorMML``, then the NativeMML output processor will be chosen if the +browser supports it, otherwise HTML-CSS output will be used. + +If you are performing your own in-line or file-based configuration, you +select which one you want to use by including either ``"output/HTML-CSS"`` +or ``"output/NativeMML"`` in the `jax` array of your MathJax configuration. +For example .. code-block:: javascript @@ -25,7 +34,7 @@ The HTML-CSS output processor produces high-quality output in all major browsers, with results that are consistent across browsers and operating systems. This is MathJax's primary output mode. It's major advantage is its quality and consistency; it's drawback is that it is -slower that the NativeMML mode at rendering the mathematics. (The +slower than the NativeMML mode at rendering the mathematics. (The HTML-CSS processor has not yet been optimized for speed, so you can expect some improvement in the future. Note that IE8 in "IE8 standards mode" is an order of magnitude slower than any other browser @@ -41,20 +50,19 @@ MathML. Opera has some built-in support for MathML that works well with simple equations, but fails with more complex formulas, so we don't recommend using the NativeMML output processor with Opera. Safari, Chrome, Konqueror, and most other browsers don't support MathML -natively. +natively, but may in the future, since MathML is part of the HTML5 +specification. -The advantage of the NativeMML output Processor is its speed, since -native MathML support is much faster than using complicated HTML and -CSS to lay out mathematics via an interpreted language like JavaScript -(as the HTML-CSS output processor does). The disadvantage is that you -are dependent on the browser's MathML implementation for your +The advantage of the NativeMML output Processor is its speed, since native +MathML support is much faster than using complicated HTML and CSS to lay +out mathematics, as the HTML-CSS output processor does. The disadvantage +is that you are dependent on the browser's MathML implementation for your rendering, and these vary in quality of output and completeness of -implementation. MathJax may rely on features that are not available -in some renderers (for example, Firefox's MathML support does not -implement some of the named widths, such as -``negativethinmathspace``). The results using the NativeMML output -processor may have spacing or other rendering problems that are -outside of MathJax's control. +implementation. MathJax may rely on features that are not available in +some renderers (for example, Firefox's MathML support does not implement +some of the named widths, such as ``negativethinmathspace``). The results +using the NativeMML output processor may have spacing or other rendering +problems that are outside of MathJax's control. Automatic Selection of the Output Processor =========================================== @@ -62,11 +70,16 @@ Automatic Selection of the Output Processor Since not all browsers support MathML natively, it would be unwise to choose the NativeMML output processor unless you are sure of your audience's browser capabilities. MathJax can help with that, however, -since there is a special configuration file that will choose between -NativeMML and HTML-CSS depending on the browser in use. To invoke it, -add ``"MMLorHTML.js"`` to your configurations `config` array, and **do -not** include an output processor in your `jax` array; MathJax will -fill that in for you based on the abilities of your user's browser. +since a number of its combined configuration files will select NativeMML +output when the browser supports it, and HTML-CSS output otherwise. These +are the configuration files that end in ``_HTMLorMML``. + +If you are doing your own configuration, there is a special configuration +file that you can include that will choose between NativeMML and HTML-CSS +depending on the browser in use. To invoke it, add ``"MMLorHTML.js"`` to +your configurations `config` array, and **do not** include an output +processor in your `jax` array; MathJax will fill that in for you based on +the abilities of your user's browser. .. code-block:: javascript @@ -74,8 +87,8 @@ fill that in for you based on the abilities of your user's browser. jax: ["input/TeX"] You can customize which choice to make on a browser-by-browser basis -or a global basis. See the ``config/MathJax.js`` file or the -:ref:`Configuring MathJax ` section for futher +or a global basis. See the ``config/default.js`` file or the +:ref:`Configuring MMLorHTML ` section for futher details. MathJax produces MathML that models the underlying mathematics as best @@ -84,7 +97,7 @@ particular MathML implementation. When you make the choice to use the NativeMML output processor, you are making a trade-off: gaining speed at the expense of quality and reliability, a decision that should not be taken lightly. Note, however, that a user can employ the MathJax -contectual menu to select the other other renderer if he or she +contectual menu to select the other renderer if he or she wishes. @@ -94,7 +107,7 @@ HTML-CSS with IE8 ================= Internet Explorer 8 has at least eight different rendering modes in -which can operate, and that are triggered by the `DOCTYPE` of the +which it can operate, and that are triggered by the `DOCTYPE` of the document being viewed. Its "quirks" mode is its fastest mode, and its "IE8 standards" mode is its slowest. This is the mode triggered by strict HTML document types, and since most modern content management @@ -124,3 +137,7 @@ described above to select NativeMML output when possible, and request that your users install the `MathPlayer plugin `_, which will render the mathematics much more quickly. + +It appears that IE9 in IE9 standards mode may perform faster than IE8, but +since IE9 is still in beta testing as of this writing, we have yet to see +exactly what the performance of MathJax in IE9 will be like. diff --git a/docs/source/tex.rst b/docs/source/tex.rst index 50473df72..6ebc4b7c9 100644 --- a/docs/source/tex.rst +++ b/docs/source/tex.rst @@ -4,13 +4,13 @@ MathJax TeX and LaTeX Support ***************************** -The support for TeX and LaTeX in MathJax consists of two parts: the -`tex2jax` preprocessor, and the TeX input processor. The first of -these looks for mathematics within your web page (indicated by math -delimiters like ``$$...$$``) and marks the mathematics for later -processing by MathJax. The TeX input processor is what converts the -TeX notation into MathJax's internal format, where one of MathJax's -output processors then displays it in the web page. +The support for :term:`TeX` and :term:`LaTeX` in MathJax consists of two +parts: the `tex2jax` preprocessor, and the `TeX` input processor. The +first of these looks for mathematics within your web page (indicated by +math delimiters like ``$$...$$``) and marks the mathematics for later +processing by MathJax. The TeX input processor is what converts the TeX +notation into MathJax's internal format, where one of MathJax's output +processors then displays it in the web page. The `tex2jax` preprocessor can be configured to look for whatever markers you want to use for your math delimiters. See the @@ -97,40 +97,61 @@ TeX and LaTeX extensions ======================== While MathJax includes nearly all of the Plain TeX math macros, and -many of the LaTeX macros and environments, note everything is +many of the LaTeX macros and environments, not everything is implemented in the core TeX input processor. Some less-used commands are defined in extensions to the TeX processor. MathJax will load some extensions automatically when you first use the commands they implement (for example, the ``\def`` and ``\newcommand`` macros are -implemented in the ``TeX/newcommand.js`` extension, but MathJax loads +implemented in the ``newcommand.js`` extension, but MathJax loads this extension itself when you use those macros). Not all extensions are set up to load automatically, however, so you may need to request some extensions explicitly yourself. To enable any of the TeX extensions, simply add the appropriate string -(e.g., `"TeX/AMSmath.js"`) to your config's `extensions` array. The -main extensions are described below. +(e.g., ``"AMSmath.js"``) to the `extensions` array in the ``TeX`` block +of your configuration. If you use one of the combined configuration files, +like ``TeX-AMS_HTML``, this will already include several of the extensions +automatically, but you can include others using a mathjax configuration +script prior to loading MathJax. For example +.. code-block:: html + + + + +will load the `autobold` TeX extension in addition to those already +included in the ``TeX-AMS_HTML`` configuration file. + +The main extensions are described below. AMSmath and AMSsymbol --------------------- -The `AMSmath` extension implements AMS math environments and macros, -and the `AMSsymbol` extension implements macros for accessing the AMS -symbol fonts. To use these extensions, add them to your `extensions` array. +The `AMSmath` extension implements AMS math environments and macros, and +the `AMSsymbol` extension implements macros for accessing the AMS symbol +fonts. These are already included in the combined configuration files that +load the TeX input processor. To use these extensions in your own +configurations, add them to the `extensions` array in the TeX block. .. code-block:: javascript - extensions: ["TeX/AMSmath.js", "TeX/AMSsymbol.js", ...] + TeX: { + extensions: ["AMSmath.js", "AMSsymbol.js", ...] + } -See the list of commands at the end of this document for details about -what commands are implemented in these extensions. +See the list of control sequences at the end of this document for details +about what commands are implemented in these extensions. -The `AMSmath` extension will be loaded automatically when you first -use one of the math environments it defines, but you will have to load -it explicitly if you want to use the other macros that it defines. -The `AMSsymbols` extension is not loaded automatically, so you must -include it explicitly if you want to use the macros it defines. +If you are not using one of the combined configuration files, the `AMSmath` +extension will be loaded automatically when you first use one of the math +environments it defines, but you will have to load it explicitly if you +want to use the other macros that it defines. The `AMSsymbols` extension +is not loaded automatically, so you must include it explicitly if you want +to use the macros it defines. Autobold @@ -141,7 +162,11 @@ appears in a section of an HTML page that is in bold. .. code-block:: javascript - extensions: ["TeX/autobold.js"] + TeX: { + extensions: ["autobold.js"] + } + +This extension is **not** loaded by the combined configuration files. noErrors @@ -153,24 +178,27 @@ whether the dollar signs are shown or not for in-line math, and whether to put all the TeX on one line or use multiple lines (if the original text contained line breaks). -To enable the `noErrors` extension and configure it, use +This extension is loaded by all the combined configuration files that +include the TeX input processor. To enable the `noErrors` extension in +your own configuration, or to modify its parameters, add something like the +following to your :meth:`MathJax.Hub.Config()` call: .. code-block:: javascript - extensions: ["TeX/noErrors.js", ...], TeX: { - noErrors: { - inlineDelimiters: ["",""], // or ["$","$"] or ["\\(","\\)"] - multiLine: true, // false for TeX on all one line - style: { - "font-family": "serif", - "font-size": "80%", - "color": "black", - "border": "1px solid" - // add any additional CSS styles that you want - // (be sure there is no extra comma at the end of the last item) - } + extensions: ["noErrors.js"], + noErrors: { + inlineDelimiters: ["",""], // or ["$","$"] or ["\\(","\\)"] + multiLine: true, // false for TeX on all one line + style: { + "font-family": "serif", + "font-size": "80%", + "color": "black", + "border": "1px solid" + // add any additional CSS styles that you want + // (be sure there is no extra comma at the end of the last item) } + } } Display-style math is always shown in multi-line format, and without @@ -184,14 +212,14 @@ the paragraph, use .. code-block:: javascript TeX: { - noErrors: { - inlineDelimiters: ["$","$"], // or ["",""] or ["\\(","\\)"] - multiLine: false, - style: { - "font-size": "normal", - "border": "" - } + noErrors: { + inlineDelimiters: ["$","$"], // or ["",""] or ["\\(","\\)"] + multiLine: false, + style: { + "font-size": "normal", + "border": "" } + } } You may also wish to set the font family, as the default is "serif" @@ -201,28 +229,31 @@ noUndefined ----------- The `noUndefined` extension causes undefined control sequences to be -shown as their macro names rather than produce an error message. So +shown as their macro names rather than generating error messages. So ``$X_{\xxx}$`` would display as an "X" with a subscript consiting of the text ``\xxx`` in red. -To enable and configure this extension, use for example +This extension is loaded by all the combined configuration files that +include the TeX input processor. To enable the `noUndefined` extension +in your own configuration, or to modify its parameters, add something like +the following ro your :meth:`MathJax.Hub.Config()` call: .. code-block:: javascript - extensions: ["TeX/noUndefined.js", ...], TeX: { - noUndefined: { - attributes: { - mathcolor: "red", - mathbackground: "#FFEEEE", - mathsize: "90%" - } + extensions: ["noUndefined.js"], + noUndefined: { + attributes: { + mathcolor: "red", + mathbackground: "#FFEEEE", + mathsize: "90%" } - } + } + } The ``attributes`` setting specifies attributes to apply to the ``mtext`` element that encodes the name of the undefined macro. The -default settings set ``mathcolor`` to ``"red"``, but do not set any +default values set ``mathcolor`` to ``"red"``, but do not set any other attributes. This example sets the background to a light pink, and reduces the font size slightly. @@ -272,9 +303,9 @@ array. You can configure the extension as follows: .. code-block:: javascript TeX: { - unicode: { - fonts: "STIXGeneral, 'Arial Unicode MS'" - } + unicode: { + fonts: "STIXGeneral, 'Arial Unicode MS'" + } } @@ -949,6 +980,7 @@ the macro name. \subset \subseteq \subseteqq AMSsymbols + \subsetneq AMSsymbols \substack AMSmath \succ \succapprox AMSsymbols @@ -964,6 +996,7 @@ the macro name. \supset \supseteq \supseteqq AMSsymbols + \supsetneq AMSsymbols \surd \swarrow