320 lines
20 KiB
HTML
320 lines
20 KiB
HTML
|
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
|
|
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
|
|
|
|
<title>MathJax Output Formats — MathJax v2.0 documentation</title>
|
|
<link rel="stylesheet" href="_static/mj.css" type="text/css" />
|
|
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
|
|
<script type="text/javascript">
|
|
var DOCUMENTATION_OPTIONS = {
|
|
URL_ROOT: '',
|
|
VERSION: '2.0',
|
|
COLLAPSE_INDEX: false,
|
|
FILE_SUFFIX: '.html',
|
|
HAS_SOURCE: true
|
|
};
|
|
</script>
|
|
<script type="text/javascript" src="_static/jquery.js"></script>
|
|
<script type="text/javascript" src="_static/underscore.js"></script>
|
|
<script type="text/javascript" src="_static/doctools.js"></script>
|
|
<!--<script type="text/javascript" src="../../MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>-->
|
|
<link rel="top" title="MathJax v2.0 documentation" href="index.html" />
|
|
<link rel="next" title="The MathJax Community" href="community.html" />
|
|
<link rel="prev" title="MathJax AsciiMath Support" href="asciimath.html" />
|
|
</head>
|
|
<body>
|
|
|
|
<div class="related">
|
|
<h3>Navigation</h3>
|
|
<ul>
|
|
<li class="right" style="margin-right: 10px">
|
|
<a href="genindex.html" title="General Index"
|
|
accesskey="I">index</a></li>
|
|
<li class="right" >
|
|
<a href="community.html" title="The MathJax Community"
|
|
accesskey="N">next</a> |</li>
|
|
<li class="right" >
|
|
<a href="asciimath.html" title="MathJax AsciiMath Support"
|
|
accesskey="P">previous</a> |</li>
|
|
<li><a href="index.html">MathJax v2.0 documentation</a> »</li>
|
|
</ul>
|
|
</div>
|
|
|
|
<div class="document">
|
|
<div class="documentwrapper">
|
|
<div class="bodywrapper">
|
|
<div class="body">
|
|
|
|
<div class="section" id="mathjax-output-formats">
|
|
<span id="output-formats"></span><h1>MathJax Output Formats<a class="headerlink" href="#mathjax-output-formats" title="Permalink to this headline">¶</a></h1>
|
|
<p>Currently, MathJax can render math in three ways:</p>
|
|
<ul class="simple">
|
|
<li>Using HTML-with-CSS to lay out the mathematics,</li>
|
|
<li>Using <a class="reference internal" href="glossary.html#term-svg"><em class="xref std std-term">SVG</em></a> to lay out the mathematics, or</li>
|
|
<li>Using a browser’s native MathML support.</li>
|
|
</ul>
|
|
<p>These are implemented by the <cite>HTML-CSS</cite>, <cite>SVG</cite> and <cite>NativeMML</cite> output
|
|
processors.</p>
|
|
<p>If you are using one of the combined configuration files, then this will
|
|
select one of these output processors for you. If the config file ends in
|
|
<tt class="docutils literal"><span class="pre">_HTML</span></tt>, then it is the HTML-CSS output processor, and if it ends in
|
|
<tt class="docutils literal"><span class="pre">_SVG</span></tt> then the SVG output processor will be used. If it ends in
|
|
<tt class="docutils literal"><span class="pre">_HTMLorMML</span></tt>, then the NativeMML output processor will be chosen if the
|
|
browser supports it well enough, otherwise HTML-CSS output will be used.</p>
|
|
<p>If you are performing your own in-line or file-based configuration,
|
|
you select which one you want to use by including either
|
|
<tt class="docutils literal"><span class="pre">"output/HTML-CSS"</span></tt>, <tt class="docutils literal"><span class="pre">"output/SVG"</span></tt>, or <tt class="docutils literal"><span class="pre">"output/NativeMML"</span></tt> in
|
|
the <cite>jax</cite> array of your MathJax configuration. For example</p>
|
|
<div class="highlight-javascript"><div class="highlight"><pre><span class="nx">jax</span><span class="o">:</span> <span class="p">[</span><span class="s2">"input/TeX"</span><span class="p">,</span><span class="s2">"output/HTML-CSS"</span><span class="p">]</span>
|
|
</pre></div>
|
|
</div>
|
|
<p>would specify TeX input and HTML-with-CSS output for the mathematics
|
|
in your document.</p>
|
|
<p>The <strong>HTML-CSS output processor</strong> produces high-quality output in all
|
|
major browsers, with results that are consistent across browsers and
|
|
operating systems. This is MathJax’s primary output mode. Its major
|
|
advantage is its quality and consistency; its drawback is that it is
|
|
slower than the NativeMML mode at rendering the mathematics.
|
|
Historically, the performance in Internet Explorer (and IE8 in
|
|
particular) was quite poor, with the page getting slower and slower as
|
|
more math is processed. MathJax version 2.0 includes a number of
|
|
optimizations to improve the display performance in IE, and it is now
|
|
more comparable to other browsers. The HTML-CSS output uses web-based
|
|
fonts so that users don’t have to have math fonts installed on their
|
|
computers; but this does introduce some printing issues in some
|
|
browsers.</p>
|
|
<p>The <strong>SVG output processor</strong> is new in MathJax version 2.0, and it uses
|
|
<cite>Scalable Vector Graphics</cite> to render the mathematics on the page. SVG
|
|
is supported in all the major browsers and most mobile devices; note,
|
|
however, that Internet Explorer prior to IE9 does not support SVG, and
|
|
IE9 only does in “IE9 standards mode”, not its emulation modes for
|
|
earlier versions. The SVG output mode is high quality and slightly
|
|
faster than HTML-CSS, and it does not suffer from some of the
|
|
font-related issues that HTML-CSS does, so prints well in all
|
|
browsers. This format also works well in some ebook readers (e.g.,
|
|
iBooks). The disadvantage of this mode is that it does not take
|
|
advantage of STIX fonts, and so only has access to the characters in
|
|
the web-based fonts, and it variable-width tables become fixed size
|
|
once they are typeset, and don’t rescale if the window size changes
|
|
(for example). Since equation numbers are handled through
|
|
variable-width tables, that means equation numbers may not stay at the
|
|
edge of the window if it is resized.</p>
|
|
<p>The <strong>NativeMML output processor</strong> uses the browser’s internal MathML
|
|
support (if any) to render the mathematics. Currently, Firefox has
|
|
native support for MathML, and IE has the <a class="reference external" href="http://www.dessci.com/en/products/mathplayer/">MathPlayer plugin</a> for rendering
|
|
MathML. Opera has some built-in support for MathML that works well
|
|
with simple equations, but fails with more complex formulas, so we
|
|
don’t recommend using the NativeMML output processor with Opera.
|
|
Safari has some support for MathML since version 5.1, but the quality
|
|
is not as high as either Firefox’s implementation or IE with MathPlayer.
|
|
Chrome, Konqueror, and most other browsers don’t support MathML
|
|
natively, but may in the future, since MathML is part of the HTML5
|
|
specification.</p>
|
|
<p>The advantage of the NativeMML output Processor is its speed, since
|
|
native MathML support is much faster than using complicated HTML and
|
|
CSS to lay out mathematics, as the HTML-CSS output processor does.
|
|
The disadvantage is that you are dependent on the browser’s MathML
|
|
implementation for your rendering, and these vary in quality of output
|
|
and completeness of implementation. MathJax relies on features that
|
|
are not available in some renderers (for example, Firefox’s MathML
|
|
support does not implement the features needed for labeled equations).
|
|
The results using the NativeMML output processor may have spacing or
|
|
other rendering problems that are outside of MathJax’s control.</p>
|
|
<div class="section" id="automatic-selection-of-the-output-processor">
|
|
<h2>Automatic Selection of the Output Processor<a class="headerlink" href="#automatic-selection-of-the-output-processor" title="Permalink to this headline">¶</a></h2>
|
|
<p>Since not all browsers support MathML natively, it would be unwise to
|
|
choose the NativeMML output processor unless you are sure of your
|
|
audience’s browser capabilities. MathJax can help with that, however,
|
|
since a number of its combined configuration files will select
|
|
NativeMML output when the browser supports it well enough, and
|
|
HTML-CSS output otherwise. These are the configuration files that end
|
|
in <tt class="docutils literal"><span class="pre">_HTMLorMML</span></tt>.</p>
|
|
<p>If you are doing your own configuration, there is a special configuration
|
|
file that you can include that will choose between NativeMML and HTML-CSS
|
|
depending on the browser in use. To invoke it, add <tt class="docutils literal"><span class="pre">"MMLorHTML.js"</span></tt> to
|
|
your configuration’s <cite>config</cite> array, and <strong>do not</strong> include an output
|
|
processor in your <cite>jax</cite> array; MathJax will fill that in for you based on
|
|
the abilities of your user’s browser.</p>
|
|
<div class="highlight-javascript"><div class="highlight"><pre><span class="nx">config</span><span class="o">:</span> <span class="p">[</span><span class="s2">"MMLorHTML.js"</span><span class="p">],</span>
|
|
<span class="nx">jax</span><span class="o">:</span> <span class="p">[</span><span class="s2">"input/TeX"</span><span class="p">]</span>
|
|
</pre></div>
|
|
</div>
|
|
<p>By default, MathJax will choose HTML-CSS in all browsers except for
|
|
one case: Internet Explorer when the MathPlayer plugin is present.
|
|
In the past, MathJax selected NativeMML output for Firefox as well,
|
|
but we have found that there are too many rendering issues with
|
|
Firefox’s native MathML implementation, and so MathJax now selects
|
|
HTML-CSS output for Firefox by default as well. Users can still use
|
|
the Mathjax contextual menu to select the NativeMML renderer if they
|
|
wish to choose greater speed at the expense of some quality.</p>
|
|
<p>You can customize which choice MathJax makes on a browser-by-browser
|
|
basis or a global basis. See the <tt class="docutils literal"><span class="pre">config/default.js</span></tt> file or the
|
|
<a class="reference internal" href="options/MMLorHTML.html#configure-mmlorhtml"><em>Configuring MMLorHTML</em></a> section for further
|
|
details. As an example, this configuration tells MathJax to use
|
|
native MathML support rather than HTML-CSS output for Firefox:</p>
|
|
<div class="highlight-html"><div class="highlight"><pre><span class="nt"><script </span><span class="na">type=</span><span class="s">"text/x-mathjax-config"</span><span class="nt">></span>
|
|
<span class="nx">MathJax</span><span class="p">.</span><span class="nx">Hub</span><span class="p">.</span><span class="nx">Config</span><span class="p">({</span>
|
|
<span class="nx">MMLorHTML</span><span class="o">:</span> <span class="p">{</span> <span class="nx">prefer</span><span class="o">:</span> <span class="p">{</span> <span class="nx">Firefox</span><span class="o">:</span> <span class="s2">"MML"</span> <span class="p">}</span> <span class="p">}</span>
|
|
<span class="p">});</span>
|
|
<span class="nt"></script></span>
|
|
<span class="nt"><script </span><span class="na">type=</span><span class="s">"text/javascript"</span>
|
|
<span class="na">src=</span><span class="s">"http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"</span><span class="nt">></span>
|
|
<span class="nt"></script></span>
|
|
</pre></div>
|
|
</div>
|
|
<p>With this configuration, MathML output will be used for both Firefox
|
|
and IE with the MathPlayer plugin. Note, however, that a user can
|
|
employ the MathJax contextual menu to select the other renderer if he
|
|
or she wishes.</p>
|
|
<p>MathJax produces MathML that models the underlying mathematics as best
|
|
it can, rather than using complicated hacks to improve output for a
|
|
particular MathML implementation. When you make the choice to use the
|
|
NativeMML output processor, you are making a trade-off: gaining speed
|
|
at the expense of quality and reliability, a decision that should not
|
|
be taken lightly.</p>
|
|
</div>
|
|
<div class="section" id="automatic-line-breaking">
|
|
<span id="automatic-linebreaking"></span><h2>Automatic Line Breaking<a class="headerlink" href="#automatic-line-breaking" title="Permalink to this headline">¶</a></h2>
|
|
<p>The HTML-CSS and SVG output processors implement (most of) the MathML3
|
|
automatic line-breaking specification. (The NativeMML output
|
|
processor relies on the browser’s native MathML support to handle line
|
|
breaking when it is used.) Since line-breaking takes extra processing
|
|
and so can slow down the mathematical output, it is off by default,
|
|
but you can enable it by adding</p>
|
|
<div class="highlight-html"><div class="highlight"><pre><span class="nt"><script </span><span class="na">type=</span><span class="s">"text/x-mathjax-config"</span><span class="nt">></span>
|
|
<span class="nx">MathJax</span><span class="p">.</span><span class="nx">Hub</span><span class="p">.</span><span class="nx">Config</span><span class="p">({</span>
|
|
<span class="s2">"HTML-CSS"</span><span class="o">:</span> <span class="p">{</span> <span class="nx">linebreaks</span><span class="o">:</span> <span class="p">{</span> <span class="nx">automatic</span><span class="o">:</span> <span class="kc">true</span> <span class="p">}</span> <span class="p">},</span>
|
|
<span class="nx">SVG</span><span class="o">:</span> <span class="p">{</span> <span class="nx">linebreaks</span><span class="o">:</span> <span class="p">{</span> <span class="nx">automatic</span><span class="o">:</span> <span class="kc">true</span> <span class="p">}</span> <span class="p">}</span>
|
|
<span class="p">});</span>
|
|
<span class="nt"></script></span>
|
|
</pre></div>
|
|
</div>
|
|
<p>to your page just before the <tt class="docutils literal"><span class="pre"><script></span></tt> tag that loads
|
|
<tt class="docutils literal"><span class="pre">MathJax.js</span></tt> itself.</p>
|
|
<p>Note that line breaking only applies to displayed equations, not
|
|
in-line equations (unless the in-line euqation is itself longer than a
|
|
line), and that the line-breaks are only computed once when the
|
|
equation is initially typeset, and do not change if the user changes
|
|
the window size, or if the container changes size for some other
|
|
reason.</p>
|
|
<p>You can control what width is used to determine where the line breaks
|
|
shoud occur using the <tt class="docutils literal"><span class="pre">container</span></tt> parameter of the <tt class="docutils literal"><span class="pre">linebreaks</span></tt>
|
|
block. By default it is the width of the containing element, but you
|
|
can make it a fixed width, or make it a percentage of the container.
|
|
See the <a class="reference internal" href="options/HTML-CSS.html#configure-html-css"><em>HTML-CSS configuration</em></a> or
|
|
<a class="reference internal" href="options/SVG.html#configure-svg"><em>SVG configuration</em></a> pages for more details.</p>
|
|
</div>
|
|
<div class="section" id="html-css-with-ie">
|
|
<span id="html-css-with-ie8"></span><h2>HTML-CSS with IE<a class="headerlink" href="#html-css-with-ie" title="Permalink to this headline">¶</a></h2>
|
|
<p>The performance of MathJax in Internet Explorer 8 and 9 has been
|
|
substantially improved in version 2.0. The HTML-CSS output processing
|
|
was redesigned to avoid the page reflows that were the main source of
|
|
the speed problem in I8 and IE9. For test pages having between 20 and
|
|
50 typeset expressions, we see an 80% reduction in output processing
|
|
time for IE8, a 50% reduction for IE9, and between 15% and 25%
|
|
reduction for most other browsers over the v1.1a times. Since the
|
|
processing time in v1.1a grows non-linearly in IE, you should see even
|
|
larger savings for pages with more equations when using v2.0.</p>
|
|
<p>In the past, we recommended forcing IE8 and IE9 into IE7-emulation
|
|
mode in order to get better performance. That is no longer necessary.
|
|
Indeed, the fastest modes in IE8 and IE9 now are their IE8 standards
|
|
and IE9 standards modes, so it is best to force the highest mode
|
|
possible. That can be accomplished by adding</p>
|
|
<div class="highlight-html"><div class="highlight"><pre><span class="nt"><meta</span> <span class="na">http-equiv=</span><span class="s">"X-UA-Compatible"</span> <span class="na">content=</span><span class="s">"IE=edge"</span><span class="nt">></span>
|
|
</pre></div>
|
|
</div>
|
|
<p>at the top of the <tt class="docutils literal"><span class="pre"><head></span></tt> section of your HTML documents. Note
|
|
that this line must come at the beginning of the <tt class="docutils literal"><span class="pre"><head></span></tt>, before
|
|
any stylesheets, scripts, or other content are loaded.</p>
|
|
</div>
|
|
<div class="section" id="html-css-extensions">
|
|
<span id="id1"></span><h2>HTML-CSS Extensions<a class="headerlink" href="#html-css-extensions" title="Permalink to this headline">¶</a></h2>
|
|
<p>The HTML-CSS output jax uses elements with width set to 100% when it
|
|
typesets displayed equations. If there are floating elements on the
|
|
left or right, this can mean that displayed mathematics isn’t properly
|
|
centered, and can cause equation numbers to overlap the floating
|
|
content. To avoid this, you can specify the <cite>handle-floats</cite> extension
|
|
in the <cite>extensions</cite> array of your <cite>HTML-CSS</cite> configuration block.</p>
|
|
<div class="highlight-javascript"><div class="highlight"><pre><span class="s2">"HTML-CSS"</span><span class="o">:</span> <span class="p">{</span>
|
|
<span class="nx">extensions</span><span class="o">:</span> <span class="p">[</span><span class="s2">"handle-floats.js"</span><span class="p">]</span>
|
|
<span class="p">}</span>
|
|
</pre></div>
|
|
</div>
|
|
<p>This will use CSS that puts the displayed equations into elements that
|
|
work like tabel cells, and won’t overlap the floaring content.
|
|
Because this is somewhat of a misuse of CSS, it is not used by
|
|
default, but it has proved successful in most situations, so you may
|
|
consider using it in pages that include material that floats to the
|
|
left or right of text containing displayed mathematics, especially
|
|
when equation numbers or tags are used.</p>
|
|
<p>See the <a class="reference internal" href="options/HTML-CSS.html#configure-html-css"><em>HTML-CSS configuration options</em></a> for
|
|
other options of the HTML-CSS output jax.</p>
|
|
</div>
|
|
</div>
|
|
|
|
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sphinxsidebar">
|
|
<div class="sphinxsidebarwrapper">
|
|
<h3><a href="index.html">Table Of Contents</a></h3>
|
|
<ul>
|
|
<li><a class="reference internal" href="#">MathJax Output Formats</a><ul>
|
|
<li><a class="reference internal" href="#automatic-selection-of-the-output-processor">Automatic Selection of the Output Processor</a></li>
|
|
<li><a class="reference internal" href="#automatic-line-breaking">Automatic Line Breaking</a></li>
|
|
<li><a class="reference internal" href="#html-css-with-ie">HTML-CSS with IE</a></li>
|
|
<li><a class="reference internal" href="#html-css-extensions">HTML-CSS Extensions</a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
|
|
<h4>Previous topic</h4>
|
|
<p class="topless"><a href="asciimath.html"
|
|
title="previous chapter">MathJax AsciiMath Support</a></p>
|
|
<h4>Next topic</h4>
|
|
<p class="topless"><a href="community.html"
|
|
title="next chapter">The MathJax Community</a></p>
|
|
<div id="searchbox" style="display: none">
|
|
<h3>Quick search</h3>
|
|
<form class="search" action="search.html" method="get">
|
|
<input type="text" name="q" size="18" />
|
|
<input type="submit" value="Go" />
|
|
<input type="hidden" name="check_keywords" value="yes" />
|
|
<input type="hidden" name="area" value="default" />
|
|
</form>
|
|
<p class="searchtip" style="font-size: 90%">
|
|
Enter search terms or a module, class or function name.
|
|
</p>
|
|
</div>
|
|
<script type="text/javascript">$('#searchbox').show(0);</script>
|
|
</div>
|
|
</div>
|
|
<div class="clearer"></div>
|
|
</div>
|
|
<div class="related">
|
|
<h3>Navigation</h3>
|
|
<ul>
|
|
<li class="right" style="margin-right: 10px">
|
|
<a href="genindex.html" title="General Index"
|
|
>index</a></li>
|
|
<li class="right" >
|
|
<a href="community.html" title="The MathJax Community"
|
|
>next</a> |</li>
|
|
<li class="right" >
|
|
<a href="asciimath.html" title="MathJax AsciiMath Support"
|
|
>previous</a> |</li>
|
|
<li><a href="index.html">MathJax v2.0 documentation</a> »</li>
|
|
</ul>
|
|
</div>
|
|
<div class="footer">
|
|
© Copyright 2012 Design Science.
|
|
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.7.
|
|
</div>
|
|
|
|
</body>
|
|
</html> |