gollum 1.0.0

data/lib/gollum/frontend/public/javascript/MathJax/README.txt

@@ -0,0 +1,480 @@
+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.
+
+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:
+
+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.
+
+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 &lt;, &gt;
+and &amp; to encode these characters so that the browser will not
+interpret them, but MathJax will.  E.g., 
+
+	... when $x &lt; 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 &lt; 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 &#x221A; 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.
+
+
+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.