use MathJax instead of jsMath (more portable IMHO)

This commit is contained in:
Yann Esposito (Yogsototh) 2010-08-16 12:02:28 +02:00
parent bd6108bc65
commit 0b10f693ff
50257 changed files with 104488 additions and 40256 deletions

View file

@ -66,19 +66,7 @@ self.instance_variable_set(:@conf, conf)
<script type="text/javascript" src="/Scratch/js/jquery.cookie.js"></script>
<script type="text/javascript" src="/Scratch/js/index.js"></script>
<% if containMaths %>
<script type="text/javascript">
jsMath = {
Controls: {cookie: {scale: 133, font:'image', autofont:0}},
Parser: {prototype: {
macros: {warning: ["Macro","\\color{##00CC00}{\\rm jsMath\\ image\\ mode\\ appears\\ to\\ be\\ working!}",1]}
}}
}
$(document).ready(function(){
jsMath.Process(document);
});
</script>
<script type="text/javascript" src="/Scratch/js/jsMath-3.6e/jsMath.js"></script>
<script type="text/javascript" src="/Scratch/js/jsMath-3.6e/plugin/noImageFonts.js"></script>
<script type="text/javascript" src="/Scratch/js/MathJax/MathJax.js"></script>
<% end %>
<title><%= @item[:title] %></title>
</head>

43
output/Scratch/js/MathJax/MathJax.js vendored Normal file

File diff suppressed because one or more lines are too long

55
output/Scratch/js/MathJax/README.txt vendored Normal file
View file

@ -0,0 +1,55 @@
OVERVIEW:
MathJax is an open-source JavaScript display engine for LaTeX and
MathML 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 downlaod 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.
Some of the main features of MathJax include:
o High-quality display of LaTeX and MathML math notation in HTML pages
o Supported in most browsers with no plug-ins, extra fonts, or special
setup for the reader
o Easy for authors, flexible for publishers, extensible for developers
o Supports math accessibility, cut and paste interoperability and other
advanced functionality
o 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 on 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/docs/
COMMUNITY:
The main MathJax website is www.mathjax.org, and it includes announcements
and other important information. MathJax also has a SourceForge site at
http://sourceforge.net/projects/mathjax/ that includes the download site
for the MathJax distribution, the bug-tracker for reporting bugs, and
several user forums for asking questions and getting assistance:
Bug tracker: http://sourceforge.net/tracker/?group_id=261188&atid=1240827
MathJax Help: http://sourceforge.net/projects/mathjax/forums/forum/948701
Open Discussion: http://sourceforge.net/projects/mathjax/forums/forum/948700
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.

View file

@ -0,0 +1,18 @@
/*
* ../SourceForge/trunk/mathjax/config/MMLorHTML.js
*
* Copyright (c) 2010 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
*/
MathJax.Unpack([
['(function(c){var i="1.0";var g=','MathJax.Hub','.Insert({prefer:{MSIE:"MML",Firefox:"MML",Opera:"HTML",other:"HTML"}},(',1,'.config.MMLorHTML||{}));var e={Firefox:3,Opera:9.52,MSIE:6,Chrome:0.3,Safari:2,Konqueror:4};var h=(c','.Browser','.version==="0.0"||','c.Browser.versionAtLeast','(e[c',5,']||0));var b;try{new ActiveXObject("MathPlayer.Factory.1");b=true}catch(d){b=false}var f=(c',5,'.isFirefox&&',7,'("1.5"))||(c',5,'.isMSIE&&b)||(c',5,'.isOpera&&',7,'("9.52"));var a=(g.prefer&&typeof(g.prefer)==="object"?g.prefer[',1,5,']||g.prefer.other||"HTML":g.prefer);if(h||f){if(f&&(a==="MML"||!h)){','c.config.jax.unshift("output/','NativeMML")}else{',24,'HTML-CSS")}}else{c.PreProcess','.disabled=true;','c.prepareScripts',28,'MathJax.Message.Set("Your browser does not support MathJax",null,4000);c.Startup.signal.Post("MathJax not supported")}})(',1,');MathJax.Ajax.loadComplete("[MathJax]/config/MMLorHTML.js");']
]);

View file

@ -0,0 +1,590 @@
/*************************************************************
*
* MathJax/config/MathJax.js
*
* This configuration file is loaded when there is no explicit
* configuration script in the <script> tag that loads MathJax.js
*
* Use it to customize the MathJax settings. See comments below.
*
* ---------------------------------------------------------------------
*
* Copyright (c) 2009-10 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.Config({
//
// A comma-separated list of configuration files to load
// when MathJax starts up. E.g., to define local macros, etc.
// The default directory is the MathJax/config directory.
//
// Example: config: ["local/local.js"],
// Example: config: ["local/local.js","MMLtoHTML.js"],
//
config: [],
//
// A comma-separated list of CSS stylesheet files to be loaded
// when MathJax starts up. The default directory is the
// MathJax/config directory.
//
// Example: styleSheets: ["MathJax.css"],
//
styleSheets: [],
//
// Styles to be defined dynamically at startup time.
//
// Example:
// styles: {
// ".MathJax .merror": {
// color: "blue",
// "background-color": "green"
// }
// },
//
styles: {},
//
// A comma-separated list of input and output jax to initialize at startup.
// Their main code is loaded only when they are actually used, so it is not
// inefficient to include jax that may not actually be used on the page. These
// are found in the MathJax/jax directory.
//
jax: ["input/TeX","output/HTML-CSS"],
//
// A comma-separated list of extensions to load at startup. The default
// directory is MathJax/extensions.
//
// Example: extensions: ["tex2jax.js","TeX/AMSmath.js","TeX/AMSsymbols.js"],
//
extensions: ["tex2jax.js"],
//
// Patterns to remove from before and after math script tags. If you are not
// using one of the preprocessors (e.g., tex2jax), you need to insert something
// extra into your HTML file in order to avoid a bug in Internet Explorer. IE
// removes spaces from the DOM that it thinks are redundent, and since a SCRIPT
// tag usually doesn't add content to the page, if there is a space before and after
// a MathJax SCRIPT tag, IE will remove the first space. When MathJax inserts
// the typeset mathematics, this means there will be no space before it and the
// preceeding text. In order to avoid this, you should include some "guard characters"
// before or after the math SCRIPT tag; define the patterns you want to use below.
// Note that these are used as regular expressions, so you will need to quote
// special characters. Furthermore, since they are javascript strings, you must
// quote javascript special characters as well. So to obtain a backslash, you must
// use \\ (doubled for javascript). For example, "\\[" is the pattern \[ in the
// regular expression. That means that if you want an actual backslash in your
// guard characters, you need to use "\\\\" in order to get \\ in the regular
// expression, and \ in the actual text. If both preJax and postJax are defined,
// both must be present in order to be removed.
//
// See also the preRemoveClass comments below.
//
// Example:
// preJax: "\\\\\\\\", // makes a double backslash the preJax text
// or
// preJax: "\\[\\[", // jax scripts must be enclosed in double brackets
// postJax: "\\]\\]",
//
preJax: null,
postJax: null,
//
// The CSS class for a math preview to be removed preceeding a MathJax
// SCRIPT tag. If the tag just before the MathJax SCRIPT tag is of this
// class, its contents are removed when MathJax processes the SCRIPT
// tag. This allows you to include a math preview in a form that will
// be displayed prior to MathJax performing its typesetting. It also
// avoids the Internet Explorer space-removal bug, and can be used in
// place of preJax and postJax if that is more convenient.
//
// For example
//
// <span class="MathJax_Preview">[math]</span><script type="math/tex">...</script>
//
// would display "[math]" in place of the math until MathJax is able to typeset it.
//
preRemoveClass: "MathJax_Preview",
//
// This value controls whether the "Processing Math: nn%" message are displayed
// in the lower left-hand corner. Set to "false" to prevent those messages (though
// file loading and other messages will still be shown).
//
showProcessingMessages: true,
//
// This value controls the verbosity of the messages in the lower left-hand corner.
// Set it to "none" to eliminate all messages, or set it to "simple" to show
// "Loading..." and "Processing..." rather than showing the full file name and the
// percentage of the mathematics processed.
//
messageStyle: "normal",
//
// These two parameters control the alignment and shifting of displayed equations.
// The first can be "left", "center", or "right", and determines the alignment of
// displayed equations. When the alignment is not "center", the second determines
// an indentation from the left or right side for the displayed equations.
//
displayAlign: "center",
displayIndent: "0em",
//
// Normally MathJax will perform its starup commands (loading of
// configuration, styles, jax, and so on) as soon as it can. If you
// expect to be doing additional configuration on the page, however, you
// may want to have it wait until the page's onload hander is called. If so,
// set this to "onload".
//
delayStartupUntil: "none",
//
// Normally MathJax will typeset the mathematics on the page as soon as
// the page is loaded. If you want to delay that process, in which case
// you will need to call MathJax.Hub.Typeset() yourself by hand, set
// this value to true.
//
skipStartupTypeset: false,
//============================================================================
//
// These parameters control the tex2jax preprocessor (when you have included
// "tex2jax.js" in the extensions list above).
//
tex2jax: {
//
// The Id of the element to be processed (defaults to full document)
//
element: null,
//
// The delimiters that surround in-line math expressions. The first in each
// pair is the initial delimiter and the second is the terminal delimiter.
// Comment out any that you don't want, but be sure there is no extra
// comma at the end of the last item in the list -- some browsers won't
// be able to handle that.
//
inlineMath: [
['$','$'], // uncomment this for standard TeX math delimiters
['\\(','\\)']
],
//
// The delimiters that surround displayed math expressions. The first in each
// pair is the initial delimiter and the second is the terminal delimiter.
// Comment out any that you don't want, but be sure there is no extra
// comma at the end of the last item in the list -- some browsers won't
// be able to handle that.
//
displayMath: [
['$$','$$'],
['\\[','\\]']
],
//
// 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.
//
skipTags: ["script","noscript","style","textarea","pre","code"],
//
// 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 automatically preceeded by '(^| )(' and
// followed by ')( |$)', so your pattern will have to match full words
// in the class name. Assigning an element this class name will
// prevent `tex2jax` from processing its contents.
//
ignoreClass: "tex2jax_ignore",
//
// This is the class name used to mark elements whose contents SHOULD
// be processed by tex2jax. This is used to turn on processing within
// tags that have been marked as ignored or skipped above. Note that
// this is a regular expression, and so you need to be sure to quote
// any regexp special characters. The pattern is automatically
// preceeded by '(^| )(' and followed by ')( |$)', so your pattern
// will have to match full words in the class name. Use this to
// restart processing within an element that has been marked as
// ignored above.
//
processClass: "tex2jax_process",
//
// Set to "true" to allow \$ to produce a dollar without starting in-line
// math mode. If you uncomment the ['$','$'] line above, you should change
// this to true so that you can insert plain dollar signs into your documents
//
processEscapes: false,
//
// Controls whether tex2jax processes LaTeX environments outside of math
// mode. Set to "false" to prevent processing of environments except within
// math mode.
//
processEnvironments: true,
//
// Controls whether tex2jax inserts MathJax_Preview spans to make a
// preview available, and what preview to use, when it locates in-line
// and display mathetics on the page. The default is "TeX", which
// means use the TeX code as the preview (until it is processed by
// MathJax). Set to "none" to prevent the 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 (e.g., you
// could have it say "[math]" or load an image).
//
// E.g., preview: ["[math]"],
// or preview: [["img",{src: "http://myserver.com/images/mypic.jpg"}]]
//
preview: "TeX"
},
//============================================================================
//
// These parameters control the mml2jax preprocessor (when you have included
// "mml2jax.js" in the extensions list above).
//
mml2jax: {
//
// The Id of the element to be processed (defaults to full document)
//
element: null,
//
// Controls whether mml2jax inserts MathJax_Preview spans to make a
// preview available, and what preview to use, whrn it locates
// mathematics on the page. The default is "alttext", which means use
// the <math> tag's alttext attribute as the preview (until it is
// processed by MathJax), if the tag has one. Set to "none" to
// prevent the 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 (e.g., you could have it say "[math]" or
// load an image).
//
// E.g., preview: ["[math]"],
// or preview: [["img",{src: "http://myserver.com/images/mypic.jpg"}]]
//
preview: "alttext"
},
//============================================================================
//
// These parameters control the jsMath2jax preprocessor (when you have included
// "jsMath2jax.js" in the extensions list above).
//
jsMath2jax: {
//
// The Id of the element to be processed (defaults to full document)
//
element: null,
//
// Controls whether jsMath2jax inserts MathJax_Preview spans to make a
// preview available, and what preview to use, when it locates
// mathematics on the page. The default is "TeX", which means use the
// TeX code as the preview (until it is processed by MathJax). Set to
// "none" to prevent the 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 (e.g., you could have it say "[math]"
// or load an image).
//
// E.g., preview: ["[math]"],
// or preview: [["img",{src: "http://myserver.com/images/mypic.jpg"}]]
//
preview: "TeX"
},
//============================================================================
//
// These parameters control the TeX input jax.
//
TeX: {
//
// This specifies the side on which \tag{} macros will place the tags.
// Set to "left" to place on the left-hand side.
//
TagSide: "right",
//
// This is the amound of indentation (from right or left) for the tags.
//
TagIndent: ".8em",
//
// This is the width to use for the multline environment
//
MultLineWidth: "85%",
//
// List of macros to define. These are of the form
// name: value
// where 'value' is the replacement text for the macro \name.
// The 'value' can also be [value,n] where 'value' is the replacement
// text and 'n' is the number of parameters for the macro.
// Note that backslashes must be doubled in the replacement string.
//
// E.g.,
//
// Macros: {
// RR: '{\\bf R}',
// bold: ['{\\bf #1}', 1]
// }
//
Macros: {}
},
//============================================================================
//
// These parameters control the MathML inupt jax.
//
MathML: {
//
// This specifies whether to use TeX spacing or MathML spacing when the
// HTML-CSS output jax is used.
//
useMathMLspacing: false
},
//============================================================================
//
// These parameters control the HTML-CSS output jax.
//
"HTML-CSS": {
//
// This controls the global scaling of mathematics as compared to the
// surrounding text. Values between 100 and 133 are usually good choices.
//
scale: 100,
//
// 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 STIX fonts, or set it to an empty list, [], if
// you want to force MathJax to use web-based or image fonts.
//
availableFonts: ["STIX","TeX"],
//
// This is the preferred font to use when more than one of those
// listed above is available.
//
preferredFont: "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. Set this to
//
// webFont: null,
//
// if you want to prevent the use of web-based fonts.
//
webFont: "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. Set this to
//
// imageFont: null,
//
// if you want to prevent the use of image fonts (e.g., you have 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, so without image fonts, FF3.0 users
// will be required to to download and install either the STIX fonts or the
// MathJax TeX fonts.
//
imageFont: "TeX",
//
// This controls whether the MathJax contextual menu will be available
// on the mathematics in the page. If true, then right-clicking (on
// the PC) or control-clicking (on the Mac) will produce a MathJax
// menu that allows you to get the source of the mathematics in
// various formats, change the size of the mathematics relative to the
// surrounding text, and get information about MathJax.
//
// Set this to false to disable the menu. When true, the MathMenu
// items below configure the actions of the menu.
//
showMathMenu: true,
//
// This allows you to define or modify the styles used to display
// various math elements created by MathJax.
//
// Example:
// styles: {
// ".MathJax_Preview": {
// "font-size": "80%", // preview uses a smaller font
// color: "red" // and is in red
// }
// }
//
styles: {},
//
// Configuration for <maction> tooltips
// (see also the #MathJax_Tooltip CSS in MathJax/jax/output/HTML-CSS/config.js,
// which can be overriden using the styles values above).
//
tooltip: {
delayPost: 600, // milliseconds delay before tooltip is posted after mouseover
delayClear: 600, // milliseconds delay before tooltip is cleared after mouseout
offsetX: 10, offsetY: 5 // pixels to offset tooltip from mouse position
}
},
//============================================================================
//
// These parameters control the NativeMML output jax.
//
NativeMML: {
//
// This controls the global scaling of mathematics as compared to the
// surrounding text. Values between 100 and 133 are usually good choices.
//
scale: 100,
//
// This controls whether the MathJax contextual menu will be available
// on the mathematics in the page. If true, then right-clicking (on
// the PC) or control-clicking (on the Mac) will produce a MathJax
// menu that allows you to get the source of the mathematics in
// various formats, change the size of the mathematics relative to the
// surrounding text, and get information about MathJax.
//
// Set this to false to disable the menu. When true, the MathMenu
// items below configure the actions of the menu.
//
// There is a separate setting for MSIE, since the code to handle that
// is a bit delicate; if it turns out to have unexpected consequences,
// you can turn it off without turing off other browser support.
//
showMathMenu: true,
showMathMenuMSIE: true,
//
// This allows you to define or modify the styles used to display
// various math elements created by MathJax.
//
// Example:
// styles: {
// ".MathJax_MathML": {
// color: "red" // MathML is in red
// }
// }
//
styles: {}
},
//============================================================================
//
// These parameters control the contextual menus that are available on the
// mathematics within the page (provided the showMathMenu value is true above).
//
MathMenu: {
//
// This is the hover delay for the display of submenus in the
// contextual menu. When the mouse is still over a submenu label for
// this long, the menu will appear. (The menu also will appear if you
// click on the label.) It is in milliseconds.
//
delay: 400,
//
// This is the URL for the MathJax Help menu item.
//
helpURL: "http://www.mathjax.org/help/user/",
//
// These control whether the "Math Renderer", "Font Preferences",
// and "Contextual Menu" submenus will be displayed or not.
//
showRenderer: true,
showFontMenu: false,
showContext: false,
//
// These are the settings for 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.
//
windowSettings: {
status: "no", toolbar: "no", locationbar: "no", menubar: "no",
directories: "no", personalbar: "no", resizable: "yes", scrollbars: "yes",
width: 100, height: 50
},
//
// This allows you to change the CSS that controls the menu
// appearance. See the extensions/MathMenu.js file for details
// of the default settings.
//
styles: {}
},
//============================================================================
//
// These parameters control the MMLorHTML configuration file.
// NOTE: if you add MMLorHTML.js to the config array above,
// you must REMOVE the output jax from the jax array.
//
MMLorHTML: {
//
// The output jax that is to be preferred when both are possible
// (set to "MML" for native MathML, "HTML" for MathJax's HTML-CSS output jax).
//
prefer: {
MSIE: "MML",
Firefox: "MML",
Opera: "HTML",
other: "HTML"
}
}
});
MathJax.Ajax.loadComplete("[MathJax]/config/MathJax.js");

View file

@ -0,0 +1,37 @@
/*************************************************************
*
* 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");

View file

@ -0,0 +1,4 @@
# Sphinx build info version 1
# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
config: fedf9ba9a5b2ef65b82b1fa1eea24e52
tags: fbb0d17656682115ca4d033fb2f83ba1

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

View file

@ -0,0 +1,173 @@
<!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 v1.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: '1.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>
<link rel="top" title="MathJax v1.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 v1.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 CSS
style objects, 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 attibute 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 .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-family&quot;</span><span class="o">:</span> <span class="s2">&quot;serif&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="s2">&quot;.MathJax_Preview&quot;</span><span class="o">:</span> <span class="p">{</span><span class="nx">color</span><span class="o">:</span> <span class="s2">&quot;#888888&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</span>
<span class="pre">.merror</span></tt>, which specifies a background color, foreground color,
border, and so on, and a second for <tt class="docutils literal"><span class="pre">.MathJax_Preview</span></tt> that sets its
color.</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>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/CSS-styles.txt"
rel="nofollow">Show Source</a></li>
</ul>
<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 v1.0 documentation</a> &raquo;</li>
</ul>
</div>
<div class="footer">
&copy; Copyright 2010 Design Science.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0b2.
</div>
</body>
</html>

View file

@ -0,0 +1,170 @@
<!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 v1.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: '1.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>
<link rel="top" title="MathJax v1.0 documentation" href="index.html" />
<link rel="next" title="CSS Style Objects" href="CSS-styles.html" />
<link rel="prev" title="Converting to MathJax from jsMath" href="jsMath.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="jsMath.html" title="Converting to MathJax from jsMath"
accesskey="P">previous</a> |</li>
<li><a href="index.html">MathJax v1.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
configutation 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 elements that formt
he 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="jsMath.html"
title="previous chapter">Converting to MathJax from jsMath</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="CSS-styles.html"
title="next chapter">CSS Style Objects</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/HTML-snippets.txt"
rel="nofollow">Show Source</a></li>
</ul>
<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="jsMath.html" title="Converting to MathJax from jsMath"
>previous</a> |</li>
<li><a href="index.html">MathJax v1.0 documentation</a> &raquo;</li>
</ul>
</div>
<div class="footer">
&copy; Copyright 2010 Design Science.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0b2.
</div>
</body>
</html>

Binary file not shown.

After

Width:  |  Height:  |  Size: 3.6 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 28 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 15 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 15 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 7.1 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 6.9 KiB

View file

@ -0,0 +1,79 @@
.. _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 attibute 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 .merror": {
"background-color": "#FFFF88",
color: "#CC0000",
border: "1px solid #CC0000",
padding: "1px 3px",
"font-family": "serif",
"font-style": "normal",
"font-size": "90%"
},
".MathJax_Preview": {color: "#888888"},
}
This defines two CSS styles, one for the selector ``.MathJax
.merror``, which specifies a background color, foreground color,
border, and so on, and a second for ``.MathJax_Preview`` that sets its
color.
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.

View file

@ -0,0 +1,83 @@
.. _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
configutation 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 elements that formt
he 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>

View file

@ -0,0 +1,196 @@
.. _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:* 20 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.
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 or 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 need 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:: 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

View file

@ -0,0 +1,259 @@
.. _api-callback:
**************************
The MathJax.Callback Class
**************************
The ``MathJax.Callback`` 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 `Callback`
object is used to tie the execution of a function to the completion of
an asynchronous action. See :ref:`Synchronizing with MathJax
<synchronization>` for more details, and :ref:`Using Callbacks
<using-callbacks>` in particular for examples of how to specify and
use MathJax `Callback` objects.
Specifying a callback
---------------------
When a method includes a callback as one of its arguments, that
callback 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 executed, and even
the object that will be used as the javascript `this` object when the
function is called.
Most functions that take callbacks as arguments accept a `callback
specification` rather than an actual callback object, though you can
use the :meth:`MathJax.Callback` function to convert a callback
specification into a Callback object if needed.
A callback specification is any one of the following:
.. describe:: fn
A function that is to be called when the callback is executed.
No additional data is passed to it (other that what it is
called with at the time the callback is executed), and `this`
will be the window object.
.. describe:: [fn]
An array containing a function to be called when the callback
is executed (as above).
.. describe:: [fn, data...]
An array containing a function together with data to be passed
to that function when the callback is executed; `this` is still
the window object. For example,
.. code-block:: javascript
[function (x,y) {return x+y}, 2, 3]
would specify a callback that would pass ``2`` and ``3`` to
the given function, and it would return their sum, ``5``, when
the callback is executed.
.. describe:: [object, fn]
An array containing an object to use as `this` and a function to
call for the callback. For example,
.. code-block:: javascript
[{x:'foo', y:'bar'}, function () {this.x}]
would produce a callback that returns the string ``"foo"``
when it is called.
.. describe:: [object, fn, data...]
Similar to the previous case, but with data that is passed to
the function as well.
..describe:: ["method", object]
Here, `object` is an object that has a method called `method`, and
the callback will execute that method (with the object as
`this`) when it is called. For example,
.. code-block:: javascript
["length",[1,2,3,4]]
would call the `length` method on the array ``[1,2,3,4]`` when
the callback is called, returning ``4``.
.. describe:: ["method", object, data...]
Similar to the previous case, but with data that is passed to
the method. E.g.,
.. code-block:: javascript
["slice",[1,2,3,4],1,3]
would perform the equivalent of ``[1,2,3,4].slice(1,3)``,
which returns the array ``[2,3]`` as a result.
.. describe:: {hook: fn, data: [...], object: this}
Here the data for the callback are given in an associative
array of `key:value` pairs. The value of `hook` is the
function to call, the value of `data` is an array of the
arguments to pass to the function, and the value of `object`
is the object to use as `this` in the function call. The
specification need not include all three `key:value` pairs; any
that are missing get default values (a function that does
nothing, an empty array, and the window object, respectively).
.. describe:: "string"
This specifies a callback where the string is executed via an
``eval()`` statement. The code is run in the global context,
so any variables or functions created by the string become
part of the global namespace. The return value is the value of
the last statement executed in the string.
Executing a Callback Object
===========================
The `Callback` object is itself a function, and calling that function
executes the callback. You can pass the callback additional
parameters, just as you can any function, and these will be added to
the callback function's argument list following any data that was
supplied at the time the callback was created. For example
.. code-block:: javascript
var f = function (x,y) {return x + " and " +y}
var cb = MathJax.Callback([f, "foo"]);
var result = cb("bar"); // sets result to "foo and bar"
Usually, the callback is not executed by the code that creates it (as
it is in the example above), but by some other code that runs at a
later time at the completion of some other activity (say the loading
of a file), or in response to a user action. For example:
.. code-block:: javascript
function f(x) {alert("x contains "+x)};
function DelayedX(time) {
var x = "hi";
setTimeout(MathJax.Callback([f, x], time);
}
The ``DelayedX`` function arranges for the function ``f`` to be called at
a later time, passing it the value of a local variable, ``x``. Normally,
this would require the use of a closure, but that is not needed when a
`MathJax.Callback` object is used.
Callback Object Properties
--------------------------
.. describe:: hook
The function to be called when the callback is executed.
.. describe:: data
An array containing the arguments to pass to the callback
function when it is executed.
.. describe:: object
The object to use as `this` during the call to the callback
function.
.. describe:: called
Set to ``true`` after the callback has been called, and undefined
otherwise. A callback will not be exectued a second time unless
the callback's :meth:`reset()` method is called first, or its
``autoReset`` property is set to ``true``.
.. describe:: autoReset
Set this to ``true`` if you want to be able to call the callback
more than once. (This is the case for signal listeners, for example).
.. describe:: isCallback
Always set to ``true`` (used to detect if an object is a callback
or not).
Callback Object Methods
-----------------------
.. method:: reset()
Clears the callback's `called` property.
MathJax.Callback Methods
------------------------
.. method:: Delay(time[, callback])
Waits for the specified time (given in milliseconds) and then
performs the callback. It returns the Callback object (or a blank
one if none was supplied). The returned callback structure has a
`timeout` property set to the result of the ``setTimeout()`` call
that was used to perform the wait so that you can cancel the wait,
if needed. Thus :meth:`MathJax.Callback.Delay()` can be used to
start a timeout delay that executes the callback if an action
doesn't occur within the given time (and if the action does occur,
the timeout can be canceled). Since
:meth:`MathJax.Callback.Delay()` returns a callback structure, it
can be used in a callback queue to insert a delay between queued
commands.
:Parameters:
- **time** --- the amount of time to wait
- **callback** --- the callback specification
:Returns: the callback object
.. method:: executeHooks(hooks[, data[,reset]])
Calls each callback in the `hooks` array (or the single hook if it
is not an array), passing it the arguments stored in the data
array. It `reset` is ``true``, then the callback's
:meth:`reset()` method will be called before each hook is
executed. If any of the hooks returns a `Callback` object, then
it collects those callbacks and returns a new callback that will
execute when all the ones returned by the hooks have been
completed. Otherwise, :meth:`MathJax.Callback.executeHooks()`
returns ``null``.
:Parameters:
- **hooks** --- array of hooks to be called, or a hook
- **data** --- array of arguments to pass to each hook in turn
- **reset** --- ``true`` if the :meth:`reset()` method should be called
:Returns: callback that waits for all the hooks to complete, or ``null``
.. method:: Queue([callback,...])
Creates a `MathJax.CallBack.Queue` object and pushes the given
callbacks into the queue. See :ref:`Using Queues <using-queues>`
for more details about MathJax queues.
:Parameters:
- **callback** --- one or more callback specifications
:Returns: the `Queue` object
.. method:: Signal(name)
Looks for a named signal, creates it if it doesn't already exist,
and returns the signal object. See
:ref:`Using Signals <using-signals>` for more details.
:Parameters:
- **name** --- name of the signal to get or create
:Returns: the `Signal` object

View file

@ -0,0 +1,122 @@
.. _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:: name
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
A reference to the input jax that created the element.
.. describe:: outputJax
A reference to 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.
.. 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., update the equation to the
new one given by `text`). When the processing is complete, the
`callback`, if any, is called.
:Parameters:
- **text** --- the new mathematic source string for the element
- **callback** --- the callback specification
:Returns: the callback object
.. Method:: Reprocess([callback])
:noindex:
Remove the output and produce it again. This may be necessary if
there are changes to the CSS styles that would affect the layout
of the mathematics, for example. 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
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.

View file

@ -0,0 +1,122 @@
.. _api-html:
***********************
The MathJax.HTML Object
***********************
The ``MathJax.HTML`` object provides routines for creating HTML
elements and adding them to the page, and int 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
.. 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 coookie
- **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"}``.

View file

@ -0,0 +1,330 @@
.. _api-hub:
**********************
The MathJax.Hub Object
**********************
The MathJax Hub, `MathJax.Hub`, is the main control structure for
MathJax. It is where input and output :term:`jax` are tied together,
and it is what handles processing of the MathJax ``<script>`` tags.
Processing of the mathematics on the page may require external files
to be loaded (when the mathematics includes less common functionality,
for example, that is defined in an extension file), and since file
loading is asynchronous, a number of the methods below may return
before their actions are completed. For this reason, they include
callback functions that are called when the action completes. These
can be used to synchronize actions that require the mathematics to be
completed before those action occur. See the :ref:`Using Callbacks
<using-callbacks>` documentation for more details.
Properties
==========
.. describe:: config: { ... }
This holds the configuration parameters for MathJax. Set these
values using :meth:`MathJax.Hub.Config()` described below. The
options and their default values are given in the :ref:`Core
Options <configure-hub>` reference page.
.. describe:: processUpdateTime: 500
The minimum time (in milliseconds) between updates of the
"Processing Math" message.
.. describe:: signal
The hub processing signal (tied to the
:meth:`MathJax.Hub.Register.MessageHook()` method).
.. describe:: Browser
The name of the browser as determined by MathJax. It will be one
of ``Firefox``, ``Safari``, ``Chrome``, ``Opera``, ``MSIE``,
``Konqueror``, or ``unkown``. This is actually an object with
additional properties and methods concerning the browser:
.. describe:: version
The browser version number, e.g., ``"4.0"``
.. describe:: isMac and isPC
These are boolean values that indicate whether the browser is
running on a Macintosh computer or a Windows computer. They
will both be ``false`` for a Linux computer
.. describe:: isForefox, isSafari, isChrome, isOpera, isMSIE, isKonqueror
These are ``true`` when the browser is the indicated one, and
``false`` otherwise.
.. describe:: versionAtLeast(version)
This tests whether the browser version is at least that given
in the `version` string. Note that you can not simply do a
numeric comparison, as version 4.10 should be considered later
than 4.9, for example. Similarly, 4.10 is different from 4.1,
for instance.
.. describe:: Select(choices)
This lets you perform browser-specific functions. Here,
`choices` is an object whose properties are the names of the
browsers and whose values are the functions to be performed.
Each function is passed one parameter, which is the
``MathJax.Hub.Browser`` object. You do not need to include
every browser as one of your choices (only those for which you
need to do special processing. For example:
.. code-block:: javascript
MathJax.Hub.Browser.Select(
MSIE: function (browser) {
if (browser.versionAtLeast("8.0")) {... do version 8 stuff ... }
... do general MSIE stuff ...
},
Firefox: function (browser) {
if (browser.isMac) {... do Mac stuff ... }
... do general Firefox stuff
}
);
Methods
=======
.. Method:: Config(options)
Sets the configuration options (stored in ``MathJax.Hub.config``)
to the values stored in the `options` object. See
:ref:`Configuring MathJax <configuration>` for details on how this
is used and the options that you can set.
:Parameters:
- **options** --- object containing options to be set
:Returns: ``null``
.. describe:: Register.PreProcessor(callback)
Used by preprocessors to register themselves with MathJax so that
they will be called during the :meth:`MathJax.Hub.PreProcess()`
action.
:Parameters:
- **callback** --- the callback specification for the preprocessor
:Returns: ``null``
.. describe:: Register.MessageHook(type,callback)
Registers a listener for a particular message being sent to the
hub processing signal (where `PreProcessing`, `Processing`, and
`New Math` messages are sent). When the message equals the
`type`, the `callback` will be called with the message as its
parameter.
:Parameters:
- **type** --- a string indicating the message to look for
- **callback** --- a callback specification
:Returns: ``null``
.. describe:: Register.StartupHook(type,callback)
Registers a listener for a particular message being sent to the
startup signal (where initialization and component startup
messages are sent). When the message equals the `type`, the
`callback will be called with the message as its parameter.
See the :ref:`Using Signals <using-signals>` dcocumentation for
more details.
:Parameters:
- **type** --- a string indicating the message to look for
- **callback** --- a callback specification
:Returns: ``null``
.. describe:: Register.LoadHook(file,callback)
Registers a callback to be called when a particular file is
completely loaded and processed. (The callback is called when the
file makes its :meth:`MathJax.Ajax.loadComplete()` call.) The
`file` should be the complete file name, e.g.,
``"[MathJax]/config/MathJax.js"``.
:Parameters:
- **file** --- the name of the file to wait for
- **callback** --- a callback specification
:Returns: the callback object
.. Method:: Queue(callback,...)
:noindex:
Pushes the given callbacks onto the main MathJax command queue.
This synchronizes the commands with MathJax so that they will be
performed in the proper order even when some run asynchronously.
See :ref:`Using Queues <using-queues>` for more details about how
to use queues, and the MathJax queue in particular. You may
supply as many `callback` specifications in one call to the
:meth:`Queue()` method as you wish.
:Parameters:
- **callback** --- a callback specification
:Returns: the callback object for the last callback added to the queue
.. Method:: Typeset([element[,callback]])
Calls the preprocessors on the given element, and then typesets
any math elements within the element. If no `element` is
provided, the whole document is processed. The `element` is
either the DOM `id` of the element, or a reference to the DOM
element itself. The `callback` is called when the process is
complete. See the :ref:`Modifying Math <typeset-math>` section
for details of how to use this method properly.
:Parameters:
- **element** --- the element whose math is to be typeset
- **callback** --- the callback specification
:Returns: the callback object
.. method:: PreProcess([element[,callback]])
Calls the loaded preprocessors on the entire document, or on the
given DOM element. The `element` is either the DOM `id` of the
element, or a reference to the DOM element itself. The `callback`
is called when the processing is complete.
:Parameters:
- **element** --- the element to be preprocessed
- **callback** --- the callback specification
:Returns: the callback object
.. method:: Process([element[,callback]])
Scans either the entire document or a given DOM `element` for
MathJax ``<script>`` tags and processes the math those tags
contain. The `element` is either the DOM `id` of the element to
scan, or a reference to the DOM element itself. The `callback` is
called when the processing is complete.
:Parameters:
- **element** --- the element to be processed
- **callback** --- the callback specification
:Returns: the callback object
.. method:: Update([element[,callback]])
Scans either the entire document or a given DOM element for
mathematics that has changed since the last time it was processed,
or is new, and typesets the mathematics they contain. The
`element` is either the DOM `id` of the element to scan, or a
reference to the DOM element itself. The `callback` is called
when the processing is complete.
:Parameters:
- **element** --- the element to be updated
- **callback** --- the callback specification
:Returns: the callback object
.. method:: Reprocess([element[,callback]])
Removes any typeset mathematics from the document or DOM
element, and then processes the mathematics again,
re-typesetting everything. This may be necessary, for example, if
the CSS styles have changed and those changes would affect the
mathematics. The `element` is either the DOM `id` of the element
to scan, or a reference to the DOM element itself. The `callback`
is called when the processing is complete.
:Parameters:
- **element** --- the element to be reprocessed
- **callback** --- the callback specification
:Returns: the callback object
.. method:: getAllJax([element])
Returns a list of all the element jax in the document or a
specific DOM element. The `element` is either the DOM `id` of the
element, or a reference to the DOM element itself.
:Parameters:
- **element** --- the element to be searched
:Returns: array of `element jax` objects
.. method:: getJaxByType(type[,element])
Returns a list of all the element jax of a given MIME-type in the
document or a specific DOM element. The `element` is either the
DOM `id` of the element to search, or a reference to the DOM
element itself.
:Parameters:
- **type** --- MIME-type of `element jax` to find
- **element** --- the element to be searched
:Returns: array of `element jax` objects
.. method:: getJaxByInputType(type[,element])
Returns a list of all the element jax associated with input
``<script>`` tags with the given MIME-type within the given DOM
element or the whole document. The `element` is either the DOM
`id` of the element to search, or a reference to the DOM element
itself.
:Parameters:
- **type** --- MIME-type of input (e.g., ``"math/tex"``)
- **element** --- the element to be searched
:Returns: array of `element jax` objects
.. method:: getJaxFor(element)
Returns the element jax associated with a given DOM
element. If the element does not have an associated element jax,
``null`` is returned. The `element` is either the DOM `id` of the
element, or a reference to the DOM element itself.
:Parameters:
- **element** --- the element whose element jax is required
:Returns: `element jax` object or ``null``
.. method:: isJax(element)
Returns ``0`` if the element is not a ``<script>`` that can be
processed by MathJax or the result of an output jax, returns ``-1``
if element is an unprocessed ``<script>`` tag that could be
handled by MathJax, and returns ``1`` if element is a processed
``<script>`` tag or an element that is the result of an output jax.
:Parameters:
- **element** --- the element to inspect
:Returns: integer (-1, 0, 1)
.. Method:: Insert(dst,src)
Inserts data from the `src` object into the `dst` object. The
`key:value` pairs in `src` are (recursively) copied into `dst`, so
that if `value` is itself an object, its contents is copied into
the corresponding object in `dst`. That is, objects within `src`
are merged into the corresponding objects in `dst` (they don't
replace them).
:Parameters:
- **dst** --- the destination object
- **src** --- the source object
:Returns: the modified destination object
.. Method:: formatError(script,error)
This is called when an internal error occurs during the processing
of a math element (i.e., an error in the MathJax code itself).
The `script` is a reference to the ``<script>`` tag where the
error occurred, and `error` is the ``Error`` object for the error.
The default action is to insert an HTML snippet at the location of
the script, but this routine can be overriden durring MathJax
configuration in order to perform some other action.
``MathJax.Hub.lastError`` holds the ``error`` value of the last
error on the page.
:Parameters:
- **script** --- the ``<script>`` tag causing the error
- **error** --- the ``Error`` object for the error
:Returns: ``null``

View file

@ -0,0 +1,44 @@
.. _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 objects 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. We will use `Object` (capitalized) or
`MathJax.Object` for, when the distinction is important.
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>

View file

@ -0,0 +1,86 @@
.. _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:: name
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"``);
Methods
=======
.. Method:: Translate(script)
:noindex:
This is the main routine called by MathJax when a ``<script>`` of
the appropriate type is found. The default :meth:`Translate()`
method simply loads the ``jax.js`` file and returns that callback
for that load function so that MathJax will know when to try
the :meth:`Translate()` action again. When the ``jax.js`` file
loads, it should override the default :meth:`Translate()` with its
own version that does the actual translation; that way, when the
second Translate call is made, it will be to the actual
translation routine rather than the default loader.
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
: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``

View file

@ -0,0 +1,148 @@
.. _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({
name: "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:: name
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.
Methods
=======
.. Method:: Translate(script)
This is the method that the ``MathJax.Hub`` calls when it needs
the input or output jax to process the given math ``<script>``
call. Its default action is to start loading the jax's ``jax.js``
file, and redefine the :meth:`Translate()` method to be the
:meth:`noTranslate()` method below. The ``jax.js`` file should
redefine the :meth:`Translate()` method to perform the translation
operation for the specific jax. For an input jax, it should
return the `ElementJax` object that it created.
:Parameters:
- **script** --- reference to the DOM ``<script>`` object for
the mathematics to be translated
:Returns: an `ElementJax` object, or ``null``
.. Method:: noTranslate(script)
This is a temporary routine that is used while the ``jax.js`` file
is loading. It throws an error indicating the the
:meth:`Translate()` method hasn't been redefined. That way, if
the ``jax.js`` file failes to load for some reason, you will
receive an error trying to process mathematics with this input
jax.
:Parameters:
- **script** --- reference to the DOM ``<script>`` object for
the mathematics to be translated
:Returns: ``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`` array (which may
have been modified during the configuration process).
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. perform the :meth:`MathJax.Ajax.loadComplete()` call for the
``jax.js`` file.

View file

@ -0,0 +1,86 @@
.. _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 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 message (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 nuber 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:: 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

View file

@ -0,0 +1,210 @@
.. _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"

View file

@ -0,0 +1,100 @@
.. _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:: name
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"``);
Methods
=======
.. Method:: Translate(script)
:noindex:
This is the main routine called by MathJax when an element jax is
to be converted to output. The default :meth:`Translate()`
method simply loads the ``jax.js`` file and returns that callback
for that load function so that MathJax will know when to try
the :meth:`Translate()` action again. When the ``jax.js`` file
loads, it should override the default :meth:`Translate()` with its
own version that does the actual translation; that way, when the
second Translate call is made, it will be to the actual
translation routine rather than the default loader.
You should use ``MathJax.Hub.getJaxFor(script)`` to obtain the
element jax for the given script. The translation process may add
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.
:Parameters:
- **script** --- the ``<script>`` element to be translated
:Returns: the `element jax` resulting from the translation
.. 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``

View file

@ -0,0 +1,99 @@
.. _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` obejct
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 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 make 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.

View file

@ -0,0 +1,154 @@
.. _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 pulicise the fact that MathJax has performed certain
actions, giving other code running the 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 stored 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 in each 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 exectured. 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 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``

View file

@ -0,0 +1,83 @@
********************
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 most of MathJax to
operate asynchronously is handled here.
.. describe:: MathJax.Message
Contains the code to handle the intermittant 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.Extensions
Initially empty, this is where extensions can load their code.
For example, the `tex2jax` preprocessor creates
``MathJax.Extensions.tex2jax`` for its code and variables.
.. 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 creates 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.
.. describe:: MathJax.isReady
This is set to ``true`` when MathJax is set up and ready to
perform typesetting actions (and is ``null`` otherwise).

View file

@ -0,0 +1,228 @@
.. _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 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 preceed it int he 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.fullName()`` 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 one
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 accpets 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, Internet Explorer does 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 myTimer (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.

View file

@ -0,0 +1,60 @@
*********************
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-traking system where you can report errors that you have found
with MathJax in your environment.
.. _community-forums:
Forums
======
If you want to discuss MathJax development, or if you need help, or if
you have solutions you want to share, our `forums at SourceForge
<http://sourceforge.net/projects/mathjax/forums>`_ give you that
opportunity. We try hard to answer questions quickly, and users can
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.
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 forums.
.. _community-tracker:
Issue tracking
==============
Have you found a bug or want to suggest an improvement? Post it to
our `bug tracker
<http://sourceforge.net/tracker/?group_id=261188&atid=1240827>`_. We
monitor the bug tracker closely, and work hard to respond to problems
quickly.
Before you create a new ticket, however, please `search the forums
<http://sourceforge.net/search/?group_id=261188&type_of_search=forums>`_
and `existing tickets
<http://sourceforge.net/search/?group_id=261188&type_of_search=artifact>`_
first 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-svn>` to verify that the
problem persists in the lastest 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>`_.

View file

@ -0,0 +1,375 @@
.. _loading:
*******************************
Loading and Configuring MathJax
*******************************
You load MathJax into a web page by including its main JavaScript file
into the page. That is done via a ``<script>`` tag that links to the
``MathJax.js`` file. Place the following line in the ``<head>``
section of your document:
.. code-block:: html
<script type="text/javascript" src="path-to-MathJax/MathJax.js"></script>
where ``path-to-MathJax`` is replaced by the URL of the MathJax
directory on your server, or (if you are using MathJax locally rather
than through a server) the location of that directory on your hard
disk. For example, if the MathJax directory is at the top level of
your web server's directory hierarchy, you might use
.. code-block:: html
<script type="text/javascript" src="/MathJax/MathJax.js"></script>
to load MathJax.
Although it is possible to load MathJax from a site other than your
own web server, there are issues involved in doing so that you need to
take into consideration. See the :ref:`Notes About Shared Servers
<cross-domain-linking>` for more details. Please do **not** link to
the copy of MathJax at ``www.mathjax.org``, as we do not have the
resources to act as a web service for all the sites on the web that
would like to display mathematics. If you are able to run MathJax
from your own server, please do so (this will probably give you better
response time in any case).
It is best to load MathJax in the document's ``<head>`` block, but it
is also possible to load MathJax into the ``<body>`` section, if
needed. If you do this, load it as early as possible, as
MathJax will begin to load its components as soon as it is included in
the page, and that will help speed up the processing of the
mathematics on your page. MathJax does expect there to be a
``<head>`` section to the document, however, so be sure there is one
if you are loading MathJax in the ``<body>``.
It is also possible to load MathJax dynamically after the page has
been prepared, for example, via a `GreaseMonkey
<http://www.greasespot.net/>`_ script, or using a specially prepared
`bookmarklet <http://en.wikipedia.org/wiki/Bookmarklet>`_. This is an
advanced topic, however; see :ref:`Loading MathJax Dynamically
<ajax-mathjax>` for more details.
Configuring MathJax
===================
There are several ways to configure MathJax, but the easiest is to use
the ``config/MathJax.js`` file that comes with MathJax. See the
comments in that file, or the :ref:`configuration details
<configuration>` section, for explanations of the meanings of the various
configuration options. You can edit the ``config/MathJax.js`` file to
change any of the settings that you want to customize. When you
include MathJax in your page via
.. code-block:: html
<script type="text/javascript" src="path-to-MathJax/MathJax.js"></script>
it will load ``config/MathJax.js`` automatically as one of its
first actions.
Alternatively, you can configure MathJax efficiently by calling
:meth:`MathJax.Hub.Config()` when you include MathJax in your page, as
follows:
.. code-block:: html
<script type="text/javascript" src="path-to-MathJax/MathJax.js">
MathJax.Hub.Config({
extensions: ["tex2jax.js"],
jax: ["input/TeX", "output/HTML-CSS"],
tex2jax: {
inlineMath: [ ['$','$'], ["\\(","\\)"] ],
displayMath: [ ['$$','$$'], ["\\[","\\]"] ],
},
"HTML-CSS": { availableFonts: ["TeX"] }
});
</script>
This example includes the ``tex2jax`` preprocessor and configures it
to use both the standard TeX and LaTeX math delimiters. It uses the
TeX input processor and the HTML-CSS output processor, and forces the
HTML-CSS processor to use the TeX fonts rather that other locally
installed fonts (e.g., :term:`STIX` fonts). See the
:ref:`configuration options <configuration>` section (or the comments
in the ``config/MathJax.js`` file) for more information about the
configuration options that you can include in the
:meth:`MathJax.Hub.Config()` call. Note that if you configure MathJax
using this in-line approach, the ``config/MathJax.js`` file is **not**
loaded.
Finally, if you would like to use several different configuration
files (like ``config/MathJax.js``, but with different settings in each
one), you can copy ``config/MathJax.js`` to ``config/MathJax-2.js``,
or some other convenient name, and use
.. code-block:: html
<script type="text/javascript" src="path-to-MathJax/MathJax.js">
MathJax.Hub.Config({ config: "MathJax-2.js" });
</script>
to load the alternative configuration file ``config/MathJax-2.js``
from the MathJax ``config`` directory. In this way, you can have as
many distinct configuration files as you need.
.. _common-configurations:
Common Configurations
=====================
The following examples show configurations that are useful for some
common situations. This is certainly not an exhaustive list, and
there are variations possible for any of them. Again, the comments in
the ``config/MathJax.js`` file can help you decide what settings to
include, even if you are using the in-line configuration method.
The TeX setup
-------------
This example calls the ``tex2jax`` preprocessor to identify
mathematics in the page by looking for TeX and LaTeX math delimiters.
It uses ``$...$`` and ``\(...\)`` for in-line mathematics, while
``$$...$$`` and ``\[...\]`` mark displayed equations. Because dollar
signs are used to mark mathematics, if you want to produce an actual
dollar sign in your document, you must "escape" it using a slash:
``\$``. This configuration also loads the ``AMSmath`` and
``AMSsymbols`` extensions so that the macros and environments they
provide are defined for use on the page.
.. code-block:: javascript
MathJax.Hub.config({
extensions: ["tex2jax.js","TeX/AMSmath.js","TeX/AMSsymbols.js"],
jax: ["input/TeX","output/HTML-CSS"],
tex2jax: {
inlineMath: [['$','$'],["\\(","\\)"]],
processEscapes: true,
},
});
Other extensions that you may consider adding to the `extensions`
array include: ``TeX/noErrors.js``, which shows the original TeX code
if an error occurs while processing the mathematics (rather than an
error message), ``TeX/noUndefined.js``, which shows undefined
macros names in red (rather than producing an error), and
``TeX/autobold.js``, which automatically inserts ``\boldsymbol{...}``
around your mathematics when it appears in a section of your page that
is in bold. Most of the other TeX extensions are loaded automatically
when needed, and so do not need to be included explicitly in your
`extensions` array.
See the :ref:`tex2jax configuration <configure-tex2jax>` section for
other configuration options for the ``tex2jax`` preprocessor, and the
:ref:`TeX input jax configuration <configure-TeX>` section for options
that control the TeX input processor.
The MathML setup
----------------
This example calls the ``mml2jax`` preprocessor to identify
mathematics in the page that is in :term:`MathML` format, which uses
``<math display="block">`` to indicate displayed equations, and
``<math display="inline">`` or simply ``<math>`` to mark in-line
formulas.
.. code-block:: javascript
MathJax.Hub.config({
extensions: ["mml2jax.js"],
jax: ["input/MathML","output/HTML-CSS"]
});
Note that this will work in HTML files, not just XHTML files (MathJax
works with both), and that the web page need not be served with any
special MIME-type. Also note that, unless you are using XHTML rather
than HTML, you should not include a namespace prefix for your
``<math>`` tags; for example, you should not use ``<m:math>`` except
in a file where you have tied the ``m`` namespace to the MathML DTD.
See the :ref:`mml2jax configuration <configure-mml2jax>` section for
other configuration options for the ``mml2jax`` preprocessor, and the
:ref:`MathML input jax configuration <configure-MathML>` section for
options that control the MathML input processor.
Both TeX and MathML
-------------------
This example provides for both TeX and MathML input in the same file.
It calls on both the ``tex2jax`` and ``mml2jax`` preprocessors and the
TeX and MathML input jax to do the job.
.. code-block:: javascript
MathJax.Hub.config({
extensions: ["tex2jax.js", "mml2jax.js"],
jax: ["input/TeX", "input/MathML", "output/HTML-CSS"],
});
Notice that no ``tex2jax`` configuration section is included, so it
uses its default options (no single dollar signs for in-line math).
The majority of the code for the TeX and MathML input processors are
not loaded until they are actually needed by the mathematics on the
page, so if this configuration is used on a page that include only
MathML, the TeX input processor will not be loaded. Thus it is
reasonably efficient to specify both input processors even if only one
(or neither one) is used.
TeX input with MathML output
----------------------------
This example configures MathJax to use the ``tex2jax`` preprocessor
and TeX input processor, but the choice of output format is determined
by MathJax depending on the capabilities of the users's browser. The
is performed by the ``MMLorHTML.js`` configuration file that is loaded
in the `config`` array.
.. code-block:: javascript
MathJax.Hub.Config({
config: ["MMLorHTML.js"],
extensions: ["tex2jax.js"],
jax: ["input/TeX"]
});
With this setup, Firefox or Internet Explorer with the `MathPlayer
plugin <http://www.dessci.com/en/products/mathplayer/>`_ installed
will use the NativeMML output processor, while all other browsers will
use the HTML-CSS output processor. Since native MathML support is
faster than MathJax's HTML-CSS processor, this will mean that the web
pages will display faster for Firefox and IE than they woudl
otherwise. This speed comes at the cost, however, as you are now
relying on the native MathML support to render the mathematics, and
that is outside of MathJax's control. There may be spacing or other
display differences (compared to MathJax's HTML-CSS output) when the
NativeMML output processor is used.
See :ref:`MathJax Output Formats <output-formats>` for more
information on the NativeMML and HTML-CSS output processors. See the
:ref:`MMLorHTML configuration <configure-MMLorHTML>` section for
details on the options that control the ``MMLorHTML`` configuration.
MathML input and output in all browsers
---------------------------------------
This example configures MathJax to look for MathML within your page,
and to display it using the browser's native MathML support, if
possible, or its HTML-CSS output if not.
.. code-block:: javascript
MathJax.Hub.Config({
config: ["MMLorHTML.js"],
extensions: ["mml2jax.js"],
jax: ["input/MathML"]
});
Using this configuration, MathJax finally makes MathML available in
all modern browsers.
See the :ref:`MMLorHTML configuration <configure-MMLorHTML>` section
for details on the options that control the ``MMLorHTML``
configuration file, the :ref:`MathML configuration <configure-MathML>`
section for the options that control the MathML output processor, and
the :ref:`mml2jax configuration <configure-mml2jax>` section for the
options that control the ``mml2jax`` preprocessor.
.. _configuration:
Configuration Objects
=====================
The various components of MathJax, including its input and output
processors, its preprocessors, its extensions, and the MathJax core,
all can be configured through the ``config/MathJax.js`` file, or via a
:meth:`MathJax.Hub.Config()` call (indeed, if you look closely, you
will see that ``config/MathJax.js`` is itself one big call to
:meth:`MathJax.Hub.Config()`). Anything that is in
``config/MathJax.js`` can be included in-line to configure MathJax.
The structure that you pass to :meth:`MathJax.Hub.Config()` is a
JavaScript object that includes name-value pairs giving the names of
parameters and their values, with pairs separated by commas. Be
careful not to include a comma after the last value, however, as some
browsers (namely Internet Explorer) will fail to process the
configuration if you do.
The MathJax components, like the TeX input processor, have their own
sections in the configuration object, labeled by the component name,
and using an configuration object as its value. The object is itself
a configuration object made up of name-value pairs that give the
configuration options for the component.
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 configration that includes two settings for the MathJax Hub (one
for `showProcessingMessages` and one of the `jax` array), and a
configuration object for the TeX input processor. The latter includes
a setting for the TeX input processor's `TagSide` option (to set tags
on the left rather than the right) and a setting for `Macros`, which
defines new TeX macros (in this case, two macros, one called ``\RR``
that produces a bold "R", and one called ``\bold`` that puts is
argument in bold face).
The ``config/MathJax.js`` file is another example that shows nearly
all the configuration options for all of MathJax's components.
Configuration Options by Component
==================================
The individual options are explained in the following sections, which
are categorized by the component they affect.
.. toctree::
:maxdepth: 1
The core options <options/hub>
.. toctree::
:maxdepth: 1
The tex2jax preprocessor options <options/tex2jax>
The mml2jax preprocessor options <options/mml2jax>
The jsMath2jax preprocessor options <options/jsMath2jax>
.. toctree::
:maxdepth: 1
The TeX input processor options <options/TeX>
The MathML input processor options <options/MathML>
The HTML-CSS output processor options <options/HTML-CSS>
The NativeMML output processor options <options/NativeMML>
The MMLorHTML configuration options <options/MMLorHTML>
.. toctree::
:maxdepth: 1
The MathMenu options <options/MathMenu>
The MathZoom options <options/MathZoom>
The FontWarnings options <options/FontWarnings>

View file

@ -0,0 +1,181 @@
.. _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`` 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 so MathJax will not be able to tell if it is
safe for it to process the contents of the page. Indeed, it will wait
forever for its ``onload`` handler to fire, and so will never process
the page.
To solve this problem, you will need to call MathJax's ``onload``
handler yourself, to let it know that it is OK to typeset the
mathematics on the page. You accomplish this by calling the
:meth:`MathJax.Hub.Startup.onload()` method as part of your MathJax
startup script. To do this, you will need to give MathJax an in-line
configuration, so you will not be able to use the
``config/MathJax.js`` file (though you can add it to your in-line
configuration's `config` array).
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 = "/MathJax/MathJax.js"; // use the location of your MathJax
var config = 'MathJax.Hub.Config({' +
'extensions: ["tex2jax.js"],' +
'jax: ["input/TeX","output/HTML-CSS"]' +
'});' +
'MathJax.Hub.Startup.onload();';
if (window.opera) {script.innerHTML = config}
else {script.text = config}
document.getElementsByTagName("head")[0].appendChild(script);
})();
Be sure to set the ``src`` to the correct URL for your copy of
MathJax. You can adjust the ``config`` variable to your needs, but be
careful to get the commas right. The ``window.opera`` test is because
Opera doesn't handle setting ``script.text`` properly, while Internet
Explorer doesn't handle setting the ``innerHTML`` of a script tag.
Here is a version that uses the ``config/MathJax.js`` file to
configure MathJax:
.. code-block:: javascript
(function () {
var script = document.createElement("script");
script.type = "text/javascript";
script.src = "/MathJax/MathJax.js"; // use the location of your MathJax
var config = 'MathJax.Hub.Config({ config: "MathJax.js" }); ' +
'MathJax.Hub.Startup.onload();';
if (window.opera) {script.innerHTML = config}
else {script.text = config}
document.getElementsByTagName("head")[0].appendChild(script);
})();
Note that the **only** reliable way to configure MathJax is to use an
in-line configuration 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. In the scripts below, you need to insert the URL
of a copy of MathJax from your own server.
----
Here is a script that runs MathJax in any document that contains
MathML (whether its 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 Forefox 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.src = "http://www.yoursite.edu/MathJax/MathJax.js"; // put your URL here
var config = 'MathJax.Hub.Config({' +
'extensions:["mml2jax.js"],' +
'jax:["input/MathML","output/HTML-CSS"]' +
'});' +
'MathJax.Hub.Startup.onload()';
if (window.opera) {script.innerHTML = config} else {script.text = config}
document.getElementsByTagName("head")[0].appendChild(script);
}
}
**Source**: `mathjax_mathml.user.js <_statis/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');
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);
}
}
//
// Load MathJax and have it process the page
//
var script = document.createElement("script");
script.src = "http://www.yoursite.edu/MathJax/MathJax.js"; // put your URL here
var config = 'MathJax.Hub.Config({' +
'config: ["MMLorHTML.js"],' +
'extensions:["TeX/noErrors.js","TeX/noUndefined.js",' +
'"TeX/AMSmath.js","TeX/AMSsymbols.js"],' +
'jax:["input/TeX"]' +
'});' +
'MathJax.Hub.Startup.onload()';
if (window.opera) {script.innerHTML = config} else {script.text = config}
document.getElementsByTagName("head")[0].appendChild(script);
}
**Source**: `mathjax_wikipedia.user.js <_statis/mathjax_wikipedia.user.js>`_

View file

@ -0,0 +1,75 @@
.. _glossary:
********
Glossary
********
.. if you add new entries, keep the alphabetical sorting!
.. glossary::
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 employs 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>`_
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/>`_
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>`_

View file

@ -0,0 +1,71 @@
#####################
MathJax Documentation
#####################
MathJax is an open-source JavaScript display engine for LaTeX and
MathML 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>
Using MathJax in Web Platforms <platforms/index>
.. toctree::
:maxdepth: 1
MathJax TeX and LaTeX Support <tex>
MathJax MathML Support <mathml>
MathJax Output Formats <output>
.. toctree::
:maxdepth: 1
The MathJax Community <community>
.. _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>
.. toctree::
:maxdepth: 1
Converting to MathJax from jsMath <jsMath>
Reference Pages
===============
.. toctree::
:maxdepth: 1
HTML snippets <HTML-snippets>
CSS style objects <CSS-styles>
Glossary <glossary>
* :ref:`Search <search>`
--------
This version of the documentation was built |today|.

View file

@ -0,0 +1,184 @@
.. _installation:
******************************
Installing and Testing MathJax
******************************
MathJax can be loaded from a public web server or privately from your
hard drive or other local media. To use MathJax in either way, you
will need to obtain a copy of MathJax and its font package. There are
two main ways to do this: via ``svn`` or via a pre-packaged archive.
We recommend the former, as it is easier to keep your installation up
to date using ``svn``.
.. _getting-mathjax-svn:
Obtaining MathJax via SVN
=========================
The easiest way to get MathJax and keep it up to date is to use the
`subversion <http://subversion.apache.org/>`_ source control system,
``svn``. Use the commands
.. code-block:: sh
svn co http://mathjax.svn.sourceforge.net/svnroot/mathjax/trunk/mathjax mathjax
cd mathjax
unzip fonts.zip
to obtain and set up a copy of MathJax. (The `SourceForge development
page <http://sourceforge.net/projects/mathjax/develop>`_ also shows
how to do this.)
Whenever you want to update MathJax, you can now use
.. code-block:: sh
cd mathjax
svn status
to check if there are updates to MathJax. If MathJax needs updating,
use
.. code-block:: sh
cd mathjax
svn update
# if fonts.zip is updated, do the following as well:
rm -rf fonts
unzip fonts.zip
to udpate your copy of MathJax to the current release version. If the
``fonts.zip`` file has been updated, you will need to remove the old
fonts directory and unpack the new one bring your installation up to
date. If you keep MathJax updated in this way, you will be sure that
you have the latest bug fixes and new features as they become
available.
This gets you the current development copy of MathJax, which is the
"bleeding-edge" version that contains all the latest changes to
MathJax. At times, however, these may be less stable than the
"release" version. If you prefer to use the most stable version (that
may not include all the latest patches and features), use
.. code-block:: sh
svn co http://mathjax.svn.sourcesforge.net/svnroot/mathjax/tags/mathjax-1.0 mathajx
cd mathjax
unzip fonts.zip
to obtain the version 1.0 release. When you wish to update to a new
release, you will need to check out a new copy of MathJax with the new
release number.
.. _getting-mathjax-zip:
Obtaining MathJax via an archive
================================
Release versions of MathJax are available in archive files from the
`MathJax download page <http://www.mathjax.org/download/>`_ or the
`SourceForge files page
<http://sourceforge.net/projects/mathjax/files/>`_, where you can
download the archives that you need.
You should download the ``MathJax-v1.0.zip`` file, then simply unzip
it. Once the MathJax directory is unpacked, you should move it to the
desired location on your server (or your hard disk, if you are using
it locally rather then through a web server). One natural location is
to put it at the top level of your web server's hierarchy. That would
let you refer to the main MathJax file as ``/MathJax/MathJax.js`` from
within any page on your server.
Testing your installation
=========================
Use the HTML files in the ``test`` directory to see if your
installation is working properly::
test/
index.html # Tests default configuration
index-images.html # Tests image-font fallback display
sample.html # Sample page with lots of pretty equations
Open these files in your browser to see that they appear to be working
properly. If you have installed MathJax on a server, use the web
address for those files rather than opening them locally. When you
view the ``index.html`` file, you should see (after a few moments) a
message that MathJax appears to be working. If not, you should check
that the files have been transferred to the server completely, that
the fonts archive has been unpacked in the correct location, and that
the permissions allow the server to access the files and folders that
are part of the MathJax directory (be sure to verify the MathJax
folder's permissions as well). Checking the server logs may help
locate problems with the installation.
.. _cross-domain-linking:
Notes about shared installations
================================
Typically, you want to have MathJax installed on the same server as
your web pages that use MathJax. There are times, however, when that
may be impractical, or when you want to use a MathJax installation at
a different site. For example, a departmental server at
``www.math.yourcollege.edu`` might like to use a college-wide
installation at ``www.yourcollege.edu`` rather than installing a
separate copy on the departmental machine. MathJax can certainly
be loaded from another server, but there is one imporant caveat ---
Firefox's same-origin security policy for cross-domain scripting.
Firefoxs interpretation of the same-origin policy is more strict than
most other browsers, and it affects how fonts are loaded with the
`@font-face` CSS directive. MathJax uses this directory to load
web-based math fonts into a page when the user doesn't have them
installed locally on their own computer. Firefox's security policy,
however, only allows this when the fonts come from the same server as
the web page itself, so if you load MathJax (and hence its web fonts)
from a different server, Firefox won't be able to access those web
fonts. In this case, MathJax will pause while waiting for the font to
download (which will never happen) and will time out after about 15
seconds for each font it tries to access. Typically that is three or
four fonts, so your Foirefox users will experience a minute or so
delay before mathematics is displayed, and then it will probably
display incorrectly because the browser doesn't have access to the
correct fonts.
There is a solution to this, however, if you manage the server where
MathJax is installed, and if that server is running the `Apache web
server <http://www.apache.org/>`_. In the remote server's
``MathJax/fonts/HTML-CSS/TeX/otf`` folder, create a file called
``.htaccess`` that contains the following lines: ::
<FilesMatch "\.(ttf|otf|eot)$">
<IfModule mod_headers.c>
Header set Access-Control-Allow-Origin "*"
</IfModule>
</FilesMatch>
and make sure the permissions allow the server to read this file.
(The file's name starts with a period, which causes it to be an
"invisible" file on unix-based operating systems. Some systems,
particularly graphic user interfaces, may not allow you to create such
files, so you might need to use the command-line interface to
accomplish this.)
This file should make it possible for pages at other sites to load
MathJax from this server in such a way that Firefox will be able to
download the web-based fonts. If you want to restrict the sites that
can access the web fonts, change the ``Access-Control-Allow-Origin``
line to something like::
Header set Access-Control-Allow-Origin "http://www.math.yourcollege.edu"
so that only pages at ``www.math.yourcollege.edu`` will be able to
download the fonts from this site. See the open font library
discussion of `web-font linking
<http://openfontlibrary.org/wiki/Web_Font_linking_and_Cross-Origin_Resource_Sharing>`_
for more details.

View file

@ -0,0 +1,31 @@
.. _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:`Configuring MathJax
<configuration>` for details about loading and configuring MathJax.
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"``.
.. code-block:: javascript
extensions: ["jsMath2jax.js"],
jax: ["input/TeX", ...]
There are a few configuration options for ``jsMath2jax``, which you
can find in the ``config/MathJax.js`` file, or in the :ref:`jsMath
configuration options <configure-jsMath2jax>` section.

View file

@ -0,0 +1,36 @@
****************
What is MathJax?
****************
MathJax is an open-source JavaScript display engine for LaTeX and
MathML 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 downlaod 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, or `MathML <http://www.w3.org/TR/MathML3>`_, a World Wide
Web Constortium standard for representing mathematics in XML format.
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 past 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.

View file

@ -0,0 +1,97 @@
.. _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` reprocessor 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, 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 the copy
the source markup, and so on, so there is added value to using MathJax
even whith a pure MathML workflow.
MathML in HTML pages
====================
For MathML that is handled via the pre-processor, you should not use
the named MathML entities, but rather use the 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
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.
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``.
- Limited support for line breaking (they are only allowed in direct
children of ``mrow`` or implied ``mrow`` elements.
- No support for alignment groups in table.
- No support for right-to-left rendering.
See the `results of the MathML3.0 test suite
<http://www.w3.org/Math/testsuite/results/tests.html>`_ for details.

View file

@ -0,0 +1,224 @@
****************************
The MathJax Processing Model
****************************
The purpose of MathJax is to bring the ability to include mathematics
easily in web pages to as wide a range of browsers as possible.
Authors can specify mathematics in a variety of formats (e.g.,
:term:`MathML` or :term:`LaTeX`), and MathJax provides high-quality
mathematical typesetting even in those browsers that do not have
native MathML support. This all happens without the need for special
downloads or plugins, but rendering will be enhanced if high-quality
math fonts (e.g., :term:`STIX`) are available to the browser.
MathJax is broken into several different kinds of components: page
preprocessors, input processors, output processors, and the MathJax
Hub that organizes and connects the others. The input and output
processors are called :term:`jax`, and are described in more detail
below.
When MathJax runs, it looks through the page for special tags that
hold mathematics; for each such tag, it locates an appropriate input
jax which it uses to convert the mathematics into an internal form
(called an element jax), and then calls an output jax to transform the
internal format into HTML content that displays the mathematics within
the page. The page author configures MathJax by indicating which
input and output jax are to be used.
Often, and especially with pages that are authored by hand, the
mathematics is not stored (initially) within the special tags needed
by MathJax, as that would require more notation than the average page
author is willing to type. Instead, it is entered in a form that is
more natural to the page author, for example, using the standard TeX
math delimiters ``$...$`` and ``$$...$$`` to indicate what part of the
document is to be typeset as mathematics. In this case, MathJax can
run a preprocessor to locate the math delimiters and replace them by
the special tags that it uses to mark the formulas. There are
preprocessors for :ref:`TeX notation <TeX-support>`, :ref:`MathML
notation <MathML-support>`, and the :ref:`jsMath notation
<jsMath-support>` that uses `span` and `div` tags.
For pages that are constructed programatically, such as HTML
pages that result from running a processor on text in some other
format (e.g., pages produced from Markdown documents, or via programs
like `tex4ht`), it would be best to use MathJax's special tags
directly, as described below, rather than having MathJax run
another preprocessor. This will speed up the final display of the
mathematics, since the extra preprocessing step would not be needed,
and it also avoids the conflict between the use of the less-than sign,
``<``, in mathematics and asn an HTML special character (that starts
an HTML tag).
How mathematics is stored in the page
=====================================
In order to identify mathematics in the page, MathJax uses special
``<script>`` tags to enclose the mathematics. This is done because
such tags can be located easily, and because their content is not
further processed by the browser; for example, less-than signs can be
used as they are in mathematics, without worrying about them being
mistaken for the beginnings of HTML tags. One may also consider the
math notation as a form of "script" for the mathematics, so a
``<script>`` tag makes at least some sense for storing the math.
Each ``<script>`` tag has a ``type`` attribute that identifies the
kind of script that the tag contains. The usual (and default) value
is ``type="text/javascript"``, and when a script has this type, the
browser executes the script as a javascript program. MathJax,
however, uses the type `math/tex` to identify mathematics in the TeX
and LaTeX notation, and `math/mml` for mathematics in MathML
notation. When the `tex2jax` or `mml2jax` preprocessors run, they
create ``<script>`` tags with these types so that MathJax can process
them when it runs its main typesetting pass.
For example,
.. code-block:: html
<script type="math/tex">x+\sqrt{1-x^2}</script>
represents an in-line equation in TeX notation, and
.. code-block:: html
<script type="math/tex; mode=display">
\sum_{n=1}^\infty {1\over n^2} = {\pi^2\over 6}
</script>
is a displayed TeX equation.
Alternatively, using MathML notation, you could use
.. code-block:: html
<script type="math/mml">
<math>
<mi>x</mi>
<mo>+</mo>
<msqrt>
<mn>1</mn>
<mo>&#x2212;<!-- --></mo>
<msup>
<mi>x</mi>
<mn>2</mn>
</msup>
</msqrt>
</math>
</script>
for in-line math, or
.. code-block:: html
<script type="math/mml">
<math display="block">
<mrow>
<munderover>
<mo>&#x2211;<!-- ∑ --></mo>
<mrow>
<mi>n</mi>
<mo>=</mo>
<mn>1</mn>
</mrow>
<mi mathvariant="normal">&#x221E;<!-- ∞ --></mi>
</munderover>
</mrow>
<mrow>
<mfrac>
<mn>1</mn>
<msup>
<mi>n</mi>
<mn>2</mn>
</msup>
</mfrac>
</mrow>
<mo>=</mo>
<mrow>
<mfrac>
<msup>
<mi>&#x03C0;<!-- π --></mi>
<mn>2</mn>
</msup>
<mn>6</mn>
</mfrac>
</mrow>
</math>
</script>
for displayed equations in MathML notation.
As other input jax are created, they will use other types to identify
the mathematics they can process.
Page authors can use one of MathJax's preprocessors to convert from
math delimiters that are more natural for the author to type (e.g.,
TeX math delimiters like ``$$...$$``) to MathJax's ``<script>``
format. Blog and wiki software could extend from their own markup
languages to include math delimiters, which they could convert to
MathJax's ``<script>`` format automatically.
Note, however, that Internet Explorer has a bug that causes it to
remove the space before a ``<script>`` tag if there is also a space
after it, which can cause serious spacing problems with in-line math
in Internet Explorer. There are three possible solutions to this in
MathJax. The recommended way is to use a math preview (an element
with class ``MathJax_Preview``) that is non-empty and comes right
before the ``<script>`` tag. Its contents can be just the word
``[math]``, so it does not have to be specific to the mathematics
script that follows; it just has to be non-empty (though it could have
its style set to ``display:none``). See also the ``preJax`` and
``postJax`` options in the :ref:`Core Configuration Options
<configure-hub>` document for another approach.
The components of MathJax
=========================
The main components of MathJax are its preprocessors, its input and
output jax, and the MathJax Hub, which coordinates the actions of the
other components.
**Input jax** are associated with the different script types (like
:mimetype:`math/tex` or :mimetype:`math/mml`) and the mapping of a
particular type to a particular jax is made when the various jax
register their abilities with the MathJax Hub at configuration time.
For example, the MathML input jax registers the :mimetype:`math/mml`
type, so MathJax will know to call the MathML input jax when it sees
math elements of that type. The role of the input jax is to convert
the math notation entered by the author into the internal format used
by MathJax (called an `element jax`). This internal format is
essentially MathML (represented as JavaScript objects), so an input
jax acts as a translator into MathML.
**Output jax** convert that internal element jax format into a specific
output format. For example, the NativeMML output jax inserts MathML
tags into the page to represent the mathematics, while the HTML-CSS
output jax uses HTML with CSS styling to lay out the mathematics so
that it can be displayed even in browsers that dont understand
MathML. Output jax could be produced that render the mathematics
using SVG, for example, or that speak an equation for the blind
users. The MathJax contextual menu can be used to switch between the
output jax that are available.
Each input and output jax has a small configuration file that is
loaded when that input jax is included in the `jax` array in the
MathJax configuration, and a larger file that implements the core
functionality of that particular jax. The latter file is loaded
when the first time the jax is needed by MathJax to process some
mathematics.
The **MathJax Hub** keeps track of the internal representations of the
various mathematical equations on the page, and can be queried to
obtain information about those equations. For example, one can obtain
a list of all the math elements on the page, or look up a particular
one, or find all the elements with a given input format, and so on.
In a dynamically generated web page, an equation where the source
mathematics has changed can be asked to re-render itself, or if a new
paragraph is generated that might include mathematics, MathJax can be
asked to process the equations it contains.
The Hub also manages issues concerning mouse events and other user
interaction with the equation itself. Parts of equations can be made
active so that mouse clicks cause event handlers to run, or activate
hyperlinks to other pages, and so on, making the mathematics as
dynamic as the rest of the page.

View file

@ -0,0 +1,140 @@
.. _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 in
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 called in
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.
.. 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.
.. describe:: fadeoutTime: 1.5*1000
This is the time used to perform the fade-out, in milliseconds.
The default is 1.5 seconds.

View file

@ -0,0 +1,119 @@
.. _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. 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 en-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:: 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 stores
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:: 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 controls whether the MathJax contextual menu will be
available on the mathematics in the page. If true, then
right-clicking (on the PC) or control-clicking (on the Mac) will
produce a MathJax menu that allows you to get the source of the
mathematics in various formats, change the size of the mathematics
relative to the surrounding text, get information about
MathJax, and configure other MathJax settings.
Set this to ``false`` to disable the menu. When ``true``, the
``MathMenu`` configuration block determines the operation of the
menu. See :ref:`the MathMenu options <configure-MathMenu>` 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 and offsetY: 5
These are the offset from the mouse position (in pixels)
where the tooltip will be placed.

View file

@ -0,0 +1,42 @@
.. _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. 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 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: "MML", 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 does process some MathML
natively, its support is not sufficient to handle the more
complicated output generated by MathJax, so its setting is
``"HTML"`` by default.

View file

@ -0,0 +1,27 @@
.. _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. 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.

View file

@ -0,0 +1,79 @@
.. _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: 400
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 the "Settings" submenu of the mathematics contextual menu. It
allows the user to change between the `HTML-CSS` and `NativeMML`
output processors for the mathematics on the page. 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 the "Settings" submenu of the mathematics contextual menu.
It allows the user to decide whether the MathJax menu or the
browser's default contextual manu will be shown when the context
menu click occurs over mathematics typeset by MathJax. (The main
reason to allow pass-through to the browser's menu is to gain
access to the MathPlayer contextual menu when the NativeMML output
processor is used in Internet Explorer with the `MathPlayer plugin
<http://www.dessci.com/en/products/mathplayer/>`_.) 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 the "Settings" submenu of the mathematics 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:: 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.

View file

@ -0,0 +1,42 @@
.. _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: {
delay: 600
}
});
would set the ``delay`` option to 600 milliseconds.
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).
.. describe:: delay: 400
This the time (in milliseconds) that the mouse must be still over a
typeset mathematical formula before the zoomed version is displayed
(when the zoom trigger is set to `Hover`).
.. 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.

Some files were not shown because too many files have changed in this diff Show more