diff --git a/docs/source/config-files.rst b/docs/source/config-files.rst
new file mode 100644
index 000000000..ccc0321a9
--- /dev/null
+++ 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
+
+
+
+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 ` 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 ` section for
+other configuration options for the ``tex2jax`` preprocessor, and the
+:ref:`TeX input jax configuration ` section for options
+that control the TeX input processor.
+See the :ref:`mml2jax configuration ` section for
+other configuration options for the ``mml2jax`` preprocessor, and the
+:ref:`MathML input jax configuration ` section for
+options that control the MathML input processor.
+See :ref:`MathJax Output Formats ` for more
+information on the NativeMML and HTML-CSS output processors. See the
+:ref:`MMLorHTML configuration ` 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 ` section for
+other configuration options for the ``tex2jax`` preprocessor, and the
+:ref:`TeX input jax configuration ` section for options
+that control the TeX input processor.
+See :ref:`MathJax 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 ` section for
+other configuration options for the ``mml2jax`` preprocessor, and the
+:ref:`MathML input jax configuration ` section for
+options that control the MathML input processor.
+See :ref:`MathJax Output Formats ` for more
+information on the NativeMML and HTML-CSS output processors. See the
+:ref:`MMLorHTML configuration ` 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
index 25d9c220b..dcca5f2e0 100644
--- 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 ``
-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
+
+
+
+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
-` 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 ` 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 ` section. A
+typical invocation of MathJax would be
+
+.. code-block:: html
+
+
+
+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 ```` block, but it
is also possible to load MathJax into the ```` section, if
@@ -51,325 +75,344 @@ been prepared, for example, via a `GreaseMonkey
advanced topic, however; see :ref:`Loading MathJax Dynamically
` for more details.
+.. _loading-CDN:
+
+Loading MathJax from the CDN
+============================
+
+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.
+
+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.
+
+The URL that you use to obtain MathJax determines the version that you
+get. The CDN has the following directory structure:
+
+.. code-block:: sh
+
+ 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)
+
+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).
+
+We may occasionally introduce directories for betas, as indicated above,
+but they will be temprorary, and will be removed after the official
+release.
+
+To load from a particular release, use the directory for that release.
+For example,
+
+.. code-block:: html
+
+
+
+will load the stable v1.1 version, even if we release v1.2 or other later
+versions, while
+
+.. code-block:: html
+
+
+
+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.
+
+The use of ``cdn.mathjax.org`` is governed by its `terms of service
+`_, so be
+sure to read that before linked to the MathJax CDN server.
+
Configuring MathJax
===================
-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
-` 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
+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
+`_ 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:: html
-
-
-it will load ``config/MathJax.js`` automatically as one of its
-first actions.
-
-Alternatively, you can configure MathJax efficiently by calling
-:meth:`MathJax.Hub.Config()` when you include MathJax in your page, as
-follows:
-
-.. code-block:: html
-
-
-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 ` 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.
+loads the ``config/TeX-AMS-MML_HTMLorMML.js`` configuration file from the
+MathJax distributed network service.
-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
+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
-
-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.
+to first load the main configuraiton, then the local modifications.
-.. _common-configurations:
+Using in-line configuration options
+===================================
-Common Configurations
-=====================
+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 ``
+
+
-MathML input and output in all browsers
----------------------------------------
+.. _delayStartupUntil:
-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.
+Configuring MathJax after it is loaded
+======================================
-.. code-block:: javascript
+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.
- MathJax.Hub.Config({
- config: ["MMLorHTML.js"],
- extensions: ["mml2jax.js"],
- jax: ["input/MathML"]
- });
+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.
-Using this configuration, MathJax finally makes MathML available in
-all modern browsers.
+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 ``
+
+in your theme's header file, and
+
+.. code-block:: html
+
+
+
+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.
-.. _configuration:
+Details of the MathJax configuration process
+============================================
-Configuration Objects
-=====================
+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:
-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.
+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 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.
-
-For example,
-
-.. 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]
- }
- }
- });
-
-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).
-
-The ``config/MathJax.js`` file is another example that shows nearly
-all the configuration options for all of MathJax's components.
+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.
-Configuration Options by Component
-==================================
-
-The individual options are explained in the following sections, which
-are categorized by the component they affect.
-
-.. toctree::
- :maxdepth: 1
-
- The core options
-
-.. toctree::
- :maxdepth: 1
-
- The tex2jax preprocessor options
- The mml2jax preprocessor options
- The jsMath2jax preprocessor options
-
-.. toctree::
- :maxdepth: 1
-
- The TeX input processor options
- The MathML input processor options
- The HTML-CSS output processor options
- The NativeMML output processor options
- The MMLorHTML configuration options
-
-.. toctree::
- :maxdepth: 1
-
- The MathMenu options
- The MathZoom options
- The FontWarnings options
-
-
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 23a387c52..80df118de 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -15,6 +15,8 @@ Basic Usage
Getting Started with MathJax
Installing and Testing MathJax
Loading and Configuring MathJax
+ Common MathJax Configurations
+ MathJax Configuration Options
Using MathJax in Web Platforms
.. toctree::
@@ -30,6 +32,19 @@ Basic Usage
The MathJax Community
+.. _upgrading-MathJax:
+
+Upgrading MathJax
+=================
+
+.. toctree::
+ :maxdepth: 1
+
+ What's New in MathJax v1.1
+ Migrating from MathJax v1.0 to v1.1
+ Converting to MathJax from jsMath
+
+
.. _advanced-topics:
Advanced Topics
@@ -49,10 +64,6 @@ Advanced Topics
Details of the MathJax API
-.. toctree::
- :maxdepth: 1
-
- Converting to MathJax from jsMath
Reference Pages
===============
@@ -66,6 +77,12 @@ Reference Pages
* :ref:`Search `
+* `User Help Pages `_:
+
+ + `MathJax Font Help `_
+ + `MathJax Contextual Menu `_
+ + `MathJax Zoom Feature `_
+
--------
This version of the documentation was built |today|.
diff --git a/docs/source/installation.rst b/docs/source/installation.rst
index a7e474bf4..9044ba95f 100644
--- 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
+`). 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 `.
+
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
`_ version control system to access our `GitHub repository
-`_. Use the commands
+`_. 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 `` 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 `` 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
`_ 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
-`_ (the big download button at the
+`_ (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 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) 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 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 `_. 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:
+::
@@ -207,18 +221,17 @@ server `_. In the remote server's
-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 `_, 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
+`_ 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
index b4125519e..ffa228019 100644
--- 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 ` instructions.
+:ref:`Loading and Configuring MathJax ` instructions.
The use of ``cdn.mathjax.org`` is governed by its `terms of service
-`_, so be sure to read that before linked to
-the MathJax CDN server.
+`_, 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
-`, 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
+`, and the configuration options are described in
:ref:`Configuration Options `.
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
- 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}.$$
@@ -292,7 +297,8 @@ than HTML, you should not include a namespace prefix for your
``