Commit 1290d5ee by Matthew Mongeau

Wip on sign up form.

parent 8822ffa2

Too many changes to show.

To preserve performance only 1000 of 1000+ files are displayed.

......@@ -179,7 +179,7 @@ LIVESETTINGS_OPTIONS = {
'MARKUP' : {
'MARKUP_CODE_FRIENDLY' : False,
'ENABLE_MATHJAX' : True,
'MATHJAX_BASE_URL' : u'/static/js/mathjax-MathJax-c9db6ac/',
'MATHJAX_BASE_URL' : u'/static/js/vendor/mathjax-MathJax-c9db6ac/',
'ENABLE_AUTO_LINKING' : False,
'AUTO_LINK_PATTERNS' : u'',
'AUTO_LINK_URLS' : u'',
......
.treeview, .treeview ul {
padding: 0;
margin: 0;
list-style: none;
}
.treeview ul {
background-color: white;
margin-top: 4px;
}
.treeview .hitarea {
background: url(images/treeview-default.gif) -64px -25px no-repeat;
height: 16px;
width: 16px;
margin-left: -16px;
float: left;
cursor: pointer;
}
/* fix for IE6 */
* html .hitarea {
display: inline;
float:none;
}
.treeview li {
margin: 0;
padding: 3px 0pt 3px 16px;
}
.treeview a.selected {
background-color: #eee;
}
#treecontrol { margin: 1em 0; display: none; }
.treeview .hover { color: red; cursor: pointer; }
.treeview li { background: url(images/treeview-default-line.gif) 0 0 no-repeat; }
.treeview li.collapsable, .treeview li.expandable { background-position: 0 -176px; }
.treeview .expandable-hitarea { background-position: -80px -3px; }
.treeview li.last { background-position: 0 -1766px }
.treeview li.lastCollapsable, .treeview li.lastExpandable { background-image: url(images/treeview-default.gif); }
.treeview li.lastCollapsable { background-position: 0 -111px }
.treeview li.lastExpandable { background-position: -32px -67px }
.treeview div.lastCollapsable-hitarea, .treeview div.lastExpandable-hitarea { background-position: 0; }
This source diff could not be displayed because it is too large. You can view the blob instead.
/////////////////////////////////////////////////////////////////////////////
//
// Simple image input
//
////////////////////////////////////////////////////////////////////////////////
// click on image, return coordinates
// put a dot at location of click, on imag
// window.image_input_click = function(id,event){
function image_input_click(id,event){
iidiv = document.getElementById("imageinput_"+id);
pos_x = event.offsetX?(event.offsetX):event.pageX-document.iidiv.offsetLeft;
pos_y = event.offsetY?(event.offsetY):event.pageY-document.iidiv.offsetTop;
result = "[" + pos_x + "," + pos_y + "]";
cx = (pos_x-15) +"px";
cy = (pos_y-15) +"px" ;
// alert(result);
document.getElementById("cross_"+id).style.left = cx;
document.getElementById("cross_"+id).style.top = cy;
document.getElementById("cross_"+id).style.visibility = "visible" ;
document.getElementById("input_"+id).value =result;
}
.DS_Store
docs/build/html-mathjax-site
config/local/*.js
!config/local/local.js
unpacked/config/local/*.js
!unpacked/config/local/local.js
# MathJax
## Beautiful math in all browsers
MathJax is an open-source JavaScript display engine for LaTeX, MathML, and
AsciiMath notation that works in all modern browsers. It was designed with
the goal of consolidating the recent advances in web technologies into a
single, definitive, math-on-the-web platform supporting the major browsers
and operating systems. It requires no setup on the part of the user (no
plugins to download or software to install), so the page author can write
web documents that include mathematics and be confident that users will be
able to view it naturally and easily. Simply include MathJax and some
mathematics in a web page, and MathJax does the rest.
Some of the main features of MathJax include:
- High-quality display of LaTeX, MathML, and AsciiMath notation in HTML pages
- Supported in most browsers with no plug-ins, extra fonts, or special
setup for the reader
- Easy for authors, flexible for publishers, extensible for developers
- Supports math accessibility, cut-and-paste interoperability, and other
advanced functionality
- Powerful API for integration with other web applications
See <http://www.mathjax.org/> for additional details.
## Installation and Usage
The MathJax installation and usage documentation is available in the
`docs/html` directory of the MathJax distribution (see
`docs/html/index.html` for the starting point). The documents are also
available on the MathJax web site on line at <http://www.mathjax.org/resources/docs/>.
## Community
The main MathJax website is <http://www.mathjax.org>, and it includes
announcements and other important information. MathJax is maintained and
distributed on GitHub at <http://github.com/mathjax/MathJax>. A user forum
for asking questions and getting assistance is hosted at Google, and the
bug tracker is hosted at GitHub:
Bug tracker: <https://github.com/mathjax/MathJax/issues>
MathJax-Users Group: <http://groups.google.com/group/mathjax-users>
Before reporting a bug, please check that it has not already been reported.
Also, please use the bug tracker for reporting bugs rather than the help forum.
This source diff could not be displayed because it is too large. You can view the blob instead.
This source diff could not be displayed because it is too large. You can view the blob instead.
This source diff could not be displayed because it is too large. You can view the blob instead.
This source diff could not be displayed because it is too large. You can view the blob instead.
This source diff could not be displayed because it is too large. You can view the blob instead.
/*
* /MathJax/config/MMLorHTML.js
*
* Copyright (c) 2012 Design Science, Inc.
*
* Part of the MathJax library.
* See http://www.mathjax.org for details.
*
* Licensed under the Apache License, Version 2.0;
* you may not use this file except in compliance with the License.
*
* http://www.apache.org/licenses/LICENSE-2.0
*/
(function(c,g){var f="2.0";var a=MathJax.Hub.CombineConfig("MMLorHTML",{prefer:{MSIE:"MML",Firefox:"HTML",Opera:"HTML",Chrome:"HTML",Safari:"HTML",other:"HTML"}});var e={Firefox:3,Opera:9.52,MSIE:6,Chrome:0.3,Safari:2,Konqueror:4};var b=(g.version==="0.0"||g.versionAtLeast(e[g]||0));var d=(g.isFirefox&&g.versionAtLeast("1.5"))||(g.isMSIE&&g.hasMathPlayer)||(g.isSafari&&g.versionAtLeast("5.0"))||(g.isOpera&&g.versionAtLeast("9.52"));c.Register.StartupHook("End Config",function(){var h=(a.prefer&&typeof(a.prefer)==="object"?a.prefer[MathJax.Hub.Browser]||a.prefer.other||"HTML":a.prefer);if(b||d){if(d&&(h==="MML"||!b)){if(MathJax.OutputJax.NativeMML){MathJax.OutputJax.NativeMML.Register("jax/mml")}else{c.config.jax.unshift("output/NativeMML")}c.Startup.signal.Post("NativeMML output selected")}else{if(MathJax.OutputJax["HTML-CSS"]){MathJax.OutputJax["HTML-CSS"].Register("jax/mml")}else{c.config.jax.unshift("output/HTML-CSS")}c.Startup.signal.Post("HTML-CSS output selected")}}else{c.PreProcess.disabled=true;c.prepareScripts.disabled=true;MathJax.Message.Set("Your browser does not support MathJax",null,4000);c.Startup.signal.Post("MathJax not supported")}})})(MathJax.Hub,MathJax.Hub.Browser);MathJax.Ajax.loadComplete("[MathJax]/config/MMLorHTML.js");
This source diff could not be displayed because it is too large. You can view the blob instead.
This source diff could not be displayed because it is too large. You can view the blob instead.
This source diff could not be displayed because it is too large. You can view the blob instead.
This source diff could not be displayed because it is too large. You can view the blob instead.
This source diff could not be displayed because it is too large. You can view the blob instead.
This source diff could not be displayed because it is too large. You can view the blob instead.
This source diff could not be displayed because it is too large. You can view the blob instead.
This source diff could not be displayed because it is too large. You can view the blob instead.
/*************************************************************
*
* MathJax/config/local/local.js
*
* Include changes and configuration local to your installation
* in this file. For example, common macros can be defined here
* (see below). To use this file, add "local/local.js" to the
* config array in MathJax.js or your MathJax.Hub.Config() call.
*
* ---------------------------------------------------------------------
*
* Copyright (c) 2009 Design Science, Inc.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
MathJax.Hub.Register.StartupHook("TeX Jax Ready",function () {
var TEX = MathJax.InputJax.TeX;
// place macros here. E.g.:
// TEX.Macro("R","{\\bf R}");
// TEX.Macro("op","\\mathop{\\rm #1}",1); // a macro with 1 parameter
});
MathJax.Ajax.loadComplete("[MathJax]/config/local/local.js");
.doctrees
html-mathjax-site
dirhtml
singlehtml
epub
latex
text
man
html/objects.inv
html/.buildinfo
# Makefile for Sphinx documentation
#
# You can set these variables from the command line.
SPHINXOPTS =
SPHINXBUILD = sphinx-build
PAPER =
BUILDDIR = .
# Internal variables.
PAPEROPT_a4 = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter
ALLSPHINXOPTS = -d $(BUILDDIR)/.doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest
help:
@echo "Please use \`make <target>' where <target> is one of"
@echo " html to make standalone HTML files"
@echo " dirhtml to make HTML files named index.html in directories"
@echo " singlehtml to make a single large HTML file"
# @echo " pickle to make pickle files"
# @echo " json to make JSON files"
# @echo " htmlhelp to make HTML files and a HTML help project"
# @echo " qthelp to make HTML files and a qthelp project"
# @echo " devhelp to make HTML files and a Devhelp project"
@echo " epub to make an epub"
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
@echo " latexpdf to make LaTeX files and run them through pdflatex"
@echo " text to make text files"
@echo " man to make manual pages"
@echo " changes to make an overview of all changed/added/deprecated items"
@echo " linkcheck to check all external links for integrity"
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
@echo "or"
@echo " html-mathjax-site to make the documentation for www.mathjax.org"
clean:
-rm -rf $(BUILDDIR)/*
html:
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
html-mathjax-site:
$(SPHINXBUILD) -b html -A for_site=True $(ALLSPHINXOPTS) $(BUILDDIR)/html-mathjax-site
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html-mathjax-site."
dirhtml:
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
singlehtml:
$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
@echo
@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
pickle:
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
@echo
@echo "Build finished; now you can process the pickle files."
json:
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
@echo
@echo "Build finished; now you can process the JSON files."
htmlhelp:
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
@echo
@echo "Build finished; now you can run HTML Help Workshop with the" \
".hhp project file in $(BUILDDIR)/htmlhelp."
qthelp:
$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
@echo
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
".qhcp project file in $(BUILDDIR)/qthelp, like this:"
@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/UCBerkeleyAstronomy10Spring2011.qhcp"
@echo "To view the help file:"
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/UCBerkeleyAstronomy10Spring2011.qhc"
devhelp:
$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
@echo
@echo "Build finished."
@echo "To view the help file:"
@echo "# mkdir -p $$HOME/.local/share/devhelp/UCBerkeleyAstronomy10Spring2011"
@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/UCBerkeleyAstronomy10Spring2011"
@echo "# devhelp"
epub:
$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
@echo
@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
latex:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
@echo "Run \`make' in that directory to run these through (pdf)latex" \
"(use \`make latexpdf' here to do that automatically)."
latexpdf:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo "Running LaTeX files through pdflatex..."
make -C $(BUILDDIR)/latex all-pdf
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
text:
$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
@echo
@echo "Build finished. The text files are in $(BUILDDIR)/text."
man:
$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
@echo
@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
changes:
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
@echo
@echo "The overview file is in $(BUILDDIR)/changes."
linkcheck:
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
@echo
@echo "Link check complete; look for any errors in the above output " \
"or in $(BUILDDIR)/linkcheck/output.txt."
doctest:
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
@echo "Testing of doctests in the sources finished, look at the " \
"results in $(BUILDDIR)/doctest/output.txt."
<!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>CSS Style Objects &mdash; 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="Glossary" href="glossary.html" />
<link rel="prev" title="Describing HTML snippets" href="HTML-snippets.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="glossary.html" title="Glossary"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="HTML-snippets.html" title="Describing HTML snippets"
accesskey="P">previous</a> |</li>
<li><a href="index.html">MathJax v2.0 documentation</a> &raquo;</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="css-style-objects">
<span id="id1"></span><h1>CSS Style Objects<a class="headerlink" href="#css-style-objects" title="Permalink to this headline"></a></h1>
<p>Many MathJax components allow you to specify CSS styles that control
the look of the elements they create. These are described using <cite>CSS
style objects</cite>, which are JavaScript objects that represent standard
CSS declarations. The main CSS style object is a collection of
<cite>name:value</cite> pairs where the <cite>name</cite> is the CSS selector that is being
defined, and the <cite>value</cite> is an object that gives the style for that
selector. Most often, the selector will need to be enclosed in
quotation marks, as it will contain special characters, so you would
need to use <tt class="docutils literal"><span class="pre">&quot;#myID&quot;</span></tt> rather than just <tt class="docutils literal"><span class="pre">#myID</span></tt> and <tt class="docutils literal"><span class="pre">&quot;ul</span> <span class="pre">li&quot;</span></tt>
rather than just <tt class="docutils literal"><span class="pre">ul</span> <span class="pre">li</span></tt>.</p>
<p>The value used to define the CSS style can either be a string
containing the CSS definition, or a javascript object that is itself a
collection of <cite>name:value</cite> pairs, where the <cite>name</cite> is the attribute
being defined and <cite>value</cite> is the value that attribute should be given.
Note that, since this is a JavaScript object, the pairs are separated
by commas (not semi-colons) and the values are enclosed in quotation
marks. If the name contains dashes, it should be enclosed in
quotation marks as well.</p>
<p>For example, <tt class="docutils literal"><span class="pre">jax/output/HTML-CSS/config.js</span></tt> includes the following
declaration:</p>
<div class="highlight-javascript"><div class="highlight"><pre><span class="nx">styles</span><span class="o">:</span> <span class="p">{</span>
<span class="s2">&quot;.MathJax_Display&quot;</span><span class="o">:</span> <span class="p">{</span>
<span class="s2">&quot;text-align&quot;</span><span class="o">:</span> <span class="s2">&quot;center&quot;</span><span class="p">,</span>
<span class="nx">margin</span><span class="o">:</span> <span class="s2">&quot;1em 0em&quot;</span>
<span class="p">},</span>
<span class="s2">&quot;.MathJax .merror&quot;</span><span class="o">:</span> <span class="p">{</span>
<span class="s2">&quot;background-color&quot;</span><span class="o">:</span> <span class="s2">&quot;#FFFF88&quot;</span><span class="p">,</span>
<span class="nx">color</span><span class="o">:</span> <span class="s2">&quot;#CC0000&quot;</span><span class="p">,</span>
<span class="nx">border</span><span class="o">:</span> <span class="s2">&quot;1px solid #CC0000&quot;</span><span class="p">,</span>
<span class="nx">padding</span><span class="o">:</span> <span class="s2">&quot;1px 3px&quot;</span><span class="p">,</span>
<span class="s2">&quot;font-style&quot;</span><span class="o">:</span> <span class="s2">&quot;normal&quot;</span><span class="p">,</span>
<span class="s2">&quot;font-size&quot;</span><span class="o">:</span> <span class="s2">&quot;90%&quot;</span>
<span class="p">}</span>
<span class="p">}</span>
</pre></div>
</div>
<p>This defines two CSS styles, one for the selector
<tt class="docutils literal"><span class="pre">.MathJax_Display</span></tt>, which specifies its text alignment and margin
settings, and a second for <tt class="docutils literal"><span class="pre">.MathJax</span> <span class="pre">.merror</span></tt>, which specifies a
background color, foreground color, border, and so on.</p>
<p>You can add as many such definitions to a <tt class="docutils literal"><span class="pre">styles</span></tt> object as you
wish. Note, however, that since this is a JavaScript object, the
selectors must be unique (e.g., you can&#8217;t use two definitions for
<tt class="docutils literal"><span class="pre">&quot;img&quot;</span></tt>, for example, as only the last one would be saved). If you
need to use more than one entry for a single selector, you can add
comments like <tt class="docutils literal"><span class="pre">/*</span> <span class="pre">1</span> <span class="pre">*/</span></tt> and <tt class="docutils literal"><span class="pre">/*</span> <span class="pre">2</span> <span class="pre">*/</span></tt> to the selector to make them
unique.</p>
<p>It is possible to include selectors like <tt class="docutils literal"><span class="pre">&quot;&#64;media</span> <span class="pre">print&quot;</span></tt>, in which
case the value is a CSS style object. For example:</p>
<div class="highlight-javascript"><div class="highlight"><pre><span class="nx">styles</span><span class="o">:</span> <span class="p">{</span>
<span class="s2">&quot;@media print&quot;</span><span class="o">:</span> <span class="p">{</span>
<span class="s2">&quot;.MathJax .merror&quot;</span><span class="o">:</span> <span class="p">{</span>
<span class="s2">&quot;background-color&quot;</span><span class="o">:</span> <span class="s2">&quot;white&quot;</span><span class="p">,</span>
<span class="nx">border</span><span class="o">:</span> <span class="mi">0</span>
<span class="p">}</span>
<span class="p">}</span>
<span class="p">}</span>
</pre></div>
</div>
<p>The various extensions and output processors include more examples of
CSS style objects, so see the code for those files for additional
samples. In particular, the <tt class="docutils literal"><span class="pre">extensions/MathMenu.js</span></tt>,
<tt class="docutils literal"><span class="pre">extensions/MathZoom.js</span></tt>, <tt class="docutils literal"><span class="pre">extensions/FontWarnsing.js</span></tt>, and
<tt class="docutils literal"><span class="pre">jax/output/HTML-CSS/jax.js</span></tt> files include such definitions.</p>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h4>Previous topic</h4>
<p class="topless"><a href="HTML-snippets.html"
title="previous chapter">Describing HTML snippets</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="glossary.html"
title="next chapter">Glossary</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="glossary.html" title="Glossary"
>next</a> |</li>
<li class="right" >
<a href="HTML-snippets.html" title="Describing HTML snippets"
>previous</a> |</li>
<li><a href="index.html">MathJax v2.0 documentation</a> &raquo;</li>
</ul>
</div>
<div class="footer">
&copy; Copyright 2012 Design Science.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.7.
</div>
</body>
</html>
\ No newline at end of file
<!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>Describing HTML snippets &mdash; 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="CSS Style Objects" href="CSS-styles.html" />
<link rel="prev" title="The MathJax Object-Oriented Programming Model" href="api/object.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="CSS-styles.html" title="CSS Style Objects"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="api/object.html" title="The MathJax Object-Oriented Programming Model"
accesskey="P">previous</a> |</li>
<li><a href="index.html">MathJax v2.0 documentation</a> &raquo;</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="describing-html-snippets">
<span id="html-snippets"></span><h1>Describing HTML snippets<a class="headerlink" href="#describing-html-snippets" title="Permalink to this headline"></a></h1>
<p>A number of MathJax configuration options allow you to specify an HTML
snippet using a JavaScript object. This lets you include HTML in your
configuration files even though they are not HTML files themselves.
The format is fairly simple, but flexible enough to let you represent
complicated HTML trees.</p>
<p>An HTML snippet is an array consisting of a series of elements that format
the HTML tree. Those elements are one of two things: either a string,
which represents text to be included in the snippet, or an array,
which represents an HTML tag to be included. In the latter case, the
array consists of three items: a string that is the tag name (e.g.,
&#8220;img&#8221;), an optional object that gives attributes for the tag (as
described below), and an optional HTML snippet array that gives the
contents of the tag.</p>
<p>When attributes are provided, they are given as <cite>name:value</cite> pairs,
with the <cite>name</cite> giving the attribute name, and <cite>value</cite> giving its
value. For example</p>
<div class="highlight-javascript"><div class="highlight"><pre><span class="p">[[</span><span class="s2">&quot;img&quot;</span><span class="p">,{</span><span class="nx">src</span><span class="o">:</span><span class="s2">&quot;/images/mypic.jpg&quot;</span><span class="p">}]]</span>
</pre></div>
</div>
<p>represents an HTML snippet that includes one element: an <tt class="docutils literal"><span class="pre">&lt;img&gt;</span></tt> tag
with <tt class="docutils literal"><span class="pre">src</span></tt> set to <tt class="docutils literal"><span class="pre">/images/mypic.jpg</span></tt>. That is, this is
equivalent to</p>
<div class="highlight-html"><div class="highlight"><pre><span class="nt">&lt;img</span> <span class="na">src=</span><span class="s">&quot;/images/mypic.jpg&quot;</span><span class="nt">&gt;</span>
</pre></div>
</div>
<p>Note that the snippet has two sets of square brackets. The outermost
one is for the array that holds the snippet, and the innermost set is
because the first (and only) element in the snippet is a tag, not
text. Note that the code <tt class="docutils literal"><span class="pre">[&quot;img&quot;,{src:&quot;/images/mypic.jpg&quot;}]</span></tt>
is invalid as an HTML snippet. It would represent a snippet that
starts with &#8220;img&#8221; as text in the snippet (not a tag), but the second
item is neither a string nor an array, and so is illegal. This is a
common mistake that should be avoided.</p>
<p>A more complex example is the following:</p>
<div class="highlight-javascript"><div class="highlight"><pre><span class="p">[</span>
<span class="s2">&quot;Please read the &quot;</span><span class="p">,</span>
<span class="p">[</span><span class="s2">&quot;a&quot;</span><span class="p">,{</span><span class="nx">href</span><span class="o">:</span><span class="s2">&quot;instructions.html&quot;</span><span class="p">},[</span><span class="s2">&quot;instructions&quot;</span><span class="p">]],</span>
<span class="s2">&quot; carefully before proceeding&quot;</span>
<span class="p">]</span>
</pre></div>
</div>
<p>which is equivalent to</p>
<div class="highlight-html"><div class="highlight"><pre>please read the <span class="nt">&lt;a</span> <span class="na">href=</span><span class="s">&quot;instructions.html&quot;</span><span class="nt">&gt;</span>instructions<span class="nt">&lt;/a&gt;</span> carefully
before proceeding.
</pre></div>
</div>
<p>A final example shows how to set style attributes on an object:</p>
<div class="highlight-javascript"><div class="highlight"><pre><span class="p">[[</span><span class="s2">&quot;span&quot;</span><span class="p">,</span>
<span class="p">{</span>
<span class="nx">id</span><span class="o">:</span><span class="s2">&quot;mySpan&quot;</span><span class="p">,</span>
<span class="nx">style</span><span class="o">:</span> <span class="p">{</span><span class="nx">color</span><span class="o">:</span><span class="s2">&quot;red&quot;</span><span class="p">,</span> <span class="s2">&quot;font-weight&quot;</span><span class="o">:</span><span class="s2">&quot;bold&quot;</span><span class="p">}</span>
<span class="p">},</span>
<span class="p">[</span><span class="s2">&quot; This is bold text shown in red &quot;</span><span class="p">]</span>
<span class="p">]]</span>
</pre></div>
</div>
<p>which is equivalent to</p>
<div class="highlight-html"><div class="highlight"><pre><span class="nt">&lt;span</span> <span class="na">id=</span><span class="s">&quot;mySpan&quot;</span> <span class="na">style=</span><span class="s">&quot;color: red; font-weight: bold;&quot;</span><span class="nt">&gt;</span>
This is bold text shown in red
<span class="nt">&lt;/span&gt;</span>
</pre></div>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h4>Previous topic</h4>
<p class="topless"><a href="api/object.html"
title="previous chapter">The MathJax Object-Oriented Programming Model</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="CSS-styles.html"
title="next chapter">CSS Style Objects</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="CSS-styles.html" title="CSS Style Objects"
>next</a> |</li>
<li class="right" >
<a href="api/object.html" title="The MathJax Object-Oriented Programming Model"
>previous</a> |</li>
<li><a href="index.html">MathJax v2.0 documentation</a> &raquo;</li>
</ul>
</div>
<div class="footer">
&copy; Copyright 2012 Design Science.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.7.
</div>
</body>
</html>
\ No newline at end of file
.. _css-style-objects:
*****************
CSS Style Objects
*****************
Many MathJax components allow you to specify CSS styles that control
the look of the elements they create. These are described using `CSS
style objects`, which are JavaScript objects that represent standard
CSS declarations. The main CSS style object is a collection of
`name:value` pairs where the `name` is the CSS selector that is being
defined, and the `value` is an object that gives the style for that
selector. Most often, the selector will need to be enclosed in
quotation marks, as it will contain special characters, so you would
need to use ``"#myID"`` rather than just ``#myID`` and ``"ul li"``
rather than just ``ul li``.
The value used to define the CSS style can either be a string
containing the CSS definition, or a javascript object that is itself a
collection of `name:value` pairs, where the `name` is the attribute
being defined and `value` is the value that attribute should be given.
Note that, since this is a JavaScript object, the pairs are separated
by commas (not semi-colons) and the values are enclosed in quotation
marks. If the name contains dashes, it should be enclosed in
quotation marks as well.
For example, ``jax/output/HTML-CSS/config.js`` includes the following
declaration:
.. code-block:: javascript
styles: {
".MathJax_Display": {
"text-align": "center",
margin: "1em 0em"
},
".MathJax .merror": {
"background-color": "#FFFF88",
color: "#CC0000",
border: "1px solid #CC0000",
padding: "1px 3px",
"font-style": "normal",
"font-size": "90%"
}
}
This defines two CSS styles, one for the selector
``.MathJax_Display``, which specifies its text alignment and margin
settings, and a second for ``.MathJax .merror``, which specifies a
background color, foreground color, border, and so on.
You can add as many such definitions to a ``styles`` object as you
wish. Note, however, that since this is a JavaScript object, the
selectors must be unique (e.g., you can't use two definitions for
``"img"``, for example, as only the last one would be saved). If you
need to use more than one entry for a single selector, you can add
comments like ``/* 1 */`` and ``/* 2 */`` to the selector to make them
unique.
It is possible to include selectors like ``"@media print"``, in which
case the value is a CSS style object. For example:
.. code-block:: javascript
styles: {
"@media print": {
".MathJax .merror": {
"background-color": "white",
border: 0
}
}
}
The various extensions and output processors include more examples of
CSS style objects, so see the code for those files for additional
samples. In particular, the ``extensions/MathMenu.js``,
``extensions/MathZoom.js``, ``extensions/FontWarnsing.js``, and
``jax/output/HTML-CSS/jax.js`` files include such definitions.
.. _html-snippets:
************************
Describing HTML snippets
************************
A number of MathJax configuration options allow you to specify an HTML
snippet using a JavaScript object. This lets you include HTML in your
configuration files even though they are not HTML files themselves.
The format is fairly simple, but flexible enough to let you represent
complicated HTML trees.
An HTML snippet is an array consisting of a series of elements that format
the HTML tree. Those elements are one of two things: either a string,
which represents text to be included in the snippet, or an array,
which represents an HTML tag to be included. In the latter case, the
array consists of three items: a string that is the tag name (e.g.,
"img"), an optional object that gives attributes for the tag (as
described below), and an optional HTML snippet array that gives the
contents of the tag.
When attributes are provided, they are given as `name:value` pairs,
with the `name` giving the attribute name, and `value` giving its
value. For example
.. code-block:: javascript
[["img",{src:"/images/mypic.jpg"}]]
represents an HTML snippet that includes one element: an ``<img>`` tag
with ``src`` set to ``/images/mypic.jpg``. That is, this is
equivalent to
.. code-block:: html
<img src="/images/mypic.jpg">
Note that the snippet has two sets of square brackets. The outermost
one is for the array that holds the snippet, and the innermost set is
because the first (and only) element in the snippet is a tag, not
text. Note that the code ``["img",{src:"/images/mypic.jpg"}]``
is invalid as an HTML snippet. It would represent a snippet that
starts with "img" as text in the snippet (not a tag), but the second
item is neither a string nor an array, and so is illegal. This is a
common mistake that should be avoided.
A more complex example is the following:
.. code-block:: javascript
[
"Please read the ",
["a",{href:"instructions.html"},["instructions"]],
" carefully before proceeding"
]
which is equivalent to
.. code-block:: html
please read the <a href="instructions.html">instructions</a> carefully
before proceeding.
A final example shows how to set style attributes on an object:
.. code-block:: javascript
[["span",
{
id:"mySpan",
style: {color:"red", "font-weight":"bold"}
},
[" This is bold text shown in red "]
]]
which is equivalent to
.. code-block:: html
<span id="mySpan" style="color: red; font-weight: bold;">
This is bold text shown in red
</span>
.. _api-ajax:
***********************
The MathJax.Ajax Object
***********************
The `MathJax.Ajax` structure holds the data and functions for handling
loading of external modules. Modules are loaded only once, even if
called for in several places. The loading of files is asynchronous,
and so the code that requests an external module will continue to run
even when that module has not completed loading, so it is important to
be aware of the timing issues this may cause. Similarly, creating or
loading stylesheets is an asynchronous action. In particular, all
actions that rely on the file or stylesheet having been loaded must be
delayed until after the file has been downloaded completely. This is
the reason for the large number of routines that take callback
functions.
Any operation that could cause the loading of a file or stylesheet
must be synchronized with the rest of the code via such callbacks.
Since processing any mathematics might cause files to be loaded (e.g.,
little-used markup might be implemented in an extension that is loaded
only when that markup is used), any code that dynamically typesets
mathematics will need to be structured to use callbacks to guarantee
that the mathematics has been completely processed before the code
tries to use it. See the :ref:`Synchronizing with MathJax <synchronization>`
documentation for details on how to do this properly.
Properties
==========
.. describe:: timeout
Number of milliseconds to wait for a file to load before
it is considered to have failed to load.
*Default:* 15 seconds
.. describe:: STATUS.OK
The value used to indicate that a file load has occurred
successfully.
.. describe:: STATUS.ERROR
The value used to indicate that a file load has caused an error or
a timeout to occur.
.. describe:: loaded
An object containing the names of the files that have been loaded (or
requested) so far. ``MathJax.Ajax.loaded["file"]`` will be
non-``null`` when the file has been loaded, with the value being
the ``MathJax.Ajax.STATUS`` value of the load attempt.
.. describe:: loading
An object containing the files that are currently loading, the
callbacks that are to be run when they load or timeout, and
additional internal data.
.. describe:: loadHooks
An object containing the load hooks for the various files, set up by
the :meth:`LoadHook()` method, or by the
:meth:`MathJax.Hub.Register.LoadHook()` method.
Methods
=======
.. method:: Require(file[,callback])
Loads the given file if it hasn't been already. The file must be a
JavaScript file or a CSS stylesheet; i.e., it must end in ``.js``
or ``.css``. Alternatively, it can be an object with a single
`key:value` pair where the `key` is one of ``js`` or ``css`` and
the `value` is the file of that type to be loaded (this makes it
possible to have the file be created by a CGI script, for example,
or to use a ``data::`` URL). The file must be relative to the
MathJax home directory and can not contain ``../`` file path
components.
When the file is completely loaded and run, the `callback`, if
provided, will be executed passing it the status of the file load.
If there was an error while loading the file, or if the file fails
to load within the time limit given by ``MathJax.Ajax.timout``,
the status will be ``MathJax.Ajax.STATUS.ERROR`` otherwise it
will be ``MathJax.Ajax.STATUS.OK``. If the file is already
loaded, the callback will be called immediately and the file will
not be loaded again.
:Parameters:
- **file** --- name of the file to be loaded
- **callback** --- the callback specification
:Returns: the callback object
.. method:: Load(file[,callback])
Used internally to load a given file without checking if it
already has been loaded, or where it is to be found.
:Parameters:
- **file** --- name of the file to be loaded
- **callback** --- the callback specification
:Returns: the callback object
.. method:: loadComplete(file)
Called from within the loaded files to inform MathJax that the
file has been completely loaded and initialized. The `file`
parameter is the name of the file that has been loaded. This
routine will cause any callback functions registered for the file
or included in the :meth:`MathJax.Ajax.Require()` calls to be
executed, passing them the status of the load
(``MathJax.Ajax.STATUS.OK`` or ``MathJax.Ajax.STATUS.ERROR``) as
their last parameter.
:Parameters:
- **file** --- name of the file that has been loaded
:Returns: ``null``
.. method:: loadTimeout(file)
Called when the timeout period is over and the file hasn't loaded.
This indicates an error condition, and the
:meth:`MathJax.Ajax.loadError()` method will be executed, then the
file's callback will be run with ``MathJax.Ajax.STATUS.ERROR`` as
its parameter.
:Parameters:
- **file** --- name of the file that timed out
:Returns: ``null``
.. method:: loadError(file)
The default error handler called when a file fails to load. It
puts a warning message into the MathJax message box on screen.
:Parameters:
- **file** --- the name of the file that failed to load
:Returns: ``null``
.. method:: LoadHook(file,callback)
Registers a callback to be executed when the given file is
loaded. The file load operation needs to be started when this
method is called, so it can be used to register a hook for a file
that may be loaded in the future.
:Parameters:
- **file** --- the name of the file to wait for
- **callback** --- the callback specification
:Returns: the callback object
.. method:: Preloading(file1[,file2...])
Used with combined configuration files to indicate what files are
in the configuration file. Marks the files as loading (since there
will never be an explicit :meth:`Load()` or :meth:`Require()` call for
them), so that load-hooks and other load-related events can be
properly processed when the :meth:`loadComplete()` occurs.
:Parameters:
- **file1, file2, ...** --- the names of the files in the combined file
:Returns: ``null``
.. method:: Styles(styles[,callback])
Creates a stylesheet from the given style data. `styles` can
either be a string containing a stylesheet definition, or an
object containing a :ref:`CSS Style Object <css-style-objects>`.
For example:
.. code-block:: javascript
MathJax.Ajax.Styles("body {font-family: serif; font-style: italic}");
and
.. code-block:: javascript
MathJax.Ajax.Styles({
body: {
"font-family": "serif",
"font-style": "italic"
}
});
both set the body font family and style.
The callback routine is called when the stylesheet has been
created and is available for use.
:Parameters:
- **styles** --- CSS style object for the styles to set
- **callback** --- the callback specification
:Returns: the callback object
.. note::
Internet Explorer has a limit of 32 dynamically created
stylesheets, so it is best to combine your styles into one
large group rather than making several smaller calls.
.. method:: fileURL(file)
Returns a complete URL to a file (replacing ``[MathJax]`` with the
actual root URL location).
:Parameters:
- **file** --- the file name possibly including ``[MathJax]``
:Returns: the full URL for the file
.. _api-element-jax:
****************************
The MathJax.ElementJax Class
****************************
The element jax is the bridge between the input and output jax, and
contains the data produced by the input jax needed by the output jax
to display the results. It is tied to the individual ``<script>`` tag
that produced it, and is the object used by JavaScript programs to
interact with the mathematics on the page.
An element jax is stored in the ``jax.js`` file in a subdirectory of
the ``jax/element`` directory, with the subdirectory name being the
name of the element jax. Currently, there is only one element jax
class, the `mml` element jax, and it is stored in ``jax/element/mml``.
The `MathJax.ElementJax` class is a subclass of the :ref:`MathJax Jax
<api-jax>` class, and inherits the properties and methods of that
class. Those listed below are the additional or overridden ones from
that class.
Class Properties
================
.. describe:: id
The name of the jax.
.. describe:: version
The version number of the jax.
.. describe:: directory
The directory where the jax files are stored (e.g., ``"[MathJax]/jax/element/mml"``).
Instance Properties
===================
.. describe:: inputJax
The name of the input jax that created the element.
.. describe:: outputJax
The name of the output jax that has processed this element.
.. describe:: inputID
The DOM `id` of the ``<script>`` tag that generated this element
(if it doesn't have one initially, the MathJax hub will supply
one). Note that this is not a reference to the element itself;
that element will have a reference to this element jax, and if
`inputID` were a reference back, that would cause a reference
loop, which some browsers would not free properly during trash
collection, thus causing a memory leak.
.. describe:: originalText
A string indicating the original input text that was processed for
this element. (In the future, this may be managed by the input jax
rather than ``MathJax.Hub``.)
.. describe:: mimeType
The MIME-type of the element jax (`jax/mml` in the case of an
`mml` element jax).
Other data specific to the element jax subclass may also appear here.
Methods
=======
.. Method:: Text(text[,callback])
Sets the input text for this element to the given text and
reprocesses the mathematics. (I.e., updates the equation to the
new one given by `text`). When the processing is complete, the
`callback`, if any, is called.
:Parameters:
- **text** --- the new mathematics source string for the element
- **callback** --- the callback specification
:Returns: the callback object
.. Method:: Rerender([callback])
:noindex:
Removes the output and produces it again (for example, if CSS has
changed that would alter the spacing of the mathematics). Note
that the internal representation isn't regenerated; only the
output is. The `callback`, if any, is called when the process
completes.
:Parameters:
- **callback** --- the callback specification
:Returns: the callback object
.. Method:: Reprocess([callback])
:noindex:
Removes the output and then retranslates the input into the
internal form and reredners the output again. The `callback`, if
any, is called when the process completes.
:Parameters:
- **callback** --- the callback specification
:Returns: the callback object
.. Method:: Remove()
:noindex:
Removes the output for this element from the web page (but does
not remove the original ``<script>``). The ``<script>`` will be
considered unprocessed, and the next call to
:meth:`MathJax.hub.Typeset()` will re-display it.
:Returns: ``null``
.. Method:: SourceElement()
Returns a reference to the original ``<script>`` DOM element
associated to this element jax.
:Returns: the ``<script>`` element
.. Method:: needsUpdate()
Indicates whether the mathematics has changed so that its output
needs to be updated.
:Returns: ``true`` if the mathematics needs to be reprocessed,
``false`` otherwise
Output jax may add new methods to the base element jax class to
perform exporting to other formats. For example, a MathML output jax
could add ``toMathML()``, or an accessibility output jax could add
``toAudible()``. These could be made available via the MathJax
contextual menu.
.. _api-html:
***********************
The MathJax.HTML Object
***********************
The ``MathJax.HTML`` object provides routines for creating HTML
elements and adding them to the page, and in particular, it contains
the code that processes MathJax's :ref:`HTML snippets <html-snippets>`
and turns them into actual DOM objects. It also implements the
methods used to manage the cookies used by MathJax.
Properties
==========
.. describe:: Cookie.prefix: "mjx"
The prefix used for names of cookies stored by MathJax.
.. describe:: Cookie.expires: 365
The expiration time (in days) for cookies created by MathJax.
Methods
=======
.. method:: Element(type[,attributes[,contents]])
Creates a DOM element of the given type. If `attributes` is
non-``null``, it is an object that contains `key:value` pairs of
attributes to set for the newly created element. If `contents` is
non-``null``, it is an :ref:`HTML snippet <html-snippets>` that
describes the contents to create for the element. For example
.. code-block:: javascript
var div = MathJax.HTML.Element(
"div",
{id: "MathDiv", style:{border:"1px solid", padding:"5px"}},
["Here is math: \\(x+1\\)",["br"],"and a display $$x+1\\over x-1$$"]
);
:Parameters:
- **type** --- node type to be created
- **attributes** --- object specifying attributes to set
- **contents** --- HTML snippet representing contents of node
:Returns: the DOM element created
.. method:: addElement(parent,type[,attributes[,content]])
Creates a DOM element and appends it to the `parent` node
provided. It is equivalent to
.. code-block:: javascript
parent.appendChild(MathJax.HTML.Element(type,attributes,content))
:Parameters:
- **parent** --- the node where the element will be added
- **attributes** --- object specifying attributes to set
- **contents** --- HTML snippet representing contents of node
:Returns: the DOM element created
.. method:: TextNode(text)
Creates a DOM text node with the given text as its content.
:Parameters:
- **text** --- the text for the node
:Returns: the new text node
.. method:: addText(parent,text)
Creates a DOM text node with the given text and appends it to the
`parent` node.
:Parameters:
- **parent** --- the node where the text will be added
- **text** --- the text for the new node
:Returns: the new text node
.. method:: setScript(script,text)
Sets the contents of the ``script`` element to be the given
``text``, properly taking into account the browser limitations and
bugs.
:Parameters:
- **script** --- the script whose content is to be set
- **text** --- the text that is to be the script's new content
:Returns: ``null``
.. method:: getScript(script)
Gets the contents of the ``script`` element, properly taking into
account the browser limitations and bugs.
:Parameters:
- **script** --- the script whose content is to be retrieved
:Returns: the text of the ``script``
.. describe:: Cookie.Set(name,data)
Creates a MathJax cookie using the ``MathJax.HTML.Cookie.prefix``
and the `name` as the cookie name, and the `key:value` pairs in
the `data` object as the data for the cookie. For example,
.. code-block:: javascript
MathJax.HTML.Cookie.Set("test",{x:42, y:"It Works!"});
will create a cookie named "mjx.test" that stores the values of
``x`` and ``y`` provided in the `data` object. This data can be
retrieved using the :meth:`MathJax.HTML.Cookie.Get()` method
discussed below.
:Parameters:
- **name** --- the name that identifies the cookie
- **data** --- object containing the data to store in the cookie
:Returns: ``null``
.. describe:: Cookie.Get(name[,obj])
Looks up the data for the cookie named `name` and merges the data
into the given `obj` object, or returns a new object containing
the data. For instance, given the cookie stored by the example
above,
.. code-block:: javascript
var data = MathJax.HTML.Cookie.Get("test");
would set ``data`` to ``{x:42, y:"It Works!"}``, while
.. code-block:: javascript
var data = {x:10, z:"Safe"};
MathJax.HTML.Cookie.Get("test",data);
would leave ``data`` as ``{x:42, y:"It Works!", z:"Safe"}``.
.. _mathjax-api:
===============
The MathJax API
===============
The following links document the various components that make up
MathJax. These are implemented as JavaScript objects contained within
the single global variable, ``MathJax``. Although JavaScript includes
an object system with some inheritance capabilities, they do not
constitute a full object-oriented programming model, so MathJax
implements its own object library. This means there is an ambiguity
when we speak of an "object", as it could be either a native
JavaScript object, or a MathJax object. When the distinction is
importat, we will use `Object` (capitalized) or `MathJax.Object` for
the latter; the javascript object will always be listed in lower
case.
You may also want to view the :ref:`advanced topics <advanced-topics>`
on the main MathJax documentation page.
.. toctree::
:maxdepth: 1
The MathJax variable <variable>
The MathJax.Hub object <hub>
The MathJax.Ajax object <ajax>
The MathJax.Message object <message>
The MathJax.HTML object <html>
The MathJax.CallBack class <callback>
The MathJax.CallBack.Queue class <queue>
The MathJax.CallBack.Signal class <signal>
.. toctree::
:maxdepth: 1
The MathJax.InputJax class <inputjax>
The MathJax.OutputJax class <outputjax>
The MathJax.ElementJax class <elementjax>
The base Jax class <jax>
.. toctree::
:maxdepth: 1
The MathJax Object-Oriented Programming Model <object>
.. _api-input-jax:
**************************
The MathJax.InputJax Class
**************************
Input jax are the components of MathJax that translate
mathematics from its original format (like :term:`TeX` or
:term:`MathML`) to the MathJax internal format (an `element jax`).
An input jax is stored as a pair of files in a subdirectory of the
``jax/input`` directory, with the subdirectory name being the name of
the input jax. For example, the TeX input jax is stored in
`jax/input/TeX`. The first file, ``config.js``, is loaded when
MathJax is being loaded and configured, and is indicated by listing
the input jax directory in the `jax` array of the MathJax
configuration. The ``config.js`` file creates a subclass of the
`MathJax.InputJax` object for the new input jax and registers that
with MathJax, along with the MIME-type that will be used to indicate
the mathematics that is to be processed by the input jax.
The main body of the input jax is stored in the second file,
``jax.js``, which is loaded when the input jax is first called on to
translate some mathematics. This file augments the original input jax
subclass with the additional methods needed to do the translation.
MathJax calls the input jax's :meth:`Translate()` method when it needs
the input jax to translate the contents of a math ``<script>`` tag.
The `MathJax.InputJax` class is a subclass of the :ref:`MathJax Jax
<api-jax>` class, and inherits the properties and methods of that
class. Those listed below are the additional or overridden ones from
that class.
Properties
==========
.. describe:: id
The name of the jax.
.. describe:: version
The version number of the jax.
.. describe:: directory
The directory where the jax files are stored (e.g., ``"[MathJax]/jax/input/TeX"``).
.. describe:: elementJax
The name of the ElementJax class that this input jax will produce
(typically ``mml``, as that is the only ElementJax at the moment).
Methods
=======
.. Method:: Process(script,state)
:noindex:
This is the method that the ``MathJax.Hub`` calls when it needs
the input jax to process the given math ``<script>``. Its default
action is to do the following:
1. Start loading any element jax specified in the ``elementJax`` array;
2. Start loading the jax's ``jax.js`` file;
3. Start loading the required output jax (so it is ready when needed); and
4. Redefine itself to simply return the callback for the load operation
(so that further calls to it will cause the processing to wait for the
callback).
Once the ``jax.js`` file has loaded, this method is replaced by
the jax's ``Translate()`` method (see below), so that
subsequent calls to ``Process()`` will perform the appropriate
translation.
:Parameters:
- **script** --- reference to the DOM ``<script>`` object for
the mathematics to be translated
- **state** --- a structure containing information about the
current proccessing state of the mathematics
(internal use)
:Returns: an `ElementJax` object, or ``null``
.. Method:: Translate(script,state)
:noindex:
This is the main routine called by MathJax when a ``<script>`` of the
appropriate type is found. The default :meth:`Translate()` method
throws an error indicating that :meth:`Translate()` hasn't been
defined, so when the ``jax.js`` file loads, it should override the
default :meth:`Translate()` with its own version that does the actual
translation.
The translation process should include the creation of an
:ref:`Element Jax <api-element-jax>` that stores the data needed
for this element.
:Parameters:
- **script** --- the ``<script>`` element to be translated
- **state** --- a structure containing information about the
current proccessing state of the mathematics
(internal use)
:Returns: the `element jax` resulting from the translation
.. Method:: Register(mimetype)
:noindex:
This registers the MIME-type associated with this input jax so
that MathJax knows to call this input jax when it sees a
``<script>`` of that type. An input jax can register more than
one type, but it will be responsible for distinguishing elements
of the various types from one another.
:Parameters:
- **mimetype** --- the MIME-type of the input this jax processes
:Returns: ``null``
.. Method:: needsUpdate(jax)
:noindex:
This implements the element jax's ``needsUpdate()`` method, and
returns ``true`` if the ``jax`` needs to be rerendered (i.e., the
text has changed), and ``false`` otherwise.
:Perameters:
- **jax** --- the element jax to be checked
:Returns: ``true`` if the jax's text has changed, ``false`` otherwise
.. _api-jax:
******************
The Base Jax Class
******************
The `MathJax.InputJax`, `MathJax.OutputJax` and `MathJax.ElementJax`
classes are all subclasses of the base `Jax` class in MathJax. This
is a private class that implements the methods common to all three
other jax classes.
Unlike most MathJax.Object classes, calling the class object creates a
*subclass* of the class, rather than an instance of the class. E.g.,
.. code-block:: javascript
MathJax.InputJax.MyInputJax = MathJax.InputJax({
id: "MyInputJax",
version: "1.0",
...
});
creates ``MathJax.InputJax.MyInputJax`` as a subclass of ``MathJax.InputJax``.
Class Properties
================
.. describe:: directory
The name of the jax directory (usually ``"[MathJax]/jax"``).
Overridden in the subclass to be the specific directory for the
class, e.g. ``"[MathJax]/jax/input"``.
.. describe:: extensionDir
The name of the extensions directory (usually ``"[MathJax]/extensions"``).
Instance Properties
===================
.. describe:: id
The name of the jax.
.. describe:: version
The version number of the jax.
.. describe:: directory
The directory for the jax (e.g., ``"[MathJax]/jax/input/TeX"``).
.. describe:: require: null
An array of files to load before the ``jax.js`` file calls the
:meth:`MathJax.Ajax.loadComplete()` method.
.. describe:: config: {}
An object that contains the default configuration options for the
jax. These can be modified by the author by including a
configuration subsection for the specific jax in question.
.. describe:: JAXFILE: "jax.js"
The name of the file that contains the main code for the jax.
Methods
=======
.. Method:: Translate(script)
This is a stub for a routine that should be defined by the jax's
``jax.js`` file when it is loaded. It should perform the translation
action for the specific jax. For an input jax, it should return the
`ElementJax` object that it created. The :meth:`Translate()` method is
never called directly by MathJax; during the ``loadComplete()``
call, this function is copied to the :meth:`Process()` method, and is
called via that name. The default :meth:`Translate()` method throws an
error indicating that the :meth:`Translate()` method was not
redefined. That way, if the ``jax.js`` file fails to load for some
reason, you will receive an error trying to process mathematics with
this jax.
:Parameters:
- **script** --- reference to the DOM ``<script>`` object for
the mathematics to be translated
:Returns: an `ElementJax` object, or ``null``
.. Method:: Register(mimetype)
This method is overridden in the `InputJax`, `OutputJax` and
`ElementJax` subclasses to handle the registration of those
classes of jax.
:Parameters:
- **mimetype** --- the MIME-type to be associated with the jax
:Returns: ``null``
.. Method:: Config()
:noindex:
Inserts the configuration block for this jax from the author's
configuration specification into the jax's ``config`` property.
If the configuration includes an ``Augment`` object, that is used
to augment the jax (that is, the configuration can override the
methods of the object, as well as the data). This is called
automatically during the loading of the ``jax.js`` file.
.. Method:: Startup()
This is a method that can be overridden in the subclasses to
perform initialization at startup time (after the configuration
has occurred).
.. Method:: loadComplete (file)
:noindex:
This is called by the ``config.js`` and ``jax.js`` files when they
are completely loaded and are ready to signal that fact to
MathJax. For ``config.js``, this simply calls the
:meth:`MathJax.Ajax.loadComplete()` method for the ``config.js``
file. For ``jax.js``, the actions performed here are the
following:
1. Post the "[name] Jax Config" message to the startup signal.
2. Perform the jax's :meth:`Config()` method.
3. Post the "[name] Jax Require" message to the startup signal.
4. Load the files from the jax's ``require`` and
``config.extensions`` arrays.
5. Post the "[name] Jax Startup" message to the startup signal.
6. Perform the jax's :meth:`Startup()` method.
7. Post the "[name] Jax Ready" message to the startup signal.
8. Copy the ``preTranslate``, ``Translate``, and
``postTranslate`` functions to ``preProcess``, ``Process``,
and ``postProcess``.
9. Perform the :meth:`MathJax.Ajax.loadComplete()` call for the
``jax.js`` file.
Note that the configuration process (the :meth:`Config()` call) can
modify the ``require`` or ``config.extensions`` arrays to add more
files that need to be loaded, and that the :meth:`Startup()` method
isn't called until those files are completely loaded.
.. _api-message:
**************************
The MathJax.Message Object
**************************
The ``MathJax.Message`` object contains the methods used to manage the
small message area that appears at the lower-left corner of the
window. MathJax uses this area to inform the user of time-consuming
actions, like loading files and fonts, or how far along in the
typesetting process it is.
The page author can customize the look of the message window by
setting styles for the ``#MathJax_Message`` selector (which can be
set via
.. code-block:: javascript
MathJax.Hub.Config({
styles: {
"#MathJax_Message": {
...
}
}
});
Because of a bug in Internet Explorer, in order to change the side of
the screen where the message occurs, you must also set the side
for ``#MathJax_MSIE_Frame``, as in
.. code-block:: javascript
MathJax.Hub.Config({
styles: {
"#MathJax_Message": {left: "", right: 0},
"#MathJax_MSIE_Frame": {left: "", right: 0}
}
});
It is possible that a message is already being displayed when another
message needs to be posted. For this reason, when a message is
displayed on screen, it gets an id number that is used when you want
to remove or change that message. That way, when a message is
removed, the previous message (if any) can be redisplayed if it hasn't
been removed. This allows for intermittent messages (like file
loading messages) to obscure longer-term messages (like "Processing
Math" messages) temporarily.
Methods
=======
.. method:: Set(message,[n,[delay]])
This sets the message being displayed to the given `message`
string. If `n` is not ``null``, it represents a message id
number and the text is set for that message id, otherwise a new id
number is created for this message. If `delay` is provided, it is
the time (in milliseconds) to display the message before it is
cleared. If `delay` is not provided, the message will not be
removed automatically; you must call the
:meth:`MathJax.Messsage.Clear()` method by hand to remove it.
:Parameters:
- **message** --- the text to display in the message area
- **n** --- the message id number
- **delay** --- amout of time to display the message
:Returns: the message id number for this message.
.. method:: Clear(n[,delay])
This causes the message with id `n` to be removed after the given
`delay`, in milliseconds. The default delay is 600 milliseconds.
:Parameters:
- **n** --- the message id number
- **delay** --- the delay before removing the message
:Returns: ``null``
.. method:: Remove()
This removes the message frame from the window (it will reappear when
future messages are set, however).
:Returns: ``null``
.. method:: File(file)
This sets the message area to a "Loading *file*" message, where *file*
is the name of the file (with ``[MathJax]`` representing the root
directory).
:Parameters:
- **file** --- the name of the file being loaded
:Returns: the message id number for the message created
.. method:: filterText(text,n)
This method is called on each message before it is displayed. It can
be used to modify (e.g., shorten) the various messages before they are
displayed. The default action is to check if the ``messageStyle``
configuration parameter is ``simple``, and if so, convert loading and
processing messages to a simpler form. This method can be overridden
to perform other sanitization of the message strings.
:Parameters:
- **text** --- the text of the message to be posted
- **n** --- the id number of the message to be posted
:Returns: the modified message text
.. method:: Log()
Returns a string of all the messages issued so far, separated by
newlines. This is used in debugging MathJax operations.
:Returns: string of all messages so far
.. _api-object:
*********************************************
The MathJax Object-Oriented Programming Model
*********************************************
MathJax uses an object-oriented programming model for its main
components, such as the `Input jax`, `Output jax`, and `Element jax`.
The model is intended to be light-weight and is based on JavaScript's
prototype inheritance mechanism. Object classes are created by making
subclasses of `MathJax.Object` or one of its subclasses, and are
instantiated by calling the object class as you would a function.
For example:
.. code-block:: javascript
MathJax.Object.Foo = MathJax.Object.Subclass({
Init: function (x) {this.setX(x)},
getX: function () {return this.x},
setX: function (x) {this.x = x}
});
var foo = MathJax.Object.Foo("bar");
foo.getX(); // returns "bar"
foo.setX("foobar");
foo.getX(); // returns "foobar"
Object classes can have static properties and methods, which are
accessed via the object class variable. E.g.,
``MathJax.Object.Foo.SUPER`` or ``MathJax.Object.Foo.Augment()`` for
the object in the example above. Static values are not inherited by
subclasses.
Static Properties
=================
.. describe:: SUPER
Pointer to the super class for this subclass. (It is a reference to
`MathJax.Object` in the example above.)
Static Methods
==============
.. method:: Subclass(def[,static])
Creates a subclass of the given class using the contents of the
`def` object to define new methods and properties of the object
class, and the contents of the optional `static` object to define
new static methods and properties.
:Parameters:
- **def** --- object that defines the properties and methods
- **static** --- object that defines static properties and methods
:Returns: the new object class
.. method:: Augment(def[,static])
Adds new properties and methods to the class prototype. All
instances of the object already in existence will receive the new
properties and methods automatically.
:Parameters:
- **def** --- object that defines the properties and methods
- **static** --- object that defines static properties and methods
:Returns: the object class itself
Properties
==========
.. describe:: constructor
Pointer to the constructor function for this class. E.g.,
``foo.constructor`` would be a reference to ``MathJax.Object.Foo``
in the example above.
Methods
=======
.. method:: Init([data])
An optional function that is called when an instance of the class
is created. When called, the `this` variable is set to the newly
instantiated object, and the `data` is whatever was passed to the
object constructor. For instance, in the example above, the
variable ``foo`` is created by calling
``MathJax.Object.Foo("bar")``, which calls the
``MathJax.Object.Foo`` object's :meth:`Init()` method with `data`
equal to ``"bar"``. If desired, the :meth:`Init()` method can
create a *different* object, and return that, in which case this
becomes the return value for the object constructor.
:Parameters:
- **data** --- the data from the constructor call
:Returns: ``null`` or the object to be returned by the constructor
.. method:: isa(class)
Returns ``true`` if the object is an instance of the given class,
or of a subclass of the given class, and ``false`` otherwise. So
using the ``foo`` value defined above,
.. code-block:: javascript
foo.isa(MathJax.Object); // returns true
foo.isa(MathJax.Object.Foo); // returns true
foo.isa(MathJax.InputJax); // returns false
.. method:: can(method)
Checks if the object has the given `method` and returns ``true``
if so, otherwise returns ``false``. This allows you to test if an
object has a particular function available before trying to call
it (i.e., if an object implements a particular feature). For example:
.. code-block:: javascript
foo.can("getX"); // returns true
foo.can("bar"); // returns false
.. method:: has(property)
Checks if the object has the given `property` and returns ``true``
if so, otherwise returns ``false``. This allows you to test if an
object has a particular property available before trying to use
it. For example:
.. code-block:: javascript
foo.has("getX"); // returns true
foo.has("x"); // returns true
foo.has("bar"); // returns false
Accessing the Super Class
=========================
If a subclass overrides a method of its parent class, it may want to
call the original function as part of its replacement method. The
semantics for this are a bit awkward, but work efficiently. Within a
method, the value ``arguments.callee.SUPER`` refers to the super
class, so you can access any method of the superclass using that. In
order to have `this` refer to the current object when you call the
super class, however, you need to use ``call()`` or
``apply()`` to access the given method.
For example, ``arguments.callee.SUPER.method.call(this,data)`` would
call the superclass' `method` and pass it `data` as its argument,
properly passing the current object as `this`. Alternatively, you can
use ``this.SUPER(arguments)`` in place of ``arguments.callee.SUPER``.
It is also possible to refer to the super class explicitly rather than
through ``arguments.callee.SUPER``, as in the following example:
.. code-block:: javascript
MathJax.Class1 = MathJax.Object.Subclass({
Init: function(x) {this.x = x},
XandY: function(y) {return "Class1: x and y = " + this.x + " and " + y}
});
MathJax.Class2 = MathJax.Class1.Subclass({
XandY: function (y) {return "Class2: "+arguments.callee.SUPER.XandY.call(this,y)}
});
MathJax.Class3 = MathJax.Class2.Subclass({
XandY: function (y) {return "Class3: "+MathJax.Class2.prototype.XandY.call(this,y)}
});
MathJax.Class4 = MathJax.Class1.Subclass({
XandY: function (y) {return "Class4: "+this.SUPER(arguments).XandY.call(this,y)}
});
var foo = MathJax.Class2("foo");
foo.XandY("bar"); // returns "Class2: Class1: x and y = foo and bar"
var bar = MathJax.Class3("bar");
bar.XandY("foo"); // returns "Class3: Class2: Class1: x and y = bar and foo"
var moo = MathJax.Class4("moo");
moo.XandY("cow"); // returns "Class4: Class1: x and y = moo and cow"
Since both of these mechanisms are rather awkward, MathJax provides an
alternative syntax that is easier on the programmer, but at the cost
of some inefficiency in creating the subclass and in calling methods
that access the super class.
Since most calls to the super class are to the overridden method, not
to some other method, the method name and the ``call()`` are
essentially redundant. You can get a more convenient syntax by
wrapping the `def` for the :meth:`Subclass()` call in a call to
``MathJax.Object.SimpleSUPER()``, as in the following example:
.. code-block:: javascript
MathJax.Class1 = MathJax.Object.Subclass({
Init: function (x) {this.x = x},
XandY: function (y) {return "Class1: x and y = " + this.x + " and " + y}
});
MathJax.Class2 = MathJax.Class1.Subclass(
MathJax.Object.SimpleSUPER({
XandY: function (y) {return "Class2: "+this.SUPER(y)},
AnotherMethod: function () {return this.x} // it's OK if a method doesn't use SUPER
})
);
var foo = MathJax.Class2("foo");
foo.XandY("bar"); // returns "Class2: Class1: x and y = foo and bar"
.. _api-output-jax:
***************************
The MathJax.OutputJax Class
***************************
Output jax are the components of MathJax that translate
mathematics from the MathJax internal format (an `element jax`)
to whatever output is required to represent the mathematics (e.g.,
MathML elements, or HTML-with-CSS that formats the mathematics on screen).
An output jax is stored as a pair of files in a subdirectory of the
the ``jax/output`` directory, with the subdirectory name being the
name of the output jax. For example, the NativeMML output jax is
stored in `jax/output/NativeMML`. The first file, ``config.js``, is
loaded when MathJax is being loaded and configured, and is indicated
by listing the input jax directory in the `jax` array of the MathJax
configuration. The ``config.js`` file creates a subclass of the
`MathJax.OutputJax` object for the new output jax and registers it
with MathJax, along with the MIME-type of the element jax that it can
process.
The main body of the output jax is stored in the second file, ``jax.js``,
which is loaded when the output jax is first called on to translate
some mathematics. This file augments the original output jax
subclass with the additional methods needed to produce the output.
MathJax calls the input jax's :meth:`Translate()` method when it needs
the output jax to translate an element jax to produce output.
The `MathJax.OutputJax` class is a subclass of the :ref:`MathJax Jax
<api-jax>` class, and inherits the properties and methods of that
class. Those listed below are the additional or overridden ones from
that class.
Properties
==========
.. describe:: id
The name of the jax.
.. describe:: version
The version number of the jax.
.. describe:: directory
The directory where the jax files are stored (e.g., ``"[MathJax]/jax/output/HTML-CSS"``);
.. describe:: fontDir
The directory where the fonts are stored (e.g., ``"[MathJax]/fonts"``)
.. describe:: imageDir
The directory where MathJax images are found (e.g. ``"[MathJax]/images"``)
Methods
=======
.. Method:: preProcess(state)
This is called by ``MathJax.Hub`` to ask the output processor to
prepare to process math scripts. Its default action is to start
loading the jax's ``jax.js`` file, and redefine itself to simply
return the callback for the load operation (so that further calls
to it will cause the processing to wait for the callback).
Once the ``jax.js`` file has loaded, this method is replaced by
the jax's :meth:`preTranslate()` method, so that subsequent calls
to :meth:`preProcess()` will perform the appropriate translation.
:Parameters:
- **state** --- a structure containing information about the
current proccessing state of the mathematics
:Returns: ``null``
.. Method:: preTranslate(state)
This routine replaces :meth:`preProcess()` above when the jax's
``jax.js`` file is loaded. It is called by ``MathJax.Hub`` to ask
the output processor to prepare to process math scripts. (For
example, the HTML-CSS output jax uses this to determine em-sizes
for all the mathematics at once, to minimize page reflows that
slow down Internet Explorer.)
The routine can use ``state.jax[this.id]`` to obtain the array of
element jax that are to be processed. The output jax can use the
``state`` variable to maintain its own state information, but
any properties that it adds to the variable should have a prefix
that is the output jax's ID. For example, the HTML-CSS output jax
might use ``state.HTMLCSSlast`` to keep track of the last equation
it processed, or could add ``state.HTMLCSS = {...}`` to create an
object of its own within the state variable.
:Parameters:
- **state** --- a structure containing information about the
current proccessing state of the mathematics
:Returns: ``null``
.. Method:: Translate(script,state)
:noindex:
This is the main routine called by MathJax when an element jax is
to be converted to output. The default :meth:`Translate()`
method throws an error indicating that :meth:`Translate()` hasn't been
defined, so when the ``jax.js`` file loads, it should override the
default :meth:`Translate()` with its own version that does the actual
translation.
You should use ``MathJax.Hub.getJaxFor(script)`` to obtain the
element jax for the given script. The translation process may
modify the element jax (e.g., if it has data that needs to be
stored with the jax), and may insert DOM elements into the
document near the jax's ``<script>`` tag. The output jax can use
the ``state`` variable to maintain information about its
processing state, but see :meth:`preTranslate()` above for naming
conventions for properties that are added.
:Parameters:
- **script** --- the ``<script>`` element to be translated
- **state** --- a structure containing information about the
current proccessing state of the mathematics
:Returns: the `element jax` resulting from the translation
.. Method:: postTranslate(state)
This routines is called by ``MathJax.Hub`` when the translation
of math elements is complete, and can be used by the output
processor to finalize any actions that it needs to complete.
(For example, making the mathematics visible, or forcing a reflow
of the page.)
The routine can use ``state.jax[this.id]`` to obtain the array of
element jax that were processed, or can use the ``state`` variable
to store its own state information (see :meth:`preProcess()`
above for caveats about naming properties).
:Parameters:
- **state** --- a structure containing information about the
current proccessing state of the mathematics
:Returns: ``null``
.. Method:: Register(mimetype)
:noindex:
This registers the MIME-type for the element jax associated with
this output jax so that MathJax knows to call this jax when it
wants to display an element jax of that type. Several output jax
may register for the same input jax, in which case the first one
to register will be the default one for that type.
:Parameters:
- **mimetype** --- the MIME-type of the input this jax processes
:Returns: ``null``
.. Method:: Remove(jax)
:noindex:
Removes the output associated with the given element jax. The
routine can use ``jax.SourceElement()`` to locate the ``<script>``
tag associated with the element jax.
:Parameters:
- **jax** --- the element jax whose display should be removed
:Returns: ``null``
If an output jax wants its output to handle the contextual menu item
and zooming, then it needs to tie into the event-handling code
(`MathEvents`) and the zoom-handling code (`MathZoom`). That requires
the following methods.
.. Method:: getJaxFromMath(math)
This is called by the event-handling code (`MathEvents`) to get
the element jax associated with the DOM element that caused an
event to occur. The output jax will have attached event handlers
to some DOM element that is part of its output, and the
`MathEvents` code uses this routine to map back to the jax
associated with that output.
:Parameters:
- **math** --- a DOM element that triggered a DOM event
(e.g., a mouse click)
:Returns: the `ElementJax` structure associated with the DOM element
.. Method:: Zoom(jax,span,math,Mw,Mh)
This routine is called by the zoom-handling code (`MathZoom`)
when an expression has received its zoom trigger event (e.g., a
double-click). The ``jax`` is the math that needs to be zoomed,
``span`` is a ``<span>`` element in which the zoomed version of
the math should be placed, ``math`` is the DOM element that
received the zoom trigger event, and ``Mw`` and ``Mh`` are the
maximum width and height allowed for the zoom box (the ``span``).
The return value is an object with the following properties:
- ``Y`` --- the vertical offset from the top of the ``span`` to
the baseline of the mathematics
- ``mW`` --- the width of the original mathematics element
- ``mH`` --- the height of the original mathematics element
- ``zW`` --- the width of the zoomed math
- ``zH`` --- the height of the zoomed math
All of these values are in pixels.
:Parameters:
- **jax** --- the jax to be zoomed
- **span** --- the ``<span>`` in which to place the zoomed math
- **math** --- the DOM element generating the zoom event
- **Mw** --- the maximum width of the zoom box
- **Mh** --- the maximum height of the zoom box
:Returns: a structure as described above
.. _api-queue:
********************************
The MathJax.Callback.Queue Class
********************************
The ``MathJax.Callback.Queue`` object is one of the key mechanisms
used by MathJax to synchronize its actions with those that occur
asynchronously, like loading files and stylesheets. A `Queue` object
is used to coordinate a sequence of actions so that they are performed
one after another, even when one action has to wait for an
asynchronous process to complete. This guarantees that operations are
performed in the right order even when the code must wait for some
other action to occur. See :ref:`Synchronizing with MathJax
<synchronization>` for more details, and :ref:`Using Queues
<using-queues>` in particular for examples of how to specify and use
MathJax `Queue` objects.
Properties
----------
.. describe:: pending
This is non-zero when the queue is waiting for a command to
complete, i.e. a command being processed returns a `Callback`
object, indicating that the queue should wait for that action to
complete before processing additional commands.
.. describe:: running
This is non-zero when the queue is executing one of the commands in
the queue.
.. describe:: queue
An array containing the queued commands that are yet to be performed.
Methods
-------
.. method:: Push(callback,...)
Adds commands to the queue and runs them (if the queue is not
pending or running another command). If one of the callbacks is
an actual `Callback` object rather than a callback specification,
then the command queued is an internal command to wait for the
given callback to complete. That is, that callback is not itself
queued to be executed, but a wait for that callback is queued.
The :meth:`Push()` method returns the last callback that was
added to the queue (so that it can be used for further
synchronization, say as an entry in some other queue).
:Parameters:
- **callback** --- the callback specifications to be added to the queue
:Returns: the last callback object added to the queue
.. method:: Process()
:noindex:
Process the commands in the queue, provided the queue is not
waiting for another command to complete. This method is used
internally; you should not need to call it yourself.
.. method:: Suspend()
Increments the `running` property, indicating that any commands that
are added to the queue should not be executed immediately, but should
be queued for later execution (when its :meth:`Resume()` is
called). This method is used internally; you should not need to
call it yourself.
.. method:: Resume()
Decrements the `running` property, if it is positive. When it is
zero, commands can be processed, but that is not done
automatically --- you would need to call :meth:`Process()` to make
that happen. This method is used internally; you should not need
to call it yourself.
.. method:: wait(callback)
Used internally when an entry in the queue is a `Callback` object
rather than a callback specification. A callback to this function
(passing it the original callback) is queued instead, and it
simply returns the callback it was passed. Since the queue will
wait for a callback if it is the return value of one of the
commands it executes, this effectively makes the queue wait for the
original callback at that point in the command queue.
:Parameters:
- **callback** --- the function to complete before returning to the queue
:Returns: the passed callback function
.. method:: call()
An internal function used to restart processing of the queue after
it has been waiting for a command to complete.
.. _api-signal:
*********************************
The MathJax.Callback.Signal Class
*********************************
The ``MathJax.Callback.Signal`` object is one of the key mechanisms
used by MathJax to synchronize its actions with those that occur
asynchronously, like loading files and stylesheets. A `Signal` object
is used to publicize the fact that MathJax has performed certain
actions, giving other code running the web page the chance to react to
those actions. See :ref:`Synchronizing with MathJax
<synchronization>` for more details, and :ref:`Using Signals
<using-signals>` in particular for examples of how to specify and use
MathJax `Signal` objects.
The `Callback Signal` object is a subclass of the :ref:`Callback Queue
<api-queue>` object.
Properties
----------
.. describe:: name
The name of the signal. Each signal is named so that
various components can access it. The first one to request a
particular signal causes it to be created, and other requests for
the signal return references to the same object.
.. describe:: posted
Array used internally to store the post history so that when new
listeners express interests in this signal, they can be informed
of the signals that have been posted so far. This can be cleared
using the signal's :meth:`Clear()` method.
.. describe:: listeners
Array of callbacks to the listeners who have expressed interest in
hearing about posts to this signal. When a post occurs, the
listeners are called, each in turn, passing them the message that
was posted.
Methods
-------
.. method:: Post(message[,callback])
Posts a message to all the listeners for the signal. The listener
callbacks are called in turn (with the message as an argument),
and if any return a `Callback` object, the posting will be
suspended until the callback is executed. In this way, the
:meth:`Post()` call can operate asynchronously, and so the
`callback` parameter is used to synchronize with its operation;
the `callback` will be called when all the listeners have responded
to the post.
If a :meth:`Post()` to this signal occurs while waiting for the
response from a listener (either because a listener returned a
`Callback` object and we are waiting for it to complete when the
:meth:`Post()` occurred, or because the listener itself called the
``Post()`` method), the new message will be queued and will be
posted after the current message has been sent to all the
listeners, and they have all responded. This is another way in
which posting can be asynchronous; the only sure way to know that
a posting has occurred is through its `callback`. When the posting
is complete, the callback is called, passing it the signal object
that has just completed.
Returns the callback object (or a blank callback object if none
was provided).
:Parameters:
- **message** --- the message to send through the signal
- **callback** --- called after the message is posted
:Returns: the callback or a blank callback
.. method:: Clear([callback])
:noindex:
This causes the history of past messages to be cleared so new
listeners will not receive them. Note that since the signal may
be operating asynchronously, the :meth:`Clear()` may be queued for
later. In this way, the :meth:`Post()` and :meth:`Clear()`
operations will be performed in the proper order even when they
are delayed. The `callback` is called when the :meth:`Clear()`
operation is completed.
Returns the callback (or a blank callback if none is provided).
:Parameters:
- **callback** --- called after the signal history is cleared
:Returns: the callback or a blank callback
.. method:: Interest(callback[,ignorePast])
This method registers a new listener on the signal. It creates a
`Callback` object from the callback specification, attaches it to
the signal, and returns that `Callback` object. When new messages
are posted to the signal, it runs the callback, passing it the
message that was posted. If the callback itself returns a
`Callback` object, that indicates that the listener has started an
asynchronous operation and the poster should wait for that
callback to complete before allowing new posts on the signal.
If `ignorePast` is ``false`` or not present, then before
:meth:`Interest()` returns, the callback will be called with all
the past messages that have been sent to the signal.
:Parameters:
- **callback** --- called whenever a message is posted (past or present)
- **ignorePast** --- ``true`` means ignore previous messages
:Returns: the callback object
.. method:: NoInterest(callback)
This removes a listener from the signal so that no new messages
will be sent to it. The callback should be the one returned by
the original :meth:`Interest()` call that attached the listener to
the signal in the first place. Once removed, the listener will no
longer receive messages from the signal.
:Parameters:
- **callback** --- the listener to be removed from signal
:Returns: ``null``
.. method:: MessageHook(message, callback)
This creates a callback that is called whenever the signal posts
the given message. This is a little easier than having to write a
function that must check the message each time it is called.
Although the `message` here is a string, if a message posted to the
signal is an array, then only the first element of that array is
used to match against the message. That way, if a message contains an
identifier plus arguments, the hook will match the identifier and
still get called with the complete set of arguments.
Returns the `Callback` object that was produced.
:Parameters:
- **message** --- the message to look for from the signal
- **callback** --- called when the message is posted
:Returns: the callback object
.. method:: ExecuteHook(message)
Used internally to call the listeners when a particular
message is posted to the signal.
:Parameters:
- **message** --- the posted message
:Returns: ``null``
********************
The MathJax variable
********************
MathJax has a single global variable, ``MathJax``, in which all its
data, and the data for loaded components, are stored. The MathJax
variable is a nested structure, with its top-level properties being
objects themselves.
Main MathJax Components
=======================
.. describe:: MathJax.Hub
Contains the MathJax hub code and variables, including the startup
code, the onload handler, the browser data, and so forth.
.. describe:: MathJax.Ajax
Contains the code for loading external modules and creating
stylesheets. Most of the code that causes MathJax to
operate asynchronously is handled here.
.. describe:: MathJax.Message
Contains the code to handle the intermittent message window that
periodically appears in the lower left-hand corner of the window.
.. describe:: MathJax.HTML
Contains support code for creating HTML elements dynamically from
descriptions stored in JavaScript objects.
.. describe:: MathJax.CallBack
Contains the code for managing MathJax callbacks, queues and
signals.
.. describe:: MathJax.Extension
Initially empty, this is where extensions can load their code.
For example, the `tex2jax` preprocessor creates
``MathJax.Extension.tex2jax`` for its code and variables.
.. describe:: MathJax.Menu
Initially null, this is where the MathJax contextual menu is
stored, when ``extensions/MathMenu.js`` is loaded.
.. describe:: MathJax.Object
Contains the code for the MathJax object-oriented programming model.
.. describe:: MathJax.InputJax
The base class for all input `jax` objects. Subclasses for
specific input jax are created as sub-objects of
``MathJax.InputJax``. For example, the TeX input jax loads itself
as ``MathJax.InputJax.TeX``.
.. describe:: MathJax.OutputJax
The base class for all output `jax` objects. Subclasses for
specific output jax are created as sub-objects of
``MathJax.OutputJax``. For example, the HTML-CSS output jax loads
itself as ``MathJax.OutputJax["HTML-CSS"]``.
.. describe:: MathJax.ElementJax
The base class for all element `jax` objects. Subclasses for
specific element jax are created as sub-objects of
``MathJax.ElementJax``. For example, the mml element jax loads
itself as ``MathJax.ElementJax.mml``.
Properties
==========
.. describe:: MathJax.version
The version number of the MathJax library as a whole.
.. describe:: MathJax.fileversion
The version number of the ``MathJax.js`` file specifically.
.. describe:: MathJax.isReady
This is set to ``true`` when MathJax is set up and ready to
perform typesetting actions (and is ``null`` otherwise).
.. _AsciiMath-support:
*************************
MathJax AsciiMath Support
*************************
The support for :term:`AsciiMath` in MathJax consists of two parts:
the `asciimath2jax` preprocessor, and the `AsciiMath` input processor.
The first of these looks for mathematics within your web page
(indicated by delimiters like ```...```) and marks the mathematics for
later processing by MathJax. The AsciiMath input processor is what
converts the AsciiMath notation into MathJax's internal format, where
one of MathJax's output processors then displays it in the web page.
The AsciiMath input jax actually includes a copy of Peter Jipsen's
``ASCIIMathML.js`` file (see the `AsciiMath home page
<http://www1.chapman.edu/~jipsen/mathml/asciimath.html>`_ for
details), and is included by permission of the author. This means
that the results of MathJax's AsciiMath processing should be the same
as using the actual ``ASCIIMathML.js`` package (at least as far as the
MathML that it generates is concerned). Thanks go to David Lippman
for writing the initial version of the AsciiMath preprocessor and
input jax.
The `asciimath2jax` preprocessor can be configured to look for whatever
markers you want to use for your math delimiters. See the
:ref:`asciimath2jax configuration options <configure-asciimath2jax>` section for
details on how to customize the action of `asciimath2jax`.
The AsciiMath input processor handles conversion of your mathematical
notation into MathJax's internal format (which is essentially MathML).
The AsciiMath input processor has few configuration options (see the
:ref:`AsciiMath options <configure-AsciiMath>` section for details).
The AsciiMath input jax handles only the original ASCIIMathML notation
(from ASCIIMathML v1.4.7), not the extened LaTeXMathML notation added
in version 2.0 of ASCIIMathML, though the AsciiMath input jax does
expose the tables that define the symbols that AsciiMath processes,
and so it would be possible to extend them to include additional
symbols. In general, it is probably better to use MathJax's :ref:`TeX
input jax <TeX-support>` to handle LaTeX notation instead.
AsciiMath delimiters
====================
By default, the `asciimath2jax` preprocessor defines the back-tick
(`````) as the delimiters for mathematics in AsciiMath format. It
does **not** define ``$...$`` as math delimiters. That is because
dollar signs appear too often in non-mathematical settings, which
could cause some text to be treated as mathematics unexpectedly. For
example, with single-dollar delimiters, "... the cost is $2.50 for the
first one, and $2.00 for each additional one ..." would cause the
phrase "2.50 for the first one, and" to be treated as mathematics
since it falls between dollar signs. For this reason, if you want to
use single-dollars for AsciiMath notation, you must enable that
explicitly in your configuration:
.. code-block:: javascript
MathJax.Hub.Config({
asciimath2jax: {
delimiters: [['$','$'], ['`','`']]
}
});
Note that the dollar signs are frequently used as a delimiter for
mathematics in the :term:`TeX` format, and you can not enable the
dollar-sign delimiter for both. It is probably best to leave dollar
signs for TeX notation.
See the ``config/default.js`` file, or the :ref:`asiimath2jax
configuration options <configure-asciimath2jax>` page, for additional
configuration parameters that you can specify for the `asciimath2jax`
preprocessor, which is the component of MathJax that identifies
AsciiMath notation within the page.
AsciiMath in HTML documents
===============================
The AsciiMath syntax is descibed in the `ASCIIMathML syntax page
<http://www1.chapman.edu/~jipsen/mathml/asciimathsyntax.html>`_.
Keep in mind that your mathematics is part of an HTML document, so you
need to be aware of the special characters used by HTML as part of its
markup. There cannot be HTML tags within the math delimiters (other
than ``<BR>``) as AsciiMath-formatted math does not include HTML tags.
Also, since the mathematics is initially given as text on the page,
you need to be careful that your mathematics doesn't look like HTML
tags to the browser (which parses the page before MathJax gets to see
it). In particular, that means that you have to be careful about
things like less-than and greater-than signs (``<`` and ``>``), and
ampersands (``&``), which have special meaning to the browsers. For
example,
.. code-block:: html
... when `x<y` we have ...
will cause a problem, because the brower will think ``<y`` is the
beginning of a tag named ``y`` (even though there is no such tag in
HTML). When this happens, the browser will think the tag continues up
to the next ``>`` in the document (typically the end of the next
actual tag in the HTML file), and you may notice that you are missing
part of the text of the document. In the example above, the "``we
have ...``" will not be displayed because the browser thinks it is
part of the tag starting at ``<y``. This is one indication you can
use to spot this problem; it is a common error and should be avoided.
Usually, it is sufficient to simply put spaces around these symbols to
cause the browser to avoid them, so
.. code-block:: html
... when `x < y` we have ...
should work. Alternatively, you can use the HTML entities ``&lt;``,
``&gt;`` and ``&amp;`` to encode these characters so that the browser
will not interpret them, but MathJax will. E.g.,
.. code-block:: html
... when `x &lt; y` we have ...
Keep in mind that the browser interprets your text before MathJax
does.
.. _using-callbacks:
***************
Using Callbacks
***************
A "callback" is a function that MathJax calls when it completes an
action that may occur asynchronously (like loading a file). Many of
MathJax's functions operate asynchronously, and MathJax uses callbacks
to allow you to synchronize your code with the action of those
functions. The `MathJax.Callback` structure manages these callbacks.
Callbacks can include not only a function to call, but also data to be
passed to the function, and an object to act as the JavaScript `this`
value in the resulting call (i.e., the object on which the callback is
to execute).
Callbacks can be collected into :ref:`Queues <using-queues>` where the
callbacks will be processed in order, with later callbacks waiting
until previous ones have completed before they are called. They are
also used with :ref:`Signals <using-signals>` as the means of
receiving information about the signals as they occur.
A number of methods in `MathJax.Hub` and `MathJax.Ajax` accept
callback specifications as arguments and return callback structures.
These routines always will return a callback even when none was
specified in the arguments, and in that case, the callback is a "do
nothing" callback. The reason for this is so that the resulting
callback can be used in a `MathJax.Callback.Queue` for synchronization
purposes, so that the actions following it in the queue will not be
performed until after the callback has been fired.
For example, the :meth:`MathJax.Ajax.Require()` method can be used to
load external files, and it returns a callback that is called when the
file has been loaded and executed. If you want to load several files
and wait for them all to be loaded before performing some action, you
can create a `Queue` into which you push the results of the
:meth:`MathJax.Ajax.Require()` calls, and then push a callback for the
action. The final action will not be performed until all the
file-load callbacks (which precede it in the queue) have been called;
i.e., the action will not occur until all the files are loaded.
Specifying a Callback
---------------------
Callbacks can be specified in a number of different ways, depending on
the functionality that is required of the callback. The easiest case
is to simply provide a function to be called, but it is also possible
to include data to pass to the function when it is called, and to
specify the object that will be used as `this` when the function is
called.
For example, the :meth:`MathJax.Ajax.Require()` method can accept a
callback as its second argument (it will be called when the file given
as the first argument is loaded and executed). So you can call
.. code-block:: javascript
MathJax.Ajax.Require("[MathJax]/config/myConfig.js",function () {
alert("My configuration file is loaded");
});
and an alert will appear when the file is loaded. An example of
passing arguments to the callback function includes the following:
.. code-block:: javascript
function loadHook (x) {alert("loadHook: "+x)}
MathJax.Ajax.Require("[MathJax]/config/myConfig.js",[loadHook,"myConfig"]);
Here, the ``loadHook()`` function accepts one argument and generates
an alert that includes the value passed to it. The callback in the
:meth:`MathJax.Ajax.Require()` call is ``[loadHook,"myConfig"]``,
which means that (the equivalent of) ``loadHook("myConfig")`` will be
performed when the file is loaded. The result should be an alert with
the text `loadHook: myConfig`.
The callback for the :meth:`MathJax.Ajax.Require()` method actually
gets called with a status value, in addition to any parameters already
included in the callback specification, that indicates whether the
file loaded successfully, or failed for some reason (perhaps the file
couldn't be found, or it failed to compile and run). So you could use
.. code-block:: javascript
MathJax.Ajax.Require("[MathJax]/config/myConfig.js",function (status) {
if (status === MathJax.Ajax.STATUS.OK) {
alert("My configuration file is loaded");
} else {
alert("My configuration file failed to load!");
}
});
to check if the file loaded properly. With additional parameters, the
example might be
.. code-block:: javascript
function loadHook (x,status) {alert("loadHook: "+x+" has status "+status)}
MathJax.Ajax.Require("[MathJax]/config/myConfig.js",[loadHook,"myConfig"]);
Note that the parameters given in the callback specification are used
first, and then additional parameters from the call to the callback
come afterward.
Callbacks to Object Methods
===========================
When you use a method of a JavaScript object, a special variable
called `this` is defined that refers to the object whose method is
being called. It allows you to access other methods or properties of
the object without knowing explicitly where the object is stored.
For example,
.. code-block:: javascript
var aPerson = {
firstname: "John",
lastname: "Smith",
showName: function () {alert(this.firstname+" "+this.lastname)}
};
creates an object that contains three items, a `firstname`, and
`lastname`, and a method that shows the person's full name in an
alert. So ``aPerson.showName()`` would cause an alert with the text
``John Smith`` to appear. Note, however that this only works if the
method is called as ``aPerson.showName()``; if instead you did
.. code-block:: javascript
var f = aPerson.showName; // assign f the function from aPerson
f(); // and call the function
the association of the function with the data in ``aPerson`` is lost,
and the alert will probably show ``undefined undefined``. (In this
case, ``f`` will be called with ``this`` set to the ``window``
variable, and so ``this.firstname`` and ``this.lastname`` will refer
to undefined values.)
Because of this, it is difficult to use an object's method as a
callback if you refer to it as a function directly. For example,
.. code-block:: javascript
var aFile = {
name: "[MathJax]/config/myConfig.js",
onload: function (status) {
alert(this.name+" is loaded with status "+status);
}
};
MathJax.Ajax.Require(aFile.name,aFile.onload);
would produce an alert indicating that "undefined" was loaded with a
particular status. That is because ``aFile.onload`` is a reference to
the `onload` method, which is just a function, and the association
with the `aFile` object is lost. One could do
.. code-block:: javascript
MathJax.Ajax.Require(aFile.name,function (status) {aFile.onload(status)});
but that seems needlessly verbose, and it produces a closure when one
is not really needed. Instead, MathJax provides an alternative
specification for a callback that allows you to specify both the
method and the object it comes from:
.. code-block:: javascript
MathJax.Ajax.Require(aFile.name,["onload",aFile]);
This requests that the callback should call ``aFile.onload`` as the
function, which will maintain the connection between ``aFile`` and its
method, thus preserving the correct value for `this` within the method.
As in the previous cases, you can pass parameters to the method as
well by including them in the array that specifies the callback:
.. code-block:: javascript
MathJax.Ajax.Require("filename",["method",object,arg1,arg2,...]);
This approach is useful when you are pushing a callback for one of
MathJax's Hub routines into the MathJax processing queue. For example,
.. code-block:: javascript
MathJax.Hub.Queue(["Typeset",MathJax.Hub,"MathDiv"]);
pushes the equivalent of ``MathJax.Hub.Typeset("MathDiv")`` into the
processing queue.
See the :ref:`Callback Object <api-callback>` reference pages for more
information about the valid methods of specifying a callback.
Creating a Callback Explicitly
==============================
When you call a method that accepts a callback, you usually pass it a
callback specification (like in the examples above), which *describes*
a callback (the method will create the actual `Callback` object, and
return that to you as its return value). You don't usually create
`Callback` objects directly yourself.
There are times, however, when you may wish to create a callback
object for use with functions that don't create callbacks for you.
For example, the ``setTimeout()`` function can take a function as its
argument, and you may want that function to be a method of an object,
and would run into the problem described in the previous section if
you simply passed the object's method to ``setTimeout()``. Or you
might want to pass an argument to the function called by
``setTimeout()``. (Altough the ``setTimeout()`` function can accept
additional arguements that are supposed to be passed on to the code
when it is called, some versions of Internet Explorer do not implement
that feature, so you can't rely on it.) You can use a `Callback`
object to do this, and the :meth:`MathJax.Callback()` method will
create one for you. For example,
.. code-block:: javascript
function f(x) {alert("x = "+x)}
setTimeout(MathJax.Callback([f,"Hello World!"]),500);
would create a callback that calls ``f("Hello World!")``, and
schedules it to be called in half a second.
*********************
The MathJax Community
*********************
If you are an active MathJax user, you may wish to become involved in
the wider community of MathJax users. The MathJax project maintains
forums where users can ask questions about how to use MathJax, make
suggestions about future features for MathJax, and present their own
solutions to problems that they have faced. There is also a
bug-tracking system where you can report errors that you have found
with MathJax in your environment.
.. _community-forums:
Forums
======
If you need help using MathJax or you have solutions you want to share, please
use the `MathJax Users Google Group
<http://groups.google.com/group/mathjax-users>`_. We try hard to answer
questions quickly, and users are welcome to help with that as well. Also, users
can post code snippets showing how they have used MathJax, so it may be a good
place to find the examples you are looking for.
If you want to discuss MathJax development, please use the `MathJax Dev Google
Group <http://groups.google.com/group/mathjax-dev>`_. We made this group
to discuss anything beyond what an end-user might be interested in, so if you
have any suggestions or questions about MathJax performance, technology, or
design, feel free to submit it to the group.
The community is only as good as the users who participate, so if
you have something to offer, please take time to make a post on one of
our groups.
.. _community-tracker:
Issue tracking
==============
Found a bug or want to suggest an improvement? Post it to our `issue tracker
<http://github.com/mathjax/MathJax/issues>`_. We monitor the tracker closely,
and work hard to respond to problems quickly.
Before you create a new issue, however, please search the issues to see if it
has already been reported. You could also be using an outdated version of
MathJax, so be sure to :ref:`upgrade your copy <getting-mathjax-git>` to verify
that the problem persists in the latest version.
.. _badge:
"Powered by MathJax"
====================
If you are using MathJax and want to show your support, please consider using
our `"Powered by MathJax" badge
<http://www.mathjax.org/community/mathjax-badge>`_.
.. _ajax-mathjax:
***************************
Loading MathJax Dynamically
***************************
MathJax is designed to be included via a ``<script>`` tag in the
``<head>`` section of your HTML document, and it does rely on being
part of the original document in that it uses an ``onload`` or
``DOMContentLoaded`` event handler to synchronize its actions with the
loading of the page. If you wish to insert MathJax into a document
after it has been loaded, that will normally occur *after* the page's
``onload`` handler has fired, and prior to version 2.0, MathJax had to
be told not to wait for the page ``onload`` event by calling
:meth:`MathJax.Hub.Startup.onload()` by hand. That is no longer
necessary, as MathJax v2.0 detects whether the page is already
available and when it is, it processes it immediately rather than
waiting for an event that has already happened.
Here is an example of how to load and configure MathJax dynamically:
.. code-block:: javascript
(function () {
var script = document.createElement("script");
script.type = "text/javascript";
script.src = "http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML";
document.getElementsByTagName("head")[0].appendChild(script);
})();
If you need to provide in-line configuration, you can do that using a
MathJax's configuration script:
.. code-block:: javascript
(function () {
var head = document.getElementsByTagName("head")[0], script;
script = document.createElement("script");
script.type = "text/x-mathjax-config";
script[(window.opera ? "innerHTML" : "text")] =
"MathJax.Hub.Config({\n" +
" tex2jax: { inlineMath: [['$','$'], ['\\\\(','\\\\)']] }\n" +
"});"
head.appendChild(script);
script = document.createElement("script");
script.type = "text/javascript";
script.src = "http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML";
head.appendChild(script);
})();
You can adjust the configuration to your needs, but be careful to get
the commas right, as Internet Explorer 6 and 7 will not tolerate an
extra comma before a closing brace. The ``window.opera`` test is
because some versions of Opera don't handle setting ``script.text``
properly, while some versions of Internet Explorer don't handle
setting ``script.innerHTML``.
Note that the **only** reliable way to configure MathJax is to use an
in-line configuration block of the type discussed above. You should
**not** call :meth:`MathJax.Hub.Config()` directly in your code, as it will
not run at the correct time --- it will either run too soon, in which case
``MathJax`` may not be defined and the function will throw an error, or it
will run too late, after MathJax has already finished its configuration
process, so your changes will not have the desired effect.
MathJax and GreaseMonkey
========================
You can use techniques like the ones discussed above to good effect in
GreaseMonkey scripts. There are GreaseMonkey work-alikes for all the
major browsers:
- Firefox: `GreaseMonkey <http://addons.mozilla.org/firefox/addon/748>`_
- Safari: `GreaseKit <http://8-p.info/greasekit/>`_ (also requires `SIMBL <http://www.culater.net/software/SIMBL/SIMBL.php>`_)
- Opera: Built-in (`instructions <http://www.ghacks.net/2008/08/10/greasemonkey-in-opera/>`_)
- Internet Explorer: `IEPro7 <http://www.ie7pro.com/>`_
- Chrome: Built-in for recent releases
Note, however, that most browsers don't allow you to insert a script
that loads a ``file://`` URL into a page that comes from the web (for
security reasons). That means that you can't have your GreaseMonkey
script load a local copy of MathJax, so you have to refer to a
server-based copy. The MathJax CDN works nicely for this.
----
Here is a script that runs MathJax in any document that contains
MathML (whether it includes MathJax or not). That allows
browsers that don't have native MathML support to view any web pages
with MathML, even if they say it only works in Firefox and
IE+MathPlayer.
.. code-block:: javascript
// ==UserScript==
// @name MathJax MathML
// @namespace http://www.mathjax.org/
// @description Insert MathJax into pages containing MathML
// @include *
// ==/UserScript==
if ((window.unsafeWindow == null ? window : unsafeWindow).MathJax == null) {
if ((document.getElementsByTagName("math").length > 0) ||
(document.getElementsByTagNameNS == null ? false :
(document.getElementsByTagNameNS("http://www.w3.org/1998/Math/MathML","math").length > 0))) {
var script = document.createElement("script");
script.type = "text/javascript";
script.src = "http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML-full";
document.getElementsByTagName("head")[0].appendChild(script);
}
}
**Source**: `mathjax_mathml.user.js <_static/mathjax_mathml.user.js>`_
----
Here is a script that runs MathJax in Wikipedia pages after first
converting the math images to their original TeX code.
.. code-block:: javascript
// ==UserScript==
// @name MathJax in Wikipedia
// @namespace http://www.mathjax.org/
// @description Insert MathJax into Wikipedia pages
// @include http://en.wikipedia.org/wiki/*
// ==/UserScript==
if ((window.unsafeWindow == null ? window : unsafeWindow).MathJax == null) {
//
// Replace the images with MathJax scripts of type math/tex
//
var images = document.getElementsByTagName('img'), count = 0;
for (var i = images.length - 1; i >= 0; i--) {
var img = images[i];
if (img.className === "tex") {
var script = document.createElement("script"); script.type = "math/tex";
if (window.opera) {script.innerHTML = img.alt} else {script.text = img.alt}
img.parentNode.replaceChild(script,img); count++;
}
}
if (count) {
//
// Load MathJax and have it process the page
//
var script = document.createElement("script");
script.type = "text/javascript";
script.src = "http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML-full";
document.getElementsByTagName("head")[0].appendChild(script);
}
}
**Source**: `mathjax_wikipedia.user.js <_static/mathjax_wikipedia.user.js>`_
.. _glossary:
********
Glossary
********
.. if you add new entries, keep the alphabetical sorting!
.. glossary::
AsciiMath
A notation for mathematics that uses characters commonly
available on all computer keyboards to represent the math in
an algebra-like syntax that should be intuitive and easily
read.
.. seealso::
`AsciiMath home page <http://www1.chapman.edu/~jipsen/mathml/asciimath.html>`_
Callback
A JavaScript function that is used to perform actions that
must wait for other actions to complete before they are
performed.
Callback Queue
MathJax uses `Queues` to synchronize its activity so that
actions that operate asynchronously (like loading files) will
be performed in the right order. :term:`Callback` functions
are pushed onto the queue, and are performed in order, with
MathJax handling the synchronization if operations need to
wait for other actions to finish.
Callback Signal
A JavaScript object that acts as a mailbox for MathJax events.
Like an event handler, but it also keeps a history of
messages. Your code can register an "interest" in a signal,
or can register a :term:`callback` to be called when a
particular message is sent along the signal channel.
HTML-CSS
MathJax output form that relys only on HTML and CSS 2.1,
allowing MathJax to remain compatible across all browsers.
jax
MathJax's input and output processors are called "jax", as is
its internal format manager. The code for the jax are in the
``MathJax/jax`` directory.
LaTeX
LaTeX is a variant of :term:`TeX` that is now the dominant TeX style.
.. seealso::
`LaTeX Wikipedia entry <http://en.wikipedia.org/wiki/LaTeX>`_
Markdown
A text format commonly used in blogs and wikis for creating
web pages without the need for complicated markup notation.
It is intended to be an easy-to-read and easy-to-write format
that still gives you the ability to specify a rich text result
(including things like bold, italics, bullet lists, and so
on).
.. seealso::
`Markdown home page <http://daringfireball.net/projects/markdown/>`_
MathML
An XML specification created to describe mathematical
notations and capture both its structure and content. MathML
is much more verbose than :term:`TeX`, but is much more
machine-readable.
.. seealso::
`MathML Wikipedia entry <http://en.wikipedia.org/wiki/MathML>`_
STIX
The Scientific and Technical Information Exchange font
package. A comprehensive set of scientific glyphs.
.. seealso::
`STIX project <http://stixfonts.org/>`_
SVG
Acronym for `Scalable Vector Graphics`. SVG is a graphics
format that allows images to be described as a collection of
graphics objects (like lines, rectangles, etc) rather than as
a bitmap of colored pixels. MathJax can use this format to
display mathematics as an alterantive to its HTML-CSS or
NativeMML output.
.. seealso::
`SVG Wilipedia entry <http://en.wikipedia.org/wiki/Scalable_Vector_Graphics>`_
TeX
A document markup language with robust math markup commands
developed by Donald Knuth in the late 1970's, but still in
extensive use today. It became the industry standard for
typesetting of mathematics, and is one of the most common
formats for mathematical journals, articles, and books.
.. seealso::
`TeX Wikipedia entry <http://en.wikipedia.org/wiki/TeX>`_
#####################
MathJax Documentation
#####################
MathJax is an open-source JavaScript display engine for LaTeX,
MathML, and AsciiMath notaion that works in all modern browsers.
Basic Usage
===========
.. toctree::
:maxdepth: 1
What is MathJax? <mathjax>
Getting Started with MathJax <start>
Installing and Testing MathJax <installation>
Loading and Configuring MathJax <configuration>
Common MathJax Configurations <config-files>
MathJax Configuration Options <options/index>
Using MathJax in Web Platforms <platforms/index>
.. toctree::
:maxdepth: 1
MathJax TeX and LaTeX Support <tex>
MathJax MathML Support <mathml>
MathJax AsciiMath Support <asciimath>
MathJax Output Formats <output>
.. toctree::
:maxdepth: 1
The MathJax Community <community>
.. _upgrading-MathJax:
Upgrading MathJax
=================
.. toctree::
:maxdepth: 1
What's New in MathJax v2.0 <whats-new-2.0>
What's New in MathJax v1.1 <whats-new-1.1>
Migrating from MathJax v1.0 to v1.1 <upgrade>
Converting to MathJax from jsMath <jsMath>
.. _advanced-topics:
Advanced Topics
===============
.. toctree::
:maxdepth: 1
The MathJax Processing Model <model>
The MathJax Startup Sequence <startup>
Synchronizing Your Code with MathJax <synchronize>
Loading MathJax Dynamically <dynamic>
Modifying Math on the Page <typeset>
.. toctree::
:maxdepth: 1
Details of the MathJax API<api/index>
Reference Pages
===============
.. toctree::
:maxdepth: 1
HTML snippets <HTML-snippets>
CSS style objects <CSS-styles>
Glossary <glossary>
* :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|.
.. _jsMath-support:
*********************************
Converting to MathJax from jsMath
*********************************
MathJax is the successor to the popular `jsMath
<http://www.math.union.edu/locate/jsMath/>`_ package for rendering
mathematics in web pages. Like jsMath, MathJax works by locating and
processing the mathematics within the webpage once it has been loaded
in the browser by a user viewing your web pages. If you are using
jsMath with its ``tex2math`` preprocessor, then switching to MathJax
should be easy, and is simply a matter of configuring MathJax
appropriately. See the section on :ref:`Loading and Configuring MathJax
<loading>` for details.
On the other hand, if you are using jsMath's ``<span
class="math">...</span>`` and ``<div class="math">...</div>`` tags to
mark the mathematics in your document, then you should use MathJax's
``jsMath2jax`` preprocessor when you switch to MathJax. To do this,
include ``"jsMath2jax.js"`` in the `extensions` array of your
configuration, with the `jax` array set to include ``"input/TeX"``. For
example,
.. code-block:: html
<script type="text/x-mathjax-config">
MathJax.Hub.Config({
extensions: ["jsMath2jax.js"]
});
</script>
<script
src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS_HTML">
</script>
would load the ``jsMath2jax`` preprocessor, along with a configuration
file that processes TeX input and produces HTML-with-CSS output.
There are a few configuration options for ``jsMath2jax``, which you
can find in the ``config/default.js`` file, or in the :ref:`jsMath
configuration options <configure-jsMath2jax>` section.
If you are generating your jsMath documents programmatically, it would be
better to convert from generating the jsMath ``<span>`` and ``<div>`` tags
to producing the corresponding MathJax ``<script>`` tags. You would use
``<script type="math/tex">`` in place of ``<span class="math">`` and
``<script type="math/tex; mode=display">`` in place of ``<div
class="math">``. See the section on :ref:`How mathematics is stored in the
page <mathjax-script-tags>` for more details.
****************
What is MathJax?
****************
MathJax is an open-source JavaScript display engine for LaTeX, MathML,
and AsciiMath notation that works in all modern browsers. It was
designed with the goal of consolidating the recent advances in web
technologies into a single, definitive, math-on-the-web platform
supporting the major browsers and operating systems, including those
on mobile devices. It requires no setup on the part of the user (no
plugins to download or software to install), so the page author can
write web documents that include mathematics and be confident that
users will be able to view it naturally and easily. One simply
includes MathJax and some mathematics in a web page, and MathJax does
the rest.
MathJax uses web-based fonts (in those browsers that support it) to
produce high-quality typesetting that scales and prints at full
resolution (unlike mathematics included as images). MathJax can be
used with screen readers, providing accessibility for the visually
impaired. With MathJax, mathematics is text-based rather than
image-based, and so it is available for search engines, meaning that
your equations can be searchable, just like the text of your pages.
MathJax allows page authors to write formulas using TeX and LaTeX
notation, `MathML <http://www.w3.org/TR/MathML3>`_, a World Wide Web
Consortium standard for representing mathematics in XML format, or
`AsciiMath <http://www1.chapman.edu/~jipsen/mathml/asciimath.html>`_
notation. MathJax will even convert TeX notation into MathML, so that
it can be rendered more quickly by those browsers that support MathML
natively, or so that you can copy and paste it into other programs.
MathJax is modular, so it loads components only when necessary, and
can be extended to include new capabilities as needed. MathJax is
highly configurable, allowing authors to customize it for the special
requirements of their web sites. Finally, MathJax has a rich
application programming interface (API) that can be used to make the
mathematics on your web pages interactive and dynamic.
.. _MathML-support:
**********************
MathJax MathML Support
**********************
The support for :term:`MathML` in MathJax consists of three parts: the
`mml2jax` preprocessor, the `MathML` input processor, and the `NativeMML`
output processor. The first of these looks for ``<math>`` tags within
your document and marks them for later processing by MathJax. The
second converts the MathML to the internal format used by MathJax, and
the third turns the internal format into MathML within the page so
that it can be displayed by the browser's native MathML support.
Because of MathJax's modular design, you do not need to use all three
of these components. For example, you could use the `tex2jax`
preprocessor and the TeX input processor, but the NativeMML output
processor, so that your mathematics is entered in TeX format, but
displayed as MathML. Or you could use the `mml2jax` preprocessor and
MathML input processor with the HTML-CSS output processor to make
MathML available in browsers that don't have native MathML support.
It is also possible to have MathJax select the output processor for
you so that MathML is used in those browsers that support it well
enough, while HTML-CSS is used for those that don't. See the
:ref:`common configurations <common-configurations>` section for
details and examples.
Of course it is also possible to use all three components together.
It may seem strange to go through an internal format just to return to
MathML in the end, but this is actually what makes it possible to view
MathML within an HTML page (rather than an XHTML page), without
the complications of handling special MIME-types for the document, or
any of the other setup issues that make using native MathML
difficult. MathJax handles the setup and properly marks the
mathematics so that the browser will render it as MathML. In
addition, MathJax provides its contextual menu for the MathML, which
lets the user zoom the mathematics for easier reading, get and copy
the source markup, and so on, so there is added value to using MathJax
even with a pure MathML workflow.
MathML in HTML pages
====================
For MathML that is handled via the preprocessor, you should not use
named MathML entities, but rather use numeric entities like
``&#x221A;`` or unicode characters embedded in the page itself. The
reason is that entities are replaced by the browser before MathJax
runs, and some browsers report errors for unknown entities. For
browsers that are not MathML-aware, that will cause errors to be
displayed for the MathML entities. While that might not occur in the
browser you are using to compose your pages, it can happen with other
browsers, so you should avoid the named entities whenever possible.
If you must use named entities, you may need to declare them in the
`DOCTYPE` declaration by hand.
When you use MathML in an HTML document rather than an XHTML one
(MathJax will work woth both), you should not use the "self-closing"
form for tags with no content, but should use separate open and close
tags. That is, use
.. code-block:: html
<mspace width="thinmathspace"></mspace>
rather than ``<mspace width="thinmathspace />``. This is because HTML
(prior to HTML5) does not have self-closing tags, and some browsers
will get the nesting of tags wrong if you attempt to use them. For
example, with ``<mspace width="1em" />``, since there is no closing
tag, the rest of the mathematics will become the content of the
``<mspace>`` tag; but since ``<mspace>`` should have no content, the
rest of the mathematics will not be displayed. This is a common error
that should be avoided. Modern browsers that support HTML5 should be
able to handle self-closing tags, but older browsers have problems
with them, so if you want your mathematics to be visible to the widest
audience, do not use the self-closing form in HTML documents.
Supported MathML commands
=========================
MathJax supports the `MathML3.0 <http://www.w3.org/TR/MathML3/>`_
presentation mathematics tags, with some limitations. The MathML
support is still under active development, so some tags are not yet
implemented, and some features are not fully developed, but are
coming.
The deficiencies include:
- No support for the elementary math tags: ``mstack``, ``mlongdiv``,
``msgroup``, ``msrow``, ``mscarries``, and ``mscarry``.
- No support for alignment groups in tables.
- No support for right-to-left rendering.
- Not all attributes are supported for tables. E.g., ``columnspan``
and ``rowspan`` are not implemented yet.
See the `results of the MathML3.0 test suite
<http://www.w3.org/Math/testsuite/results/tests.html>`_ for details.
.. _configure-AsciiMath:
*****************************
The AsciiMath input processor
*****************************
The options below control the operation of the AsciiMath input
processor that is run when you include ``"input/AsciiMath"`` in the
`jax` array of your configuration or load a combined configuration
file that includes the AsciiMath input jax. They are listed with
their default values. To set any of these options, include a
``AsciiMath`` section in your :meth:`MathJax.Hub.Config()` call. For
example
.. code-block:: javascript
MathJax.Hub.Config({
AsciiMath: {
displaystyle: false
}
});
would set the ``displaystyle`` configuration option so that the limits
for operators like summation symbols will appear next to them rather
than above and below.
.. describe:: displaystyle: true
Determines whether operators like summation symbols will have
their limits above and below the operators (true) or to their
right (false). The former is how they would appear in displayed
equations that appear on their own lines, while the latter is
better suited to in-line equations so that they don't interfere
with the line spacing so much.
.. describe:: decimal: "."
This is the character to be used for decimal points in numbers.
if you change this to ``","``, then you need to be careful about
entering points or intervals. E.g., use ``(1, 2)`` rather than
``(1,2)`` in that case.
.. _configure-FontWarnings:
**************************
The FontWarnings extension
**************************
The options below control the operation of the `FontWarnings`
extension that is run when you include ``"FontWarnings.js"`` in the
`extensions` array of your configuration. They are listed with their
default values. To set any of these options, include a
``FontWarnings`` section in your :meth:`MathJax.Hub.Config()` call.
For example
.. code-block:: javascript
MathJax.Hub.Config({
FontWarnings: {
fadeoutTime: 2*1000
}
});
would set the ``fadeoutTime`` option to 2000 milliseconds (2 seconds).
.. describe:: messageStyle: { ... }
This sets the CSS styles to be used for the font warning message
window. See the ``extensions/FontWarnings.js`` file for details of
what are set by default. See the :ref:`CSS style objects
<css-style-objects>` for details about how to specify CSS styles
via javascript objects.
.. describe:: Message: { ... }
This block contains HTML snippets to be used for the various
messages that the FontWarning extension can produce. There are
three messages that you can redefine to suit your needs:
.. describe:: webFont: [ ... ]
The message used for when MathJax uses web-based fonts (rather
than local fonts installed on the user's system).
.. describe:: imageFonts: [ ... ]
The message used for when MathJax must use image fonts rather
than local or web-based fonts (for those browsers that don't
handle the ``@font-face`` CSS directive).
.. describe:: noFonts: [ ... ]
The message used when MathJax is unable to find any font to use
(i.e., neither local nor web-based nor image-based fonts are
available).
Any message that is set to ``null`` rather than an HTML snippet
array will not be presented to the user, so you can set, for
example, the ``webFont`` message to ``null`` in order to have the
``imageFonts`` and ``noFonts`` messages, but no message if MathJax
uses web-based fonts.
See the description of :ref:`HTML snippets <html-snippets>` for
details about how to describe the messages using HTML snippets.
Note that in addition to the usual rules for defining such
snippets, the FontWarnings snippets can include references to
pre-defined snippets (that represent elements common to all three
messages). These are defined below in the ``HTML`` block, and are
referenced using ``["name"]`` within the snippet, where `name` is
the name of one of the snippets defined in the ``HTML``
configuration block. For example
.. code-block:: javascript
Message: {
noFonts: [
["closeBox"],
"MathJax is unable to locate a font to use to display ",
"its mathematics, and image fonts are not available, so it ",
"is falling back on generic unicode characters in hopes that ",
"your browser will be able to display them. Some characters ",
"may not show up properly, or possibly not at all.",
["fonts"],
["webfonts"]
]
}
refers to the ``closeBox``, ``fonts`` and ``webfonts`` snippets
declared in the ``HTML`` section.
.. describe:: HTML: { ... }
This object defines HTML snippets that are common to more than one
message in the ``Message`` section above. They can be included in
other HTML snippets by by using ``["name"]`` in an HTML snippet,
where `name` refers to the name of the snippet in the ``HTML``
block. The pre-defined snippets are:
.. describe:: closeBox
The HTML for the close box in the FontWarning message.
.. describe:: webfonts
The HTML for a paragraph suggesting an upgrade to a more
modern browser that supports web fonts.
.. describe:: fonts
HTML that includes links to the MathJax and STIX font download
pages.
.. describe:: STIXfonts
HTML that gives the download link for the STIX fonts only.
(Used in place of `fonts` when the `HTML-CSS` option for
`availableFonts` only includes the :term:`STIX` fonts.)
.. describe:: TeXfonts
HTML that gives the download link for the MathJax TeX fonts
only. (Used in place of `fonts` when the `HTML-CSS` option
for `availableFonts` only includes the `TeX` fonts.)
You can add your own pre-defined HTML snippets to this object, or
override the ones that are there with your own text.
.. describe:: removeAfter: 12*1000
This is the amount of time to show the FontWarning message, in
milliseconds. The default is 12 seconds. Setting this value
to zero means that the message will not fade out (the user must
close it manually).
.. describe:: fadeoutSteps: 10
This is the number of steps to take while fading out the
FontWarning message. More steps make for a smoother fade-out.
Set to zero to cause the message to be removed without fading.
.. describe:: fadeoutTime: 1.5*1000
This is the time used to perform the fade-out, in milliseconds.
The default is 1.5 seconds.
.. _configure-HTML-CSS:
*****************************
The HTML-CSS output processor
*****************************
The options below control the operation of the HTML-CSS output
processor that is run when you include ``"output/HTML-CSS"`` in the
`jax` array of your configuration or load a combined configuration
file that includes the HTML-CSS output jax. They are listed with
their default values. To set any of these options, include a
``"HTML-CSS"`` section in your :meth:`MathJax.Hub.Config()` call.
Note that, because of the dash, you need to enclose the name in
quotes. For example
.. code-block:: javascript
MathJax.Hub.Config({
"HTML-CSS": {
preferredFont: "STIX"
}
});
would set the ``preferredFont`` option to the :term:`STIX` fonts.
.. describe:: scale: 100
The scaling factor (as a percentage) of math with respect to the
surrounding text. The `HTML-CSS` output processor tries to match
the ex-size of the mathematics with that of the text where it is
placed, but you may want to adjust the results using this scaling
factor. The user can also adjust this value using the contextual
menu item associated with the typeset mathematics.
.. describe:: minScaleAdjust: 50
This gives a minimum scale (as a percent) for the scaling used by
MathJax to match the equation to the surrounding text. This will
prevent MathJax from making the mathematics too small.
.. describe:: availableFonts: ["STIX","TeX"]
This is a list of the fonts to look for on a user's computer in
preference to using MathJax's web-based fonts. These must
correspond to directories available in the
``jax/output/HTML-CSS/fonts`` directory, where MathJax stores data
about the characters available in the fonts. Set this to
``["TeX"]``, for example, to prevent the use of the :term:`STIX`
fonts, or set it to an empty list, `[]`, if you want to force
MathJax to use web-based or image fonts.
.. describe:: preferredFont: "TeX"
Which font to prefer out of the ``availableFonts`` list, when more
than one is available on the user's computer.
.. describe:: webFont: "TeX"
This is the web-based font to use when none of the fonts listed
above are available on the user's computer. Note that currently
only the `TeX` font is available in a web-based form (they are
stored in the ``fonts/HTML-CSS`` folder in the MathJax directory).
Set this to ``null`` to disable web fonts.
.. describe:: imageFont: "TeX"
This is the font to use for image fallback mode (when none of the
fonts listed above are available and the browser doesn't support
web-fonts via the ``@font-face`` CSS directive). Note that currently
only the TeX font is available as an image font (they are stored
in the ``fonts/HTML-CSS`` directory).
Set this to ``null`` if you want to prevent the use of image fonts
(e.g., you have deleted or not installed the image fonts on your
server). In this case, only browsers that support web-based fonts
will be able to view your pages without having the fonts installed
on the client computer. The browsers that support web-based fonts
include: IE6 and later, Chrome, Safari3.1 and above, Firefox3.5
and later, and Opera10 and later. Note that Firefox3.0 is **not**
on this list.
.. describe:: undefinedFamily: "STIXGeneral, 'Arial Unicode MS', serif"
This is the font-family CSS value used for characters that are not
in the selected font (e.g., for web-based fonts, this is where to
look for characters not included in the MathJax web fonts). IE
will stop looking after the first font that exists on the system
(even if it doesn't contain the needed character), so order these
carefully.
.. describe:: mtextFontInherit: false
This setting controls whether ``<mtext>`` elements will be typeset
using the math fonts or the font of the surrounding text. When
``false``, the font for ``mathvariant="normal"`` will be used;
when ``true``, the font will be inherited from the surrounding
paragraph.
.. describe:: EqnChunk: 50
EqnChunkFactor: 1.5
EqnChunkDelay: 100
These values control how "chunky" the display of mathematical
expressions will be; that is, how often the equations will be
updated as they are processed.
``EqnChunk`` is the number of equations that will be typeset before
they appear on screen. Larger values make for less visual flicker
as the equations are drawn, but also mean longer delays before the
reader sees anything.
``EqChunkFactor`` is the factor by which the ``EqnChunk`` will
grow after each chunk is displayed.
``EqChunkDelay`` is the time (in milliseconds) to delay between
chunks (to allow the browser to respond to other user
interaction).
Set ``EqnChunk`` to 1, ``EqnChunkFactor`` to 1, and
``EqnChunkDelay`` to 10 to get the behavior from MathJax v1.1 and
below.
.. describe:: linebreaks: {}
This is an object that configures automatic linebreaking in the
HTML-CSS output. In order to be backward compatible with earlier
versions of MathJax, only explicit line breaks are performed by
default, so you must enable line breaks if you want automatic
ones. The object contains the following values:
.. describe:: automatic: false
This controls the automatic breaking of expressions: when
``false``, only ``linebreak="newline"`` is processed; when
``true``, line breaks are inserted automatically in long
expressions.
.. describe:: width: "container"
This controls how wide the lines of mathematics can be.
Use an explicit width like ``"30em"`` for a fixed width.
Use ``"container"`` to compute the size from the containing
element.
Use ``"nn% container"`` for a portion of the container.
Use ``"nn%"`` for a portion of the window size.
The container-based widths may be slower, and may not produce
the expected results if the layout width changes due to the
removal of previews or inclusion of mathematics during
typesetting.
.. describe:: styles: {}
This is a list of CSS declarations for styling the HTML-CSS
output. See the definitions in ``jax/output/HTML-CSS/config.js``
for some examples of what are defined by default. See :ref:`CSS
Style Objects <css-style-objects>` for details on how to specify
CSS style in a JavaScript object.
.. describe:: showMathMenu: true
This value has been moved to the core configuration block, since
it applies to all output jax, but it will still be honored (for
now) if it is set here. See the :ref:`Core configuration options
<configure-hub>` for more details.
.. describe:: tooltip: { ... }
This sets the configuration options for ``<maction>`` elements
with ``actiontype="tooltip"``. (See also the ``#MathJax_Tooltip``
style setting in ``jax/output/HTML-CSS/config.js``, which can be
overridden using the ``styles`` option above.)
The ``tooltip`` section can contain the following options:
.. describe:: delayPost: 600
The delay (in milliseconds) before the tooltip is posted after
the mouse is moved over the ``maction`` element.
.. describe:: delayClear: 600
The delay (in milliseconds) before the tooltop is cleared
after the mouse moves out of the ``maction`` element.
.. describe:: offsetX: 10
offsetY: 5
These are the offset from the mouse position (in pixels)
where the tooltip will be placed.
.. _configure-MMLorHTML:
***********************************
The MMLorHTML configuration options
***********************************
The options below control the operation of the MMLorHTML configuration
file that is run when you include ``"MMLorHTML.js"`` in the `config`
array of your configuration, or when you use one of the combined
configuration files that ends with ``_HTMLorMML``. They are listed
with their default values. To set any of these options, include a
``MMLorHTML`` section in your :meth:`MathJax.Hub.Config()` call. For
example
.. code-block:: javascript
MathJax.Hub.Config({
MMLorHTML: {
prefer: {
Opera: "MML"
}
}
});
would set the ``prefer`` option so that the Opera browser would prefer
MathML to HTML-CSS output (while leaving the settings for other
browsers unchanged).
Note that if you use the ``MMLorHTML.js`` configuration file, you should
**not** specify an output processor in the `jax` array of your
configuration; `MMLorHTML` will fill that in for you.
.. describe:: prefer: {
MSIE: "MML",
Firefox: "HTML",
Safari: "HTML",
Chrome: "HTML",
Opera: "HTML",
other: "HTML"
}
This lets you set the preferred renderer on a browser-by-browser
basis. You set the browser to either ``"MML"`` or ``"HTML"``
depending on whether you want to use the `NativeMML` or `HTML-CSS`
output processor. Note that although Opera and Safari do process some MathML
natively, their support is not sufficient to handle the more
complicated output generated by MathJax, so their settings are
``"HTML"`` by default. Although Firefox does support a large
subset of MathJax, it does not implement all the features needed by
MathJax, and so it is also set to ``"HTML"`` by default (this is
new in v2.0).
Note that users can still use the MathJax contextual menu to select
a different renderer after the default one has been chosen by
``MMLorHTML.js``.
.. _configure-MathEvents:
************************
The MathEvents extension
************************
The options below control the operation of the MathEvents component that
allows handles mouse and menu events attached to mathematics that is
typeset by MathJax. They are listed with their
default values. To set any of these options, include a ``MathEvents``
section in your :meth:`MathJax.Hub.Config()` call. For example
.. code-block:: javascript
MathJax.Hub.Config({
MathEvents: {
hover: 400
}
});
would set the required delay for hovering over a math element to
400 milliseconds.
.. describe:: hover: 500
This value is the time (in milliseconds) that a user must hold the
mouse still over a math element before it is considered to be
hovering over the math.
.. describe:: styles: {}
This is a list of CSS declarations for styling the zoomed
mathematics. See the definitions in ``extensions/MathEvents.js``
for details of what are defined by default. See :ref:`CSS Style
Objects <css-style-objects>` for details on how to specify CSS
style in a JavaScript object.
.. _configure-MathML:
**************************
The MathML input processor
**************************
The options below control the operation of the MathML input processor
that is run when you include ``"input/MathML"`` in the `jax` array of
your configuration or load a combined configuration file that includes
the MathML input jax. They are listed with their default values. To
set any of these options, include a ``MathML`` section in your
:meth:`MathJax.Hub.Config()` call. For example
.. code-block:: javascript
MathJax.Hub.Config({
MathML: {
useMathMLspacing: true
}
});
would set the ``useMathMLspacing`` option so that the MathML rules for
spacing would be used (rather than TeX spacing rules).
.. describe:: useMathMLspacing: false
Specifies whether to use TeX spacing or MathML spacing when the
`HTML-CSS` output jax is used.
.. _configure-MathMenu:
**********************
The MathMenu extension
**********************
The options below control the operation of the contextual menu that is
available on mathematics that is typeset by MathJax.
They are listed with their default values. To set any of these
options, include a ``MathMenu`` section in your
:meth:`MathJax.Hub.Config()` call. For example
.. code-block:: javascript
MathJax.Hub.Config({
MathMenu: {
delay: 600
}
});
would set the ``delay`` option to 600 milliseconds.
.. describe:: delay: 150
This is the hover delay for the display (in milliseconds) for
submenus in the contextual menu: when the mouse is over a submenu
label for this long, the menu will appear. (The submenu also will
appear if you click on its label.)
.. describe:: helpURL: "http://www.mathjax.org/help/user/"
This is the URL for the MathJax Help menu item. When the user
selects that item, the browser opens a new window with this URL.
.. describe:: showRenderer: true
This controls whether the "Math Renderer" item will be displayed
in the "Math Settings" submenu of the MathJax contextual menu.
It allows the user to change between the `HTML-CSS`, `NativeMML`,
and `SVG` output processors for the mathematics on the page. Set
to ``false`` to prevent this menu item from showing.
.. describe:: showFontMenu: false
This controls whether the "Font Preference" item will be displayed
in the "Math Settings" submenu of the MathJax contextual menu.
This submenu lets the user select what font to use in the
mathematics produced by the `HTML-CSS` output processor. Note that
changing the selection in the font menu will cause the page to
reload. Set to ``false`` to prevent this menu item from showing.
.. describe:: showMathPlayer: true
This controls whether the "MathPlayer" item will be displayed in
the "Math Settings" submenu of the MathJax contextual menu. This
submenu lets the user select what events should be passed on to
the `MathPlayer plugin
<http://www.dessci.com/en/products/mathplayer/>`_, when it is
present. Mouse events can be passed on (so that clicks will be
processed by MathPlayer rather than MathJax), and emnu events can
be passed on (to allow the user access to the MathPlayer menu).
Set to ``false`` to prevent this menu item from showing.
.. describe:: showContext: false
This controls whether the "Contextual Menu" item will be displayed
in the "Math Settings" submenu of the MathJax contextual menu.
It allows the user to decide whether the MathJax menu or the
browser's default contextual menu will be shown when the context
menu click occurs over mathematics typeset by MathJax. Set to
``false`` to prevent this menu item from showing.
.. describe:: windowSettings: { ... }
These are the settings for the ``window.open()`` call that
creates the `Show Source` window. The initial width and height
will be reset after the source is shown in an attempt to make the
window fit the output better.
.. describe:: styles: {}
This is a list of CSS declarations for styling the menu
components. See the definitions in ``extensions/MathMenu.js`` for
details of what are defined by default. See :ref:`CSS Style
Objects <css-style-objects>` for details on how to specify CSS
style in a JavaScript object.
.. _configure-MathZoom:
**********************
The MathZoom extension
**********************
The options below control the operation of the Math-Zoom feature that
allows users to see an enlarged version of the mathematics when they
click or hover over typeset mathematics. They are listed with their
default values. To set any of these options, include a ``MathZoom``
section in your :meth:`MathJax.Hub.Config()` call. For example
.. code-block:: javascript
MathJax.Hub.Config({
MathZoom: {
styles: {
"#MathJax_Zoom": {
"background-color": "#0000F0"
}
}
}
});
would set the background color of the Zoom box to a very light blue.
Mathematics is zoomed when the user "triggers" the zoom by an action,
either clicking on the mathematics, double-clicking on it, or holding
the mouse still over it (i.e., "hovering"). Which trigger is used is
set by the user via the math contextual menu (or by the author using
the ``menuSettings`` configuration section of the `core configuration
options <configure-hub>`).
.. describe:: delay: 500
This value is now stored as the ``hover`` parameter in the
:ref:`MathEvents <configure-MathEvents>` configuration options, and
will have no effect if given here.
.. describe:: styles: {}
This is a list of CSS declarations for styling the zoomed
mathematics. See the definitions in ``extensions/MathZoom.js``
for details of what are defined by default. See :ref:`CSS Style
Objects <css-style-objects>` for details on how to specify CSS
style in a JavaScript object.
.. _configure-NativeMML:
******************************
The NativeMML output processor
******************************
The options below control the operation of the NativeMML output
processor that is run when you include ``"output/NativeMML"`` in the
`jax` array of your configuration or load a combined configuration
file taht includes the NativeMML output jax. They are listed with
their default values. To set any of these options, include a
``NativeMML`` section in your :meth:`MathJax.Hub.Config()` call. For
example
.. code-block:: javascript
MathJax.Hub.Config({
NativeMML: {
scale: 105
}
});
would set the ``scale`` option to 105 percent.
.. describe:: scale: 100
The scaling factor (as a percentage) of math with respect to the
surrounding text. The `NativeMML` output processor tries to match
the ex-size of the mathematics with that of the text where it is
placed, but you may want to adjust the results using this scaling
factor. The user can also adjust this value using the contextual
menu item associated with the typeset mathematics.
.. describe:: minScaleAdjust: 50
This gives a minimum scale (as a percent) for the scaling used by
MathJax to match the equation to the surrounding text. This will
prevent MathJax from making the mathematics too small.
.. describe:: showMathMath: true
showMathMenuMSIE: true
These values have been moved to the core configuration block, since
it applies to all output jax, but they will still be honored (for
now) if it is set here. See the :ref:`Core configuration options
<configure-hub>` for more details.
.. describe:: styles: {}
This is a list of CSS declarations for styling the NativeMML
output. See the definitions in ``jax/output/NativeMML/config.js``
for some examples of what are defined by default. See :ref:`CSS
Style Objects <css-style-objects>` for details on how to specify
CSS style in a JavaScript object.
.. _configure-SVG:
************************
The SVG output processor
************************
The options below control the operation of the SVG output
processor that is run when you include ``"output/SVG"`` in the
`jax` array of your configuration or load a combined configuration
file that includes the SVG output jax. They are listed with their default
values. To set any of these options, include an ``SVG`` section
in your :meth:`MathJax.Hub.Config()` call. Note that, because of the
dash, you need to enclose the name in quotes. For example
.. code-block:: javascript
MathJax.Hub.Config({
"SVG": {
scale: 120
}
});
would set the ``scale`` option to 120%.
.. describe:: scale: 100
The scaling factor (as a percentage) of math with respect to the
surrounding text. The `SVG` output processor tries to match
the ex-size of the mathematics with that of the text where it is
placed, but you may want to adjust the results using this scaling
factor. The user can also adjust this value using the contextual
menu item associated with the typeset mathematics.
.. describe:: minScaleAdjust: 50
This gives a minimum scale (as a percent) for the scaling used by
MathJax to match the equation to the surrounding text. This will
prevent MathJax from making the mathematics too small.
.. describe:: font: "TeX"
This is the font to use for rendering the mathematics. Note that
currently only the `TeX` font is available.
.. describe:: blacker: 10
This is the stroke width to use for all character paths (1em =
1000 units). This is a cheap way of getting slightly lighter or
darker characters, but remember that not all displays will act the
same, so a value that is good for you may not be good for everyone.
.. describe:: undefinedFamily: "STIXGeneral, 'Arial Unicode MS', serif"
This is the font-family CSS value used for characters that are not
in the selected font (e.g., this is where to look for characters
not included in the MathJax TeX fonts). IE will stop looking
after the first font that exists on the system (even if it doesn't
contain the needed character), so order these carefully.
.. describe:: mtextFontInherit: false
This setting controls whether ``<mtext>`` elements will be typeset
using the math fonts or the font of the surrounding text. When
``false``, the font for ``mathvariant="normal"`` will be used;
when ``true``, the font will be inherited from the surrounding
paragraph.
.. describe:: addMMLclasses: false
This controls whether the MathML structure is retained and CSS
classes are added to mark the original MathML elements (as in the
output from the `HTML-CSS` output jax). By default, the SVG
output jax removes unneeded nesting in order to produce a more
efficient markup, but if you want to use CSS to style the elements
as if they were MathML, you might need to set this to true.
.. describe:: EqnChunk: 50
EqnChunkFactor: 1.5
EqnChunkDelay: 100
These values control how "chunky" the display of mathematical
expressions will be; that is, how often the equations will be
updated as they are processed.
``EqnChunk`` is the number of equations that will be typeset before
they appear on screen. Larger values make for less visual flicker
as the equations are drawn, but also mean longer delays before the
reader sees anything.
``EqChunkFactor`` is the factor by which the ``EqnChunk`` will
grow after each chunk is displayed.
``EqChunkDelay`` is the time (in milliseconds) to delay between
chunks (to allow the browser to respond to other user
interaction).
Set ``EqnChunk`` to 1, ``EqnChunkFactor`` to 1, and
``EqnChunkDelay`` to 10 to get the behavior from MathJax v1.1 and
below.
.. describe:: linebreaks: {}
This is an object that configures automatic linebreaking in the
SVG output. In order to be backward compatible with earlier
versions of MathJax, only explicit line breaks are performed by
default, so you must enable line breaks if you want automatic
ones. The object contains the following values:
.. describe:: automatic: false
This controls the automatic breaking of expressions: when
``false``, only ``linebreak="newline"`` is processed; when
``true``, line breaks are inserted automatically in long
expressions.
.. describe:: width: "container"
This controls how wide the lines of mathematics can be.
Use an explicit width like ``"30em"`` for a fixed width.
Use ``"container"`` to compute the size from the containing
element.
Use ``"nn% container"`` for a portion of the container.
Use ``"nn%"`` for a portion of the window size.
The container-based widths may be slower, and may not produce
the expected results if the layout width changes due to the
removal of previews or inclusion of mathematics during
typesetting.
.. describe:: styles: {}
This is a list of CSS declarations for styling the SVG output.
See the definitions in ``jax/output/SVG/config.js`` for some
examples of what are defined by default. See :ref:`CSS Style
Objects <css-style-objects>` for details on how to specify CSS
style in a JavaScript object.
.. describe:: tooltip: { ... }
This sets the configuration options for ``<maction>`` elements
with ``actiontype="tooltip"``. (See also the ``#MathJax_Tooltip``
style setting in ``jax/output/SVG/config.js``, which can be
overridden using the ``styles`` option above.)
The ``tooltip`` section can contain the following options:
.. describe:: delayPost: 600
The delay (in milliseconds) before the tooltip is posted after
the mouse is moved over the ``maction`` element.
.. describe:: delayClear: 600
The delay (in milliseconds) before the tooltop is cleared
after the mouse moves out of the ``maction`` element.
.. describe:: offsetX: 10
offsetY: 5
These are the offset from the mouse position (in pixels)
where the tooltip will be placed.
.. _configure-TeX:
***********************
The TeX input processor
***********************
The options below control the operation of the TeX input processor
that is run when you include ``"input/TeX"`` in the `jax` array of
your configuration or load a combined configuration file that includes
the TeX input jax. They are listed with their default values. To
set any of these options, include a ``TeX`` section in your
:meth:`MathJax.Hub.Config()` call. For example
.. code-block:: javascript
MathJax.Hub.Config({
TeX: {
Macros: {
RR: '{\\bf R}',
bold: ['{\\bf #1}', 1]
}
}
});
would set the ``Macros`` configuration option to cause two new macros
to be defined within the TeX input processor.
.. describe:: TagSide: "right"
This specifies the side on which ``\tag{}`` macros will place the
tags. Set it to ``"left"`` to place the tags on the left-hand side.
.. describe:: TagIndent: ".8em"
This is the amount of indentation (from the right or left) for the
tags produced by the ``\tag{}`` macro.
.. describe:: MultLineWidth: "85%"
The width to use for the `multline` environment that is part of
the ``AMSmath`` extension. This width gives room for tags at
either side of the equation, but if you are displaying mathematics
in a small area or a thin column of text, you might need to change
the value to leave sufficient margin for tags.
.. describe:: equationNumbers: {}
This object controls the automatic equation numbering and the
equation referencing. It contains the following values:
.. describe:: autoNumber: "none"
This controls whether equations are numbered and how. By
default it is set to ``"none"`` to be compatible with earlier
versions of MathJax where auto-numbering was not performed (so
pages will not change their appearance). You can change
this to ``"AMS"`` for equations numbered as the `AMSmath`
package would do, or ``"all"`` to get an equation number for
every displayed equation.
.. describe:: formatNumber: function (n) {return n}
A function that tells MathJax what tag to use for equation
number ``n``. This could be used to have the equations labeled
by a sequence of symbols rather than numbers, or to use section
and subsection numbers instead.
.. describe:: formatTag: function (n) {return '('+n+')'}
A function that tells MathJax how to format an equation number
for displaying as a tag for an equation. This is what appears
in the margin of a tagged or numbered equation.
.. describe:: formatID: function {return 'mjx-eqn-'+String(n).replace(/[:'"<>&]/g,"")}
A function that rells MathJax what ID to use as an anchor for
the equation (so that it can be used in URL references).
.. describe:: formatURL: function (id) {return '#'+escape(id)}
A function that takes an equation ID and returns the URL to
link to it.
.. describe:: useLabelIds: true
This controls whether element ID's use the ``\label`` name or
the equation number. When ``true``, use the label, when
``false``, use the equation number.
See the `MathJax examples page
<http://cdn.mathjax.org/mathjax/latest/test/examples.html>`_ for
some examples of equation numbering.
.. describe:: Macros: {}
This lists macros to define before the TeX input processor begins.
These are `name:value` pairs where the `name` gives the name of
the TeX macro to be defined, and `value` gives the replacement
text for the macro. The `value` can be an array of the form
`[value,n]`, where `value` is the replacement text and `n` is the
number of parameters for the macro. Note that since the `value`
is a javascript string, backslashes in the replacement text must
be doubled to prevent them from acting as javascript escape
characters.
For example,
.. code-block:: javascript
Macros: {
RR: '{\\bf R}',
bold: ['{\\bf #1}', 1]
}
would ask the TeX processor to define two new macros: ``\RR``,
which produces a bold-face "R", and ``\bold{...}``, which takes one
parameter and sets it in the bold-face font.
.. describe:: MAXMACROS: 10000
Because a definition of the form ``\def\x{\x} \x`` would cause MathJax
to loop infinitely, the `MAXMACROS` constant will limit the number of
macro substitutions allowed in any expression processed by MathJax.
.. describe:: MAXBUFFER: 5*1024
Because a definition of the form ``\def\x{\x aaa} \x`` would loop
infinitely, and at the same time stack up lots of a's in MathJax's
equation buffer, the `MAXBUFFER` constant is used to limit the size of
the string being processed by MathJax. It is set to 5KB, which should
be sufficient for any reasonable equation.
.. _configure-asciimath2jax:
******************************
The asciimath2jax Preprocessor
******************************
The options below control the operation of the `asciimath2jax` preprocessor
that is run when you include ``"asciimath2jax.js"`` in the `extensions` array
of your configuration. They are listed with their default values. To
set any of these options, include a ``asciimath2jax`` section in your
:meth:`MathJax.Hub.Config()` call. For example
.. code-block:: javascript
MathJax.Hub.Config({
asciimath2jax: {
delimiters: [['`','`'], ['$','$']]
}
});
would set the ASCIIMath delimiters for the `asciimath2jax`
preprocessor to include dollar signs as well as back-ticks.
.. describe:: delimiters: [['`','`']]
Array of pairs of strings that are to be used as math
delimiters. The first in each pair is the initial delimiter and
the second is the terminal delimiter. You can have as many pairs
as you want. For example,
.. code-block:: javascript
inlineMath: [ ['$','$'], ['`','`'] ]
would cause `asciimath2jax` to look for ``$...$`` and ```...``` as
delimiters for inline mathematics. (Note that the single dollar
signs are not enabled by default because they are used too
frequently in normal text, so if you want to use them for math
delimiters, you must specify them explicitly.)
Note that the delimiters can't look like HTML tags (i.e., can't
include the less-than sign), as these would be turned into tags by
the browser before MathJax has the chance to run. You can only
include text, not tags, as your math delimiters.
.. describe:: preview: "AsciiMath"
This controls whether `asciimath2jax` inserts ``MathJax_Preview``
spans to make a preview available, and what preview to use, when
it locates in-line or display mathematics in the page. The
default is ``"AsciiMath"``, which means use the ASCIIMath code as
the preview (which will be visible until it is processed by
MathJax). Set to ``"none"`` to prevent previews from being
inserted (the math will simply disappear until it is typeset).
Set to an array containing the description of an HTML snippet in
order to use the same preview for all equations on the page.
Examples:
.. code-block:: javascript
preview: ["[math]"], // insert the text "[math]" as the preview
.. code-block:: javascript
preview: [["img",{src: "/images/mypic.jpg"}]], // insert an image as the preview
See the :ref:`description of HTML snippets <html-snippets>` for
details on how to represent HTML code in this way.
.. describe:: skipTags: ["script","noscript","style","textarea","pre","code"]
This array lists the names of the tags whose contents should not
be processed by `asciimath2jax` (other than to look for
ignore/process classes as listed below). You can add to (or
remove from) this list to prevent MathJax from processing
mathematics in specific contexts.
.. describe:: ignoreClass: "asciimath2jax_ignore"
This is the class name used to mark elements whose contents should
not be processed by asciimath2jax (other than to look for the
``processClass`` pattern below). Note that this is a regular
expression, and so you need to be sure to quote any `regexp`
special characters. The pattern is inserted into one that
requires your pattern to match a complete word, so setting
``ignoreClass: "class2"`` would cause it to match an element with
``class="class1 class2 class3"`` but not ``class="myclass2"``.
Note that you can assign several classes by separating them by the
vertical line character (``|``). For instance, with
``ignoreClass: "class1|class2"`` any element assigned a class of
either ``class1`` or ``class2`` will be skipped.
.. describe:: processClass: "asciimath2jax_process"
This is the class name used to mark elements whose contents
*should* be processed by `asciimath2jax`. This is used to restart
processing within tags that have been marked as ignored via the
``ignoreClass`` or to cause a tag that appears in the ``skipTags``
list to be processed rather than skipped. Note that this is a
regular expression, and so you need to be sure to quote any
`regexp` special characters. The pattern is inserted into one
that requires your pattern to match a complete word, so setting
``processClass: "class2"`` would cause it to match an element with
``class="class1 class2 class3"`` but not ``class="myclass2"``.
Note that you can assign several classes by separating them by the
vertical line character (``|``). For instance, with
``processClass: "class1|class2"`` any element assigned a class of
either ``class1`` or ``class2`` will have its contents processed.
.. _configuration:
*********************
Configuration Objects
*********************
The various components of MathJax, including its input and output
processors, its preprocessors, its extensions, and the MathJax core,
all can be configured through the ``config/default.js`` file, or via a
:meth:`MathJax.Hub.Config()` call (indeed, if you look closely, you
will see that ``config/default.js`` is itself one big call to
:meth:`MathJax.Hub.Config()`). Anything that is in
``config/default.js`` can be included in-line to configure MathJax.
The structure that you pass to :meth:`MathJax.Hub.Config()` is a
JavaScript object that includes `name:value` pairs giving the names of
parameters and their values, with pairs separated by commas. Be
careful not to include a comma after the last value, however, as some
browsers (namely Internet Explorer) will fail to process the
configuration if you do.
The MathJax components, like the TeX input processor, have their own
sections in the configuration object labeled by the component name,
and using an object as its value. That 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 for 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/default.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 <hub>
.. toctree::
:maxdepth: 1
The tex2jax preprocessor options <tex2jax>
The mml2jax preprocessor options <mml2jax>
The asciimath2jax preprocessor options <asciimath2jax>
The jsMath2jax preprocessor options <jsMath2jax>
.. toctree::
:maxdepth: 1
The TeX input processor options <TeX>
The MathML input processor options <MathML>
The AsciiMath input processor options <AsciiMath>
The HTML-CSS output processor options <HTML-CSS>
The NativeMML output processor options <NativeMML>
The SVG output processor options <SVG>
The MMLorHTML configuration options <MMLorHTML>
.. toctree::
:maxdepth: 1
The MathMenu options <MathMenu>
The MathZoom options <MathZoom>
The MathEvents options <MathEvents>
The FontWarnings options <FontWarnings>
.. _configure-jsMath2jax:
***************************
The jsMath2jax Preprocessor
***************************
The options below control the operation of the `jsMath2jax`
preprocessor that is run when you include ``"jsMath2jax.js"`` in the
`extensions` array of your configuration. They are listed with their
default values. To set any of these options, include a ``jsMath2jax``
section in your :meth:`MathJax.Hub.Config()` call. For example
.. code-block:: javascript
MathJax.Hub.Config({
jsMath2jax: {
preview: "none"
}
});
would set the ``preview`` parameter to ``"none"``.
.. describe:: preview: "TeX"
This controls whether `jsMath2jax` inserts ``MathJax_Preview`` spans
to make a preview available, and what preview to use, when it
locates in-line or display mathematics in the page. The default
is ``"TeX"``, which means use the TeX code as the preview (which
will be visible until it is processed by MathJax). Set to
``"none"`` to prevent previews from being inserted (the math
will simply disappear until it is typeset). Set to an array
containing the description of an HTML snippet in order to use the
same preview for all equations on the page.
Examples:
.. code-block:: javascript
preview: ["[math]"], // insert the text "[math]" as the preview
.. code-block:: javascript
preview: [["img",{src: "/images/mypic.jpg"}]], // insert an image as the preview
See the :ref:`description of HTML snippets <html-snippets>` for
details on how to represent HTML code in this way.
.. _configure-mml2jax:
************************
The mml2jax Preprocessor
************************
The options below control the operation of the `mml2jax` preprocessor
that is run when you include ``"mml2jax.js"`` in the `extensions` array
of your configuration. They are listed with their default values. To
set any of these options, include a ``mml2jax`` section in your
:meth:`MathJax.Hub.Config()` call. For example
.. code-block:: javascript
MathJax.Hub.Config({
mml2jax: {
preview: "none"
}
});
would set the ``preview`` parameter to ``"none"``.
.. describe:: preview: "alttext"
This controls whether `mml2jax` inserts ``MathJax_Preview`` spans
to make a preview available, and what preview to use, when it
locates mathematics on the page. The default is ``"alttext"``,
which means use the ``<math>`` tag's ``alttext`` attribute as the
preview (visible until it is processed by MathJax), if the tag has
one. Set it to ``"none"`` to prevent the previews from being
inserted (the math will simply disappear until it is typeset).
Set it to an array containing the description of an HTML snippet
in order to use the same preview for all equations on the page.
Examples:
.. code-block:: javascript
preview: ["[math]"], // insert the text "[math]" as the preview
.. code-block:: javascript
preview: [["img",{src: "/images/mypic.jpg"}]], // insert an image as the preview
See the :ref:`description of HTML snippets <html-snippets>` for
details on how to represent HTML code in this way.
.. _configure-tex2jax:
************************
The tex2jax Preprocessor
************************
The options below control the operation of the `tex2jax` preprocessor
that is run when you include ``"tex2jax.js"`` in the `extensions` array
of your configuration. They are listed with their default values. To
set any of these options, include a ``tex2jax`` section in your
:meth:`MathJax.Hub.Config()` call. For example
.. code-block:: javascript
MathJax.Hub.Config({
tex2jax: {
inlineMath: [ ['$','$'], ['\\(','\\)'] ]
}
});
would set the ``inlineMath`` delimiters for the `tex2jax`
preprocessor.
.. describe:: inlineMath: [['\\\(','\\\)']]
Array of pairs of strings that are to be used as in-line math
delimiters. The first in each pair is the initial delimiter and
the second is the terminal delimiter. You can have as many pairs
as you want. For example,
.. code-block:: javascript
inlineMath: [ ['$','$'], ['\\(','\\)'] ]
would cause `tex2jax` to look for ``$...$`` and ``\(...\)`` as
delimiters for inline mathematics. (Note that the single dollar
signs are not enabled by default because they are used too
frequently in normal text, so if you want to use them for math
delimiters, you must specify them explicitly.)
Note that the delimiters can't look like HTML tags (i.e., can't
include the less-than sign), as these would be turned into tags by
the browser before MathJax has the chance to run. You can only
include text, not tags, as your math delimiters.
.. describe:: displayMath: [ ['$$','$$'], ['\\\[','\\\]'] ]
Array of pairs of strings that are to be used as delimiters for
displayed equations. The first in each pair is the initial
delimiter and the second is the terminal delimiter. You can have
as many pairs as you want.
Note that the delimiters can't look like HTML tags (i.e., can't
include the less-than sign), as these would be turned into tags by
the browser before MathJax has the chance to run. You can only
include text, not tags, as your math delimiters.
.. describe:: balanceBraces: true,
This value determines whether `tex2jax` requires braces to be
balanced within math delimiters (which allows for nested dollar
signs). Set to ``false`` to get pre-v2.0 compatibility. When
``true``,
.. code-block:: latex
$y = x^2 \hbox{ when $x > 2$}$.
will be properly handled as a single expression. When ``false``,
it would be interpreted as two searpate expressions, each with
improperly balanced braces.
.. describe:: processEscapes: false
When set to ``true``, you may use ``\$`` to represent a literal
dollar sign, rather than using it as a math delimiter. When
``false``, ``\$`` will not be altered, and the dollar sign may be
considered part of a math delimiter. Typically this is set to
``true`` if you enable the ``$ ... $`` in-line delimiters, so you
can type ``\$`` and `tex2jax` will convert it to a regular dollar
sign in the rendered document.
.. describe:: processEnvironments: true
When ``true``, `tex2jax` looks not only for the in-line and
display math delimiters, but also for LaTeX environments
(``\begin{something}...\end{something}``) and marks them for
processing by MathJax. When ``false``, LaTeX environments will
not be processed outside of math mode.
.. describe:: preview: "TeX"
This controls whether `tex2jax` inserts ``MathJax_Preview`` spans
to make a preview available, and what preview to use, when it
locates in-line or display mathematics in the page. The default
is ``"TeX"``, which means use the TeX code as the preview (which
will be visible until it is processed by MathJax). Set to
``"none"`` to prevent previews from being inserted (the math
will simply disappear until it is typeset). Set to an array
containing the description of an HTML snippet in order to use the
same preview for all equations on the page.
Examples:
.. code-block:: javascript
preview: ["[math]"], // insert the text "[math]" as the preview
.. code-block:: javascript
preview: [["img",{src: "/images/mypic.jpg"}]], // insert an image as the preview
See the :ref:`description of HTML snippets <html-snippets>` for
details on how to represent HTML code in this way.
.. describe:: skipTags: ["script","noscript","style","textarea","pre","code"]
This array lists the names of the tags whose contents should not
be processed by `tex2jax` (other than to look for ignore/process
classes as listed below). You can add to (or remove from) this
list to prevent MathJax from processing mathematics in specific
contexts.
.. describe:: ignoreClass: "tex2jax_ignore"
This is the class name used to mark elements whose contents should
not be processed by tex2jax (other than to look for the
``processClass`` pattern below). Note that this is a regular
expression, and so you need to be sure to quote any `regexp`
special characters. The pattern is inserted into one that
requires your pattern to match a complete word, so setting
``ignoreClass: "class2"`` would cause it to match an element with
``class="class1 class2 class3"`` but not ``class="myclass2"``.
Note that you can assign several classes by separating them by the
vertical line character (``|``). For instance, with
``ignoreClass: "class1|class2"`` any element assigned a class of
either ``class1`` or ``class2`` will be skipped.
.. describe:: processClass: "tex2jax_process"
This is the class name used to mark elements whose contents
*should* be processed by `tex2jax`. This is used to restart
processing within tags that have been marked as ignored via the
``ignoreClass`` or to cause a tag that appears in the ``skipTags``
list to be processed rather than skipped. Note that this is a
regular expression, and so you need to be sure to quote any
`regexp` special characters. The pattern is inserted into one
that requires your pattern to match a complete word, so setting
``processClass: "class2"`` would cause it to match an element with
``class="class1 class2 class3"`` but not ``class="myclass2"``.
Note that you can assign several classes by separating them by the
vertical line character (``|``). For instance, with
``processClass: "class1|class2"`` any element assigned a class of
either ``class1`` or ``class2`` will have its contents processed.
This source diff could not be displayed because it is too large. You can view the blob instead.
This source diff could not be displayed because it is too large. You can view the blob instead.
This source diff could not be displayed because it is too large. You can view the blob instead.
This source diff could not be displayed because it is too large. You can view the blob instead.
This source diff could not be displayed because it is too large. You can view the blob instead.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment