From 5f81a22bf6e01856311e8b33fa311ac9b6c7b973 Mon Sep 17 00:00:00 2001 From: Peter Krautzberger Date: Fri, 9 Jan 2015 16:22:39 +0100 Subject: [PATCH 01/10] first round of updates for #78 --- index.rst | 7 +++ options/CHTML-preview.rst | 69 ++++++++++++++++++++++ options/CommonHTML.rst | 75 ++++++++++++++++++++++++ whats-new-2.5.rst | 119 ++++++++++++++++++++++++++++++++++++++ 4 files changed, 270 insertions(+) create mode 100644 options/CHTML-preview.rst create mode 100644 options/CommonHTML.rst create mode 100644 whats-new-2.5.rst diff --git a/index.rst b/index.rst index 828d96c8..36a50e67 100644 --- a/index.rst +++ b/index.rst @@ -67,9 +67,14 @@ MathJax Configuration Options The TeX input processor options The MathML input processor options The AsciiMath input processor options + +.. toctree:: + :maxdepth: 1 + The HTML-CSS output processor options The NativeMML output processor options The SVG output processor options + The CommonHTML output processor options The MMLorHTML configuration options .. toctree:: @@ -81,6 +86,7 @@ MathJax Configuration Options The FontWarnings options The Safe options The MatchWebFonts options + The CHTML-preview options .. toctree:: :maxdepth: 1 @@ -131,6 +137,7 @@ Upgrading MathJax .. toctree:: :maxdepth: 1 + What's New in MathJax v2.5 What's New in MathJax v2.4 What's New in MathJax v2.3 What's New in MathJax v2.2 diff --git a/options/CHTML-preview.rst b/options/CHTML-preview.rst new file mode 100644 index 00000000..2b6b422f --- /dev/null +++ b/options/CHTML-preview.rst @@ -0,0 +1,69 @@ +.. _configure-CHTML-preview: + +***************************** +The CHTMLpreview extension +***************************** + +The options below control the operation of the `CHTML-preview` +extension that is run when you include ``"CHTML-preview.js"`` in the +`extensions` array of your configuration. They are listed with their +default values. To set any of these options, include a +``CHTML-preview`` section in your :meth:`MathJax.Hub.Config()` call. +For example + +.. code-block:: javascript + + MathJax.Hub.Config({ + CHTML-preview: { + Chunks: {EqnChunk: 10000, EqnChunkFactor: 1, EqnChunkDelay: 0}, + color: "inherit!important", + updateTime: 30, updateDelay: 6, + messageStyle: "none", + disabled: false + } + }); + +would ask for the CommonHTML output to run as a preview (`disabled: false`), +force inheritance of the surrounding text color, and set the `updateTime` and +`updateDelay` to low values (30ms / 6ms) to speed up +the preview pass. Furthermore, it configures the second pass to set the +chunking (`Chunks`) to a reflow every 10,000 equations and disable the progress +messages (`messageStyle`). + +This extension provides two-pass rendering mode. A **first**, fast-but-rough +rendering is genereated as a preview, using the +:ref:`configure-CommonHTML`, then a **second** pass using the +configured output jax runs to update the preview output. + +This two-pass mode will provide the reader with a quick, decent rendering to +start reading immediately, while silently updating that rendering with the +high quality layout later. + + +.. describe:: EqnChunk: 10000 + EqnChunkFactor: 1 + EqnChunkDelay: 0 + + These values control how "chunky" the **second** pass will be. For more + information see :ref:`configure-HTML-CSS` and :ref:`configure-SVG`. + +.. describe:: color: "inherit!important" + + This value allow you to choose a text color for the **first** passs. + +.. describe:: updateTime: 30 + updateDelay: 6 + + These values control how often the **first** pass will pause to allow user + interaction (e.g., scrolling). + +.. describe:: messageStyle: "none" + + This value controls the verbosity of the processing messages; see + :ref:`configure-hub` for more information. + +.. describe:: disabled:false + + This value enables or disables the preview mode. In particular, + it allow overriding a combined configuration file, cf. + :ref:`common-configurations`. \ No newline at end of file diff --git a/options/CommonHTML.rst b/options/CommonHTML.rst new file mode 100644 index 00000000..aa5174f7 --- /dev/null +++ b/options/CommonHTML.rst @@ -0,0 +1,75 @@ +.. _configure-CommonHTML: + +******************************* +The CommonHTML output processor +******************************* + +The options below control the operation of the CommonHTML output +processor that is run when you include ``"output/CommonHTML"`` in the +`jax` array of your configuration or load a combined configuration +file that includes the CommonHTML output jax. They are listed with their default +values. To set any of these options, include an ``CommonHTML`` section +in your :meth:`MathJax.Hub.Config()` call. For example + +.. code-block:: javascript + + MathJax.Hub.Config({ + CommonHTML: { + scale: 120 + } + }); + +would set the ``scale`` option to 120%. + +.. describe:: scale: 100 + + The scaling factor (as a percentage) of math with respect to the + surrounding text. The `CommonHTML` output processor tries to match + the ex-size of the mathematics with that of the text where it is + placed, but you may want to adjust the results using this scaling + factor. The user can also adjust this value using the contextual + menu item associated with the typeset mathematics. + +.. describe:: minScaleAdjust: 50 + + This gives a minimum scale (as a percent) for the scaling used by + MathJax to match the equation to the surrounding text. This will + prevent MathJax from making the mathematics too small. + +.. describe:: mtextFontInherit: false + + This setting controls whether ```` elements will be typeset + using the math fonts or the font of the surrounding text. When + ``false``, the font for ``mathvariant="normal"`` will be used; + when ``true``, the font will be inherited from the surrounding + paragraph. + +.. describe:: linebreaks: {} + + This is an object that configures automatic linebreaking in the + CommonHTML output. In order to be backward compatible with earlier + versions of MathJax, only explicit line breaks are performed by + default, so you must enable line breaks if you want automatic + ones. The object contains the following values: + + .. describe:: automatic: false + + This controls the automatic breaking of expressions: when + ``false``, only ``linebreak="newline"`` is processed; when + ``true``, line breaks are inserted automatically in long + expressions. + + .. describe:: width: "container" + + This controls how wide the lines of mathematics can be. + + Use an explicit width like ``"30em"`` for a fixed width. + Use ``"container"`` to compute the size from the containing + element. + Use ``"nn% container"`` for a portion of the container. + Use ``"nn%"`` for a portion of the window size. + + The container-based widths may be slower, and may not produce + the expected results if the layout width changes due to the + removal of previews or inclusion of mathematics during + typesetting. \ No newline at end of file diff --git a/whats-new-2.5.rst b/whats-new-2.5.rst new file mode 100644 index 00000000..b1a84e13 --- /dev/null +++ b/whats-new-2.5.rst @@ -0,0 +1,119 @@ +.. _whats-new-2.5: + +************************** +What's New in MathJax v2.5 +************************** + +MathJax v2.5 includes a number of new features, as well a more than 70 important bug fixes. The following are some of the highlights. + +Features +-------- + +* *Speed improvements.* The HTML-CSS output performance was improved by 30-40% (depending on content complexity, with higher gains in more complex content such as very long documents). +* *New output for fast preview.* The new CommonHTML output provides a rough but 10x-faster rendering. The ``CHTML-preview`` extension will use this fast output as a preview mode for HTML-CSS or SVG output. +* *Improved Content MathML support.* Content MathML is now fully supported via a new extension, in particular this allows customization of the conversion process. +* *Improved elementary math support* The experimental support for elementary math elements has been significantly improved special thanks to David Carlisle. +* *NodeJS compatibility*. Enable the implementation of a NodeJS API (released as `MathJax-node `__). + +Numerous display bugs, line-breaking problems, and interface issues have been resolved; for a detailed listing please check the `release milestone `__. + +Interface +--------- + +* `#834 `__ Fix incorrect line-width when zooming which can cause line-breaking problems. +* `#918 `__ Fix zoom box size in NativeMML output. +* `#835 `__ Fix zoom for equations extending beyond their bounding box. +* `#893 `__ Fix outdated ARIA values for HTML-CSS and SVG output. +* `#860 `__, `#502 `__ Preserve RDFa, microdata, aria labels, and other attributes in HTML-CSS and SVG output. +* `#935 `__ Escape special characters in TeX annotations. +* `#912 `__ Fix missing ``mstyle`` attributes in ``toMathML`` output. +* `#971 `__ Fix lost attributes when ``toMathML`` is restarted. + +Line-breaking +------------- + +* `#949 `__ Fix processing error due to empty elements. + +HTML-CSS/SVG/nativeMML display +------------------------------ + +* `#863 `__ Fix broken MathML preview in MathML pre-processor. +* `#891 `__ Fix deprecated regexp affecting mtable alignment. +* `#323 `__ Improve MathPlayer compatibility on Internet Explorer 10+. +* `#826 `__ Scale content in fallback fonts. +* `#898 `__ Fix invalid SVG output when using fallback characters. +* `#800 `__ Fix misplaced background color for stretched mphantom elements in SVG output. +* `#490 `__ Fix ``\overline`` issues in combination with text-style limits. +* `#829 `__ Implement ``\delimitershortfall``, ``\delimiterfactor``. +* `#775 `__ Fix lost text content in SVG output. +* `#917 `__ Fix cases of incorrect bounding boxes in HTML-CSS output. +* `#807 `__ Fix clipping of table columns in HTML-CSS output. +* `#804 `__ Fix cases of uneven subscripts. +* `#944 `__ Fix rendering error when scaling-all-math of labeled equations. +* `#930 `__ Fix SVG output failure when ```` element has inline styles with border or padding. +* `#931 `__ Fix baseline alignment in Safari 6.2/7.1/8.0. +* `#937 `__ Fix incorrect width in MathJax font data affecting underlining. +* `#966 `__ Fix SVG output overlapping when using prefix notation. + +TeX emulation +------------- + +* `#881 `__ Allow ``\newenvironment`` to process optional parameters. +* `#889 `__ remove extra space around some parenthesis constructs. +* `#856 `__ Recognize comma as decimal delimiter in units. +* `#877 `__ Fix bug related to multiple accent having different width. +* `#832 `__ Fix multline environment not being centered in HTML-CSS output. +* `#776 `__ Fix stretchy delimiters of ``binom`` and ``choose``. +* `#900 `__ Fix ``\buildrel`` getting TeX class ORD instead of REL. +* `#890 `__ Enable px as dimension in ``\\[...]``. +* `#901 `__ Allow ``\limits`` in more cases and add errors for some cases of multiple subscripts. +* `#903 `__ Allow ``\hfill`` to set alignment in matrices and arrays (for old fashioned TeX layout). +* `#902 `__ Convert ``\eqalignno`` and ``\leqalignno`` into ``mlabeledtr``. +* `#906 `__ Allow comma separated parameters in ``\mmlToken``. +* `#913 `__ Allow attributes in ``\mmlToken`` whose defaults are false or blank. +* `#972 `__ Fix autoload of the ``color`` extension. +* `#375 `__ Add ``\{``, ``\}``, and ``\\`` to macros working within ``\text{}`` etc. +* `#969 `__ Fix incorrect spacing with some ``\frac`` constructs. +* `#982 `__ Fix incorrect spacing in ``aligned`` environments. + +Asciimath +--------- + +* `#851 `__ Prevent leading space in quote from causing processing errors. +* `#431 `__ Fix handling of special characters in exponents. +* `#741 `__ Add underbrace macro. +* `#857 `__ Update AsciiMathML to 2.2; changes include `improve entity handling `__, `add triangle macro `__, `map ast to asterisk `__, `allow input of row vectors `__, `allow lamda `__, `switch phi/varphi mapping `__, `add underbrace macro `__, `handle empty nodes better `__, `add vector norm macro `__, `improve @ macro `__. + +MathML Handling +--------------- + +* `#847 `__ Fix line-breaks in annotation elements. +* `#805 `__ Prevent empty annotation elements from causing math processing errors. +* `#769 `__ Update ``indentshift`` implementation to meet clarified MathML specification. +* `#768 `__ Fix processing of percentage values for ``indenshift``. +* `#839 `__ Update inheritance of ``displaystyle`` in ``mtable`` to meet clarified MathML specification. +* `#695 `__ Allow Content MathML converion to be customized. +* `#964 `__ Move experimental support for elementary math and RTL to its own extension. + +Fonts +----- + +* `#845 `__ Fix webfont bug in Safari 7. +* `#950 `__ Fix webfont bug in IE 11. + +Localization +------------ + +* `#979 `__ Updated locales thanks to Translatewiki.net; activate locales for Scots and Southern Balochi. + +APIs +----- + +* `#873 `__ Combine array of elements when typesetting. +* `#693 `__ Add API to allow listeners to be cleared. + + +Misc. +----- + +* `#872 `__ Add small delay between input and output phase to prevent performance degredation. \ No newline at end of file From f71ebc1e1cab9fbb4c1719ad3abcb6b4170d67ee Mon Sep 17 00:00:00 2001 From: Peter Krautzberger Date: Fri, 9 Jan 2015 23:34:12 +0100 Subject: [PATCH 02/10] second round of updates for #78: CommonHTML updates; Getting Started tweaking --- config-files.rst | 70 ++++++++++++++++++++++++------------------------ index.rst | 2 +- start.rst | 14 +++++----- 3 files changed, 44 insertions(+), 42 deletions(-) diff --git a/config-files.rst b/config-files.rst index c2f3c7ef..cdd0d751 100644 --- a/config-files.rst +++ b/config-files.rst @@ -1,12 +1,12 @@ .. _common-configurations: -********************* -Common Configurations -********************* +*********************** +Combined Configurations +*********************** -MathJax comes with a number of pre-defined configuration files in the -``MathJax/config`` directory. The ``default.js`` file contains nearly all -the possible configuration options together with comments explaining them, +MathJax comes with a number of pre-defined and pre-compiled configuration files +in the ``MathJax/config`` directory. The ``default.js`` file contains nearly +all the possible configuration options together with comments explaining them, so you can use that file to customize MathJax to your needs. Simply load it via @@ -60,8 +60,8 @@ following configuration: MathJax.Hub.Config({ config: ["MMLorHTML.js"], - jax: ["input/TeX","input/MathML","input/AsciiMath","output/HTML-CSS","output/NativeMML"], - extensions: ["tex2jax.js","mml2jax.js","asciimath2jax.js","MathMenu.js","MathZoom.js"], + jax: ["input/TeX","input/MathML","input/AsciiMath","output/HTML-CSS","output/NativeMML", "output/CommonHTML"], + extensions: ["tex2jax.js","mml2jax.js","asciimath2jax.js","MathMenu.js","MathZoom.js", "CHTML-preview.js"], TeX: { extensions: ["AMSmath.js","AMSsymbols.js","noErrors.js","noUndefined.js"] } @@ -70,8 +70,8 @@ following configuration: In addition, it loads the mml Element Jax, the TeX, MathML, and AsciiMath input jax main code (not just the definition files), as well as the `toMathML` extension, which is used by the Show Source option -in the MathJax contextual menu. The `-full` version also loads both the -HTML-CSS and NativeMML output jax main code, plus the HTML-CSS +in the MathJax contextual menu. The `-full` version also loads the HTML-CSS, +CommonHTML, and NativeMML output jax main code, plus the HTML-CSS `mtable` extension, which is normally loaded on demand. See the :ref:`tex2jax configuration ` section for @@ -107,8 +107,8 @@ configuration: MathJax.Hub.Config({ config: ["MMLorHTML.js"], - jax: ["input/TeX","input/MathML","output/HTML-CSS","output/NativeMML"], - extensions: ["tex2jax.js","mml2jax.js","MathMenu.js","MathZoom.js"], + jax: ["input/TeX","input/MathML","output/HTML-CSS","output/NativeMML", "output/CommonHTML"], + extensions: ["tex2jax.js","mml2jax.js","MathMenu.js","MathZoom.js", "CHTML-preview.js"], TeX: { extensions: ["AMSmath.js","AMSsymbols.js","noErrors.js","noUndefined.js"] } @@ -117,8 +117,8 @@ configuration: In addition, it loads the mml Element Jax, the TeX and MathML input jax main code (not just the definition files), as well as the `toMathML` extension, which is used by the Show Source option in the -MathJax contextual menu. The ``-full`` version also loads both the -HTML-CSS and NativeMML output jax main code, plus the HTML-CSS +MathJax contextual menu. The ``-full`` version also loads the HTML-CSS, +CommonHTML, and NativeMML output jax main code, plus the HTML-CSS `mtable` extension, which is normally loaded on demand. See the :ref:`tex2jax configuration ` section for @@ -153,8 +153,8 @@ extensions. It is equivalent to the following configuration: .. code-block:: javascript MathJax.Hub.Config({ - jax: ["input/TeX","output/HTML-CSS"], - extensions: ["tex2jax.js","MathMenu.js","MathZoom.js"], + jax: ["input/TeX","output/HTML-CSS", "output/CommonHTML"], + extensions: ["tex2jax.js","MathMenu.js","MathZoom.js", "CHTML-preview.js"], TeX: { extensions: ["AMSmath.js","AMSsymbols.js","noErrors.js","noUndefined.js"] } @@ -163,8 +163,8 @@ extensions. It is equivalent to the following configuration: In addition, it loads the mml Element Jax and the TeX input jax main code (not just the definition file), as well as the `toMathML` extension, which is used by the Show Source option in the MathJax contextual menu. The ``-full`` -version also loads the HTML-CSS output jax main code, plus the HTML-CSS -`mtable` extension, which is normally loaded on demand. +version also loads the HTML-CSS and CommonHTML output jax main code, plus the +HTML-CSS `mtable` extension, which is normally loaded on demand. See the :ref:`tex2jax configuration ` section for other configuration options for the ``tex2jax`` preprocessor, and the @@ -191,16 +191,16 @@ and MathZoom extensions. It is equivalent to the following configuration: MathJax.Hub.Config({ config: ["MMLorHTML.js"], - jax: ["input/MathML","output/HTML-CSS","output/NativeMML"], - extensions: ["mml2jax.js","MathMenu.js","MathZoom.js"] + jax: ["input/MathML","output/HTML-CSS","output/NativeMML", "output/CommonHTML"], + extensions: ["mml2jax.js","MathMenu.js","MathZoom.js", "CHTML-preview.js"] }); In addition, it loads the mml Element Jax and the MathML input jax main code (not just the definition file), as well as the `toMathML` extension, which is used by the Show Source option in the MathJax contextual menu. -The ``-full`` version also loads both the HTML-CSS and NativeMML output jax main -code files, plus the HTML-CSS `mtable` extension, which is normally loaded -on demand. +The ``-full`` version also loads the HTML-CSS, CommonHTML, and NativeMML output +jax main code files, plus the HTML-CSS `mtable` extension, which is normally +loaded on demand. See the :ref:`mml2jax configuration ` section for other configuration options for the ``mml2jax`` preprocessor, and the @@ -230,15 +230,15 @@ equivalent to the following configuration: MathJax.Hub.Config({ config: ["MMLorHTML.js"], - jax: ["input/AsciiMath","output/HTML-CSS","output/NativeMML"], - extensions: ["asciimath2jax.js","MathMenu.js","MathZoom.js"] + jax: ["input/AsciiMath","output/HTML-CSS","output/NativeMML", "output/CommonHTML"], + extensions: ["asciimath2jax.js","MathMenu.js","MathZoom.js", "CHTML-preview.js"] }); In addition, it loads the mml Element Jax and the TeX input jax main code (not just the definition file), as well as the `toMathML` extension, which is used by the Show Source option in the MathJax contextual menu. The ``-full`` -version also loads the HTML-CSS output jax main code, plus the HTML-CSS -`mtable` extension, which is normally loaded on demand. +version also loads the HTML-CSS and CommonHTML output jax main code, plus the +HTML-CSS `mtable` extension, which is normally loaded on demand. See the :ref:`asciimath2jax configuration ` section for other configuration options for the ``asciimath2jax`` @@ -265,8 +265,8 @@ is equivalent to the following configuration: .. code-block:: javascript MathJax.Hub.Config({ - jax: ["input/TeX","input/MathML","output/SVG"], - extensions: ["tex2jax.js","mml2jax.js","MathMenu.js","MathZoom.js"], + jax: ["input/TeX","input/MathML","output/SVG", "output/CommonHTML"], + extensions: ["tex2jax.js","mml2jax.js","MathMenu.js","MathZoom.js", "CHTML-preview.js"], TeX: { extensions: ["AMSmath.js","AMSsymbols.js","noErrors.js","noUndefined.js"] } @@ -275,8 +275,8 @@ is equivalent to the following configuration: In addition, it loads the mml Element Jax, the TeX and MathML input jax main code (not just the definition files), as well as the `toMathML` extension, which is used by the Show Source option in the -MathJax contextual menu. The ``-full`` version also loads both the -SVG output jax main code, plus the SVG `mtable` extension, which +MathJax contextual menu. The ``-full`` version also loads the SVG and +CommonHTML output jax main code, plus the SVG `mtable` extension, which is normally loaded on demand. See the :ref:`tex2jax configuration ` section for @@ -311,8 +311,8 @@ The Accessible configuration is equivalent to the following: MathJax.Hub.Config({ config: ["MMLorHTML.js"], - jax: ["input/TeX","input/MathML","output/HTML-CSS","output/NativeMML"], - extensions: ["tex2jax.js","mml2jax.js","MathMenu.js","MathZoom.js"], + jax: ["input/TeX","input/MathML","output/HTML-CSS","output/NativeMML", "output/CommonHTML"], + extensions: ["tex2jax.js","mml2jax.js","MathMenu.js","MathZoom.js", "CHTML-preview.js"], TeX: { extensions: ["AMSmath.js","AMSsymbols.js","noErrors.js","noUndefined.js"] }, @@ -333,7 +333,7 @@ mathematics by double-clicking on any equation. In addition, it loads the mml Element Jax, the TeX and MathML input jax main code (not just the definition files), as well as the `toMathML` extension, which is used by the Show Source option in the MathJax -contextual menu. The ``-full`` version also loads both the HTML-CSS and -NativeMML output jax main code, plus the HTML-CSS `mtable` extension, which +contextual menu. The ``-full`` version also loads the HTML-CSS, CommomHTML, +and NativeMML output jax main code, plus the HTML-CSS `mtable` extension, which is normally loaded on demand. diff --git a/index.rst b/index.rst index 36a50e67..d71df566 100644 --- a/index.rst +++ b/index.rst @@ -15,7 +15,7 @@ Basic Usage Getting Started with MathJax Installing and Testing MathJax Loading and Configuring MathJax - Common MathJax Configurations + Combined MathJax Configurations .. toctree:: :maxdepth: 1 diff --git a/start.rst b/start.rst index 037eeaa0..5700b6c3 100644 --- a/start.rst +++ b/start.rst @@ -46,7 +46,7 @@ To jump start, you accomplish the first step by putting .. code-block:: html into the ```` block of your document. (It can also go in the @@ -58,11 +58,13 @@ that well enough, and otherwise use HTML-with-CSS to display the mathematics. **Note** The ``TeX-AMS-MML_HTMLorMML`` configuration is one of the most general -(and largest) configuration files, and is listed here because it will suffice for -most people's needs and quickly get you started using MathJax. -Other :ref:`combined configuration files ` are available, however, -and you can also provide additional configuration parameters to tailor one of the -combined configurations to your needs. +(and thus largest) configuration files. We list it here because it will +quickly get you started using MathJax. It is probably not the most efficient +configuration for your purposes and other +:ref:`combined configuration files ` are available. You can +also provide additional configuration parameters to tailor one of the +combined configurations to your needs or use our development tools to generate +your own combined configuration file. More details about the configuration process can be found in the :ref:`Loading and Configuring MathJax ` instructions. From bc24b6f4b38e6c85e7b9514cd8fff77fe4092672 Mon Sep 17 00:00:00 2001 From: Peter Krautzberger Date: Sat, 10 Jan 2015 01:07:56 +0100 Subject: [PATCH 03/10] third round of updates for #78: update version; add Content MathML and mml3 extension page; update mathml.rst (could use more work...); update index --- conf.py | 6 ++-- index.rst | 8 ++++- mathml.rst | 67 +++++++++++++++++++++++++------------- options/Content-MathML.rst | 43 ++++++++++++++++++++++++ options/MML3.rst | 22 +++++++++++++ 5 files changed, 120 insertions(+), 26 deletions(-) create mode 100644 options/Content-MathML.rst create mode 100644 options/MML3.rst diff --git a/conf.py b/conf.py index d6da2263..2e18e53f 100644 --- a/conf.py +++ b/conf.py @@ -38,16 +38,16 @@ # General information about the project. project = u'MathJax' -copyright = u'2014 The MathJax Consortium' +copyright = u'2015 The MathJax Consortium' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the # built documents. # # The short X.Y version. -version = '2.4' +version = '2.5' # The full version, including alpha/beta/rc tags. -release = '2.4' +release = '2.5' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. diff --git a/index.rst b/index.rst index d71df566..d7aedb25 100644 --- a/index.rst +++ b/index.rst @@ -77,6 +77,13 @@ MathJax Configuration Options The CommonHTML output processor options The MMLorHTML configuration options +.. toctree:: + :maxdepth: 1 + + The CHTML-preview options + The Content MathML options + The experimental MML3 extension + .. toctree:: :maxdepth: 1 @@ -86,7 +93,6 @@ MathJax Configuration Options The FontWarnings options The Safe options The MatchWebFonts options - The CHTML-preview options .. toctree:: :maxdepth: 1 diff --git a/mathml.rst b/mathml.rst index bd3ec20e..0de1859a 100644 --- a/mathml.rst +++ b/mathml.rst @@ -28,7 +28,7 @@ details and examples. Of course it is also possible to use all three components together. It may seem strange to go through an internal format just to return to MathML in the end, but this is actually what makes it possible to view -MathML within an HTML page (rather than an XHTML page), without +MathML within an HTML4 page (rather than an XHTML page), without the complications of handling special MIME-types for the document, or any of the other setup issues that make using native MathML difficult. MathJax handles the setup and properly marks the @@ -75,15 +75,37 @@ able to handle self-closing tags, but older browsers have problems with them, so if you want your mathematics to be visible to the widest audience, do not use the self-closing form in HTML documents. + +Supported MathML commands +========================= + +MathJax supports the `MathML3.0 `_ +mathematics tags, with some limitations. The MathML +support is still under active development, so some tags are not yet +implemented, and some features are not fully developed, but are +coming. + +The deficiencies include: + +- No support for alignment groups in tables. + +- Not all attributes are supported for tables. E.g., ``columnspan`` + and ``rowspan`` are not implemented yet. + +- Experimental support for the elementary math tags: ``mstack``, ``mlongdiv``, + ``msgroup``, ``msrow``, ``mscarries``, and ``mscarry``. + +- Experimental support for bidirectional mathematics. + +See the `results of the MathML3.0 test suite +`_ for details. + + .. _content-mathml: Content MathML ============== -New in version 2.2 is experimental support for Content MathML. This -uses an XSL style sheet developed by David Carlisle to convert Content -MathML to Presentation MathML, which is then processed by MathJax. - To use Content MathML in your documents, simply include ``"content-mathml.js"`` in the ``extensions`` array of your MathML configuration block. For example @@ -101,31 +123,32 @@ configuration block. For example Note that this script tag must come *before* the script that loads ``MathJax.js`` itself. +For more information, see :doc:`options/Content-MathML`. -Supported MathML commands -========================= - -MathJax supports the `MathML3.0 `_ -presentation mathematics tags, with some limitations. The MathML -support is still under active development, so some tags are not yet -implemented, and some features are not fully developed, but are -coming. -The deficiencies include: +.. _experimental-mathml: -- No support for the elementary math tags: ``mstack``, ``mlongdiv``, - ``msgroup``, ``msrow``, ``mscarries``, and ``mscarry``. +Experimental mml3 extension +=========================== -- No support for alignment groups in tables. +To activate experimental features in your documents, simply include +``"mml3.js"`` in the ``extensions`` array of your MathML +configuration block. For example -- No support for right-to-left rendering. +.. code-block:: html -- Not all attributes are supported for tables. E.g., ``columnspan`` - and ``rowspan`` are not implemented yet. + -See the `results of the MathML3.0 test suite -`_ for details. +Note that this script tag must come *before* the script that loads +``MathJax.js`` itself. +For more information, see :doc:`options/MML3`. Semantics and Annotations ========================= diff --git a/options/Content-MathML.rst b/options/Content-MathML.rst new file mode 100644 index 00000000..4c9ca369 --- /dev/null +++ b/options/Content-MathML.rst @@ -0,0 +1,43 @@ +.. _configure-Content-MathML: + +**************************** +The Content MathML extension +**************************** + +The options below control the operation of the Content MathML extension +that is run when you include ``"MathML/content-mathml.js"`` in the `extension` +array of your configuration. They are listed with their default values. To +set any of these options, include a ``Content-MathML`` section in your +:meth:`MathJax.Hub.Config()` call. + +.. code-block:: javascript + + MathJax.Hub.Config({ + content-mathml: { + collapsePlusMinus: true, + cistyles: { + vector: 'bold-italic', + matrix: 'bold-upright' + }, + symbols: { + gamma: '\u03B3' + } + } + }); + +These options allow the following. + +.. describe:: collapsePlusMinus: true, + + Specifies whether a Plus followed by a Minus is collapsed, e.g., + `a+(-b)` simplified to `a-b`. + +.. describe:: cistyles: {...} + + Specifies which mathvariant to use with corresponding type attribute. + +.. describe:: symbols: {...} + + Specifies symbol names to translate to characters. + +Further customization is possible by modifying its functions on the fly. \ No newline at end of file diff --git a/options/MML3.rst b/options/MML3.rst new file mode 100644 index 00000000..8d4ca765 --- /dev/null +++ b/options/MML3.rst @@ -0,0 +1,22 @@ +.. _configure-mml3: + +****************** +The MML3 extension +****************** + +The **experimental** MML3 extension is run when you include ``mml3.js`` in the +``extension`` array of the MathML section of your :meth:`MathJax.Hub.Config()` +call. For example, + +.. code-block:: javascript + + MathJax.Hub.Config({ + MathML: { + extensions: ["mml3.js"] + } + }); + +The extension has no configuration options. + +The extension provides experimental support for the so-called elementary math +elements as well as experimental support for bidirectional math. \ No newline at end of file From d4c785069c73baab28e532e760c3a229ccffd0f6 Mon Sep 17 00:00:00 2001 From: Peter Krautzberger Date: Sat, 10 Jan 2015 01:17:42 +0100 Subject: [PATCH 04/10] a few more minor fixes --- asciimath.rst | 12 +++++------- mathml.rst | 16 +++++++++------- 2 files changed, 14 insertions(+), 14 deletions(-) diff --git a/asciimath.rst b/asciimath.rst index bbfccea8..cfc12801 100644 --- a/asciimath.rst +++ b/asciimath.rst @@ -12,15 +12,13 @@ later processing by MathJax. The AsciiMath input processor is what converts the AsciiMath notation into MathJax's internal format, where one of MathJax's output processors then displays it in the web page. -The AsciiMath input jax actually includes a copy of Peter Jipsen's -``ASCIIMathML.js`` file (see the `AsciiMath home page -`_ for -details), and is included by permission of the author. This means -that the results of MathJax's AsciiMath processing should be the same -as using the actual ``ASCIIMathML.js`` package (at least as far as the +The AsciiMath input jax actually includes a copy of ``ASCIIMathML.js`` itselt +(see the `AsciiMath home page `_ for details). +This means that the results of MathJax's AsciiMath processing should be the +same as using the actual ``ASCIIMathML.js`` package (at least as far as the MathML that it generates is concerned). Thanks go to David Lippman for writing the initial version of the AsciiMath preprocessor and -input jax. +input jax and for the ongoing improvements from the AsciiMath community. The `asciimath2jax` preprocessor can be configured to look for whatever markers you want to use for your math delimiters. See the diff --git a/mathml.rst b/mathml.rst index 0de1859a..85ed8c1f 100644 --- a/mathml.rst +++ b/mathml.rst @@ -4,7 +4,7 @@ MathJax MathML Support ********************** -The support for :term:`MathML` in MathJax consists of three parts: the +The support for :term:`MathML` in MathJax comes in three parts: the `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 @@ -22,16 +22,18 @@ MathML available in browsers that don't have native MathML support. It is also possible to have MathJax select the output processor for you so that MathML is used in those browsers that support it well enough, while HTML-CSS is used for those that don't. See the -:ref:`common configurations ` section for +:ref:`combined configurations ` section for details and examples. Of course it is also possible to use all three components together. It may seem strange to go through an internal format just to return to MathML in the end, but this is actually what makes it possible to view -MathML within an HTML4 page (rather than an XHTML page), without -the complications of handling special MIME-types for the document, or -any of the other setup issues that make using native MathML -difficult. MathJax handles the setup and properly marks the +MathML within an HTML4 page (rather than an XHTML page), in particular in older +browsers, without the complications of handling special MIME-types for the +document, or 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 and copy @@ -54,7 +56,7 @@ browsers, so you should avoid the named entities whenever possible. If you must use named entities, you may need to declare them in the `DOCTYPE` declaration by hand. -When you use MathML in an HTML document rather than an XHTML one +When you use MathML in an HTML4 document rather than an XHTML one (MathJax will work with both), you should not use the "self-closing" form for tags with no content, but should use separate open and close tags. That is, use From 22664040454d526152acd46db1edbc47169e6766 Mon Sep 17 00:00:00 2001 From: Peter Krautzberger Date: Sat, 10 Jan 2015 01:25:32 +0100 Subject: [PATCH 05/10] fourth round of fixes for #78: tweak mathml.rst, fix #84 --- index.rst | 1 + options/MML3.rst | 6 +++--- options/handle-floats.rst | 24 ++++++++++++++++++++++++ 3 files changed, 28 insertions(+), 3 deletions(-) create mode 100644 options/handle-floats.rst diff --git a/index.rst b/index.rst index d7aedb25..9735a632 100644 --- a/index.rst +++ b/index.rst @@ -80,6 +80,7 @@ MathJax Configuration Options .. toctree:: :maxdepth: 1 + The HTML-CSS floats extension The CHTML-preview options The Content MathML options The experimental MML3 extension diff --git a/options/MML3.rst b/options/MML3.rst index 8d4ca765..2c35446f 100644 --- a/options/MML3.rst +++ b/options/MML3.rst @@ -16,7 +16,7 @@ call. For example, } }); -The extension has no configuration options. - The extension provides experimental support for the so-called elementary math -elements as well as experimental support for bidirectional math. \ No newline at end of file +elements as well as experimental support for bidirectional math. + +The extension has no configuration options. \ No newline at end of file diff --git a/options/handle-floats.rst b/options/handle-floats.rst new file mode 100644 index 00000000..bfd0e14a --- /dev/null +++ b/options/handle-floats.rst @@ -0,0 +1,24 @@ +.. _configure-handle-floats: + +*************************** +The handle-floats extension +*************************** + +The floats extension for the HTML-CSS output is run when you include +``handle-floats.js`` in the ``extension`` array of the HTML-CSS section of your +:meth:`MathJax.Hub.Config()` call. For example, + +.. code-block:: javascript + + MathJax.Hub.Config({ + "HTML-CSS": { + extensions: ["handle-floats.js"] + } + }); + +This extension allows HTML-CSS output to deal with floating elements +better. In particular, when there are tags or equation numbers, these +would overlap floating elements, but with this extension, the width of +the line should properly correspond to the amount of space remaining. + +The extension has no configuration options. From d02f7558a79da37bf66765c95b2349d62211cb14 Mon Sep 17 00:00:00 2001 From: Peter Krautzberger Date: Wed, 14 Jan 2015 12:15:51 +0100 Subject: [PATCH 06/10] for #78: document mathjax/MathJax#860 --- options/hub.rst | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/options/hub.rst b/options/hub.rst index 7016c974..a4da56b6 100644 --- a/options/hub.rst +++ b/options/hub.rst @@ -279,6 +279,14 @@ behavior of MathJax. They are given with their default values. on :ref:`CSS style objects ` for details on how these are specified in JavaScript. +.. describe:: ignoreMMLattributes: { ... } + + This block contains ``attributeName: boolean`` pairs that control + which attributes should **not** be preserved from the + original MathML. E.g., ``id:true`` will be ignored, while ``id:false`` will + preserve all ids even if other criteria would normally prevent some ids + from being copied to the output; use false carefully. + .. describe:: v1.0-compatible: true This controls whether MathJax issues the warning about not having an From 9b0dd20816b53ac7aab787cda9b954ebc0ff4cc5 Mon Sep 17 00:00:00 2001 From: Peter Krautzberger Date: Thu, 15 Jan 2015 08:46:11 +0100 Subject: [PATCH 07/10] for #78: corrections after review by @dpvc --- index.rst | 2 +- options/CHTML-preview.rst | 21 +++++++++++---------- options/Content-MathML.rst | 2 +- 3 files changed, 13 insertions(+), 12 deletions(-) diff --git a/index.rst b/index.rst index 9735a632..51c0a7ea 100644 --- a/index.rst +++ b/index.rst @@ -80,7 +80,7 @@ MathJax Configuration Options .. toctree:: :maxdepth: 1 - The HTML-CSS floats extension + The HTML-CSS floats extension The CHTML-preview options The Content MathML options The experimental MML3 extension diff --git a/options/CHTML-preview.rst b/options/CHTML-preview.rst index 2b6b422f..58760ce3 100644 --- a/options/CHTML-preview.rst +++ b/options/CHTML-preview.rst @@ -14,7 +14,7 @@ For example .. code-block:: javascript MathJax.Hub.Config({ - CHTML-preview: { + "CHTML-preview": { Chunks: {EqnChunk: 10000, EqnChunkFactor: 1, EqnChunkDelay: 0}, color: "inherit!important", updateTime: 30, updateDelay: 6, @@ -27,10 +27,10 @@ would ask for the CommonHTML output to run as a preview (`disabled: false`), force inheritance of the surrounding text color, and set the `updateTime` and `updateDelay` to low values (30ms / 6ms) to speed up the preview pass. Furthermore, it configures the second pass to set the -chunking (`Chunks`) to a reflow every 10,000 equations and disable the progress -messages (`messageStyle`). +chunking (`Chunks`) to a reflow every 10,000 equations and disables the +progress messages (`messageStyle`). -This extension provides two-pass rendering mode. A **first**, fast-but-rough +This extension provides a two-pass rendering mode. A **first**, fast-but-rough rendering is genereated as a preview, using the :ref:`configure-CommonHTML`, then a **second** pass using the configured output jax runs to update the preview output. @@ -49,21 +49,22 @@ high quality layout later. .. describe:: color: "inherit!important" - This value allow you to choose a text color for the **first** passs. + This value allows you to choose a text color for the **first** passs. .. describe:: updateTime: 30 updateDelay: 6 - These values control how often the **first** pass will pause to allow user + These values control how often the **second** pass will pause to allow user interaction (e.g., scrolling). .. describe:: messageStyle: "none" - This value controls the verbosity of the processing messages; see - :ref:`configure-hub` for more information. + This value controls the verbosity of the processing messages during the + the **second** pass; see :ref:`configure-hub` for more information. .. describe:: disabled:false This value enables or disables the preview mode. In particular, - it allow overriding a combined configuration file, cf. - :ref:`common-configurations`. \ No newline at end of file + it allows overriding a combined configuration file, cf. + :ref:`common-configurations`. The user can independently enable or disable + the fast preview via the MathJax Menu. \ No newline at end of file diff --git a/options/Content-MathML.rst b/options/Content-MathML.rst index 4c9ca369..89ba2ad6 100644 --- a/options/Content-MathML.rst +++ b/options/Content-MathML.rst @@ -13,7 +13,7 @@ set any of these options, include a ``Content-MathML`` section in your .. code-block:: javascript MathJax.Hub.Config({ - content-mathml: { + "content-mathml": { collapsePlusMinus: true, cistyles: { vector: 'bold-italic', From 2fbfb4875e642a6782a306a86155420bbb6f7ce3 Mon Sep 17 00:00:00 2001 From: Peter Krautzberger Date: Fri, 30 Jan 2015 11:49:01 +0100 Subject: [PATCH 08/10] update Whats-new-2.5 for release --- whats-new-2.5.rst | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/whats-new-2.5.rst b/whats-new-2.5.rst index b1a84e13..2160231e 100644 --- a/whats-new-2.5.rst +++ b/whats-new-2.5.rst @@ -54,6 +54,8 @@ HTML-CSS/SVG/nativeMML display * `#931 `__ Fix baseline alignment in Safari 6.2/7.1/8.0. * `#937 `__ Fix incorrect width in MathJax font data affecting underlining. * `#966 `__ Fix SVG output overlapping when using prefix notation. +* `#993 `__ Add workaround for Native MathML in Gecko to re-enable ``mlabeledtr`` etc. +* `#1002 `__ Enable SVG output to inherit surrounding text color. TeX emulation ------------- @@ -75,6 +77,7 @@ TeX emulation * `#375 `__ Add ``\{``, ``\}``, and ``\\`` to macros working within ``\text{}`` etc. * `#969 `__ Fix incorrect spacing with some ``\frac`` constructs. * `#982 `__ Fix incorrect spacing in ``aligned`` environments. +* `#1013 `__ Fix processing error caused by ``'`` in commutative diagrams using ``AMScd.js``. Asciimath --------- @@ -116,4 +119,5 @@ APIs Misc. ----- -* `#872 `__ Add small delay between input and output phase to prevent performance degredation. \ No newline at end of file +* `#872 `__ Add small delay between input and output phase to prevent performance degredation. +* `#1016 `__ Fix bug related to ``