commit b6d16ccd10ea808e964a6eea7deae18df4bd6491
parent 155436ba97bb1ffc9310a48c022e3b925b0e99bf
Author: Davide P. Cervone <dpvc@union.edu>
Date: Mon, 7 Mar 2011 20:44:55 -0500
Break configuration into three parts, add upgrade and what's new, and update installation, loading, and configuration documents
Diffstat:
7 files changed, 1074 insertions(+), 377 deletions(-)
diff --git a/docs/source/config-files.rst b/docs/source/config-files.rst
@@ -0,0 +1,192 @@
+.. _common-configurations:
+
+*********************
+Common 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,
+so you can use that file to customize MathJax to your needs. Simply load
+it via
+
+.. code-block:: html
+
+ <script type="text/javascript" src="path-to-MathJax/MathJax.js?config=default"></script>
+
+where ``path-to-MathJax`` is the URL to the MathJax directory on your
+server or hard disk.
+
+The remaining files are combined configuration files that include not just
+configuration parameters but also the files that MathJax would need to
+load for those configurations. This means MathJax will have to load fewer
+files, and since each file access requires establishing connections over
+the network, it can be better to load one larger file than several smaller
+ones. See :ref:`Loading and Configuring MathJax <loading>` for more
+details about how to load configurations, and how to modify the parameters
+for a configuration file.
+
+The following sections describe the contents of the combined configuration
+files. Each comes in two flavors: a standard version and a "full" version.
+The standard version simply defines the output processor(s) that are part
+of the configuration, but doesn't load the code that implements the output
+processor; the full version loads the complete output processors, so
+everything that MathJax needs for the page should be loaded up front, and
+there will be no delay once the page is ready to be processed. To obtain
+the "full" version, add ``-full`` to the end of the configuration file
+name.
+
+
+The ``TeX-AMS-MML_HTMLorMML`` configuration file
+================================================
+
+This configuration file is the most general of the pre-defined
+configurations. It loads all the important MathJax components, including
+the TeX and MathML preprocessors and input processors, the AMSmath,
+AMSsymbols, noErrors, and noUndefined TeX extensions, both the native
+MathML and HTML-with-CSS output processor definitions, and the MathMenu and
+MathZoom extensions. It is equivalent to the following configuration:
+
+.. code-block:: javascript
+
+ 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"],
+ TeX: {
+ extensions: ["AMSmath.js","AMSsymbols.js","noErrors.js","noUndefined.js"]
+ }
+ });
+
+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
+is normally loaded on demand.
+
+See the :ref:`tex2jax configuration <configure-tex2jax>` section for
+other configuration options for the ``tex2jax`` preprocessor, and the
+:ref:`TeX input jax configuration <configure-TeX>` section for options
+that control the TeX input processor.
+See the :ref:`mml2jax configuration <configure-mml2jax>` section for
+other configuration options for the ``mml2jax`` preprocessor, and the
+:ref:`MathML input jax configuration <configure-MathML>` section for
+options that control the MathML input processor.
+See :ref:`MathJax Output Formats <output-formats>` for more
+information on the NativeMML and HTML-CSS output processors. See the
+:ref:`MMLorHTML configuration <configure-MMLorHTML>` section for
+details on the options that control the ``MMLorHTML`` configuration.
+
+
+The ``TeX-AMS_HTML`` configuration file
+================================================
+
+This configuration file is for sites that only use TeX format for their
+mathematics, and that want the output to be as close to TeX output as
+possible. This uses the HTML-CSS output jax (even when the user's browser
+understands MathML). The user can still use the MathJax contextual menu
+to select the NativeMML output jax if they desire.
+
+This file includes all the important MathJax components for TeX input and
+output, including the `tex2jax` preprocessor and TeX input jax, the
+AMSmath, AMSsymbols, noErrors, and noUndefined TeX extensions, the
+HTML-with-CSS output processor definition, and the MathMenu and MathZoom
+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"],
+ TeX: {
+ extensions: ["AMSmath.js","AMSsymbols.js","noErrors.js","noUndefined.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.
+
+See the :ref:`tex2jax configuration <configure-tex2jax>` section for
+other configuration options for the ``tex2jax`` preprocessor, and the
+:ref:`TeX input jax configuration <configure-TeX>` section for options
+that control the TeX input processor.
+See :ref:`MathJax Output Formats <output-formats>` for more
+information on the HTML-CSS output processor.
+
+
+The ``MML_HTMLorMML`` configuration file
+================================================
+
+This configuration file is for sites that only use MathML format for their
+mathematics. It will use MathML output in browsers where that is
+supported, and HTML-CSS output otherwise. The user can still use the
+MathJax contextual menu to select the other output format if they desire.
+
+This file includes all the important MathJax components for MathML input
+and output, including the `mml2jax` preprocessor and MathML input jax, the
+NativeMML and HTML-CSS output processor definition files, and the MathMenu
+and MathZoom extensions. It is equivalent to the following configuration:
+
+.. code-block:: javascript
+
+ MathJax.Hub.Config({
+ config: ["MMLorHTML.js"],
+ jax: ["input/MathML","output/HTML-CSS","output/NativeMML"],
+ extensions: ["mml2jax.js","MathMenu.js","MathZoom.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.
+
+See the :ref:`mml2jax configuration <configure-mml2jax>` section for
+other configuration options for the ``mml2jax`` preprocessor, and the
+:ref:`MathML input jax configuration <configure-MathML>` section for
+options that control the MathML input processor.
+See :ref:`MathJax Output Formats <output-formats>` for more
+information on the NativeMML and HTML-CSS output processors. See the
+:ref:`MMLorHTML configuration <configure-MMLorHTML>` section for
+details on the options that control the ``MMLorHTML`` configuration.
+
+
+The ``Accessible`` configuration file
+================================================
+
+This configuration file is essentially the same as
+``TeX-AMS-MML_HTMLorMML`` except that it includes configuration that is
+designed for assitive technology, particularly for those with visual
+challenges. It is equivalent to the following configuration:
+
+.. code-block:: javascript
+
+ 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"],
+ TeX: {
+ extensions: ["AMSmath.js","AMSsymbols.js","noErrors.js","noUndefined.js"]
+ },
+ NativeMML: { showMathMenuMSIE: false },
+ menuSettings: { zoom: "Double-Click" },
+ errorSettings: { message: ["[Math Error]"] }
+ });
+
+This turns off the MathJax contextual Message for Internet Explorer, since
+it can interfere with some screen readers. It also sets the zoom trigger
+to double-click, so that readers can see a larger version of the
+mathematics but 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
+is normally loaded on demand.
+
diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst
@@ -6,18 +6,28 @@ Loading and Configuring MathJax
You load MathJax into a web page by including its main JavaScript file
into the page. That is done via a ``<script>`` tag that links to the
-``MathJax.js`` file. Place the following line in the ``<head>``
+``MathJax.js`` file. To do that, place the following line in the ``<head>``
section of your document:
.. code-block:: html
<script type="text/javascript" src="path-to-MathJax/MathJax.js"></script>
-where ``path-to-MathJax`` is replaced by the URL of the MathJax
-directory on your server, or (if you are using MathJax locally rather
-than through a server) the location of that directory on your hard
-disk. For example, if the MathJax directory is at the top level of
-your web server's directory hierarchy, you might use
+where ``path-to-MathJax`` is replaced by the URL of the copy of MathJax
+that you are loading. For example, if you are using the MathJax
+distributed network service, the tag might be
+
+.. code-block:: html
+
+ <script type="text/javascript"
+ src="http://cdn.mathjax.org/mathjax/latest/MathJax.js">
+ </script>
+
+If you have installed MathJax yourself, ``path-to-MathJax`` will be the
+location of MathJax on your server, or (if you are using MathJax locally
+rather than through a server) the location of that directory on your hard
+disk. For example, if the MathJax directory is at the top level of your
+web server's directory hierarchy, you might use
.. code-block:: html
@@ -25,15 +35,29 @@ your web server's directory hierarchy, you might use
to load MathJax.
-Although it is possible to load MathJax from a site other than your
-own web server, there are issues involved in doing so that you need to
-take into consideration. See the :ref:`Notes About Shared Servers
-<cross-domain-linking>` for more details. Please do **not** link to
-the copy of MathJax at ``www.mathjax.org``, as we do not have the
-resources to act as a web service for all the sites on the web that
-would like to display mathematics. If you are able to run MathJax
-from your own server, please do so (this will probably give you better
-response time in any case).
+If you install MathJax on a server in a domain that is different from the
+one containing the page that will load MathJax, then there are issues
+involved in doing so that you need to take into consideration. See the
+:ref:`Notes About Shared Servers <cross-domain-linking>` for more details.
+
+When you load MathJax, it is common to include additional parameters for
+MathJax as part of the URL. These control MathJax's configuration, and are
+discussed in the :ref:`Configuration Objects <configuration>` section. A
+typical invocation of MathJax would be
+
+.. code-block:: html
+
+ <script type="text/javascript"
+ src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
+ </script>
+
+which loads MathJax with a configuration file that includes everything you
+need in order to enter mathematics in either TeX, LaTeX, or MathML
+notation, and produces output using MathML if the browser supports that,
+or HTML-with-CSS otherwise. If you **don't** load an explicit
+configuration file, you will need to include an in-line configuration
+block in order to tell MathJax how to read and display the mathematics on
+your pages. See the section below for details.
It is best to load MathJax in the document's ``<head>`` block, but it
is also possible to load MathJax into the ``<body>`` section, if
@@ -51,325 +75,344 @@ been prepared, for example, via a `GreaseMonkey
advanced topic, however; see :ref:`Loading MathJax Dynamically
<ajax-mathjax>` for more details.
+.. _loading-CDN:
-Configuring MathJax
-===================
+Loading MathJax from the CDN
+============================
-There are several ways to configure MathJax, but the easiest is to use
-the ``config/MathJax.js`` file that comes with MathJax. See the
-comments in that file, or the :ref:`configuration details
-<configuration>` section, for explanations of the meanings of the various
-configuration options. You can edit the ``config/MathJax.js`` file to
-change any of the settings that you want to customize. When you
-include MathJax in your page via
+MathJax is now available as a web service from ``cdn.mathjax.org``, so you
+can obtain MathJax from there without needing to install it on your own
+server. The CDN is part of a distributed "cloud" network, so it is
+handled by servers around the world. That means that you should get acces
+to a server geographically near you, for a fast, reliable connection.
-.. code-block:: html
+The CDN hosts the most current version of MathJax, as well as older
+versions, so you can either link to a version that stays up-to-date as
+Mathjax is improved, or you can stay with one of the release versions so
+that you pages always use the same version of MathJax.
- <script type="text/javascript" src="path-to-MathJax/MathJax.js"></script>
+The URL that you use to obtain MathJax determines the version that you
+get. The CDN has the following directory structure:
-it will load ``config/MathJax.js`` automatically as one of its
-first actions.
+.. code-block:: sh
-Alternatively, you can configure MathJax efficiently by calling
-:meth:`MathJax.Hub.Config()` when you include MathJax in your page, as
-follows:
+ mathjax/ # project-name
+ 1.0-latest/
+ 1.1-beta/ # temporary
+ 1.1-latest/ # the 1.1 release with any ciritical patches
+ ...
+ latest/ # the most current version (1.1-latest in this case)
-.. code-block:: html
+Each directory corresponds to an official MathJax release; however,
+hotfixes (urgent bug fixes) will be applied in each release branch as
+necessary, even if new releases are not prepared. In other words,
+``1.1-latest`` will initially point to v1.1, but over time may be updated
+with patches that would correspond to releases that might be numbers 1.1a,
+1.1b, etc., even if such releases are not actually prepared for
+distribution (they likely won't be).
- <script type="text/javascript" src="path-to-MathJax/MathJax.js">
- MathJax.Hub.Config({
- extensions: ["tex2jax.js"],
- jax: ["input/TeX", "output/HTML-CSS"],
- tex2jax: {
- inlineMath: [ ['$','$'], ["\\(","\\)"] ],
- displayMath: [ ['$$','$$'], ["\\[","\\]"] ],
- },
- "HTML-CSS": { availableFonts: ["TeX"] }
- });
- </script>
+We may occasionally introduce directories for betas, as indicated above,
+but they will be temprorary, and will be removed after the official
+release.
-This example includes the ``tex2jax`` preprocessor and configures it
-to use both the standard TeX and LaTeX math delimiters. It uses the
-TeX input processor and the HTML-CSS output processor, and forces the
-HTML-CSS processor to use the TeX fonts rather that other locally
-installed fonts (e.g., :term:`STIX` fonts). See the
-:ref:`configuration options <configuration>` section (or the comments
-in the ``config/MathJax.js`` file) for more information about the
-configuration options that you can include in the
-:meth:`MathJax.Hub.Config()` call. Note that if you configure MathJax
-using this in-line approach, the ``config/MathJax.js`` file is **not**
-loaded.
-
-Finally, if you would like to use several different configuration
-files (like ``config/MathJax.js``, but with different settings in each
-one), you can copy ``config/MathJax.js`` to ``config/MathJax-2.js``,
-or some other convenient name, and use
+To load from a particular release, use the directory for that release.
+For example,
.. code-block:: html
- <script type="text/javascript" src="path-to-MathJax/MathJax.js">
- MathJax.Hub.Config({ config: "MathJax-2.js" });
- </script>
-
-to load the alternative configuration file ``config/MathJax-2.js``
-from the MathJax ``config`` directory. In this way, you can have as
-many distinct configuration files as you need.
-
-
-.. _common-configurations:
-
-Common Configurations
-=====================
-
-The following examples show configurations that are useful for some
-common situations. This is certainly not an exhaustive list, and
-there are variations possible for any of them. Again, the comments in
-the ``config/MathJax.js`` file can help you decide what settings to
-include, even if you are using the in-line configuration method.
+ <script type="text/javascript" src="http://cdn.mathjax.org/mathjax/1.1-latest/MathJax.js"></script>
-The TeX setup
--------------
+will load the stable v1.1 version, even if we release v1.2 or other later
+versions, while
-This example calls the ``tex2jax`` preprocessor to identify
-mathematics in the page by looking for TeX and LaTeX math delimiters.
-It uses ``$...$`` and ``\(...\)`` for in-line mathematics, while
-``$$...$$`` and ``\[...\]`` mark displayed equations. Because dollar
-signs are used to mark mathematics, if you want to produce an actual
-dollar sign in your document, you must "escape" it using a slash:
-``\$``. This configuration also loads the ``AMSmath`` and
-``AMSsymbols`` extensions so that the macros and environments they
-provide are defined for use on the page.
+.. code-block:: html
-.. code-block:: javascript
-
- MathJax.Hub.Config({
- extensions: ["tex2jax.js","TeX/AMSmath.js","TeX/AMSsymbols.js"],
- jax: ["input/TeX","output/HTML-CSS"],
- tex2jax: {
- inlineMath: [['$','$'],["\\(","\\)"]],
- processEscapes: true,
- },
- });
+ <script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js"></script>
-Other extensions that you may consider adding to the `extensions`
-array include: ``TeX/noErrors.js``, which shows the original TeX code
-if an error occurs while processing the mathematics (rather than an
-error message), ``TeX/noUndefined.js``, which shows undefined
-macros names in red (rather than producing an error), and
-``TeX/autobold.js``, which automatically inserts ``\boldsymbol{...}``
-around your mathematics when it appears in a section of your page that
-is in bold. Most of the other TeX extensions are loaded automatically
-when needed, and so do not need to be included explicitly in your
-`extensions` array.
+will always be the most current stable release, so it will go from v1.1 to
+v1.2 autmatically when that is released. Note that all the versions
+available on the CDN are stable versions; the development version is not
+hosted on the CDN.
-See the :ref:`tex2jax configuration <configure-tex2jax>` section for
-other configuration options for the ``tex2jax`` preprocessor, and the
-:ref:`TeX input jax configuration <configure-TeX>` section for options
-that control the TeX input processor.
+The use of ``cdn.mathjax.org`` is governed by its `terms of service
+<http://www.mathjax.org/download/mathjax-cdn-terms-of-service/>`_, so be
+sure to read that before linked to the MathJax CDN server.
-The MathML setup
-----------------
+Configuring MathJax
+===================
-This example calls the ``mml2jax`` preprocessor to identify
-mathematics in the page that is in :term:`MathML` format, which uses
-``<math display="block">`` to indicate displayed equations, and
-``<math display="inline">`` or simply ``<math>`` to mark in-line
-formulas.
+There are two ways to configure MathJax: via a configuration file, or by
+including configuration commands wthin the web page itself. These can be
+used independently, or in combination. For example, you can load a main
+pre-defined configuration file, but include in-line commands to
+adjust the configuration to your needs.
+
+Note that you must use at least one of these two forms of configuration.
+Unlike earlier versions of MathJax, version 1.1 does not load a default
+configuration file. If you have been using version 1.0's
+``config/MathJax.js`` for your configuration, you will need to load that
+configuration file explicitly via a ``config`` parameter, as described
+below.
+
+
+.. _config-files:
+
+Using a configuration file
+==========================
+
+The first way to configure MathJax is to use a configuration file.
+MathJax comes with a number of pre-defined configuration files, which are
+stored in the ``MathJax/config`` directory. Among these are the following
+
+.. describe:: default.js
+
+ A file that contains nearly all the configuration options with comments
+ describing them, which you can edit to suit your needs.
+
+.. describe:: TeX-AMS-MML_HTMLorMML.js
+
+ Allows math to be specified in TeX, LaTeX, or MathML notation, with the
+ `AMSmath` and `AMSsymbols` packages included, producing output using
+ MathML if the browser supports it, and HTML-with-CSS otherwise.
+
+.. describe:: TeX-AMS_HTML.js
+
+ Allows math to be specified in TeX or LaTeX notation (with the
+ `AMSmath` and `AMSsymbols` packages included, and produces output
+ using the HTML-CSS output processor.
+
+.. describe:: MML_HTMLorMML.js
+
+ Allows math to be specified using MathML notation, and produces MathML
+ output if the browser supports it, or HTML-CSS output otherwise.
+
+.. describe:: Accessible.js
+
+ Essentially the same as ``TeX-AMS-MML_HTMLorMML``, but with some
+ settings specified to make MathJax work better with assistive
+ technology (for the visually impaired). This includes setting the
+ zoom trigger to be a double-click, and removing the MathMenu in
+ Internet Explorer (which can interfere with some screen readers).
+
+The first of these is a file that you can edit to suit your needs. It
+contains nearly all the configuration options that MathJax allows, and has
+comments explaining them. The others are what are called `combined
+configuration files`, which not only configure MathJax, but also pre-load the
+various files that the configuration requires. (The contents of these
+files are explained in more detail in the `Common Configurations
+<common-configurations>`_ section.)
+
+Usually, MathJax loads its components only when they are needed, but each
+component will require a separate file to be loaded, and that can cause
+delays before the mathematics is displayed. The combined configuration
+files load the majority of the needed files all as one large file, reducing
+the number of network requests that are needed. That means you will
+probably be getting the componets that MathJax needs faster than you would
+without the combined file, but you may be loading components that are never
+actually used; that is the trade off.
+
+Each of the combined configuration files comes in two flavors: the ones
+listed above, which only configure the output processors but don't include
+the main code, and a "full" version, that also includes the complete
+output processors. For example, with ``TeX-AMS_HTML.js`` and
+``TeX-AMS_HTML-full.js``, the latter includes the complete HTML-CSS output
+processor. The "full" configuration files are substantially larger (on
+the order of 70KB), so you need to decide whether it is worth loading the
+full configuraiton for your pages.
+
+If most of your pages include mathematics, then it is to your advantage to
+load the full version, but if you are including MathJax in a theme file for
+a blog or wiki that only includes mathematics occasionally, then perhaps it
+is better to use the standard configuration instead, in which case the
+output processors are only loaded when they are actually needed, saving the
+loading of 70KB for pages that don't. Of course, if your server is
+configured to compress the files it sends, the difference between the two
+is considerably reduced. Furthermore, most browsers will cache the
+javascript they receive, so the download cost should only occur on the
+first page a user views, so it may be best to use the "full" version after
+all. Note, however, that mobile devices sometimes have limits on the size
+of files that they cache, so they may be forced to download the
+configuration on every page. You need to keep these issues in mind as you
+decide on which configuration to use.
+
+To load a configuration file, use ``config=filename`` (where ``filename``
+is one of the names above without the ``.js``) as a parameter to the URL of
+the ``MathJax.js`` file. For example
-.. code-block:: javascript
+.. code-block:: html
- MathJax.Hub.Config({
- extensions: ["mml2jax.js"],
- jax: ["input/MathML","output/HTML-CSS"]
- });
+ <script type="text/javascript"
+ src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
+ </script>
-Note that this will work in HTML files, not just XHTML files (MathJax
-works with both), and that the web page need not be served with any
-special MIME-type. Also note that, unless you are using XHTML rather
-than HTML, you should not include a namespace prefix for your
-``<math>`` tags; for example, you should not use ``<m:math>`` except
-in a file where you have tied the ``m`` namespace to the MathML DTD.
+loads the ``config/TeX-AMS-MML_HTMLorMML.js`` configuration file from the
+MathJax distributed network service.
-See the :ref:`mml2jax configuration <configure-mml2jax>` section for
-other configuration options for the ``mml2jax`` preprocessor, and the
-:ref:`MathML input jax configuration <configure-MathML>` section for
-options that control the MathML input processor.
+You can include more than one configuration file by separating them with
+commas. For example, if you have a locally defined configuration file
+called ``MathJax/config/local/local.js`` that modifies the settings for the
+``TeX-AMS_HML`` configuration, defines some new TeX macros, and so on, you
+can use
+.. code-block:: html
-Both TeX and MathML
--------------------
+ <script type="text/javascript"
+ src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS_HTML,local/local.js">
+ </script>
-This example provides for both TeX and MathML input in the same file.
-It calls on both the ``tex2jax`` and ``mml2jax`` preprocessors and the
-TeX and MathML input jax to do the job.
+to first load the main configuraiton, then the local modifications.
-.. code-block:: javascript
- MathJax.Hub.Config({
- extensions: ["tex2jax.js", "mml2jax.js"],
- jax: ["input/TeX", "input/MathML", "output/HTML-CSS"],
- });
+Using in-line configuration options
+===================================
-Notice that no ``tex2jax`` configuration section is included, so it
-uses its default options (no single dollar signs for in-line math).
+The second way to configure MathJax is through `in-line configuration`,
+that puts the configuration options within the web page itself. This
+process has changed in version 1.1 to make it compatible with HTML5.
+Earlier versions of MathJax had in-line configuration included within the
+content of the ``<script>`` tag that loads ``MathJax.js``, but HTML5 makes
+it illegal to have content for a script with a ``src`` attribute.
-The majority of the code for the TeX and MathML input processors are
-not loaded until they are actually needed by the mathematics on the
-page, so if this configuration is used on a page that include only
-MathML, the TeX input processor will not be loaded. Thus it is
-reasonably efficient to specify both input processors even if only one
-(or neither one) is used.
+MathJax solves this problem by using separate ``<script>`` tags to perform
+configuration for MathJax. Because MathJax starts its configuration
+process as soon as it is loaded, the configuration script must come
+**before** the script tag that loads ``MathJax.js`` itself. You do this
+by including a ``<script>`` with ``type="text/x-mathjax-config"``, whose
+content will be run when MathJax performs its configuration. Generally,
+this script will include a :meth:`MathJax.Hub.Config()` call to perform
+MathJax configuration, but it can also include other MathJax commands,
+such as registering signal actions, or any JavaScript commands that you
+want. You can have as many such script tags as you want, and MathJax will
+process them in order as they appear in the document.
+For instance,
-TeX input with MathML output
-----------------------------
+.. code-block:: html
-This example configures MathJax to use the ``tex2jax`` preprocessor
-and TeX input processor, but the choice of output format is determined
-by MathJax depending on the capabilities of the user's browser. The
-is performed by the ``MMLorHTML.js`` configuration file that is loaded
-in the `config`` array.
+ <script type="text/x-mathjax-config">
+ MathJax.Hub.Config({
+ extensions: ["tex2jax.js"],
+ jax: ["input/TeX", "output/HTML-CSS"],
+ tex2jax: {
+ inlineMath: [ ['$','$'], ["\\(","\\)"] ],
+ displayMath: [ ['$$','$$'], ["\\[","\\]"] ],
+ processEscapes: true
+ },
+ "HTML-CSS": { availableFonts: ["TeX"] }
+ });
+ </script>
+ <script type="text/javascript" src="path-to-MathJax/MathJax.js">
-.. code-block:: javascript
+This example includes the `tex2jax` preprocessor and configures it to use
+both the standard :term:`TeX` and :term:`LaTeX` math delimiters. It uses
+the `TeX` input processor and the `HTML-CSS` output processor, and forces the
+HTML-CSS processor to use the TeX fonts rather that other locally installed
+fonts (e.g., :term:`STIX` fonts). See the :ref:`configuration options
+<configuration>` section (or the comments in the ``config/default.js``
+file) for more information about the configuration options that you can
+include in the :meth:`MathJax.Hub.Config()` call. Note that this
+configuration does **not** load any pre-defined configuration file.
+
+Note that you can combine in-line configuration with file-based
+configuration, simply include ``text/x-mathjax-config`` scripts as above,
+but also include ``config=filename`` when you load the ``MathJax.js``
+file. For example, the `tex2jax` preprocessor does **not** the TeX
+single-dollar in-line math delimiters by default. You can load one of the
+pre-defined configuration files that include the TeX preprocessor, and use
+an in-line configuration block to enable the single-dollar signs:
- MathJax.Hub.Config({
- config: ["MMLorHTML.js"],
- extensions: ["tex2jax.js"],
- jax: ["input/TeX"]
- });
-
-With this setup, Firefox or Internet Explorer with the `MathPlayer
-plugin <http://www.dessci.com/en/products/mathplayer/>`_ installed
-will use the NativeMML output processor, while all other browsers will
-use the HTML-CSS output processor. Since native MathML support is
-faster than MathJax's HTML-CSS processor, this will mean that the web
-pages will display faster for Firefox and IE than they would
-otherwise. This speed comes at the cost, however, as you are now
-relying on the native MathML support to render the mathematics, and
-that is outside of MathJax's control. There may be spacing or other
-display differences (compared to MathJax's HTML-CSS output) when the
-NativeMML output processor is used.
-
-See :ref:`MathJax Output Formats <output-formats>` for more
-information on the NativeMML and HTML-CSS output processors. See the
-:ref:`MMLorHTML configuration <configure-MMLorHTML>` section for
-details on the options that control the ``MMLorHTML`` configuration.
-
-
-MathML input and output in all browsers
----------------------------------------
-
-This example configures MathJax to look for MathML within your page,
-and to display it using the browser's native MathML support, if
-possible, or its HTML-CSS output if not.
-
-.. code-block:: javascript
-
- MathJax.Hub.Config({
- config: ["MMLorHTML.js"],
- extensions: ["mml2jax.js"],
- jax: ["input/MathML"]
- });
-
-Using this configuration, MathJax finally makes MathML available in
-all modern browsers.
-
-See the :ref:`MMLorHTML configuration <configure-MMLorHTML>` section
-for details on the options that control the ``MMLorHTML``
-configuration file, the :ref:`MathML configuration <configure-MathML>`
-section for the options that control the MathML output processor, and
-the :ref:`mml2jax configuration <configure-mml2jax>` section for the
-options that control the ``mml2jax`` preprocessor.
-
-
-.. _configuration:
-
-Configuration Objects
-=====================
-
-The various components of MathJax, including its input and output
-processors, its preprocessors, its extensions, and the MathJax core,
-all can be configured through the ``config/MathJax.js`` file, or via a
-:meth:`MathJax.Hub.Config()` call (indeed, if you look closely, you
-will see that ``config/MathJax.js`` is itself one big call to
-:meth:`MathJax.Hub.Config()`). Anything that is in
-``config/MathJax.js`` can be included in-line to configure MathJax.
-
-The structure that you pass to :meth:`MathJax.Hub.Config()` is a
-JavaScript object that includes name-value pairs giving the names of
-parameters and their values, with pairs separated by commas. Be
-careful not to include a comma after the last value, however, as some
-browsers (namely Internet Explorer) will fail to process the
-configuration if you do.
-
-The MathJax components, like the TeX input processor, have their own
-sections in the configuration object, labeled by the component name,
-and using an configuration object as its value. The object is itself
-a configuration object made up of name-value pairs that give the
-configuration options for the component.
+.. code-block:: html
-For example,
+ <script type="text/x-mathjax-config">
+ MathJax.Hub.Config({
+ tex2jax: {
+ inlineMath: [ ['$','$'], ["\\(","\\)"] ],
+ processEscapes: true
+ }
+ });
+ </script>
+ <script type="text/javascript" src="path-to-MathJax/MathJax.js?config=TeX-AMS_HTML">
+ </script>
-.. code-block:: javascript
- MathJax.Hub.Config({
- showProcessingMessages: false,
- jax: ["input/TeX", "output/HTML-CSS"],
- TeX: {
- TagSide: "left",
- Macros: {
- RR: '{\\bf R}',
- bold: ['{\\bf #1}',1]
- }
- }
- });
+.. _delayStartupUntil:
+
+Configuring MathJax after it is loaded
+======================================
+
+Because MathJax begins its configuration process immediately after it is
+loaded (so that it can start loading files as quickly as it can), the
+configuration blocks for MathJax must come before ``MathJax.js`` is loaded,
+so they will be available to MathJax when it starts up. There are
+situations, however, when you might want to put off configuring MathJax
+until later in the page.
+
+One such situation is when you have a site that loads MathJax as part of a
+theme or template, but want to be able to modify the configuration on
+specific pages of the site. To accomplish this, you need to ask MathJax
+to delay its startup configuration until some later time. MathJax uses
+the ``delayStartupUntil`` parameter to control the timing of the startup
+sequence. By default, it is set to ``none``, meaning there is no delay
+and MathJax starts configuration right away.
+
+You can set ``delayStartupUntil=onload`` in order to prevent MathJax from
+continuing its startup process until the page's onLoad handler fires. This
+allows MathJax to find the ``text/x-mathjax-config`` blocks that occur
+anywhere on the page, not just the ones that appear above the ``<script>``
+that loads ``MathJax.js``. It also means that MathJax will not begin
+loading any of the files that it needs until then as well, which may delay
+the displaying of your mathematics, since the onLoad handler doesn't
+execute until all the images and other media are available. (If you have
+used a combined configuration file, however, it already includes all the
+main files that MathJax needs, so there is not much loss in delaying the
+startup.)
+
+You can set ``delayStartupUntil=configured`` in order to delay the startup
+configuration until the :meth:`MathJax.Hub.Configured()` method is
+called. This allows you to delay startup until later on the page, but
+then restart MathJax configuration process as soon as possible rather than
+waiting for the entire page to load. For example, you could use
-is a configuration that includes two settings for the MathJax Hub (one
-for `showProcessingMessages` and one of the `jax` array), and a
-configuration object for the TeX input processor. The latter includes
-a setting for the TeX input processor's `TagSide` option (to set tags
-on the left rather than the right) and a setting for `Macros`, which
-defines new TeX macros (in this case, two macros, one called ``\RR``
-that produces a bold "R", and one called ``\bold`` that puts is
-argument in bold face).
+.. code-block:: html
-The ``config/MathJax.js`` file is another example that shows nearly
-all the configuration options for all of MathJax's components.
+ <script type="text/javascript"
+ src="path-to-MathJax/MathJax.js?config=TeX-AMS-MML_HTMLorMML&delayStartupUntil=configured">
+ </script>
+in your theme's header file, and
-Configuration Options by Component
-==================================
+.. code-block:: html
-The individual options are explained in the following sections, which
-are categorized by the component they affect.
+ <script type="text/javascript">
+ MathJax.Hub.Configured()
+ </script>
-.. toctree::
- :maxdepth: 1
+in its footer, so that MathJax will delay setting up until the footer is
+reached, but will not have to wait until images and other files are
+laoded. If you have ``text/x-mathjax-config`` script tags within the main
+body of the document, MathJax will read and process those before
+continuing its startup. In this way you can use a default configuration
+that can be modified on a page-by-page basis.
- The core options <options/hub>
-.. toctree::
- :maxdepth: 1
+Details of the MathJax configuration process
+============================================
- The tex2jax preprocessor options <options/tex2jax>
- The mml2jax preprocessor options <options/mml2jax>
- The jsMath2jax preprocessor options <options/jsMath2jax>
+Since there are a number of different ways to configure MathJax, it is
+important to know how they interact. The configuration process is the
+following:
-.. toctree::
- :maxdepth: 1
+1. Process any configuration file explicitly specified as a script parameter.
+2. Process the in-line script body (deprecated), if present.
+3. If delayed startup is requested, wait for the indicated signal.
+4. Process ``text/x-mathjax-config`` config blocks.
+5. Process any config files queued in the configuration's `config` array
+ by earlier config code.
- The TeX input processor options <options/TeX>
- The MathML input processor options <options/MathML>
- The HTML-CSS output processor options <options/HTML-CSS>
- The NativeMML output processor options <options/NativeMML>
- The MMLorHTML configuration options <options/MMLorHTML>
-
-.. toctree::
- :maxdepth: 1
+Note that ``text/x-mathjax-config`` script blocks must either precede the
+``MathJax.js`` script element, or startup must be delayed. Otherwise, blocks
+that follow the ``MathJax.js`` script element may or may not be available
+when MathJax runs, and browser-dependent erratic behavior will result.
- The MathMenu options <options/MathMenu>
- The MathZoom options <options/MathZoom>
- The FontWarnings options <options/FontWarnings>
-
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -15,6 +15,8 @@ Basic Usage
Getting Started with MathJax <start>
Installing and Testing MathJax <installation>
Loading and Configuring MathJax <configuration>
+ Common MathJax Configurations <config-files>
+ MathJax Configuration Options <options/index>
Using MathJax in Web Platforms <platforms/index>
.. toctree::
@@ -30,6 +32,19 @@ Basic Usage
The MathJax Community <community>
+.. _upgrading-MathJax:
+
+Upgrading MathJax
+=================
+
+.. toctree::
+ :maxdepth: 1
+
+ What's New in MathJax v1.1 <whats-new>
+ Migrating from MathJax v1.0 to v1.1 <upgrade>
+ Converting to MathJax from jsMath <jsMath>
+
+
.. _advanced-topics:
Advanced Topics
@@ -49,10 +64,6 @@ Advanced Topics
Details of the MathJax API<api/index>
-.. toctree::
- :maxdepth: 1
-
- Converting to MathJax from jsMath <jsMath>
Reference Pages
===============
@@ -66,6 +77,12 @@ Reference Pages
* :ref:`Search <search>`
+* `User Help Pages <http://www.mathjax.org/help/user>`_:
+
+ + `MathJax Font Help <http://www.mathjax.org/help/fonts>`_
+ + `MathJax Contextual Menu <http://www.mathjax.org/help/menu>`_
+ + `MathJax Zoom Feature <http://www.mathjax.org/help/zoom>`_
+
--------
This version of the documentation was built |today|.
diff --git a/docs/source/installation.rst b/docs/source/installation.rst
@@ -4,6 +4,12 @@
Installing and Testing MathJax
******************************
+The easiest way to use MathJax is to link directly to the MathJax
+distributed network service (see :ref:`Using the MathJax CDN
+<mathjax-CDN>`). In that case, there is no need to install MathJax
+yourself, and you can begin using MathJax right away; skip this document on
+installation and go directly to :ref:`Configuring MathJax <loading>`.
+
MathJax can be loaded from a public web server or privately from your hard drive
or other local media. To use MathJax in either way, you will need to obtain a
copy of MathJax and its font package. There are three ways to do this: via
@@ -18,11 +24,11 @@ Obtaining MathJax via Git
The easiest way to get MathJax and keep it up to date is to use the `Git
<http://git-scm.com/>`_ version control system to access our `GitHub repository
-<http://github.com/mathjax/mathjax>`_. Use the commands
+<http://github.com/mathjax/mathjax>`_. Use the command
.. code-block:: sh
- git clone git://github.com/mathjax/MathJax.git mathjax
+ git clone git://github.com/mathjax/MathJax.git MathJax
to obtain and set up a copy of MathJax. Note that there is no longer
a ``fonts.zip`` file, and that the ``fonts`` directory is now part of
@@ -32,7 +38,7 @@ Whenever you want to update MathJax, you can now use
.. code-block:: sh
- cd mathjax
+ cd MathJax
git remote show origin
to check if there are updates to MathJax (this will print several
@@ -41,21 +47,22 @@ date or out of date). If MathJax needs updating, use
.. code-block:: sh
- cd mathjax
+ cd MathJax
git pull origin
to udpate your copy of MathJax to the current release version. If you
keep MathJax updated in this way, you will be sure that you have the
latest bug fixes and new features as they become available.
-This gets you the current development copy of MathJax, which is the
-"bleeding-edge" version that contains all the latest changes to
-MathJax. At times, however, these may be less stable than the
-"release" version. If you prefer to use the most stable version (that
-may not include all the latest patches and features), use ``git tag
--l`` to see all versions and use ``git checkout <tag_name>`` to
-checkout that version of MathJax. When you want to upgrade to a new
-release, you will need to repeat this for the latest release tag.
+This gets you the current development copy of MathJax, which is the version
+that contains all the latest changes to MathJax. Although we try to make
+sure this version is a stable and usable version of MathJax, it is under
+active development, and at times it may be less stable than the "release"
+version. If you prefer to use the most stable version (that may not
+include all the latest patches and features), use ``git tag -l`` to see all
+versions and use ``git checkout <tag_name>`` to checkout that version of
+MathJax. When you want to upgrade to a new release, you will need to
+repeat this for the latest release tag.
.. _getting-mathjax-svn:
@@ -66,11 +73,11 @@ Obtaining MathJax via SVN
If you are more comfortable with the `subversion
<http://subversion.apache.org/>`_ source control system, you may want
to use GitHub's ``svn`` service to obtain MathJax. If you want to get the
-latest revision using ``svn``, use the commands
+latest revision using ``svn``, use the command
.. code-block:: sh
- svn checkout http://svn.github.com/mathjax/MathJax.git mathjax
+ svn checkout http://svn.github.com/mathjax/MathJax.git MathJax
to obtain and set up a copy of MathJax. Note that there is no longer
a ``fonts.zip`` file, and that the ``fonts`` directory is now part of
@@ -80,7 +87,7 @@ Whenever you want to update MathJax, you can now use
.. code-block:: sh
- cd mathjax
+ cd MathJax
svn status -u
to check if there are updates to MathJax. If MathJax needs updating,
@@ -88,19 +95,20 @@ use
.. code-block:: sh
- cd mathjax
+ cd MathJax
svn update
to udpate your copy of MathJax to the current release version. If you
keep MathJax updated in this way, you will be sure that you have the
latest bug fixes and new features as they become available.
-This gets you the current development copy of MathJax, which is the
-"bleeding-edge" version that contains all the latest changes to
-MathJax. At times, however, these may be less stable than the
-"release" version. If you prefer to use one of the tagged releases
-instead, then either use ``git`` as described above, or one of the
-archive files as described below. You can use
+This gets you the current development copy of MathJax, which is the version
+that contains all the latest changes to MathJax. Although we try to make
+sure this version is a stable and usable version of MathJax, it is under
+active development, and at times it may be less stable than the "release"
+version. If you prefer to use one of the tagged releases instead, then
+either use ``git`` as described above, or one of the archive files as
+described below. You can use
.. code-block:: sh
@@ -134,10 +142,19 @@ let you refer to the main MathJax file as ``/MathJax/MathJax.js`` from
within any page on your server.
From the `MathJax GitHub download link
-<http://github.com/mathjax/mathjax/>`_ (the big download button at the
+<http://github.com/mathjax/mathjax/>`_ (the download button at the
right), you can also select the ``Download .tar.gz`` or ``Download
-.zip`` buttons to get a copy of the current "bleeding-edge" version of
-MathJax that contains all the latest changes and bug-fixes.
+.zip`` buttons to get a copy of the current development version of
+MathJax that contains all the latest changes and bug-fixes.
+
+If a packaged release recevies any important updates, then those updates
+will be part of the `branch` for that version. The link to the ``.zip``
+file in the download list will be the original release version, not the
+patched version. To obtain the patched version, use the `Branches` drop
+down menu (at the far left of the menus within the page) to select the the
+release branch, and then use the downlaod button and the ``Downlaod
+.tar.gz`` or ``Download .zip`` button to get the latest patched version of
+that release.
Testing your installation
@@ -156,8 +173,7 @@ properly. If you have installed MathJax on a server, use the web
address for those files rather than opening them locally. When you
view the ``index.html`` file, you should see (after a few moments) a
message that MathJax appears to be working. If not, you should check
-that the files have been transferred to the server completely, that
-the fonts archive has been unpacked in the correct location, and that
+that the files have been transferred to the server completely, and that
the permissions allow the server to access the files and folders that
are part of the MathJax directory (be sure to verify the MathJax
folder's permissions as well). Checking the server logs may help
@@ -177,29 +193,27 @@ a different site. For example, a departmental server at
installation at ``www.yourcollege.edu`` rather than installing a
separate copy on the departmental machine. MathJax can certainly
be loaded from another server, but there is one imporant caveat ---
-Firefox's same-origin security policy for cross-domain scripting.
-
-Firefox’s interpretation of the same-origin policy is more strict than
-most other browsers, and it affects how fonts are loaded with the
-`@font-face` CSS directive. MathJax uses this directive to load
-web-based math fonts into a page when the user doesn't have them
-installed locally on their own computer. Firefox's security policy,
-however, only allows this when the fonts come from the same server as
-the web page itself, so if you load MathJax (and hence its web fonts)
-from a different server, Firefox won't be able to access those web
-fonts. In this case, MathJax will pause while waiting for the font to
-download (which will never happen) and will time out after about 15
-seconds for each font it tries to access. Typically that is three or
-four fonts, so your Firefox users will experience a minute or so
-delay before mathematics is displayed, and then it will probably
-display incorrectly because the browser doesn't have access to the
-correct fonts.
+Firefox's and IE9's same-origin security policy for cross-domain scripting.
+
+Firefox's interpretation of the same-origin policy is more strict than most
+other browsers, and it affects how fonts are loaded with the `@font-face`
+CSS directive. MathJax uses this directive to load web-based math fonts
+into a page when the user doesn't have them installed locally on their own
+computer. Firefox's security policy, however, only allows this when the
+fonts come from the same server as the web page itself, so if you load
+MathJax (and hence its web fonts) from a different server, Firefox won't be
+able to access those web fonts. In this case, MathJax will pause while
+waiting for the font to download (which will never happen); it will time
+out after about 5 seconds and switch to image fonts as a fallback.
+Similarly, IE9 has a similar same-origin policy in its `IE9 standards
+mode`, so it exhibits this same behavior.
There is a solution to this, however, if you manage the server where
MathJax is installed, and if that server is running the `Apache web
server <http://www.apache.org/>`_. In the remote server's
``MathJax/fonts/HTML-CSS/TeX/otf`` folder, create a file called
-``.htaccess`` that contains the following lines: ::
+``.htaccess`` that contains the following lines:
+::
<FilesMatch "\.(ttf|otf|eot)$">
<IfModule mod_headers.c>
@@ -207,18 +221,17 @@ server <http://www.apache.org/>`_. In the remote server's
</IfModule>
</FilesMatch>
-and make sure the permissions allow the server to read this file.
-(The file's name starts with a period, which causes it to be an
-"invisible" file on unix-based operating systems. Some systems,
-particularly graphic user interfaces, may not allow you to create such
-files, so you might need to use the command-line interface to
-accomplish this.)
+and make sure the permissions allow the server to read this file. (The
+file's name starts with a period, which causes it to be an "invisible" file
+on unix-based operating systems. Some systems, particularly those with
+graphical user interfaces, may not allow you to create such files, so you
+might need to use the command-line interface to accomplish this.)
-This file should make it possible for pages at other sites to load
-MathJax from this server in such a way that Firefox will be able to
-download the web-based fonts. If you want to restrict the sites that
-can access the web fonts, change the ``Access-Control-Allow-Origin``
-line to something like::
+This file should make it possible for pages at other sites to load MathJax
+from this server in such a way that Firefox and IE9 will be able to
+download the web-based fonts. If you want to restrict the sites that can
+access the web fonts, change the ``Access-Control-Allow-Origin`` line to
+something like::
Header set Access-Control-Allow-Origin "http://www.math.yourcollege.edu"
@@ -231,7 +244,7 @@ for more details.
.. _ff-local-fonts:
-Forefox and Local Fonts
+Firefox and local fonts
=======================
Firefox's same-origin security policy affects its ability to load
@@ -252,3 +265,28 @@ containing the page that uses MathJax. This is an unfortunate
restriction, but it is a limitiation imposed by Firefox's security
model that MathJax can not circumvent. Currently, this is not a
problem for other browsers.
+
+One solution to this problem is to install the MathJax fonts locally, so
+that Firefox will not have to use web-based fonts in the first place. To
+do that, either install the `STIX fonts <http://stixfonts.org>`_, or copy
+the fonts from ``MathJax/fonts/HTML-CSS/TeX/otf`` into your systems fonts
+directory and restart your browser (see the `MathJax fonts help page
+<http://www.mathjax.org/help/fonts>`_ for details).
+
+
+IE9 and remote fonts
+====================
+
+IE9's same-origin policy affects its ability to load web-based fonts, as
+described above. This has implications not ony to cross-domain loading of
+MathJax, but also to the case where you view a local page (with a
+``file://`` URL) that accesses MathJax from a remote site, like the MathJax
+CDN service. In this case, IE9 does **not** honor the
+``Access-Control-Allow-Origin`` setting of the remote server (as it would
+if the web page came from an ``http://`` URL), and so it **never** allows the
+font to be accessed.
+
+One solution to this problem is to install the MathJax fonts locally so
+that MathJax doesn't have to use web-based fonts in the first place. Your
+best bet is to install the `STIX fonts`_ on your system (see the `MathJax
+fonts help page`_ for details).
diff --git a/docs/source/start.rst b/docs/source/start.rst
@@ -46,11 +46,11 @@ This is the most general configuration, and should suffice for most
people's needs. Other configurations are available, however, and you
can also provide additional configuration parameters to taylor one of
the confiogurations to your needs. More details can be found in the
-:ref:`Loading and Configuring MathJax <installation>` instructions.
+:ref:`Loading and Configuring MathJax <loading>` instructions.
The use of ``cdn.mathjax.org`` is governed by its `terms of service
-<http://www.mathjax.org/>`_, so be sure to read that before linked to
-the MathJax CDN server.
+<http://www.mathjax.org/download/mathjax-cdn-terms-of-service/>`_, so be
+sure to read that before linked to the MathJax CDN server.
To see how to enter mathematics in your web pages, see `Putting
mathematics in a web page`_ below.
@@ -128,10 +128,10 @@ output in MathML form if the user's browser supports that, and will use
HTML-with-CSS to render the mathematics otherwise.
There are a number of other prebuilt configuration files that you can
-choose from as well, or you could use the ``config/default.js`` file
-and customize the settings yourself. The combined configuration files
-are described more fully in :ref:`Installing and Configuring MathJax
-<installation>`, and the configuration options are described in
+choose from as well, or you could use the ``config/default.js`` file and
+customize the settings yourself. The combined configuration files are
+described more fully in :ref:`Common Configurations
+<common-configurations>`, and the configuration options are described in
:ref:`Configuration Options <configuration>`.
Note: The configuration process has changed in MathJax v1.1, so if you have
@@ -218,7 +218,7 @@ one, and" to be treated as mathematics since it falls between dollar
signs. For this reason, if you want to use single-dollars for in-line
math mode, you must enable that explicitly in your configuration:
-.. code-block:: javascript
+.. code-block:: html
<script type="text/x-mathjax-config">
MathJax.Hub.Config({
@@ -229,11 +229,13 @@ math mode, you must enable that explicitly in your configuration:
See the ``config/default.js`` file, or the :ref:`tex2jax configuration
options <configure-tex2jax>` page, for additional configuration
-parameters that you can specify for the ``tex2jax`` preprocessor,
+parameters that you can specify for the `tex2jax` preprocessor,
which is the component of MathJax that identifies TeX notation within
-the page).
+the page). See the :ref:`TeX and LaTeX <TeX-support>` page for
+more on MathJax's support for TeX.
-Here is a complete sample page containing TeX mathematics:
+Here is a complete sample page containing TeX mathematics (also available
+in the ``test/sample-tex.html`` file):
.. code-block:: html
@@ -241,12 +243,15 @@ Here is a complete sample page containing TeX mathematics:
<html>
<head>
<title>MathJax TeX Test Page</title>
+ <script type="text/x-mathjax-config">
+ MathJax.Hub.Config({tex2jax: {inlineMath: [['$','$'], ['\\(','\\)']]}});
+ </script>
<script type="text/javascript"
- src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
+ src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
</script>
</head>
<body>
- When \(a \ne 0\), there are two solutions to \(ax^2 + bx + c = 0\) and they are
+ When $a \ne 0$, there are two solutions to \(ax^2 + bx + c = 0\) and they are
$$x = {-b \pm \sqrt{b^2-4ac} \over 2a}.$$
</body>
</html>
@@ -292,7 +297,8 @@ than HTML, you should not include a namespace prefix for your
``<math>`` tags; for example, you should not use ``<m:math>`` except
in a file where you have tied the ``m`` namespace to the MathML DTD.
-Here is a complete sample page containing MathML mathematics:
+Here is a complete sample page containing MathML mathematics (also
+available in the ``test/sample-mml.html`` file):
.. code-block:: html
@@ -301,7 +307,7 @@ Here is a complete sample page containing MathML mathematics:
<head>
<title>MathJax MathML Test Page</title>
<script type="text/javascript"
- src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
+ src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
</script>
</head>
<body>
@@ -342,25 +348,20 @@ should use
.. code-block:: html
- <mspace width="5pt"></mspace>
-
-rather than
-
-.. code-block:: html
-
- <mspace width="5pt" />
+ <mspace width="thinmathspace"></mspace>
-in an HTML document. If you use the self-closing form, some browsers
-will not build the math tree properly, and MathJax will receive a
-damaged math structure, which will not be rendered as the original
-notation would have been. Unfortunately, there is nothing MathJax can
-do about that, since the browser has incorrectly interpreted the tags
-long before MathJax has a chance to work with them.
+rather than ``<mspace width="5pt" />`` in an HTML document. If you use the
+self-closing form, some browsers will not build the math tree properly, and
+MathJax will receive a damaged math structure, which will not be rendered
+as the original notation would have been. Unfortunately, there is nothing
+MathJax can do about that, since the browser has incorrectly interpreted
+the tags long before MathJax has a chance to work with them.
The component of MathJax that recognizes MathML notation is called the
-``mml2jax`` extension, and it has only a few configuration options; see the
+`mml2jax` extension, and it has only a few configuration options; see the
``config/default.js`` file or the :ref:`mml2jax configuration options
-<configure-mml2jax>` page for more details.
+<configure-mml2jax>` page for more details. See the :ref:`MathML
+<MathML-support>` page for more on MathJax's MathML support.
Where to go from here?
@@ -372,7 +373,7 @@ able to use it to write web pages that include mathematics. At this
point, you can start making pages that contain mathematical content!
You could also read more about the details of how to :ref:`customize
-MathJax <configuration>`.
+MathJax <loading>`.
If you are trying to use MathJax in blog or wiki software or in some
other content-management system, you might want to read about :ref:`using
diff --git a/docs/source/upgrade.rst b/docs/source/upgrade.rst
@@ -0,0 +1,234 @@
+.. _upgrade:
+
+***********************************
+Migrating from MathJax v1.0 to v1.1
+***********************************
+
+MathJax v1.1 fixes a number of bugs in v1.0, and improves support for
+new versions of browsers and mobile devices. It includes changes to
+increase its performance, and to make it more compliant with HTML5. It
+has more flexible configuration options, and the ability to load
+configuration files that combine multiple files into a single one to
+increase loading speed when MathJax starts up. Finally, MathJax.org now
+offers MathJax as a web service through a distributed "cloud" server.
+
+This document describes the changes you may need to make to your MathJax
+configurations in order to take advantage of these improvements.
+
+
+Configuration Changes
+=====================
+
+The main changes that you will see as a page author are in the way that
+MathJax can be loaded and configured. If you have been using in-line
+configuration by putting a :meth:`MathJax.Hub.Config()` call in the body of
+the ``<script>`` tag that loads MathJax, then your site should work
+unchanged with version 1.1 of MathJax. You may wish to consider moving to
+the new HTML5-compliant method of configuring MathJax, however, which uses
+a separate ``<script>`` tag to specify the configuration. That tag should
+come **before** the one that loads ``Mathjax.js``, and should have
+``type="text/x-mathjax-config"`` rather than ``type="text/javascript"``.
+For example,
+
+.. code-block:: html
+
+ <script type="text/javascript" src="/MathJax/MathJax.js">
+ MathJax.Hub.Config({
+ jax: ["input/TeX","output/HTML-CSS"],
+ extensions: ["tex2jax.js"]
+ });
+ </script>
+
+would become
+
+.. code-block:: html
+
+ <script type="text/x-mathjax-config">
+ MathJax.Hub.Config({
+ jax: ["input/TeX","output/HTML-CSS"],
+ extensions: ["tex2jax.js"]
+ });
+ </script>
+ <script type="text/javascript" src="/MathJax/MathJax.js"></script>
+
+instead. This will make sure your pages pass HTML5 validation. Be sure
+that you put the configuration block **before** the script that loads
+MathJax. See :ref:`Loading and Configuring MathJax <loading>` for more
+details.
+
+If your page simply loads ``MathJax.js`` and relies on
+``config/MathJax.js``, then you will need to modify your ``<script>`` tag
+in order to use MathJax v1.1. This is because MathJax no longer loads a
+default configuration file; you are required to explicity specify the
+configuration file if you use one. Furthermore, the name of the
+``config/MathJax.js`` file was a source of confusion, so it has been
+renamed ``config/default.js`` instead. Thus, if you used
+
+.. code-block:: html
+
+ <script type="text/javascript" src="/MathJax/MathJax.js"></script>
+
+in the past, you should replace it with
+
+.. code-block:: html
+
+ <script type="text/javascript" src="/MathJax/MathJax.js?config=default"></script>
+
+instead. If you don't do this, you will receive a warning message that
+directs you to a page that explains how to update your script tags to use
+the new configuration format.
+
+
+Combined Configurations
+=======================
+
+New with version 1.1 is the ability to combine several files into a single
+configuration file, and to load that via the same script that loads
+MathJax. This should make configuring MathJax easier, and also helps to
+speed up the initial loading of MathJax's components, since only one file
+needs to be downloaded.
+
+MathJax comes with four pre-built configurations, and our hope is that one
+of these will suit your needs. They are described in more detail in the
+:ref:`Using a Configuration File <config-files>` section. To load one,
+add ``?config=filename`` (where ``filename`` is the name of the
+configuration file without the ``.js``) to the URL that loads
+``MathJax.js``. For example
+
+.. code-block:: html
+
+ <script type="text/javascript" src="/MathJax/MathJax.js">
+ MathJax.Hub.Config({
+ jax: ["input/TeX","output/HTML-CSS"],
+ extensions: ["tex2jax.js","AMSmath.js","AMSsymbols.js"]
+ });
+ </script>
+
+could be replaced by the single line
+
+.. code-block:: html
+
+ <script type="text/javascript" src="/MathJax/MathJax.js?config=TeX-AMS_HTML"></script>
+
+In this way, you don't have to include the in-line configuration, and all
+the needed files will be downloaded when MathJax starts up. For complete
+details about the contents of the combined configuration files, see the
+:ref:`Common Configurations <common-configurations>` section.
+
+If you want to use a pre-defined configuration file, but want to modify some
+of the configuration parameters, you can use both a
+``text/x-mathjax-config`` block and a ``config=filename`` parameter in
+combination. For example,
+
+.. code-block:: html
+
+ <script type="text/x-mathjax-config">
+ MathJax.Hub.Config({
+ TeX: {
+ inlineMath: [ ['$','$'], ['\\(','\\)'] ],
+ processEscapes: true
+ }
+ });
+ </script>
+ <script type="text/javascript" src="/MathJax/MathJax.js?config=TeX-AMS_HTML"></script>
+
+would load the ``TeX-AMS_HTML`` configuration file, but would reconfigure
+the inline math delimiters to include ``$...$`` in addition to
+``\(...\)``, and would set the ``processEscapes`` parameter to ``true``.
+
+
+Loading MathJax from the CDN
+============================
+
+The MathJax installation is fairly substantial (due to the large number of
+images needed for the image fonts), and so you may not want to (or be able
+to) store MathJax on your own server. Keeping MathJax up to date can also
+be a maintenance problem, and you might prefer to let others handle that
+for you. In either case, using the MathJax distributed network service may be
+the best way for you to obtain MathJax. That way you can be sure you are
+using an up-to-date version of MathJax, and that the server will be fast
+and reliable.
+
+To use the MathJax CDN service, simply load MathJax as follows:
+
+.. code-block:: html
+
+ <script type="text/javascript"
+ src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
+ </scrip>
+
+Of course, you can load any configuration file that you wish, or use a
+``text/x=mathajx-config`` block to configure MathJax in-line.
+:ref:`More details <loading-CDN>` are available, if you need them.
+
+The use of ``cdn.mathjax.org`` is governed by its `terms of service
+<http://www.mathjax.org/download/mathjax-cdn-terms-of-service/>`_, so be
+sure to read that before linked to the MathJax CDN server.
+
+
+Change in default TeX delimiters
+================================
+
+In addition to the fact that MathJax v1.1 no longer loads a default
+configuration file, there is a second configuration change that could
+affect your pages. The ``config/MathJax.js`` file properly configured the
+`tex2jax` preprocessor to use only ``\(...\)`` and not ``$...$`` for in-line
+math delimiters, but the `tex2jax` preprocessor itself incorrectly
+defaulted to including ``$...$`` as in-line math delimiters. The result
+was that if you used in-line configuration to specify the ``tex2jax``
+preprocessor, single-dollar delimiters were enabled by default, while if
+you used file-based configuration, they weren't.
+
+This inconsistency was an error, and the correct behavior was supposed to
+have the single-dollar delimiters disabled in both cases. This is now
+true in v1.1 of MathJax. This means that if you used in-line
+configuration to specify the `tex2jax` preprocessor, you will need to
+change your configuration to explicitly enable the single-dollar
+delimiters if you want to use them.
+
+For example, if you had
+
+.. code-block:: html
+
+ <script type="text/javascript" src="/MathJax/MathJax.js">
+ MathJax.Hub.Config({
+ jax: ["input/TeX","output/HTML-CSS"],
+ extensions: ["tex2jax.js"]
+ });
+ </script>
+
+and you want to use single-dollar delimiters for in-line math, then you
+should replace this with
+
+.. code-block:: html
+
+ <script type="text/x-mathjax-config">
+ MathJax.Hub.Config({
+ jax: ["input/TeX","output/HTML-CSS"],
+ extensions: ["tex2jax.js"],
+ tex2jax: {
+ inlineMath: [ ['$','$'], ['\\(','\\)'] ],
+ processEscapes: true
+ }
+ });
+ </script>
+ <script type="text/javascript" src="/MathJax/MathJax.js"></script>
+
+The same technique can be used in conjunction with a combined
+configuration file. For example
+
+.. code-block:: html
+
+ <script type="text/x-mathjax-config">
+ MathJax.Hub.Config({
+ tex2jax: {
+ inlineMath: [ ['$','$'], ['\\(','\\)'] ],
+ processEscapes: true
+ }
+ });
+ </script>
+ <script type="text/javascript" src="/MathJax/MathJax.js?config=TeX-AMS_HTML"></script>
+
+will load the pre-defined ``TeX-AMS_HTML`` configuration, but will modify
+the settings to allow ``$...$`` delimiters, and to process ``\$`` to
+produce dollar signs within the text of the page.
diff --git a/docs/source/whats-new.rst b/docs/source/whats-new.rst
@@ -0,0 +1,172 @@
+.. _whats-new:
+
+**************************
+What's New in MathJax v1.1
+**************************
+
+MathJax version 1.1 includes a number of important improvements and
+enhancements over version 1.0. We have worked hard to fix bugs, improve
+support for browsers and mobile devices, supprot TeX and MathML better, and
+increase MathJax's performance.
+
+In addition to these changes, MathJax.org now offers MathJax as a network
+service. Instead of having to install MathJax on your own server, you can
+link to our content delivery network (CDN) to get fast access to
+up-to-date and past versions of MathJax. See :ref:`Loading MathJax from
+the CDN <loading-CDN>` for more details.
+
+The following sections outline the changes in v1.1:
+
+Optimization
+============
+
+* Combined configuraiton files that load all the needed files in one piece
+ rather than loading them individually. This simplifies configuration
+ and speeds up typsetting of the mathematics on the page.
+
+* Improved responsiveness to mouse events during typesetting.
+
+* Parallel downloading of files needed by MathJax, for faster startup
+ times.
+
+* Shorter timeout for web fonts, so if they can't be downlaoded, you don't
+ have to wait so long.
+
+* Rollover to image fonts if a web font fails to load (so you don't have
+ to wait for *every* font to fail.
+
+* The MathJax files are now packed only with `yuicompressor` rather than a
+ custom compressor. The CDN serves gzipped versions, which compressed
+ better than the gzipped custom-packed files.
+
+* Improved rendering speed in IE by removing ``position:relative`` from
+ the style for mathematics.
+
+* Improve rendering speed for most browsers by isolating the mathematics
+ from page during typesetting (avoids full page reflows).
+
+
+Enhancements
+============
+
+* Allow the input and output jax configuration blocks to specify extensions
+ to be loaded when the jax is loaded (this avoids needing to load them up
+ front, so they don't have to be loaded on pages that don't include
+ mathematics, for example).
+
+* Better handling of background color from style attributes.
+
+* Ability to pass configuration parameters via script URL.
+
+* Support HTML5 compliant configuration syntax.
+
+* Switch the Git repository from storing the fonts in `fonts.zip` to
+ storing the `fonts/` directory directly.
+
+* Improved About box.
+
+* add a minimum scaling factor (so math won't get too small)
+
+
+TeX Support
+============
+
+* Added support for ``\href``, ``\style``, ``\class``, ``\cssId``.
+* Avoid recursive macro definitions and other resource consumption possibilities.
+* Fix for ``\underline`` bug.
+* Fix for bug with ``\fbox``.
+* Fix height problem with ``\raise`` and ``\lower``.
+* Fix problem with ``\over`` used inside array entries.
+* Fix problem with nesting of math delimiters inside text-mode material.
+* Fix single digit super- and subscripts followed by punctuation.
+* Make sure `movablelimits` is off for ``\underline`` and related macros.
+* Fix problem with dimensions given with ``pc`` units.
+
+
+MathML Support
+==============
+
+* Fix ``<`` and ``&`` being translated too early.
+* Handle self-closing tags in HTML files better.
+* Combine adjacent relational operators in ``<mo>`` tags.
+* Fix entity name problems.
+* Better support for MathML namespaces.
+* Properly handle comments within MathML in IE.
+* Properly consider ``<mspace>`` and ``<mtext>`` as space-like.
+* Improved support for ``<maction>`` with embelished operators.
+
+
+Other Bug Fixes
+===============
+
+* Fixed CSS bleed through with zoom and other situations.
+* Fixed problems with ``showMathMenuMSIE`` when set to ``false``.
+* Replaced illegal prefix characters in cookie name.
+* Improve placement of surd for square roots and n-th roots.
+* Fixed layer obscuring math from MathPlayer for screen readers.
+* Newlines in CDATA comments are now handled properly.
+* Resolved conflict between `jsMath2jax` and `tex2jax` both processing the
+ same equation.
+* Fixed problem with ``class="tex2jax_ignore"`` affecting the processing of
+ sibling elements.
+
+
+Browser Support
+===============
+
+**Android**
+
+* Added detection and configuration for Android browser.
+* Allow use of OTF web fonts in Android 2.2.
+
+
+**Blackberry**
+
+* MathJax now works with OS version 6.
+
+
+**Chrome**
+
+* Use OTF web fonts rather than SVG fonts for version 4 and above.
+
+
+**Firefox**
+
+* Added Firefox 4 detection and configuration.
+* Fix for extra line-break bug when displayed equations are in
+ preformatted text.
+* Update fonts so that FF 3.6.13 and above can read them.
+
+
+**Internet Explorer**
+
+* Changes for compatibility with IE9.
+* Fix for IE8 incorrectly parsing MathML.
+* Fix for IE8 namespace problem.
+* Fix for null ``parentNode`` problem.
+* Fix for ``outerHTML`` not quoting values of attributes.
+
+**iPhone/iPad**
+
+* Add support for OTF web fonts in iOS4.2.
+
+**Nokia**
+
+* MathJax now works with Symbian\ :sup:`3`\ .
+
+**Opera**
+
+* Prevent Opera from using STIX fonts unless explicitly requested via the
+ font menu (since Opera can't display many of the characters).
+* Fix for bad em-size detection in 10.61.
+* Fixed a problem with the About dialog in Opera 11.
+
+
+**Safari**
+
+* Use OTF web fonts for Safari/PC.
+
+
+**WebKit**
+
+* Better version detection.
