Removed most of the README content, which is now in the docs folder in HTML format
This commit is contained in:
dpvc
parent
44120ba21a
commit
e3f1386abb
|
|
@ -1,9 +1,15 @@
|
|||
OVERVIEW:
|
||||
|
||||
MathJax (TM) is an open source, Ajax-based math display solution designed
|
||||
with a goal of consolidating advances in many web technologies in a
|
||||
single definitive math-on-the-web platform supporting all major
|
||||
browsers.
|
||||
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:
|
||||
|
||||
|
|
@ -22,445 +28,14 @@ Some of the main features of MathJax include:
|
|||
See http://www.mathjax.org/ for additional details.
|
||||
|
||||
|
||||
INSTALLATION:
|
||||
INSTALLATION AND USAGE:
|
||||
|
||||
MathJax can be used on a web server to support mathematics in your
|
||||
public web pages, or it can be used locally from your hard disk for
|
||||
your private pages. To use MathJax in either way, you will need to
|
||||
obtain a copy of MathJax (see below) and its font package. These two
|
||||
are separate pieces because the fonts are not likely to change often,
|
||||
while the main code will be updated fairly regularly.
|
||||
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
|
||||
|
||||
Obtaining MathJax from SourceForge via SVN:
|
||||
|
||||
The easiest way to obtain MathJax and keep it up-to-date is to use the
|
||||
subversion program (svn) to check it out from the MathJax project at
|
||||
SourceForge.net. The page
|
||||
|
||||
http://sourceforge.net/projects/mathjax/develop
|
||||
|
||||
lists the command you need to use to obtain a copy of MathJax via svn.
|
||||
Once you have checked out a version of MathJax, you will find that it
|
||||
includes a file called "fonts.zip" in the top-level directory. You
|
||||
will need to unpack that file in order to complete the installation of
|
||||
MathJax. It will create a fonts directory that contains the web fonts
|
||||
and images fonts used by MathJax to support users who do not have math
|
||||
fonts installed on their computers. Once you have checked out
|
||||
MathJax, you will need to move the MathJax directory to your web
|
||||
server in a location that is convenient for your use.
|
||||
|
||||
Obtaining MathJax from SourceForge as an archive file:
|
||||
|
||||
You can obtain MathJax from the MathJax project at SourceForge via
|
||||
the link
|
||||
|
||||
http://sourceforge.net/projects/mathjax/files/
|
||||
|
||||
where you will need to download a copy of the MathJax ZIP file (for
|
||||
the current version) and the MathJax-webfonts ZIP file. Unpack the
|
||||
MathJax ZIP file first, and then unpack the MathJax-webfonts ZIP file
|
||||
into that. That should produce a fonts directory in the MathJax
|
||||
folder (and MathJax/fonts should contain an HTML-CSS directory). The
|
||||
fonts directory contains web fonts and image fonts used by MathJax to
|
||||
support users who do not have math fonts installed on their
|
||||
computers. Once you have unpacked both archives, you can move the
|
||||
MathJax directory to your web server in a location that is convenient
|
||||
for your use.
|
||||
|
||||
|
||||
TESTING MATHJAX:
|
||||
|
||||
Once you have MathJax installed, you can use the files in the
|
||||
MathJax/test directory to test that your installation is working
|
||||
properly. You can also use it to test if your version of MathJax
|
||||
needs updating. If you have checked out MathJax using subversion
|
||||
(svn), you can simply use "svn status" to see if your installation
|
||||
needs to be updated, and "svn update" to get any updates.
|
||||
|
||||
|
||||
USING MATHJAX IN A WEB PAGE:
|
||||
|
||||
To use MathJax in a web page, you need to load MathJax.js near the top of
|
||||
the document (preferably in the document HEAD). A SCRIPT tag like
|
||||
|
||||
<script type="text/javascript" src="/MathJax/MathJax.js"></script>
|
||||
|
||||
will do it if you have MathJax at the top level of your web server.
|
||||
When called in this form, MathJax can be configured through the file
|
||||
MathJax/config/MathJax.js, which contains the parameters that control
|
||||
MathJax. There are comments in this file that explain what each of
|
||||
the parameters does, so look there for details.
|
||||
|
||||
Alternatively, you can configure MathJax in-line within your web page
|
||||
(avoiding an extra file transfer). To do that, place the
|
||||
configuration information within the SCRIPT tag itself, as in the
|
||||
following example:
|
||||
|
||||
<script type="text/javascript" src="/MathJax/MathJax.js">
|
||||
MathJax.Hub.Config({
|
||||
extensions: ["tex2jax.js","TeX/noErrors.js"],
|
||||
jax: ["input/TeX","output/HTML-CSS"],
|
||||
tex2jax: {inlineMath: [['$','$'],["\\(","\\)"]]},
|
||||
"HTML-CSS": {availableFonts:["TeX"]}
|
||||
});
|
||||
</script>
|
||||
|
||||
which loads the tex2jax preprocessor and an extension that causes TeX
|
||||
errors to show the original TeX code rather than an error message,
|
||||
specifies the input and output jax (input format is TeX and output
|
||||
format is HTML/CSS), configures the tex2jax preprocessor to allow
|
||||
dollar signs to delimit inline-math as well as \(...\), and forces the
|
||||
HTML/CSS output to use the MathJax TeX fonts (in particular, the STIX
|
||||
fonts won't be used.)
|
||||
|
||||
If you configure MathJax in this fashion, the MathJax/config/MathJax.js
|
||||
file is not loaded, and your in-line configuration is used instead.
|
||||
Note that you can include any of the parameters from the
|
||||
config/MathJax.js file (and in fact any arbitrary JavaScript as well).
|
||||
|
||||
With the default configuration, MathJax runs the tex2jax preprocessor
|
||||
to look for TeX-style mathematics delimiters as a means of identifying
|
||||
the mathematics on the page. This uses \(...\) to mark in-line
|
||||
mathematics and \[...\] or $$...$$ for displayed mathematics. LaTeX
|
||||
environments can also mark mathematics, as in
|
||||
\begin{equation}...\end{equation}. Once the preprocessor runs,
|
||||
MathJax will typeset the mathematics on the page.
|
||||
|
||||
Note that there can not be HTML tags within the math delimiters (other
|
||||
than <BR>) as TeX-formatted math does not include HTML tags. Also,
|
||||
since the mathematics is initially given as text on the page, you need
|
||||
to be careful that your mathematics doesn't look like HTML tags to the
|
||||
browser (which parses the page before MathJax gets to see it). In
|
||||
particular, that means that you have to be careful about things like
|
||||
less-than and greater-than signs (<,>), and ampersands (&), which have
|
||||
special meaning to the browsers. For example,
|
||||
|
||||
... when $x<y$ we have ...
|
||||
|
||||
will cause a problem, because the brower will think "<y" is the
|
||||
beginning of a tag named "y" (even though there is no such tag in
|
||||
HTML). Usually, it is sufficient to simply put spaces around these
|
||||
symbols to cause the browser to avoid them, so
|
||||
|
||||
... when $x < y$ we have ...
|
||||
|
||||
should work. Alternatively, you can use the HTML entities <, >
|
||||
and & to encode these characters so that the browser will not
|
||||
interpret them, but MathJax will. E.g.,
|
||||
|
||||
... when $x < y$ we have ...
|
||||
|
||||
Finally, there are \lt and \gt macros defined to make it easier to
|
||||
enter < and > using TeX-like syntax:
|
||||
|
||||
... when $x \lt y$ we have ...
|
||||
|
||||
Keep in mind that the browser interprets your text before MathJax
|
||||
does.
|
||||
|
||||
|
||||
MATHJAX WITH NO PREPROCESSOR:
|
||||
|
||||
The usual way to use MathJax is with the tex2jax preprocessor, but if
|
||||
you are generating web pages via some other preprocessor of your own,
|
||||
you may wish to bypass the tex2math preprocessing and mark the
|
||||
mathematics in your page directly. This avoids an extra file
|
||||
transfer, the time involed in running the tex2jax preprocessor, and
|
||||
the issues involving less-than, greater-than, and ampersand discussed
|
||||
in the section above.
|
||||
|
||||
When MathJax processes a page, it looks for mathematics stored in
|
||||
special SCRIPT tags. These are
|
||||
|
||||
<script type="math/tex">...</script>
|
||||
|
||||
for in-line math, and
|
||||
|
||||
<script type="math/tex; mode=display">...</script>
|
||||
|
||||
for displayed math, where the contents of the SCRIPT tags are TeX or
|
||||
LaTeX mathematics. Since SCRIPT tags can include less-than,
|
||||
greater-than, and ampersand characters, this neatly avoids the problem
|
||||
that these cause when you use the tex2jax preprocessor.
|
||||
|
||||
Unfortunately, this method introduces a problem of its own, due to a
|
||||
bug in Internet Explorer. The problem is that IE incorrectly removes
|
||||
blank spaces from the page in order to avoid what it considers to be
|
||||
multiple spaces in a row. In particular, if there is a space both
|
||||
before and after a tag that IE thinks does not insert content into the
|
||||
page, it removes one of the two blanks. Because SCRIPT tags don't
|
||||
get displayed, IE will remove one of the spaces, so
|
||||
|
||||
... when <script type="math/tex">x < y</script> we have ...
|
||||
|
||||
will become "...whenx < y we have..." in the output, with no space
|
||||
between the "when" and the "x". Because the space is removed before
|
||||
MathJax runs, MathJax has no way to recover the missing space, as it
|
||||
simply is no longer part of the page as far as IE is concerned.
|
||||
|
||||
MathJax provides two different mechanisms to avoid this problem. One
|
||||
is to add a prefix or postfix for the mathematics tags, which is text
|
||||
that you insert before or after the tag that MathJax will remove when
|
||||
it processes the tag. Patterns for the prefix and postfix are given
|
||||
in the "preJax" and "postJax" parameters of the MathJax.Hub.Config()
|
||||
command (see the MathJax/config/MathJax.js file for more details).
|
||||
For example, setting
|
||||
|
||||
preJax: "@@"
|
||||
|
||||
would mean that
|
||||
|
||||
... when @@<script type="math/tex">x < y</script> we have ...
|
||||
|
||||
would produce ".. when x < y we have ..." properly typeset. (One need
|
||||
not use both a preJax and postJax, as one is enough, but both are
|
||||
provided so that you can use either or both in combination.) Note,
|
||||
however, that the "@@" in this example will be displayed as part of
|
||||
the page until MathJax processes the mathematics and replaces the
|
||||
preJax with the typeset mathematics. This may cause visual confusion
|
||||
that disturbs your readers. It might be better to use something like
|
||||
"[math]" as the text for the preJax, since this may make more sense to
|
||||
your readers. Because the pre- and postJax are regular expression
|
||||
patterns (not litteral strings), you will need to handle this
|
||||
carefully because [ and ] have special meaning in regular expressions.
|
||||
Use
|
||||
|
||||
preJax: "\\[math\\]"
|
||||
|
||||
to make preJax be "\[math\]" (the double backslashes are to quote the
|
||||
backslash as part of the JavaScript string, and the resulting \[ and
|
||||
\] quote these characters in the resulting regular expression so they
|
||||
are treated as literal characters rather than having their special
|
||||
meansings in regular expressions).
|
||||
|
||||
The other approach is to use a "MathJax preview" before the SCRIPT
|
||||
tag. This is a means by which you can supply an alternative form for
|
||||
the mathematics to be displayed prior to when MathJax runs. You
|
||||
could use a simple HTML version (if the mathematics is simple enough),
|
||||
or an IMG tag, or just the raw TeX code, for example. Note that the
|
||||
mathematics between the SCRIPT tags is NOT displayed (since it is a
|
||||
script, not text), so the preview can be used to show the TeX code up
|
||||
until the mathematics is typeset. (The tex2jax preprocessor does that
|
||||
automatically, for example). To make a preview, include a SPAN with
|
||||
CLASS="MathJax_Preview" as the element just before the math SCRIPT
|
||||
tag, e.g.,
|
||||
|
||||
... when <span class="MathJax_Preview">x < y</span><script
|
||||
type="math/tex">x < y</script> we have ...
|
||||
|
||||
This circumvents the Internet Explorer space-removal bug, while at the
|
||||
same time giving your readers a preview of the mathematics until
|
||||
MathJax has been able to typeset it.
|
||||
|
||||
You can use CSS styles to make it easier to distinguish the preview
|
||||
from the rest of the text. For example:
|
||||
|
||||
<script type="text/javascript" src="/MathJax/MathJax.js">
|
||||
MathJax.Hub.Config({
|
||||
...
|
||||
styles: {
|
||||
".MathJax_Preview": {
|
||||
color: "red",
|
||||
border: "1px solid",
|
||||
padding: "2px"
|
||||
}
|
||||
},
|
||||
...
|
||||
});
|
||||
</script>
|
||||
|
||||
would cause the preview mathematics to be shown in red, with a border
|
||||
and 2px of padding between the border and the preview text.
|
||||
|
||||
|
||||
MATHJAX WITH MATHML:
|
||||
|
||||
In addition to the TeX input processor, MathJax includes a MathML input
|
||||
processor, so that you can specify your mathematics using MathML rather
|
||||
than TeX, if you wish. (The input and output processors are called "jax".)
|
||||
As with the TeX input jax, there is a pre-processor that looks for MathML
|
||||
in your web page (XHTML or HTML) and converts it to the form needed by
|
||||
MathJax. The preprocessor is called "mml2jax.js", and the associated input
|
||||
jax is "input/MathML". You can request these in your
|
||||
MathJax/config/MathJax.js file, or in line, as in the following example:
|
||||
|
||||
<script type="text/javascript" src="/MathJax/MathJax.js">
|
||||
MathJax.Hub.Config({
|
||||
extensions: ["mml2jax.js"],
|
||||
jax: ["input/MathML","output/HTML-CSS"]
|
||||
});
|
||||
</script>
|
||||
|
||||
When it is used, the mml2jax preprocessor will scan your page for <math>
|
||||
tags and insert them into the <script> tags that MathJax needs to identify
|
||||
the mathematics on the page. This works in both HTML and XHTML pages, and
|
||||
with browsers that don't have native support for MathML. While MathJax is
|
||||
not as fast as a native implementation of MathML, it does bring MathML to
|
||||
all major browsers. (It is even possible to set up a GreaseMonkey-style
|
||||
script to have MathJax automatically process any MathML on any page you
|
||||
visit, so MathJax can be used to make MathML available even when the page
|
||||
author has not specifically loaded MathJax. There are some caveats for
|
||||
this, however, so such a script is not currently being supplied.)
|
||||
|
||||
For MathML that is handled via the pre-processor, you should not use the
|
||||
MathML named entities, but rather use the numeric entities like √ or
|
||||
unicode characters embedded in the page itself. The reason is that the
|
||||
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.
|
||||
|
||||
|
||||
MATHML WITH NO PREPROCESSOR:
|
||||
|
||||
Just as there is a way to enter TeX code without a preprocessor, MathJax
|
||||
provides a means of specifying MathML without a preprocessor. In this
|
||||
case, you enclose your complete <math> substree within a
|
||||
<script type="math/mml">...</script> tag. E.g.:
|
||||
|
||||
<script type="math/mml">
|
||||
<math display="block">
|
||||
<mi>x</mi><mo>=</mo><mn>1</mn>
|
||||
</math>
|
||||
</script>
|
||||
|
||||
Note that the <math> tag's display attribute controls whether the node is
|
||||
typeset in-line or as a displayed equation. The same caveats concerning
|
||||
spacing apply to MathML as to TeX, so see the section on MATHJAX WITH NO
|
||||
PREPROCESSOR above for how to deal with an Internet Explorer bug that
|
||||
requires special treatment.
|
||||
|
||||
|
||||
MATHML OUTPUT:
|
||||
|
||||
In addition to the HTML-CSS output jax, MathJax provides a native-MathML
|
||||
output jax that generates MathML to display your mathematics rather than
|
||||
complicated HTML with CSS. For browsers that support MathML, this can be
|
||||
considerably faster, plus it provides for accessibility and the ability to
|
||||
cut and paste mathematics that MathML offers. MathML output is available
|
||||
for both TeX input and MathML input, so MathJax can act as a TeX-to-MathML
|
||||
converter right in the browser.
|
||||
|
||||
To use the native MathML output jax, specify "output/NativeMML" rather than
|
||||
"output/HTML-CSS" in the jax array of your MathJax.Hub.Config() call (or in
|
||||
MathJax/config/MathJax.js). For example:
|
||||
|
||||
<script type="text/javascript" src="/MathJax/MathJax.js">
|
||||
MathJax.Hub.Config({
|
||||
extensions: ["tex2jax.js"],
|
||||
jax: ["input/TeX","output/NativeMML"]
|
||||
});
|
||||
</script>
|
||||
|
||||
Note that this will only work for those browsers that support MathML
|
||||
natively, so you should be careful to know your audience if you use this
|
||||
output jax. Also, note that the MathML output jax produces MathML3.0, not
|
||||
2.0, and so some browsers may not be able to handle all the constructs that
|
||||
MathJax will produce. Although it is slower, the HTML-CSS output jax is
|
||||
more reliable than the NativeMML output jax, at least from a cross-browser
|
||||
standpoint, particularly when the TeX input jax is used.
|
||||
|
||||
Because of the speed of the native MathML rendering, some users may prefer
|
||||
to use that than the HTML-CSS output jax, but you may not want to prevent
|
||||
those who don't have native MathML support from viewing your pages, so you
|
||||
may want to select between NativeMML and HTML-CSS automatically, depending
|
||||
on the capabilities of the browser. MathJax provides a configuration file
|
||||
that does just that. To use it, include "MMLorHTML.js" in the config array
|
||||
of your MathJax.Hub.Config() call. If you use this, be sure NOT to include
|
||||
an output jax in your jax array, as MMLorHTML.js will fill that in for you.
|
||||
For example:
|
||||
|
||||
<script type="text/javascript" src="/MathJax/MathJax.js">
|
||||
MathJax.Hub.Config({
|
||||
config: ["MMLorHTML.js"],
|
||||
extensions: ["tex2jax.js"],
|
||||
jax: ["input/TeX"]
|
||||
});
|
||||
</script>
|
||||
|
||||
In the case where both NativeMML and HTML-CSS are supported, the MMLorHTML
|
||||
configuration file will choose HTML-CSS, even though it is slower; this is
|
||||
because it is more reliable, since MathJax produces MathML3.0 and not all
|
||||
browsers can display that. This is configurable, however, and you may want
|
||||
to change the preference to NativeMML instead, especially if your input
|
||||
language is MathML already. This can be done using the MMLorHTML section
|
||||
of your configuration:
|
||||
|
||||
<script type="text/javascript" src="/MathJax/MathJax.js">
|
||||
MathJax.Hub.Config({
|
||||
config: ["MMLorHTML.js"],
|
||||
extensions: ["tex2jax.js"],
|
||||
jax: ["input/TeX"],
|
||||
MMLorHTML: {prefer: "MML"}
|
||||
});
|
||||
</script>
|
||||
|
||||
Note, however, that not all users will have your own preferences about what
|
||||
"looks best" or "performs best", so while you may value speed above all
|
||||
else, others may value readability or reliability more. Also, remember
|
||||
that browsers other than the one you are using (or the same browser on
|
||||
other operating systems) may not support native MathML as well as yours
|
||||
does. For example, Opera does handle simple MathML fairly well, but breaks
|
||||
down quickly for some more complex equations, and while you may have
|
||||
Firefox all set up for MathML, others may not have installed the needed
|
||||
fonts, and will be unhappy to get a warning dialog box whenever they visit
|
||||
your web page. So think carefully about the assumptions you are making on
|
||||
behalf of your readers. At some point, MathJax may include a control panel
|
||||
that will allow users to select preferences on their own, but that is not
|
||||
available currently.
|
||||
|
||||
|
||||
CONVERSION FROM JSMATH:
|
||||
|
||||
If you are currently using jsMath and would like to switch to MathJax, the
|
||||
transition should be fairly straight-forward. If you are using jsMath's
|
||||
easy/load.js, then you should simply switch the line that loads
|
||||
jsMath/easy/load.js to
|
||||
|
||||
<script src="path-to-mathjax/MathJax/MathJax.js"></script>
|
||||
|
||||
where "path-to-mathjax" is the path to the MathJax folder on your server.
|
||||
This uses the MathJax/config/MathJax.js file to configure MathJax, similar
|
||||
to easy/load.js, and you can read the comments in that file for details.
|
||||
Be sure to include "tex2jax.js" in your extensions array if you want the
|
||||
TeX preprocessor to run (comparable to the tex2math plugin for jsMath).
|
||||
|
||||
If you did not use the tex2math plugin for jsMath and instead inserted your
|
||||
own <span class="math">...</span> and <div class="math">...</div> tags with
|
||||
class="math", then you need to do a little more work for MathJax. These
|
||||
need to be replaced by <script type="math/tex">...</script> and <script
|
||||
type="math/tex; mode=display">...</script> tags. See also the section
|
||||
MATHJAX WITHOUT A PREPROCESSOR above for some caveats concerning an
|
||||
Internet Explorer bug that you will need to be aware of.
|
||||
|
||||
If you are using a preprocessor of your own to write your HTML files, it
|
||||
should be a simple matter of changing over the inserted tags to the ones
|
||||
that MathJax needs. If you have existing HTML pages, however, and don't
|
||||
want to (or can't) reprocess them, then you may want to use the jsMath2jax
|
||||
preprocessor, which will first convert the span and div tags to script tags
|
||||
before running MathJax. To do so, include "jsMath2jax.js" in your
|
||||
extensions array, as in the following example:
|
||||
|
||||
<script type="text/javascript" src="/MathJax/MathJax.js">
|
||||
MathJax.Hub.Config({
|
||||
extensions: ["jsMath2jax.js"],
|
||||
jax: ["input/TeX", "output/HTML-CSS"]
|
||||
});
|
||||
</script>
|
||||
|
||||
You should remove all the jsMath calls, like jsMath.Process(), or script
|
||||
tags that load jsMath extensions. Only the single script tag that loads
|
||||
MathJax should be needed.
|
||||
|
||||
If you have created pages with dynamic mathematics that is processed by
|
||||
jsMath on the fly, that is handled somewhat differently with MathJax.
|
||||
MathJax has a richer API for dealing with mathematics on the page, but the
|
||||
documentation is not yet ready. There have been discussions in the MathJax
|
||||
on-line forums that deal with this topic, so your best bet right now is to
|
||||
read them.
|
||||
http://www.mathjax.org/docs/
|
||||
|
||||
|
||||
COMMUNITY:
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user