suzanne.soy/scribble-mathjax
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Break configuration into three parts, add upgrade and what's new, and update installation, loading, and configuration documents

Browse Source
This commit is contained in:
Davide P. Cervone 2011-03-07 20:44:55 -05:00
parent 155436ba97
commit b6d16ccd10
7 changed files with 1086 additions and 389 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

192
docs/source/config-files.rst Normal file
View File

@ -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.

639
docs/source/configuration.rst
View File

@ -6,18 +6,28 @@ Loading and Configuring MathJax
You load MathJax into a web page by including its main JavaScript file 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 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: section of your document:
.. code-block:: html .. code-block:: html
<script type="text/javascript" src="path-to-MathJax/MathJax.js"></script> <script type="text/javascript" src="path-to-MathJax/MathJax.js"></script>
where ``path-to-MathJax`` is replaced by the URL of the MathJax where ``path-to-MathJax`` is replaced by the URL of the copy of MathJax
directory on your server, or (if you are using MathJax locally rather that you are loading. For example, if you are using the MathJax
than through a server) the location of that directory on your hard distributed network service, the tag might be
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
<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 .. code-block:: html
@ -25,15 +35,29 @@ your web server's directory hierarchy, you might use
to load MathJax. to load MathJax.
Although it is possible to load MathJax from a site other than your If you install MathJax on a server in a domain that is different from the
own web server, there are issues involved in doing so that you need to one containing the page that will load MathJax, then there are issues
take into consideration. See the :ref:`Notes About Shared Servers involved in doing so that you need to take into consideration. See the
<cross-domain-linking>` for more details. Please do **not** link to :ref:`Notes About Shared Servers <cross-domain-linking>` for more details.
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 When you load MathJax, it is common to include additional parameters for
would like to display mathematics. If you are able to run MathJax MathJax as part of the URL. These control MathJax's configuration, and are
from your own server, please do so (this will probably give you better discussed in the :ref:`Configuration Objects <configuration>` section. A
response time in any case). 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 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 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 advanced topic, however; see :ref:`Loading MathJax Dynamically
<ajax-mathjax>` for more details. <ajax-mathjax>` 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
<script type="text/javascript" src="http://cdn.mathjax.org/mathjax/1.1-latest/MathJax.js"></script>
will load the stable v1.1 version, even if we release v1.2 or other later
versions, while
.. code-block:: html
<script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js"></script>
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
<http://www.mathjax.org/download/mathjax-cdn-terms-of-service/>`_, so be
sure to read that before linked to the MathJax CDN server.
Configuring MathJax Configuring MathJax
=================== ===================
There are several ways to configure MathJax, but the easiest is to use There are two ways to configure MathJax: via a configuration file, or by
the ``config/MathJax.js`` file that comes with MathJax. See the including configuration commands wthin the web page itself. These can be
comments in that file, or the :ref:`configuration details used independently, or in combination. For example, you can load a main
<configuration>` section, for explanations of the meanings of the various pre-defined configuration file, but include in-line commands to
configuration options. You can edit the ``config/MathJax.js`` file to adjust the configuration to your needs.
change any of the settings that you want to customize. When you
include MathJax in your page via 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:: html .. code-block:: html
<script type="text/javascript" src="path-to-MathJax/MathJax.js"></script> <script type="text/javascript"
src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
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
<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> </script>
This example includes the ``tex2jax`` preprocessor and configures it loads the ``config/TeX-AMS-MML_HTMLorMML.js`` configuration file from the
to use both the standard TeX and LaTeX math delimiters. It uses the MathJax distributed network service.
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 You can include more than one configuration file by separating them with
files (like ``config/MathJax.js``, but with different settings in each commas. For example, if you have a locally defined configuration file
one), you can copy ``config/MathJax.js`` to ``config/MathJax-2.js``, called ``MathJax/config/local/local.js`` that modifies the settings for the
or some other convenient name, and use ``TeX-AMS_HML`` configuration, defines some new TeX macros, and so on, you
can use
.. code-block:: html .. code-block:: html
<script type="text/javascript" src="path-to-MathJax/MathJax.js"> <script type="text/javascript"
MathJax.Hub.Config({ config: "MathJax-2.js" }); src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS_HTML,local/local.js">
</script> </script>
to load the alternative configuration file ``config/MathJax-2.js`` to first load the main configuraiton, then the local modifications.
from the MathJax ``config`` directory. In this way, you can have as
many distinct configuration files as you need.
.. _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 ``<script>`` tag that loads ``MathJax.js``, but HTML5 makes
it illegal to have content for a script with a ``src`` attribute.
The following examples show configurations that are useful for some MathJax solves this problem by using separate ``<script>`` tags to perform
common situations. This is certainly not an exhaustive list, and configuration for MathJax. Because MathJax starts its configuration
there are variations possible for any of them. Again, the comments in process as soon as it is loaded, the configuration script must come
the ``config/MathJax.js`` file can help you decide what settings to **before** the script tag that loads ``MathJax.js`` itself. You do this
include, even if you are using the in-line configuration method. 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.
The TeX setup For instance,
-------------
This example calls the ``tex2jax`` preprocessor to identify .. code-block:: html
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:: javascript <script type="text/x-mathjax-config">
MathJax.Hub.Config({
MathJax.Hub.Config({
extensions: ["tex2jax.js","TeX/AMSmath.js","TeX/AMSsymbols.js"],
jax: ["input/TeX","output/HTML-CSS"],
tex2jax: {
inlineMath: [['$','$'],["\\(","\\)"]],
processEscapes: true,
},
});
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.
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 MathML setup
----------------
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.
.. code-block:: javascript
MathJax.Hub.Config({
extensions: ["mml2jax.js"],
jax: ["input/MathML","output/HTML-CSS"]
});
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.
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.
Both TeX and MathML
-------------------
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.
.. code-block:: javascript
MathJax.Hub.Config({
extensions: ["tex2jax.js", "mml2jax.js"],
jax: ["input/TeX", "input/MathML", "output/HTML-CSS"],
});
Notice that no ``tex2jax`` configuration section is included, so it
uses its default options (no single dollar signs for in-line math).
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.
TeX input with MathML output
----------------------------
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.
.. code-block:: javascript
MathJax.Hub.Config({
config: ["MMLorHTML.js"],
extensions: ["tex2jax.js"], extensions: ["tex2jax.js"],
jax: ["input/TeX"] 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">
With this setup, Firefox or Internet Explorer with the `MathPlayer This example includes the `tex2jax` preprocessor and configures it to use
plugin <http://www.dessci.com/en/products/mathplayer/>`_ installed both the standard :term:`TeX` and :term:`LaTeX` math delimiters. It uses
will use the NativeMML output processor, while all other browsers will the `TeX` input processor and the `HTML-CSS` output processor, and forces the
use the HTML-CSS output processor. Since native MathML support is HTML-CSS processor to use the TeX fonts rather that other locally installed
faster than MathJax's HTML-CSS processor, this will mean that the web fonts (e.g., :term:`STIX` fonts). See the :ref:`configuration options
pages will display faster for Firefox and IE than they would <configuration>` section (or the comments in the ``config/default.js``
otherwise. This speed comes at the cost, however, as you are now file) for more information about the configuration options that you can
relying on the native MathML support to render the mathematics, and include in the :meth:`MathJax.Hub.Config()` call. Note that this
that is outside of MathJax's control. There may be spacing or other configuration does **not** load any pre-defined configuration file.
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 Note that you can combine in-line configuration with file-based
information on the NativeMML and HTML-CSS output processors. See the configuration, simply include ``text/x-mathjax-config`` scripts as above,
:ref:`MMLorHTML configuration <configure-MMLorHTML>` section for but also include ``config=filename`` when you load the ``MathJax.js``
details on the options that control the ``MMLorHTML`` configuration. 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:
.. code-block:: html
<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>
MathML input and output in all browsers .. _delayStartupUntil:
---------------------------------------
This example configures MathJax to look for MathML within your page, Configuring MathJax after it is loaded
and to display it using the browser's native MathML support, if ======================================
possible, or its HTML-CSS output if not.
.. 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({ One such situation is when you have a site that loads MathJax as part of a
config: ["MMLorHTML.js"], theme or template, but want to be able to modify the configuration on
extensions: ["mml2jax.js"], specific pages of the site. To accomplish this, you need to ask MathJax
jax: ["input/MathML"] 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 You can set ``delayStartupUntil=onload`` in order to prevent MathJax from
all modern browsers. 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.)
See the :ref:`MMLorHTML configuration <configure-MMLorHTML>` section You can set ``delayStartupUntil=configured`` in order to delay the startup
for details on the options that control the ``MMLorHTML`` configuration until the :meth:`MathJax.Hub.Configured()` method is
configuration file, the :ref:`MathML configuration <configure-MathML>` called. This allows you to delay startup until later on the page, but
section for the options that control the MathML output processor, and then restart MathJax configuration process as soon as possible rather than
the :ref:`mml2jax configuration <configure-mml2jax>` section for the waiting for the entire page to load. For example, you could use
options that control the ``mml2jax`` preprocessor.
.. code-block:: html
<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
.. code-block:: html
<script type="text/javascript">
MathJax.Hub.Configured()
</script>
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 1. Process any configuration file explicitly specified as a script parameter.
processors, its preprocessors, its extensions, and the MathJax core, 2. Process the in-line script body (deprecated), if present.
all can be configured through the ``config/MathJax.js`` file, or via a 3. If delayed startup is requested, wait for the indicated signal.
:meth:`MathJax.Hub.Config()` call (indeed, if you look closely, you 4. Process ``text/x-mathjax-config`` config blocks.
will see that ``config/MathJax.js`` is itself one big call to 5. Process any config files queued in the configuration's `config` array
:meth:`MathJax.Hub.Config()`). Anything that is in by earlier config code.
``config/MathJax.js`` can be included in-line to configure MathJax.
The structure that you pass to :meth:`MathJax.Hub.Config()` is a Note that ``text/x-mathjax-config`` script blocks must either precede the
JavaScript object that includes name-value pairs giving the names of ``MathJax.js`` script element, or startup must be delayed. Otherwise, blocks
parameters and their values, with pairs separated by commas. Be that follow the ``MathJax.js`` script element may or may not be available
careful not to include a comma after the last value, however, as some when MathJax runs, and browser-dependent erratic behavior will result.
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.
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 <options/hub>
.. toctree::
:maxdepth: 1
The tex2jax preprocessor options <options/tex2jax>
The mml2jax preprocessor options <options/mml2jax>
The jsMath2jax preprocessor options <options/jsMath2jax>
.. toctree::
:maxdepth: 1
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
The MathMenu options <options/MathMenu>
The MathZoom options <options/MathZoom>
The FontWarnings options <options/FontWarnings>

25
docs/source/index.rst
View File

@ -15,6 +15,8 @@ Basic Usage
Getting Started with MathJax <start> Getting Started with MathJax <start>
Installing and Testing MathJax <installation> Installing and Testing MathJax <installation>
Loading and Configuring MathJax <configuration> Loading and Configuring MathJax <configuration>
Common MathJax Configurations <config-files>
MathJax Configuration Options <options/index>
Using MathJax in Web Platforms <platforms/index> Using MathJax in Web Platforms <platforms/index>
.. toctree:: .. toctree::
@ -30,6 +32,19 @@ Basic Usage
The MathJax Community <community> 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:
Advanced Topics Advanced Topics
@ -49,10 +64,6 @@ Advanced Topics
Details of the MathJax API<api/index> Details of the MathJax API<api/index>
.. toctree::
:maxdepth: 1
Converting to MathJax from jsMath <jsMath>
Reference Pages Reference Pages
=============== ===============
@ -66,6 +77,12 @@ Reference Pages
* :ref:`Search <search>` * :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|. This version of the documentation was built |today|.

148
docs/source/installation.rst
View File

@ -4,6 +4,12 @@
Installing and Testing MathJax 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 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 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 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 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://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 .. 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 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 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 .. code-block:: sh
cd mathjax cd MathJax
git remote show origin git remote show origin
to check if there are updates to MathJax (this will print several 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 .. code-block:: sh
cd mathjax cd MathJax
git pull origin git pull origin
to udpate your copy of MathJax to the current release version. If you 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 keep MathJax updated in this way, you will be sure that you have the
latest bug fixes and new features as they become available. latest bug fixes and new features as they become available.
This gets you the current development copy of MathJax, which is the This gets you the current development copy of MathJax, which is the version
"bleeding-edge" version that contains all the latest changes to that contains all the latest changes to MathJax. Although we try to make
MathJax. At times, however, these may be less stable than the sure this version is a stable and usable version of MathJax, it is under
"release" version. If you prefer to use the most stable version (that active development, and at times it may be less stable than the "release"
may not include all the latest patches and features), use ``git tag version. If you prefer to use the most stable version (that may not
-l`` to see all versions and use ``git checkout <tag_name>`` to include all the latest patches and features), use ``git tag -l`` to see all
checkout that version of MathJax. When you want to upgrade to a new versions and use ``git checkout <tag_name>`` to checkout that version of
release, you will need to repeat this for the latest release tag. MathJax. When you want to upgrade to a new release, you will need to
repeat this for the latest release tag.
.. _getting-mathjax-svn: .. _getting-mathjax-svn:
@ -66,11 +73,11 @@ Obtaining MathJax via SVN
If you are more comfortable with the `subversion If you are more comfortable with the `subversion
<http://subversion.apache.org/>`_ source control system, you may want <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 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 .. 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 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 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 .. code-block:: sh
cd mathjax cd MathJax
svn status -u svn status -u
to check if there are updates to MathJax. If MathJax needs updating, to check if there are updates to MathJax. If MathJax needs updating,
@ -88,19 +95,20 @@ use
.. code-block:: sh .. code-block:: sh
cd mathjax cd MathJax
svn update svn update
to udpate your copy of MathJax to the current release version. If you 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 keep MathJax updated in this way, you will be sure that you have the
latest bug fixes and new features as they become available. latest bug fixes and new features as they become available.
This gets you the current development copy of MathJax, which is the This gets you the current development copy of MathJax, which is the version
"bleeding-edge" version that contains all the latest changes to that contains all the latest changes to MathJax. Although we try to make
MathJax. At times, however, these may be less stable than the sure this version is a stable and usable version of MathJax, it is under
"release" version. If you prefer to use one of the tagged releases active development, and at times it may be less stable than the "release"
instead, then either use ``git`` as described above, or one of the version. If you prefer to use one of the tagged releases instead, then
archive files as described below. You can use either use ``git`` as described above, or one of the archive files as
described below. You can use
.. code-block:: sh .. code-block:: sh
@ -134,11 +142,20 @@ let you refer to the main MathJax file as ``/MathJax/MathJax.js`` from
within any page on your server. within any page on your server.
From the `MathJax GitHub download link 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 right), you can also select the ``Download .tar.gz`` or ``Download
.zip`` buttons to get a copy of the current "bleeding-edge" version of .zip`` buttons to get a copy of the current development version of
MathJax that contains all the latest changes and bug-fixes. 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 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 address for those files rather than opening them locally. When you
view the ``index.html`` file, you should see (after a few moments) a 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 message that MathJax appears to be working. If not, you should check
that the files have been transferred to the server completely, that that the files have been transferred to the server completely, and that
the fonts archive has been unpacked in the correct location, and that
the permissions allow the server to access the files and folders 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 are part of the MathJax directory (be sure to verify the MathJax
folder's permissions as well). Checking the server logs may help 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 installation at ``www.yourcollege.edu`` rather than installing a
separate copy on the departmental machine. MathJax can certainly separate copy on the departmental machine. MathJax can certainly
be loaded from another server, but there is one imporant caveat --- 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 Firefox's interpretation of the same-origin policy is more strict than most
most other browsers, and it affects how fonts are loaded with the other browsers, and it affects how fonts are loaded with the `@font-face`
`@font-face` CSS directive. MathJax uses this directive to load CSS directive. MathJax uses this directive to load web-based math fonts
web-based math fonts into a page when the user doesn't have them into a page when the user doesn't have them installed locally on their own
installed locally on their own computer. Firefox's security policy, computer. Firefox's security policy, however, only allows this when the
however, only allows this when the fonts come from the same server as fonts come from the same server as the web page itself, so if you load
the web page itself, so if you load MathJax (and hence its web fonts) MathJax (and hence its web fonts) from a different server, Firefox won't be
from a different server, Firefox won't be able to access those web able to access those web fonts. In this case, MathJax will pause while
fonts. In this case, MathJax will pause while waiting for the font to waiting for the font to download (which will never happen); it will time
download (which will never happen) and will time out after about 15 out after about 5 seconds and switch to image fonts as a fallback.
seconds for each font it tries to access. Typically that is three or Similarly, IE9 has a similar same-origin policy in its `IE9 standards
four fonts, so your Firefox users will experience a minute or so mode`, so it exhibits this same behavior.
delay before mathematics is displayed, and then it will probably
display incorrectly because the browser doesn't have access to the
correct fonts.
There is a solution to this, however, if you manage the server where 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 MathJax is installed, and if that server is running the `Apache web
server <http://www.apache.org/>`_. In the remote server's server <http://www.apache.org/>`_. In the remote server's
``MathJax/fonts/HTML-CSS/TeX/otf`` folder, create a file called ``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)$"> <FilesMatch "\.(ttf|otf|eot)$">
<IfModule mod_headers.c> <IfModule mod_headers.c>
@ -207,18 +221,17 @@ server <http://www.apache.org/>`_. In the remote server's
</IfModule> </IfModule>
</FilesMatch> </FilesMatch>
and make sure the permissions allow the server to read this file. and make sure the permissions allow the server to read this file. (The
(The file's name starts with a period, which causes it to be an file's name starts with a period, which causes it to be an "invisible" file
"invisible" file on unix-based operating systems. Some systems, on unix-based operating systems. Some systems, particularly those with
particularly graphic user interfaces, may not allow you to create such graphical user interfaces, may not allow you to create such files, so you
files, so you might need to use the command-line interface to might need to use the command-line interface to accomplish this.)
accomplish this.)
This file should make it possible for pages at other sites to load This file should make it possible for pages at other sites to load MathJax
MathJax from this server in such a way that Firefox will be able to 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 download the web-based fonts. If you want to restrict the sites that can
can access the web fonts, change the ``Access-Control-Allow-Origin`` access the web fonts, change the ``Access-Control-Allow-Origin`` line to
line to something like:: something like::
Header set Access-Control-Allow-Origin "http://www.math.yourcollege.edu" Header set Access-Control-Allow-Origin "http://www.math.yourcollege.edu"
@ -231,7 +244,7 @@ for more details.
.. _ff-local-fonts: .. _ff-local-fonts:
Forefox and Local Fonts Firefox and local fonts
======================= =======================
Firefox's same-origin security policy affects its ability to load 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 restriction, but it is a limitiation imposed by Firefox's security
model that MathJax can not circumvent. Currently, this is not a model that MathJax can not circumvent. Currently, this is not a
problem for other browsers. 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).

63
docs/source/start.rst
View File

@ -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 people's needs. Other configurations are available, however, and you
can also provide additional configuration parameters to taylor one of can also provide additional configuration parameters to taylor one of
the confiogurations to your needs. More details can be found in the 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 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 <http://www.mathjax.org/download/mathjax-cdn-terms-of-service/>`_, so be
the MathJax CDN server. sure to read that before linked to the MathJax CDN server.
To see how to enter mathematics in your web pages, see `Putting To see how to enter mathematics in your web pages, see `Putting
mathematics in a web page`_ below. 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. HTML-with-CSS to render the mathematics otherwise.
There are a number of other prebuilt configuration files that you can 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 choose from as well, or you could use the ``config/default.js`` file and
and customize the settings yourself. The combined configuration files customize the settings yourself. The combined configuration files are
are described more fully in :ref:`Installing and Configuring MathJax described more fully in :ref:`Common Configurations
<installation>`, and the configuration options are described in <common-configurations>`, and the configuration options are described in
:ref:`Configuration Options <configuration>`. :ref:`Configuration Options <configuration>`.
Note: The configuration process has changed in MathJax v1.1, so if you have 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 signs. For this reason, if you want to use single-dollars for in-line
math mode, you must enable that explicitly in your configuration: math mode, you must enable that explicitly in your configuration:
.. code-block:: javascript .. code-block:: html
<script type="text/x-mathjax-config"> <script type="text/x-mathjax-config">
MathJax.Hub.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 See the ``config/default.js`` file, or the :ref:`tex2jax configuration
options <configure-tex2jax>` page, for additional 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 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 .. code-block:: html
@ -241,12 +243,15 @@ Here is a complete sample page containing TeX mathematics:
<html> <html>
<head> <head>
<title>MathJax TeX Test Page</title> <title>MathJax TeX Test Page</title>
<script type="text/x-mathjax-config">
MathJax.Hub.Config({tex2jax: {inlineMath: [['$','$'], ['\\(','\\)']]}});
</script>
<script type="text/javascript" <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> </script>
</head> </head>
<body> <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}.$$ $$x = {-b \pm \sqrt{b^2-4ac} \over 2a}.$$
</body> </body>
</html> </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 ``<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. 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 .. code-block:: html
@ -301,7 +307,7 @@ Here is a complete sample page containing MathML mathematics:
<head> <head>
<title>MathJax MathML Test Page</title> <title>MathJax MathML Test Page</title>
<script type="text/javascript" <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> </script>
</head> </head>
<body> <body>
@ -342,25 +348,20 @@ should use
.. code-block:: html .. code-block:: html
<mspace width="5pt"></mspace> <mspace width="thinmathspace"></mspace>
rather than 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
.. code-block:: html MathJax will receive a damaged math structure, which will not be rendered
as the original notation would have been. Unfortunately, there is nothing
<mspace width="5pt" /> MathJax can do about that, since the browser has incorrectly interpreted
the tags long before MathJax has a chance to work with them.
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 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 ``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? 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! point, you can start making pages that contain mathematical content!
You could also read more about the details of how to :ref:`customize 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 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 other content-management system, you might want to read about :ref:`using

234
docs/source/upgrade.rst Normal file
View File

@ -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.

172
docs/source/whats-new.rst Normal file
View File

@ -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 ``&lt;`` and ``&amp;`` 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.