[HOME] jsMath (Authors/2.x) [Prev][Top][Up][Next]

The tex2math plugin

Usually, jsMath identifies mathematics within your web page by looking for <SPAN CLASS="math"> or <DIV CLASS="math"> blocks in the HTML that defines your page. These are a bit cumbersome to type, especially for those used to entering mathematics within dollar signs or \(...\) and \[...\] commands as in LaTeX. JsMath can help out with this, however, by translating dollar signs or the LaTeX \(...\) and \[...\] syntax into the appropriate SPAN or DIV tags automatically, after the page is loaded. This is handled by the text2math plugin.

To use the tex2math plugin, include the line 

    <SCRIPT"> jsMath.Setup.Script("plugins/tex2math.js") </SCRIPT>
right after the command that loads the jsMath.js file. Then, at the bottom of the HTML file, do 
    <SCRIPT> jsMath.ConvertTeX() </SCRIPT>
just before the call to jsMath.ProcessBeforeShowing() or jsMath.ProcessBeforeShowing(). This will cause jsMath to look through all the text blocks in your file looking for $...$, $$...$$, \(...\) or \[...\] and replacing them by the appropriate SPAN or DIV.

You can include jsMath.ConvertTeX as part of the page's onload hander (along with the appropriate jsMath.Process command). For example, 

   <BODY onLoad="jsMath.ConvertTeX(); jsMath.Process()">
will convert TeX- or Latex-style math references to typeset mathematics when the page has loaded.


How to allow dollar signs as part of your text

When you use the tex2math plugin, you have to be be careful that your page doesn't contain dollar signs that you don't want to have converted to mathematics. For example, if you had "that cost $1.50 in those days, or about $5.00 today" as part of your web page, jsMath.ConvertTeX() would convert this to "that cost <SPAN CLASS="math">1.50 in those days, or about </SPAN>5.00 today", and then jsMath would try to typeset the contents of the SPAN as mathematics.

There are several ways around this. First, jsMath.ConvertTeX() only processes matching dollar signs, and these will only be considered to be matching if there is no intervening HTML between them. So one way to shield a dollar sign from being converted into mathematics is to enclose it in a SPAN or other tag of its own. For example "that cost <SPAN>$1.50</SPAN> in those days, or about <SPAN>$5.00</SPAN> today".

Alternatively, you could "escape" the dollar signs using the backslash. The jsMath.ConvertTeX() command converts \$ to $ when it appears outside of math mode. So you could enter "that cost \$1.50 in those days, or about \$5.00 today" insteead.

Another way would be to use the &#36; entity: "that cost &#36;1.50 in those days, or about &#36;5.00 today", though that is harder to read. (It would be nice to be able to use the &dollar; entity name, but sadly this does not work with all browsers.)

Finally, you could indicate your mathematics only by \(...\) for in-line mathematics and \[...\] for displayed equations, and use jsMath.ConvertLaTeX() rather than jsMath.ConvertTeX(). This will leave all dollar signs (and escaped dollar signs) alone, but convert the LaTeX-style notation to the SPAN and DIV tags. If you are including jsMath in a bulletin-board system or blog software, this may be the best solution, since you will not be able to guarantee that the person entering the data in your page has not used dollar signs that should remain as dollar signs. A third option is to use jsMath.ConvertTeX2(), which processes \(...\), \[...\] and $$...$$ but not $...$.


Controlling which math delimiters to search for

You can control which of the various delimiters tex2math will look for in your web page using the jsMath.tex2math.Convert() function (which is the basis for the other convert functions). For example 
    <SCRIPT>
      jsMath.tex2math.Convert(element,{
        processSingleDollars: 1, processDoubleDollars: 1,
        processSlashParens: 1, processSlashBrackets: 1,
        fixEscapedDollars: 1
      });
    </SCRIPT>
is equivalent to jsMath.tex2math.ConvertTeX(element). You can turn off any of these features by changing the 1 to a 0. The fixEscapedDollar flag controls whether \$ is converted to $ in your text outside of math mode. (This allows you to use \$ to prevent entering math mode.)


Using custom indicators for in-line and display mathematics

There may be times when you don't want to use \(...\) and \[...\] as the markers for in-line and display mathematics (for example, if you want to be able to display these easily in your web page). You could put <SPAN> and </SPAN> around them, but that is awkward to type.

Instead, you could define custom delimiters using the jsMath.tex2math.CustomSearch() function. You pass it four strings: the strings to use for the start and end of in-line mathematics, and the strings to use for the start and end of display mathematics. For example 

    <SCRIPT>
      jsMath.tex2math.CustomSearch('[math]','[/math]','[display]','[/display]');
    </SCRIPT>
would set things up so that you could use [math]...[/math] to indicate in-line mathematics, and [display]...[/display] to indicate displayed equations. Note that the strings are case-sensitive, and should not be something that would occur within normal text, otherwise tex2math may not be able to match the delimiters properly. For example, it is probably not a good idea to use 'math(' and ')', as the close parenthesis is used frequently within plain text, so tex2math might think the mathematics extends farther than it should.

When looking for the closing delimiter, tex2math will try to take the largest string it can that doesn't contain a copy of the opening delimiter. This means it is posible to use things like '}' as the closing delimiter, but you need to be careful that you don't have other close-braces that don't terminate math mode. You are safer if you use delimters with at least two characters, as these are much less likely to occur naturally when you don't intend them.

Once you have the delimiters defined, you still need to as tex2math to actually convert the document (or some piece of it). Use the command 

    <SCRIPT> jsMath.ConvertCustom(document) </SCRIPT>
to convert the entire document using your custom delimiters. The reason these are separated into two routines is so that you can call jsMath.ConvertCustom() as many times as you want to without having to reprocess the patterns needed for the custom delimiters.

Note that you can do several searches using different delimiters by calling jsMath.tex2math.CustomSearch() and jsMath.ConvertCustom() several times with different values. Since all of this is done before your call to jsMath.Process() or jsMath.ProcessBeforeShowing(), the math will still be typeset from the top down, even if pieces of text were converted using several different kinds of delimiters.


Processing only one element

For a large document that contains only a little bit of mathematics, it may be inefficient for jsMath to search the entire document for mathematics to convert. In this case, you may wish to process only an individual HTML element (like a particular paragraph or DIV block). To do so, you can pass an element ID to jsMath.ConvertTeX orjsMath.ConvertLaTeX (and also to jsMath.Process or jsMath.ProcessBeforeShowing). For example, 
    <P ID="has_math">
       If $x = 3$ then $x^2 = 9$.
    </P>

    <SCRIPT>
      jsMath.ConvertTeX('has_math');
      jsMath.ProcessBeforeShowing('has_math');
    </SCRIPT>
would cause just the mathematics in the one paragraph labeled "has_math" to be converted without affecting the rest of the file. You can use any type of tag to mark the mathematics to be processed, say a SPAN or a DIV, or even a TABLE or other block.

If you are generating content on the fly, processing a single element may be particularly useful. In this case, it may be more convenient to pass a reference to the element rather than an element ID. For example, 

    <SCRIPT>
      var div = document.createElement('div');
      div.innerHTML = "If $x = 3$ then $x^2 = 9$";
      jsMath.ConvertTeX(div);
      jsMath.ProcessBeforeShowing(div);
    </SCRIPT>
would create a DIV block, enter some text in it, and then convert the mathematics within that text to typeset mathematics. Note, however, that the contents of the DIV will not appear until it has been inserted into the page somewhere, say by something like document.body.appendChild(div).


Controlling tex2math more globally

Under some circumstances, you may want to be able to have tex2math process some portions of the page but not others, but you don't want to call jsMath.ConvertTeX more than once. One such situation is when you use tex2math in a bulletin-board system, where the jsMath calls are inserted automatically by the system, so you can't control what is passed to them. In that case, you may want to be able to turn on or off tex2math by way of the HTML markup itself. You can do this using special class names to indicate what tex2math should process.

If you mark an element with CLASS="tex2math_ignore, then the contents of that element will not be processed by tex2math. This allows you to use the symbols that usually indicate mathematics without them having that special meaning. For example, in 

    <DIV CLASS="tex2math_ignore">
      Normally, you enter mathematics between \( and \) or \[ and \].
    </DIV>
would prevent tex2math from trying to interpret the two and's as mathematics.

It is also possible to mark an element with CLASS="tex2math_process" to have the opposite effect: to cause tex2math to look for mathematics within the element when it normally wouldn't. Usually, tex2math will ignore the contents of SCRIPT, NOSCRIPT, STYLE, TEXTAREA and PRE tags, as it usually is inapprporiate to typeset mathematics within these items. If you really do want tex2math to process the text within one of these elements, you can use the CLASS to force that. For example, <PRE CLASS="tex2math_process"> would cause tex2math to process the contents of the PRE tag for mathematics.

Note that you can nest elements with CLASS="tex2math_process" inside ones of CLASS="tex2math_ignore" and vice versa, and you can nest as many layers deep as you wish. For example, you could make the BODY tage be CLASS="tex2math_ignore" in order to prohibit math processing, and then explicitly enable it on certain tags by using CLASS="tex2math_process". If the BODY needs to be set to a different class for display purposes, you can place a DIV with CLASS="tex2math_ignore" around the contents of the page to get the same effect.

Finally, it is possible to disable tex2math entirely on a page by including an element that is marked with ID="tex2math_off". Before doing any processing of the page, tex2math looks for an item with this ID, and if present, it does not run at all. This is intended for use in bulletin-board systems, where you don't control the complete content on the page. This lets you mark a page as not being appropriate for jsMath using only the text you can insert. For example, if you add 

    <SPAN CLASS="tex2math_off"></SPAN>
anywhere on the page, then tex2math will not run. Note that if you use tex2math on a system where you are not the only one who can enter text, it is possible for others to include such a tag in their messages, perhaps meliciously, thus disabling the rest of the mathematics on that page. You can prevent this by including 
    <SCRIPT> jsMath.text2math = {allowDisableTag: 0} </SCRIPT>
in your web page before loading tex2math.


Get jsMath at SourceForge.net. Fast, secure and Free Open Source software downloads [HOME] jsMath web pages
Created: 10 Jul 2005
Last modified: 02 Dec 2005 13:02:01
Comments to: dpvc@union.edu
[Next] The mimeTeX plugin
[Up] Information for jsMath v2.x Authors
[Prev] jsMath Basics