commit 07ee4b860b8fe9fd10b6f3f29febedd3de4e6d49
parent 9dee8248f6dfd98e4a7cb4b101d23c30c02a96f0
Author: Davide Cervone <dpvc@union.edu>
Date: Thu, 29 Jul 2010 23:19:59 +0000
Removed most of the README content, which is now in the docs folder in HTML format
git-svn-id: https://mathjax.svn.sourceforge.net/svnroot/mathjax/trunk@536 b8fd5906-0fad-46e2-a0d3-10d94ff285d1
Diffstat:
| M | mathjax/README.txt | | | 457 | +++---------------------------------------------------------------------------- |
1 file changed, 16 insertions(+), 441 deletions(-)
diff --git a/mathjax/README.txt b/mathjax/README.txt
@@ -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:
