[HOME] jsMath (Authors) [Prev][Up][Skip][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.

If you are using the easy/load.js file, it is easy to activate tex2math: simply set at least one of the following options to be 1: processSlashParens, processSlashBrackets, processDoubleDollars, or processSingleDollars, or uncomment customDelimiters and set their values. If any of these is set, tex2math will be loaded automatically and will process the web page to search for the indicated delimiters.

If you are loading jsMath.js by hand and want 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".

(There is one exception to the requirement that there be no HTML code within the mathematics: tex2math will remove <BR> tags are are within the text of the mathematics if needed. This is because some bulletin-board systems insert these automatically in the text that a user types in, and so they may appear within the text of the mathematics without the user's knowledge.)

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" instead.

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.Synchronize(function () {
        jsMath.tex2math.Convert(element,{
          processSingleDollars: 1, processDoubleDollars: 1,
          processSlashParens: 1, processSlashBrackets: 1,
          fixEscapedDollars: 1
        });
      });
    </SCRIPT>
is equivalent to jsMath.ConvertTeX(element). You can turn off any of these features by changing the 1 to a 0. The fixEscapedDollars 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.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 longest string it can that doesn't contain a copy of one of the opening delimiters. This means it is possible 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 delimiters with at least two characters, as these are much less likely to occur naturally when you don't intend them.

Note that you can not use HTML special characters like < or > as part of your custom delimiters, since the browser will already have interpreted them by the time tex2math runs. This means you can't use delimiters that look like HTML tags, unfortunately.

Once you have the delimiters defined, you still need to ask 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 or the other conversion routines (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). You should probably insert the DIV before you call jsMath.ProcessBeforeShowing(), as the placement of the element may change the scaling or other factors that affect the mathematics, and the result will be better if jsMath know about those changes.

Also, you should be aware that jsMath.ProcessBeforeShowing() may operate asynchronously; that is, it may just queue up the request for processing later (for example, if jsMath is waiting for one of its auxiliary files to load first). The upshot is you can not count on the DIV actually containing the typeset mathematics at this point. See the section on synchronizing with jsMath for more details.


Controlling tex2math more globally

It is possible to use special tags within the HTML file to tell tex2math what sections of the document should be scanned for mathematics to be processed, and which should not. See the documentation on controlling tex2math processing for additional details.


Get jsMath at SourceForge.net. Fast, secure and Free Open Source software downloads [HOME] jsMath web pages
Created: 10 Jul 2005
Last modified: 10 Sep 2008 08:15:59
Comments to: dpvc@union.edu
[Next] The autoload plugin
[Skip] Browser Support for jsMath
[Up] Information for jsMath Authors
[Prev] Controlling tex2math processing