Using TeXZilla

Basic usage in a CommonJS program or Web page

The main feature of TeXZilla is to convert a TeX expression into MathML as a string (source code) via TeXZilla.toMathMLString or as an element (DOM tree) via TeXZilla.toMathML.

You can use TeXZilla the standard way in any Javascript program. For example in a commonJS program, to convert a TeX source into a MathML source:

  var TeXZilla = require("./TeXZilla");
  console.log(TeXZilla.toMathMLString("\\sqrt{\\frac{x}{2}+y}"));

Or in a Web Page, to convert a TeX source into a MathML DOM element:

  <script type="text/javascript" src="TeXZilla-min.js"></script>
  ...
  var MathMLElement = TeXZilla.toMathML("\\sqrt{\\frac{x}{2}+y}");

Usage from the command line

Note: the stream filter mode requires TeXZilla >= 0.9.7 and does not work in slimerjs yet.

It is also possible to use TeXZilla from the command line. At the moment this is not guaranteed to work with all commonJS programs, for lack of standard commonJS APIs. The interface has been tested with slimerjs, phantomjs and nodejs.

commonjs TeXZilla.js [help]
  Print this help message.

commonjs TeXZilla.js parser aTeX [aDisplay] [aRTL] [aThrowExceptionOnError]
  Print TeXZilla.toMathMLString(aTeX, aDisplay, aRTL, aThrowExceptionOnError)
  The interpretation of arguments and the default values are the same.

commonjs TeXZilla.js webserver [port] [safe] [itexId]
  Start a Web server on the specified port (default:3141)
  See the TeXZilla wiki for details.

cat input | commonjs TeXZilla.js streamfilter [safe] [itexId] > output
  Make TeXZilla behaves as a stream filter. The TeX fragments are
  converted into MathML.
  See the TeXZilla wiki for details.

  where commonjs is slimerjs, nodejs or phantomjs.

For example

$ slimerjs TeXZilla.js parser "a^2+b^2=c^2" true
<math xmlns="http://www.w3.org/1998/Math/MathML" display="block"><semantics><mrow><msup><mi>a</mi><mn>2</mn></msup><mo>+</mo><msup><mi>b</mi><mn>2</mn></msup><mo>=</mo><msup><mi>c</mi><mn>2</mn></msup></mrow><annotation encoding="TeX">a^2+b^2=c^2</annotation></semantics></math>

See also how to use TeXZilla as a Web server or TeXZilla as a Stream Filter.

Advanced conversion methods

Note: this requires TeXZilla >= 0.9.7.

It is possible apply a stream filter to convert the TeX expressions delimited by the classical $ ... $, $$ ... $$, \( ... \) \[ ... \] into inline or display MathML. Outside TeX expressions, you can escape dollars and backslashes using the commands \$ and \\. See TeXZilla.filterString and TeXZilla.filterElement.

It is also possible to convert a TeX source into an <img> element using the TeXZilla.toImage method. The image contains a base64 representation of an SVG image with the MathML output embedded via a <foreignObject>. This is useful to dynamically insert mathematical equations in a 2D or 3D canvas.

Specifying display and RTL modes

One can use the MathML display="block" and dir="rtl" attributes on the <math> element to render equations in display and RTL modes respectively. You can pass optional booleans aDisplay and aRTL to TeXZilla.toMathMLString or TeXZilla.toMathML in order to ask TeXZilla to do that. See the live demo for how these attributes are handled.

Handling Parsing Error

By default, TeXZilla will return parsing errors in an merror element. You can change that behavior by specifying aThrowExceptionOnError = true when calling TeXZilla.toMathMLString, TeXZilla.toMathML, TeXZilla.filterString, TeXZilla.filterElement etc. In that case, TeXZilla will throw an exception that you can catch normally. See this example that demonstrates an automatic preview dealing with parsing failures.

Extracting the original TeX source

The TeXZilla converter will save the TeX source in a semantics annotation. You can retrieve it using TeXZilla.getTeXSource. For example this simple TeXZilla-show-source.js script will show the TeX source when the user double clicks on a MathML equation. See this example. Note that other tools may access this TeX source such as the MathML copy add-on.

Setting the DOM Parser and XML serializer

Some TeXZilla functions require a DOM Parser or XML serializer. If new DOMParser() or new XMLSerializer() does not work in your Javascript program, you must set the DOM parser / XML Serializer by hand using the setDOMParser and setXMLSerializer functions. For example using Mozilla's XPCOM interface:

  TeXZilla.setDOMParser(Components.
                        classes["@mozilla.org/xmlextras/domparser;1"].
                        createInstance(Components.interfaces.nsIDOMParser));

or for Firefox Add-on SDK:

  var {Cc, Ci} = require("chrome");
  TeXZilla.setDOMParser(Cc["@mozilla.org/xmlextras/domparser;1"].
                        createInstance(Ci.nsIDOMParser));

Advanced Parsing Modes

Note: this requires TeXZilla >= 0.9.7.

TeXZilla has some special modes that can be enabled to modify its parsing behavior. For instance, the safe mode will forbid the links and other MathML output that could be used by evil users for XSS injections. The itex identifier mode forces TeXZilla to treat sequences of letters as one MathML <mi> token, to align with itex's behavior.