mathTeX manual

'; echo '',$expression,''; echo '', "\n"; } ?>

	m a t h T e X m a n u a l ( for mathTeX version 1.04 ) Click for: download mathTeX	more_examples...
This page discusses mathTeX, a program that displays math on the web. See Writing Math on the Web for a more general discussion.

Copyright © 2007-2012, John Forkosh Associates, Inc.
email: john@forkosh.com

$\parstyle\usepackage{color} \large\color{blue}\begin{center}\today\\\time\end{center}$

This manual contains more information than you'll probably need to read. If you follow the QuickStart instructions below, try installing mathTeX immediately. If you need more information, continue reading until you feel comfortable trying to install mathTeX. Return to the manual as needed. Prerequisites are: some knowledge of Unix shell, of installing cgi's, of LaTeX.
"Computers are like Old Testament gods: lots of rules and no mercy."
Joseph Campbell, The Power of Myth (Doubleday 1988, page 18)

C o n t e n t s

Q u i c k S t a r t

(1) Introduction
dependencies
plugins
alternatives
web services
(2) LaTeX markup
input form
examples
(3) MathTeX markup
extra directives
(4) Installation
error messages
compile switches
run from shell
(5) GPL License

Related Pages
LaTeX Tutorial
mathTeX changeLog
mathTeX Listing

Installation:	Note: The current release of mathTeX only runs under Unix-like operating systems. First, install mathTeX's dependencies: a recent TeX distribution with dvipng, on your server. Or see mimeTeX if you can't. Then, download mathtex.zip and type unzip mathtex.zip cc mathtex.c \ –DLATEX=\"$(which latex)\" \ –DDVIPNG=\"$(which dvipng)\" \ –o mathtex.cgi (see –Dswitches for more information). Finally, just mv mathtex.cgi to your cgi-bin/ directory, chmod permissions as necessary, and you're all done.

Usage:	To see the image in your html page, just write the tag <img src="/cgi-bin/mathtex.cgi? x=\frac{-b\pm\sqrt{b^2-4ac}}{2a}">

(1) Introduction

MathTeX, licensed under the gpl, is a cgi program that lets you easily embed LaTeX math in your own html pages, blogs, wikis, etc. It parses a LaTeX math expression and immediately emits the corresponding gif (or png) image, rather than the usual TeX dvi. So just place an html <img> tag in your document wherever you want to see the corresponding LaTeX expression. For example,

   <img src="/cgi-bin/mathtex.cgi?f(x)=\int_{-\infty}^xe^{-t^2}dt"
    alt="" border=0 align="middle">

immediately generates the corresponding gif, displaying wherever you put that <img> tag.

mathTeX dependencies...

MathTeX's uses the latex and dvipng programs, along with all necessary fonts, etc, from your TeX distribution. Occasionally, you may need to download dvipng separately.
If you can't, or don't want to, install dvipng, then you may optionally specify the –DDVIPS and –DCONVERT switches when compiling mathTeX. Then mathTeX uses dvips from your TeX distribution, and convert from the ImageMagick package, instead of dvipng.

That is,

   cc –DLATEX=\"path/to/latex\" –DDVIPNG=\"path/to/dvipng\" mathtex.c –o mathtex.cgi

compiles mathtex.cgi with dependencies latex and dvipng, whereas,

   cc –DLATEX=\"path/to/latex\" –DDVIPS=\"path/to/dvips\" \
   –DCONVERT=\"path/to/convert\" mathtex.c –o mathtex.cgi

compiles mathtex.cgi with dependencies latex and dvips and convert.
(Note: dvipng is easily twice as fast as dvips/convert, and it produces somewhat smaller image files, with no discernible (to me) loss of quality or other downside. So I recommend its use if you have it installed or can install it.)

These dependencies — always latex and either dvipng or dvips/convert — must all be installed on your server before you can run mathTeX. Ask your ISP or sysadmin if you have any questions or problems installing them. Or see mimeTeX if you can't install them.

Advisory for dvips/convert users:

If you're using dvips and and convert (rather than dvipng), then be advised that recent versions of convert seem to exhibit a minor bug whereby the program's –gamma correction option is ignored when converting postscript images to any other format. The default, and unchangeable, gamma renders acceptable-looking png images, but unacceptably light gif images. Earlier versions of convert seem to respect the –gamma option and, moreover, render acceptable default gif images anyway. So if you're using dvips/convert and are seeing very light images, I'd recommend downloading ImageMagick version 6.2.6 source from http://sourceforge.net/projects/imagemagick/files/ and building your own version of convert. That should fix your problem. Alternatively, an even easier fix is to compile mathtex with the -DPNG switch, which renders acceptable-looking default png images regardless of convert version.

Additional dependencies for LaTeX's picture environment:

LaTeX's picture environment provides a rudimentary markup for drawing simple diagrams. For example, you can submit a rather complicated <img> tag to mathTeX like

   <img src="/cgi-bin/mathtex.cgi?
      \png
      \definecolor{blueblack}{RGB}{0,0,135}
      \color{blueblack}
      \begin{picture}(4,1.75)
        \thicklines
        \put(2,0.01){\arc{3}{3.53588}{5.8888}}
        \put(.375,.575){\line(1,0){3.25}}
        \put(1.22,1.375){\makebox(0,0){\footnotesize$ds$}}
        \put(.6,.5){\makebox(0,0){\footnotesize$x=0$}}
        \put(3.36,.5){\makebox(0,0){\footnotesize$x=\ell$}}
        \dottedline{.05}(1.0,.575)(1.0,1.10)
        \put(1.0,.5){\makebox(0,0){\footnotesize$x$}}
        \dottedline{.05}(1.5,.575)(1.5,1.40)
        \put(1.5,.5){\makebox(0,0){\footnotesize$x+dx$}}
        \put(1.22,.65){\makebox(0,0){\footnotesize$dx$}}
        \dottedline{.04}(0.6,1.12)(1.25,1.12)
        \put(1.0,1.14){\vector(-1,-1){.45}}
        \put(.58,0.83){\makebox(0,0){\footnotesize$T$}}
        \put(.77,1.05){\makebox(0,0){\scriptsize$\theta(x)$}}
        \put(1.18,1.16){\makebox(0,0){\scriptsize$\theta(x)$}}
        \dottedline{.04}(1.5,1.41)(2.1,1.41)
        \put(1.5,1.44){\vector(4,1){.67}}
        \put(2.22,1.59){\makebox(0,0){\footnotesize$T$}}
        \put(1.95,1.45){\makebox(0,0){\scriptsize$\theta(x+dx)$}}
      \end{picture}"
    alt="" border=0 align="middle">

which, in this case, uses LaTeX's \begin{picture}...\end{picture} environment to render the image

$\png \definecolor{blueblack}{RGB}{0,0,135} \color{blueblack} \begin{picture}(4,1.75) \thicklines \put(2,0.01){\arc{3}{3.53588}{5.8888}} \put(.375,.575){\line(1,0){3.25}} \put(1.22,1.375){\makebox(0,0){\footnotesize$ds$}} \put(.6,.5){\makebox(0,0){\footnotesize$x=0$}} \put(3.36,.5){\makebox(0,0){\footnotesize$x=\ell$}} \dottedline{.05}(1.0,.575)(1.0,1.10) \put(1.0,.5){\makebox(0,0){\footnotesize$x$}} \dottedline{.05}(1.5,.575)(1.5,1.40) \put(1.5,.5){\makebox(0,0){\footnotesize$x+dx$}} \put(1.22,.65){\makebox(0,0){\footnotesize$dx$}} \dottedline{.04}(0.6,1.12)(1.25,1.12) \put(1.0,1.14){\vector(-1,-1){.45}} \put(.58,0.83){\makebox(0,0){\footnotesize$T$}} \put(.77,1.05){\makebox(0,0){\scriptsize$\theta(x)$}} \put(1.18,1.16){\makebox(0,0){\scriptsize$\theta(x)$}} \dottedline{.04}(1.5,1.41)(2.1,1.41) \put(1.5,1.44){\vector(4,1){.67}} \put(2.22,1.59){\makebox(0,0){\footnotesize$T$}} \put(1.95,1.45){\makebox(0,0){\scriptsize$\theta(x+dx)$}} \end{picture}$

Diagrams like this are more often drawn using separate drawing programs. However, for example, if you're posting to a bulletin board/blog/wiki that supports mathTeX but doesn't let you upload separate images, then mathTeX <img> tags may be a satisfactory alternative. And note the special mathTeX \png directive at the very beginning of the example expression above. That's removed before LaTeX sees your expression, but first it directs mathTeX to generate a png image even if the default is gif. Png's seem to produce slightly sharper picture images: try clicking the above image, change the \png to \gif, submit the expression and compare images.

Using \begin{picture}...\end{picture} has a few mathTeX dependency requirements. The dvipng program doesn't recognize LaTeX postscript \specials generated in the picture environment. So you must compile mathTeX with the –DDVIPS and –DCONVERT switches described above, and (of course) these two programs must be available on your server. Moreover, even dvips has problems generating encapsulated postscript (which is what mathTeX uses) containing these \specials. So a separate script, ps2epsi, that's usually included with ghostscript distributions, is used by mathTeX to "encapsulate" dvips's output. Therefore, the ps2epsi script must also be available on your server, and you must compile mathTeX with the additional switch –DPS2EPSI=\"path/to/ps2epsi\" that specifies the path to it.

Note that you can, and should if possible, also compile mathTeX with the –DDVIPNG switch if the dvipng program is also available on your server. Then your compile line will look something like

   cc  –DLATEX=\"path/to/latex\"  –DDVIPNG=\"path/to/dvipng\"  –DDVIPS=\"path/to/dvips\" \
   –DCONVERT=\"path/to/convert\"  –DPS2EPSI=\"path/to/ps2epsi\"  mathtex.c –o mathtex.cgi

In this case mathTeX defaults to dvipng unless your expression contains \begin{picture}, when it automatically uses dvips/ps2epsi/convert instead. And when your expression contains \begin{picture}, mathTeX also automatically runs LaTeX with \usepackage{eepic}.

mathTeX plugins...

There's no inherent need to repeatedly write the cumbersome <img> tag illustrated above. You can write your own custom tags, or write a wrapper script around mathTeX to simplify the notation.

For example, the following javascript snippet (based on mathtran's mathtran_img.js) lets you just write <img alt="mathtex:c=\sqrt{a^2+b^2}"> wherever you want to see $\footnotesize c=\sqrt{a^2+b^2}$

   <script type="text/javascript">
   <!--
   // Create a namespace to hold variables and functions
   mathtex = new Object();
   // Change this to use your server
   mathtex.imgSrc = "http://www.yourdomain.com/cgi-bin/mathtex.cgi?";
   // Transform the whole document: add src to each img with
   // alt text starting with "mathtex:", unless img already has a src.
   mathtex.init = function () {
       if (! document.getElementsByTagName) return;
       var objs = document.getElementsByTagName("img");
       var len  = objs.length;
       for (i=0; i<len; i++) {
          var img = objs[i];
          if (img.alt.substring(0,8) == 'mathtex:')
             if (!img.src) {
                var tex_src = img.alt.substring(8);
                img.src = mathtex.imgSrc + encodeURIComponent(tex_src);
                // Append TEX to the class of the IMG.
                img.className +=' tex'; }
          }
       mathtex.hideElementById("mathtex.error"); }
   // Utility function
   mathtex.hideElementById = function (id) {
       var obj = document.getElementById(id);
       if (obj) obj.style.display = 'none'; }
   // resolve a cross-browser issue (see CBS events)
   mathtex.addEvent = function (obj, evType, fn, useCapture) {
       if (obj.addEventListener) { //For Mozilla.
           obj.addEventListener(evType, fn, useCapture);
           return true; }
       else if (obj.attachEvent) { //For Internet Explorer.
           var r = obj.attachEvent("on"+evType, fn);
           return r; }
       }
   // Initialize after entire document is loaded
   mathtex.addEvent(window, 'load', mathtex.init, false);
   -->
   </script>

Bulletin boards, wikis, etc, can also incorporate mathTeX images with short scripts. For example, if you're using phpBB2, then Jameson contributed the following one-line mod that lets you write [tex] ... [/tex] for mathTeX images:

   #--------[open]-----------------------------------------------------
     /includes/bbcode.php
   #--------[find]-----------------------------------------------------
     // Remove our padding from the string..
   #--------[before, add]----------------------------------------------
     $text = preg_replace('/\[tex\](.*?)\[\/tex\]/ie',
     "'<img src=\"/cgi-bin/mathtex.cgi?'.rawurlencode('$1').'\" align=\"middle\" />'",
     $text);

Similarly, if you're using phpBB3, then no mod is even needed. Just click Postings from the Administrator Control Panel, and add the Custom BBCode [tex]{TEXT}[/tex] with the HTML replacement <img src="/cgi-bin/mathtex.cgi?{TEXT}" align=middle> Now you can also write [tex] ... [/tex] to obtain mathTeX images of the enclosed expression.

Plugins for several additional packages already exist for my other math-rendering program, mimeTeX, which runs without dependencies, but produces slightly lower quality images than LaTeX. These plugins also work with mathTeX. Just substitute mathtex.cgi wherever the instructions say mimetex.cgi.

Package		Plugin
PmWiki		mimeTeX plugin
MediaWiki		"mimeTeX alternative"
MathWiki		"mimeTeX Parser"
PunBB		mimeTeX plugin
Movable Type		mimeTeX plugin
WordPress		mimeTeX plugin

Please note: If you're writing your own plugin for mathTeX, please write code using system( ), or any other shell escape mechanisms, carefully. system( ) raises security issues, either real ones if used carelessly, or just in the minds of system administrators. Either way, I've received emails from people unable to use mathTeX because of unnecessary system( ) calls prohibited by security-conscious sysadmins. MathTeX itself poses minimal risk when used as illustrated above, but you're responsible for any plugin/wrapper script you write around it.

vertical alignment...

An image like $f(x)=\int\limits_{-\infty}^xe^{-t^2}dt$ doesn't look as good as the same image $f(x)=\int\limits_{-\infty}^xe^{-t^2}dt$ that's vertically aligned with your surrounding text. Along with several standard HTTP header fields, mathTeX can also emit a special Vertical-Align: –nn header, where –nn is the number of pixels (usually negative as illustrated) needed for a style="Vertical-Align: –nn px" attribute in the <img> tag used to render your expression. To obtain its vertical-align information, mathTeX places your expression inside a LaTeX lrbox, where additional environments like \begin{gather*}...\end{gather*} are not permitted. If your expression is compatible with LaTeX's lrbox-environment, the Vertical-Align header is obtained by placing the directive \depth anywhere in your expression.

But mathTeX's special Vertical-Align: header is unrecognized and ignored by your browser. You have to get the header, interpret it, and write the corresponding <img> tag. The only feasible way to do all this is using a scripting language, as illustrated by the following, rather naive, php code

   <?php
   $mathtexurl = "http://www.yourdomain.com/cgi-bin/mathtex.cgi?";
   function verticalalign( $expression ) {
      global $mathtexurl;
      // note: curl_init() stops at the first whitespace char in $url argument
      $expression = ereg_replace(" ","~",$expression); // so remove whitespace
      $url     = $mathtexurl . "\depth~" . $expression;
      $valign  = "0";
      $ch      = curl_init( $url );
      curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true );
      curl_setopt( $ch, CURLOPT_HEADER, true );
      $gif     = curl_exec( $ch );
      $errno   = curl_errno( $ch );
      curl_close( $ch );
      if ( $errno == 0 ) {
        $fields = explode("Vertical-Align:",$gif);
        $vfield = trim($fields[1]);
        $fldlen = strspn($vfield,"+-0123456789");
        $valign = substr($vfield,0,$fldlen); }
      return $valign;
      }
   function mathtextag( $expression ) {
      global $mathtexurl;
      $valign = verticalalign($expression);
      $url    = $mathtexurl . "\depth~" . $expression;
      echo ' <img src="',$url,'" ';
      echo ' style="Vertical-Align:',$valign,'px" ';
      echo ' alt="" border=0>', "\n";
      }
   ?>

Now you can write <?php mathtextag('\frac12\left(a^2+b^2\right)'); ?> wherever you want to see $\frac12\left(a^2+b^2\right)$ correctly aligned. Note that the php code automatically prepends \depth to your expression for you. (And also note that this code calls mathTeX twice to render each expression, once to get the Vertical-Align: header and build an <img> tag, and then again to render that tag. If you're a good php programmer and write better code, please email me a copy.)

mathTeX alternatives...

Other math-on-the-web solutions are discussed at www.tug.org/interest.html, and in the tex-faq/LaTex2Html and tex-faq/mathml. Several LaTeX-based solutions similar to mathTeX that you may want to look at are latexrender, mathtran, textogif, and gladTeX. However, if you can't install a TeX distribution on your server, then you may prefer to look at a stand-alone math rendering program like mimeTeX, which has no dependencies whatsoever, but which produces slightly lower quality images than LaTeX. Alternative kinds of solutions that you may want to look at are jsmath and techexplorer.

mathTeX web services...

If you have trouble installing mathTeX on your own server, a mathTeX web service is currently available. An <img> tag of the form

  <img src="http://www.forkosh.com/mathtex.cgi?c=\sqrt{a^2+b^2}"
   alt="" border=0 align=middle>

displays $c=\sqrt{a^2+b^2}$ wherever you put that <img> tag in your own document. Note that the typical /cgi-bin/mathtex.cgi? has been replaced by http://www.forkosh.com/mathtex.cgi? in this <img> tag, using mathTeX on my server to render your expression for you. For production use, please install mathTeX on your own server.

Installing mathTeX on your own server sets up a de facto web service, unless you compile it with the –DREFERER=\"domain\" switch, restricting requests to that specific domain. Until mathML becomes widespread, LaTeX-based web services, like mathTeX or alternatives, may be the best math-on-the-web solutions. If you set one up that's intended for public access, email me its url, and I'll add it to the following list...

url of service	test
http://www.forkosh.com/mathtex.cgi	$c=\sqrt{a^2+b^2}$
http://www.cyberroadie.org/cgi-bin/mathtex.cgi	$c=\sqrt{a^2+b^2}$
http://www.problem-solving.be/cgi-bin/mathtex.cgi	unavailable
http://www.openmaths.org/cgi-bin/mathtex.cgi	unavailable

The "test" column just exercises the link to its left. Thanks to everyone.

An alternative mathTeX-based public web service you may also want to consider is Embedding math with replacemath.js, which allows you to embed math in your html pages without any <img> tags at all, just by writing LaTeX math markup between $$...$$ . Just prepare your html document in the form

  <HTML> <HEAD> <TITLE> test page </TITLE> </HEAD>
    <BODY>
      Put any LaTeX math expression you like between $$...$$,
      for example $$y=\frac1{1-x^2}$$ renders 
    </BODY>
      <script type="text/javascript"
        src="http://mathcache.s3.amazonaws.com/replacemath.js"> </script>
      <script type="text/javascript">
        replaceMath( document.body ); </script>
  </HTML>

That is, near the bottom of your document, after the </BODY> tag, place exactly the two <script> tags shown. Then, anywhere in your document, any LaTeX math expressions surrounded by $$...$$ will be rendered for you by their public web service.

(2) LaTeX math markup

MathTeX uses latex to render images, and you must already be familiar with LaTeX math markup to use it. If you're not, many online LaTeX tutorials are readily available. You may also want to browse Andrew Roberts' Latex Math I and Latex Math II, or my own LaTeX math tutorial. You can also download and read the AMS's Short math guide.

LaTeX markup...

Now, to try out mathTeX, just enter any expression you like in the Query Box below. I've started you out with a little example already in the box, or you can Click any of the Examples below to place that corresponding expression in the Query Box. Then press the Submit button, and mathTeX's rendering should be displayed in the little window immediately below it.

Now click Submit to see it rendered below...

You should see $f(x)=\int\limits_{-\infty}^x~e^{-t^2}dt$ if you submit the sample expression already in the box.

Examples...

Here are various additional random examples further demonstrating mathTeX's features and usage. To see how they're done, Click any one of them to place its corresponding expression in the Query Box above. Then press Submit to re-render it, or you can edit the expression first to suit your own purposes.

(1)

$\usepackage{color}\color{red}\large e^x=\sum_{n=0}^\infty\frac{x^n}{n!}$ $\usepackage{color}\color{blue}\Large e^x=\sum_{n=0}^\infty\frac{x^n}{n!}$ $e^x=\lim_{n\to\infty} \left(1+\frac xn\right)^n$

(2)

$f^\prime(x)\ = \lim_{\Delta x\to0}\frac{f(x+\Delta x)-f(x)}{\Delta x}$

definition of derivative

(3)

$\tilde y=\left\{ {\ddot x\mbox{ if $\widevec x$ odd} \atop\widehat{\,\bar x+1}\mbox{ if even}}\right.$

illustrating \left\{...\right.
and note the accents

(4)

$\overbrace{a,...,a}^{\mbox{k a's}}, \underbrace{b,...,b}_{\mbox{l b's}}\hspace{10} \large\underbrace{\overbrace{a...a}^{\mbox{k a's}}, \overbrace{b...b}^{\mbox{l b's}}}_{\mbox{k+l elements}}$

\overbrace{}^{} and \underbrace{}_{}
(TeXbook page 181, Exercise 18.41)

(5)

$A\ =\ \left( \begin{array}{cccc} a_{11}&a_{12}&\cdots&a_{1n}\\ a_{21}&a_{22}&\cdots&a_{2n}\\ \vdots&\vdots&\ddots&\vdots\\ a_{n1}&a_{n2}&\cdots&a_{nn}\end{array}\right)$

\begin{array}

(6)

$\parstyle\begin{eqnarray*} x+y+z&=&3\\2y&=&x+z\\2x+y&=&z\end{eqnarray*}$

using \begin{eqnarray*} to align equations

(3) MathTeX markup extensions

To facilitate its use in html <img> tags, mathTeX recognizes several special \directives that modify latex's behavior. These \directives are usually interpreted by mathTeX, and then removed from your expression before it's submitted to latex for rendering.

For example,

<img src="/cgi-bin/mathtex.cgi?\png x^2"> renders x^2 as a png image $\png x^2$ instead of the default gif format.
<img src="/cgi-bin/mathtex.cgi?\usepackage{color}\color{blue}x^2"> renders $\usepackage{color}\color{blue}x^2$ in blue. In this case, mathTeX removes the familiar LaTeX \usepackage directive from your math expression, and places it in the preamble where it belongs.

You can have as many special mathTeX \directives in an expression as you like. They're recognized anywhere at all in an expression, though these examples show them at the beginning. To simplify readability, additional examples below are more tersely illustrated as "query-string" rather than as <img src="/cgi-bin/mathtex.cgi?query-string">.

mathTeX directives...

\displaystyle or \textstyle or \parstyle

mathTeX's usual default wraps the ?query-string expression "\int_0^1 f(x)dx" as \[ \int_0^1 f(x)dx \], rendering it in LaTeX's \displaystyle math mode as $\int_0^1f(x)dx$ .
But the expression "\textstyle \int_0^1 f(x)dx" is wrapped as $ \int_0^1 f(x)dx $, rendering $\textstyle\int_0^1f(x)dx$ instead. However, if you compiled mathtex.cgi with the -DTEXTSTYLE option, then \textstyle is the default, and you can write \displaystyle in your expressions to override it.
Finally, writing \parstyle in an expression leaves it completely unwrapped, and rendered in LaTeX's paragraph mode. When using \parstyle, write your own \[ \]'s and $ $'s as needed. For example, "\parstyle\noindent the answer is $\frac89$" renders $\parstyle\noindent the anwser is $\frac89$$ . In this case you could just as easily write a LaTeX \mbox{ } in math mode. But you may find \parstyle useful for expressions using LaTeX's eqnarray environment, or for other purposes.

\usepackage{packagename}

When mathTeX sees a \usepackage in your expression, it's removed from the expression and placed in the preamble. So, for example, \usepackage{color} \color{blue} x^2+y^2 renders $\usepackage{color}\color{blue}x^2+y^2$ in blue. You can have up to nine \usepackages's in an expression. The preamble of mathTeX's default wrapper script already contains \usepackage[latin1]{inputenc}, \usepackage{amsmath} \usepackage{amsfonts} and \usepackage{amssymb}.

\tiny thru \Huge

mathTeX moves LaTeX's ten standard size directives outside the math mode wrapper, so that they can have their intended effect. For example, the expression "\Large x^2" is wrapped as \Large \[ x^2 \], rendering $x^2$ . LaTeX's \normalsize default renders $x^2$ . However, if your expression contains mathTeX's \parstyle directive, then any LaTeX size directives are left in place, exactly where you've written them.

\dpi{dots-per-inch}

mathTeX runs dvipng (or convert) at default screen resolution of 120dpi. The directive \dpi{300} generates a much larger 300dpi image instead. Here are samples of several dpi's rendered at \scriptsize and \normalsize,

dpi	\scriptsize	\normalsize
100	$\scriptsize c=\sqrt{a^2+b^2}$	$c=\sqrt{a^2+b^2}$
120	$\scriptsize c=\sqrt{a^2+b^2}$	$c=\sqrt{a^2+b^2}$
160	$\scriptsize c=\sqrt{a^2+b^2}$	$c=\sqrt{a^2+b^2}$
200	$\scriptsize c=\sqrt{a^2+b^2}$	$c=\sqrt{a^2+b^2}$

\gammacorrection{gamma-correction}

mathTeX runs dvipng with default gamma=2.5 (or convert with default 0.5). The directive \gammacorrection{3.5} renders a darker-than-usual gamma=3.5 image when run with dvipng (or lighter-than-usual when run with convert).
Note: This gamma correction confusion arises, I believe, as follows. Consider a grayscale from x=0 for black to x=1 for white. Then, the canonical formula to apply gamma correction $\gamma$ is $\mbox{x}\mapsto \mbox{x}^{1/\gamma}$ , whereby $\mbox{\raisebox{.5mm}{$\gamma$}}<1$ becomes blacker and $\mbox{\raisebox{.5mm}{$\gamma$}}>1$ becomes whiter. The convert program appears to follow this convention, whereas dvipng applies $\mbox{x}\mapsto \mbox{x}^{\gamma}$ instead.
Here are some samples (unchanging grayscale values up and down a column signal the corresponding program is unavailable)

gamma	dvipng	dvips/convert
0.25	$\dvipng \gammacorrection{0.25} c=\sqrt{a^2+b^2}$	$\dvips \gammacorrection{0.25} c=\sqrt{a^2+b^2}$
0.50	$\dvipng \gammacorrection{0.50} c=\sqrt{a^2+b^2}$	$\dvips \gammacorrection{0.50} c=\sqrt{a^2+b^2}$
1.0	$\dvipng \gammacorrection{1.0} c=\sqrt{a^2+b^2}$	$\dvips \gammacorrection{1.0} c=\sqrt{a^2+b^2}$
2.0	$\dvipng \gammacorrection{2.0} c=\sqrt{a^2+b^2}$	$\dvips \gammacorrection{2.0} c=\sqrt{a^2+b^2}$
4.0	$\dvipng \gammacorrection{4.0} c=\sqrt{a^2+b^2}$	$\dvips \gammacorrection{4.0} c=\sqrt{a^2+b^2}$

\gif or \png

mathTeX's default renders expressions as gif images. If you want a png image instead, write the directive \png in your expression. However, if you compiled mathtex.cgi with the –DPNG switch, then png is the default, and you can write \gif in your expression to obtain a gif image.

\dvips or \dvipng

mathTeX uses dvipng when it's available, or dvips and convert otherwise, to render LaTeX's dvi output as gif or png images. If all three programs are available on your server, then expressions containing \dvips are rendered using dvips/convert instead of dvipng. Or, when dvips/convert is the default (see \switches below), expressions containing \dvipng are rendered using dvipng instead of dvips/convert.

\quiet or \noquiet or \nquiet{n}

If any "! LaTeX Error:" is emitted while processing your expression, mathTeX's default replies <Enter> to the first three errors, and then replies "x", halting LaTeX before it produces a .dvi file. But if your expression contains \quiet, then mathTeX replies "q" to the first error, making LaTeX enter batchmode, whereas if your expression contains \noquiet, then mathTeX replies "x" to the first error, halting LaTeX immediately. If your expression contains \nquiet{n}, then mathTeX replies <Enter> to the first n errors, and then replies "x".

\depth

The special \depth directive signals mathTeX to emit an extra HTTP header field, of the form Vertical-Align: –nn , where –nn is the number of pixels (usually negative as illustrated) needed for a style="Vertical-Align: –nn px" attribute in the <img> tag used to render your expression. The vertical alignment section of this document discusses its use in more detail.

\cache or \nocache

By default, mathTeX saves each new image in its cache directory, rather than re-rendering the same image every time the same expression is submitted. But expressions containing \nocache are not cached. Expressions containing \today and/or \time are automatically not cached. Otherwise, include \nocache in your expression if it contains volatile information that might affect its appearance between renderings. (The \cache directive forces the image of that expression to be cached, but is usually unnecessary since caching is the default.)

\msglevel{verbosity}

To help debug problems that matheTeX's error messages don't resolve, resubmit the same failed expression with \msglevel{9} added.
After it fails again, login to a shell on your server, and cd cgi-bin/mathtex/ to mathTeX's cache directory. Then ls -alt|less to see the most recent files. These should include yourexpression.out (and yourexpression.gif if an image was created), where filename yourexpression is the 32-character MD5 hash of your failed expression.
Now cd .. back up to your cgi-bin/ directory, and you should see a new directory cgi-bin/yourexpression/ created by mathTeX. cd to it, and follow the command-line error instructions below. When done, you should probably rm -r cgi-bin/yourexpression/ which is no longer needed (ditto the .out and .gif files in mathTeX's cache if you want to clean up completely).

\which{programname}

mathTeX must be compiled with several –Dswitches that specify paths to its dependencies. If you can't determine these required paths, mathTeX's \which{programname} may provide some help (also see \switches below). For example,

directive	renders
\which{latex}	$\which{latex}$
\which{dvipng}	$\which{dvipng}$
\which{dvips}	$\which{dvips}$
\which{convert}	$\which{convert}$

displays known paths to mathTeX's dependencies, as they're installed on this server. However, there's a small "Catch-22" (circular logic that may bite you): mathTeX must already know these paths before it runs the programs that display them. You may be able to temporarily circumvent this problem by compiling

   cc mathtex.c –o mathtex.cgi

without any required switches at all. When compiled like this, mathTeX uses which to determine the required paths. If they're found, then mathTeX will run and display them; if not, you'll likely see message 7 or message 9 instead. If mathTeX does run, and displays the required paths, you should immediately re-compile it with the required –Dswitches. Execution time can be doubled, or even worse, when mathTeX has to find these paths itself.
When \which{programname} can't find the path, mathTeX displays $\parstyle\fbox{\footnotesize which(programname) = not found}$ instead. But mathTeX may also display $\parstyle\fbox{\footnotesize locate(programname) = /path/to/programname}$ , signalling that Unix which failed. In this case, mathTeX searches your server's locate database, if it exists, and displays that path instead. The "not found" message signals which and locate both failed.

\switches

Submitting the expression \switches to mathTeX renders $\switches$ , displaying several (more will be added) of mathTeX's compile-line switches. "Program image" isn't really a switch: it's the filename of the running program, usually mathtex.cgi unless you compiled it differently.
"Paths" displays what mathTeX knows about the full paths to its dependencies. On the right-hand side of each path is the source of that information. There are four possible sources, listed in order of reliablility (most reliable first):

(switch) means you compiled mathTeX with a –Dswitch for that path. You should always compile mathTeX with its dependencies: –DLATEX, and either –DDVIPNG or both –DDVIPS and –DCONVERT. When that's not possible, read \which{ } above and temporarily compile mathTeX without them.
(which) means the corresponding –Dswitch was not supplied, but Unix which found the program. If that's latex or another of your dependencies, then re-compile mathTeX with a –Dswitch containing the displayed information.
(locate) means Unix which failed, but your server's locate database found the path. Again, re-compile mathTeX if that's one of your dependencies.
(default) means no path information was found. A default path programmed into mathTeX is displayed instead. This default is frequently wrong. In fact, (default) typically means that the corresponding program isn't installed on your server at all. In that case, if the program is one of your dependencies, you'll likely see message 7 or message 9 instead of the \switches output illustrated above.

Either dvipng or dvips and convert can render LaTeX's dvi output as gif or png images. MathTeX's default choice is based on the reliablity of path information to these programs: (switch) is most reliable, followed by (which) or (locate), rated equally, and finally (default) is least realiable. If a (switch) path to dvipng is available (i.e., if you compiled mathTeX with a –DDVIPNG switch), then dvipng is default. Otherwise, if (switch) paths to both dvips and convert are available, then they're default. Otherwise, (which) or (locate) paths are preferred to (default), and dvipng wins a "tie".

\eval{ expression }

mathTeX can evaluate arithmetic expressions, which is a feature intended primarily for use in \newcommand's discussed below. Expressions can be built up from the following elements

digits 0-9 and numbers composed of uninterrupted (no whitespace) sequences of digits,
binary operators +, -, *, /, % (+ and - can be unary, preceding the first number in an expression, and % is the modulo operator),
balanced ( ... ) parentheses nested to any level (see below),
whitespace anywhere (except between digits comprising a number),
also interpreted by \eval{ } is a construction similar to (but not identical to) the ?: conditional, as follows. The expression (i?v0:v1:v2:etc), usually parenthesized as illustrated, evaluates to v0 if i evaluates to 0, or evaluates to v1 if i evaluates to 1, etc. If i < 0 then v0 is used, and if i is too large, the last v is used. All components, i and all v's, can themselves be expressions, even another (i?v0:v1:v2:etc), which in this case must be parenthesized. The only situation where parentheses aren't required is when i?v0:v1:v2:etc comprises your entire expression. For example, \eval{1+2?10:11:12:13:14:15} renders $\eval{1+2?10:11:12:13:14:15}$
and most importantly, the built-in variable
fs for current fontsize,
with 1=\tiny, 2=\scriptsize, ..., 10=\Huge,
which provides the capability for useful constructions, as follows...

All optional [ ] and mandatory { } numeric arguments for \rule[lift]{width}{height}, \raisebox{lift}[height][depth]{ }, etc, can be \eval{ }expressions as described above, rather than just numeric constants. By using the fs variable, you can construct \newcommand expressions that properly scale with font size. For example,
\small a\rule{1}{\eval{2*fs}pt}b renders $a\rule{1}{\eval{2*fs}pt}b$
\large a\rule{1}{\eval{2*fs}pt}b renders $a\rule{1}{\eval{2*fs}pt}b$
whose rendering automatically varies appropriately with font size. This kind of \newcommand construction is the primary use intended for mathTeX's expression evaluation feature.
But mathTeX also provides the \eval{expression} command to make the expression evaluation feature render "visible" results. It's not particularly useful, but an expression like 1+2+3+4+5=\eval{1+2+3+4+5} renders $1+2+3+4+5=\eval{1+2+3+4+5}$ .
Finally, one little "gotcha" is mathTeX's order of evaluation when interpreting expressions. Parentheses are respected as you'd expect. But within (...) parentheses, or in an unparenthesized expression, mathTeX finds the first (reading from the left) operator, then iteratively evaluates the separate subexpressions to that operator's left and to its right, and then finally combines those two separate results. So an expression like 2*3+4 renders 14, and you need to write (2*3)+4 to get 10.

\time

LaTeX's \today is usually sufficient for the slow-paced world of print. But you may want finer-grained resolution for the faster-paced online world. mathTeX provides \time for this purpose, replacing it with the current hh:mm:ss wherever it occurs. The date/timestamp at the top of this document is rendered by mathTeX with an expression like "\parstyle\begin{center}\today\\\time\end{center}". You can see the exact expression by clicking on that image. I'm not reproducing it here because mathTeX doesn't cache images containing \today or \time. So use \time sparingly because every occurrence is re-rendered through LaTeX.

\advertisement

An expression containing \advertisement is displayed along with your mathTeX advertisement rather than by itself, regardless of -DADFREQUENCY. For example,

c=\sqrt{a^2+b^2}		\advertisement c=\sqrt{a^2+b^2}
$c=\sqrt{a^2+b^2}$		$\advertisement c=\sqrt{a^2+b^2}$

See Advertisement to replace the default advertisement, illustrated above, with your own.

\version

An expression containing \version is displayed along with mathTeX's current version number. For example,

\version c=\sqrt{a^2+b^2}

$\version c=\sqrt{a^2+b^2}$

\environment

Submitting the expression \environment to mathTeX renders $\environment$ displaying the http environment variables known to mathTeX. This is primarily a programming aid, showing information available to mathTeX that might facilitate future enhancements.

(4) Installation and Testing

Note: The current release of mathTeX only runs
on Unix-like operating systems.

Very quickly --- First, install mathTeX's dependencies:
	a recent TeX distribution with dvipng, on your server, or see mimeTeX if you can't.
Then, download mathtex.zip and type
	unzip mathtex.zip cc mathtex.c –DLATEX=\"$(which latex)\" \ –DDVIPNG=\"$(which dvipng)\" \ –o mathtex.cgi (see –Dswitches below for more information).
Finally,
	mv mathtex.cgi to your cgi-bin/ directory, chmod permissions as necessary, and you're all done.
Read the rest of this section only if you want more information.

mathTeX's source code is standard Unix C, which should compile and run without change on any posix-compliant Unix platform. The current release of mathTeX only runs under Unix-like operating systems. The three steps needed to compile, install and test mathTeX are:

(1) Install LaTeX and download mathTeX...

First, make sure you have a recent
TeX distribution with dvipng installed on your server.
MathTeX's dependencies are the latex and dvipng programs, along with all necessary fonts, etc, from your TeX distribution.
If you prefer to compile mathTeX with the optional –DDVIPS and –DCONVERT switches (Step 2 immediately below), then dvips from your TeX distribution, and convert from the ImageMagick package, are used instead of dvipng.
These dependencies — always latex and either dvipng or dvips/convert — must all be installed on your server before you can run mathTeX. Ask your ISP or sysadmin if you have any questions or problems installing them. Or see mimeTeX if you can't install them.

Then download and unzip mathtex.zip in any convenient working directory. Your working directory should now contain

README	mathTeX release notes
COPYING	GPL license, version 3, under which you may use mathTeX
mathtex.c	mathTeX source program and all required functions
mathtex.html	this file, the mathTeX user manual

(2) Compile mathTeX and test it from the Unix shell...

To compile a mathTeX executable that emits default gif images generated by dvipng (recommended), just type
cc mathtex.c –DLATEX=\"$(which latex)\" \
–DDVIPNG=\"$(which dvipng)\" –o mathtex.cgi
Alternatively, to compile a mathTeX executable that emits default gif images generated by dvips/convert, just type
cc mathtex.c –DLATEX=\"$(which latex)\" \
–DDVIPS=\"$(which dvips)\" –DCONVERT=\"$(which convert)\" \
–o mathtex.cgi
But note that dvipng is easily twice as fast as dvips/convert, and it produces somewhat smaller image files.
For default png (instead of gif) images, add the optional –DPNG switch to either cc command above. All of mathTeX's optional compile-line switches are discussed below.
The required switches shown above define paths to mathTeX's dependencies, either latex and dvipng, or latex and dvips/convert. See required switches below for additional information about these path switches, including discussion of that $(which program) construction.
Immediately after compiling mathTeX, test it from the Unix shell by typing
./mathtex.cgi "x^2+y^2" –m 9 –o test
at the command prompt. After the copyright notice, screen output should look something like
```
    mathTeX> running image:     ./mathtex.cgi
    mathTeX> input expression:  "x^2+y^2"
    mathTeX> working directory: 8dfaf8281769c217b7e78b27a4747285/
    mathTeX> output image file: test.gif 
```
Bring up the output file test.gif in your browser, which should display the rendered image of x^2+y^2. If it does, you can rm -r that working directory and proceed to the next (Install) step. If not, there's some error that _must_ be fixed before proceeding: mathTeX is not going to emit gifs from your server if it won't run from the command line.
To troubleshoot command-line errors...
- First, cd 8dfaf8281769c217b7e78b27a4747285/ to that working directory (whose name is the 32-character MD5 hash of your expression) shown on the screen output above.
- If it's not an empty file, view latex.err A message something like latex: command not found probably means that your –DLATEX=\"path/to/latex\" is wrong, or that latex is installed wrong. Fix that, or any other indicated error, and then re-compile mathTeX and test it again.
- Otherwise, if latex.err is empty, then view latex.out which contains runtime messages issued by latex, including messages reporting unresolved errors. For example, \usepackage{junk} reports the error File `junk.sty' not found. Find and fix any reported errors, and then re-compile mathTeX and test it again.
- If latex.err and latex.out contain no errors, then latex.dvi should contain the dvi image of your expression. Check it with xdvi or any other dvi viewer supplied with your latex distribution. Then view dvipng.err and dvipng.out for any reported errors (note that dvipng emits a benign copyright message to dvipng.out).
- You should have found some error along the way. Troubleshoot as necessary. Your most likely (and most obvious) problems are: mathTeX's dependencies are installed incorrectly or not at all, you compiled mathtex.cgi with the wrong paths (check which's output), or you don't have rw permissions in the directory you're testing from.

(3) Install mathTeX and test it from a browser...

Install your compiled mathtex.cgi executable only after successfully testing it from the Unix shell. Just
mv mathtex.cgi to your web server's cgi-bin/ directory,
chmod permissions as necessary, and you're all done.
cgi-bin/mathtex.cgi must be executable by your web server, and it must have rw permissions in the cgi-bin/ directory where it's installed. The first time it runs, mathtex.cgi will mkdir mathtex/, where rendered images are subsequently cached. Permissions and ownerships must be set to allow this. chmod 755 typically works, but ask your ISP or sysadmin if you have any questions or problems.
Immediately after installation, type a url into your browser's locator window something like
http://www.yourdomain.com/cgi-bin/mathtex.cgi?\message
which should display message 1
$\message$
in the upper-left corner of your window. If, instead, you see Not Found or Error 500 emitted by your server, then mathTeX isn't running. Check that you installed it in the correct directory, set its permissions properly, etc.
The preceding test just checked that mathtex.cgi runs from your server. This current test checks that your –DLATEX, etc, paths are correct, and that mathtex.cgi has rw permissions in your cgi-bin/ directory. Type a url into your browser's locator window something like
http://www.yourdomain.com/cgi-bin/mathtex.cgi?x^2+y^2
which should display $x^2+y^2$ in the upper-left corner of your window, just like clicking this link does, which tests my mathtex.cgi,
http://www.forkosh.com/cgi-bin/mathtex.cgi?x^2+y^2
If you see the same image from your own yourdomain link, then you've completed a successful mathTeX installation.
Otherwise, you'll probably see one of mathTeX's error messages illustrated below. Read the accompanying description, and try to resolve the problem accordingly.

Run-time error messages...

Gif images for 15 messages are embedded in mathTeX, displayable so long as mathtex.cgi can run from your server, even without latex and without rw permissions in your cgi-bin/ directory. In addition, your server may display the first two messages below if mathtex.cgi can't run. Any embedded mathTeX message can be intentionally displayed by submitting an expression containing the special mathTeX directive \message{1} through \message{15} (an out-of-bounds argument, or \message with no argument, displays message 1). Otherwise, various errors signal "unintentional" displays of the corresponding message, e.g., if your –DLATEX switch specifies the wrong path to latex, then you'll see message 7 (unless some earlier error supercedes it).

Message	Description

The requested URL was not found.	You typed the wrong url, or mathtex.cgi is not installed where you think it is.

Internal server error 500	If mathtex.cgi's permissions are chmod'ed improperly, if your account isn't set up to run cgi's, etc, then mathTeX will not run at all. You'll probably see this error message emitted by your server instead.

$\message{1}$	Immediately after installing mathtex.cgi to your cgi-bin/ directory, type a url of the form yourdomain.com/cgi-bin/mathtex.cgi?\message into your browser. You should see this message. It means mathtex.cgi ran successfully, its permissions are set properly, and the account hosting yourdomain can run cgi's.

$\message{2}$	Traps any otherwise unidentified error condition.

$\message{3}$	The combination of permissions/ownerships on mathtex.cgi itself, and on the cgi-bin/ directory where it's installed, prohibit mathTeX from creating its cache directory mathtex/ underneath cgi-bin/. Change permissions/ownerships as needed.

$\message{4}$	Same problem as message 3 above, except this time mathTeX can't create a temporary work directory under cgi-bin/.

$\message{5}$	Unanticipated error. MathTeX should be able to cd to a directory it just created.

$\message{6}$	Unanticipated error. MathTeX should be able to open a file (for write) in a directory it just created.

$\message{7}$	Either latex is not installed, or your –DLATEX path to it is incorrect. It's also possible that the shell host on which you compiled mathTeX has different volumes or mount points than your server (see path switches). Check with your ISP or sysadmin, or try mathTeX's \which directive.

$\message{8}$	A simple latex error, like \alfa instead of \alpha, should not cause this problem (unless your expression contains \noquiet). It's more likely caused by a missing font or package, etc. Simplify your expression until it works, and see if that helps identify the cause. Or add \msglevel{9} to your expression, and check files latex.out and latex.err for error messages.

$\message{9}$	Either dvipng is not installed, or your –DDVIPNG path to it is incorrect. Also see the remark in message 7.

$\message{10}$	Rerun the same expression with \msglevel{9} added. Then check files latex.out and latex.err, and dvipng.out and dvipng.err for any clues to the cause of this error.

$\message{11}$	Either dvips is not installed, or your –DDVIPS path to it is incorrect. Also see the remark in message 7.

$\message{12}$	Rerun the same expression with \msglevel{9} added. Then check files latex.out and latex.err, and dvips.out and dvips.err for any clues to the cause of this error.

$\message{13}$	Either convert is not installed, or your –DCONVERT path to it is incorrect. Also see the remark in message 7.

$\message{14}$	Rerun the same expression with \msglevel{9} added. Then check files latex.out and latex.err, dvips.out and dvips.err, and convert.out and convert.err for any clues to the cause of this error.

$\message{15}$	An image file was apparently created successfully, but is now inaccessible to mathTeX. Rerun the same expression. If it fails again, rerun it with \msglevel{9} added. Then check all .out and .err files for any clues to the cause of this error.

Compile-line switches...

Required switches...

MathTeX's required –D switches specify paths to the programs it needs to render LaTeX expressions as images. Your Unix PATH environment variable usually contains the directories where these programs reside. And in that case, the Unix shell command which progname emits the string /path/to/progname.
Then you can manually copy which's output to the switch, e.g., if which latex emits /usr/bin/latex then just write the switch –DLATEX=\"/usr/bin/latex\" Alternatively, you can use the Unix shell's $( ) construction to automatically pipe which's output into the switch, e.g., –DLATEX=\"$(which latex)\" automatically places that same path to latex between the literal \" \" quotes.
If which doesn't work, you must nevertheless make sure that latex and mathTeX's other dependencies are all installed on your server. Then determine the proper paths to them yourself (ask your ISP or sysadmin, or try mathTeX's \which directive), and manually write mathTeX's required –D switches as described above.
Occasionally, which may seem to work, but actually doesn't, because your shell account and internet server are hosted on different machines, with different volumes mounted and/or different mount points. When this happens, server volumes are nfs-mounted by your shell machine, so you can work on your internet files. Conversely, shell volumes aren't necessarily mounted by the server, so latex could be visible from your shell but not from the server. Check with your ISP or sysadmin about network topology if you suspect something like this, or mathTeX's \which directive may help. In any case, mathTeX's dependencies, latex and either dvipng or dvips/convert, must be available to your server, and you must compile mathtex.cgi with their paths on your server.

–DLATEX=\"/path/to/latex\"
–DDVIPNG=\"/path/to/dvipng\"

mathTeX always requires the –DLATEX switch, and its recommended default (using dvipng to render latex's dvi output as gif or png images) also requires the –DDVIPNG switch. So your standard cc command to compile mathTeX looks like
cc mathtex.c \
–DLATEX=\"$(which latex)\" \
–DDVIPNG=\"$(which dvipng)\" \
–o mathtex.cgi

–DDVIPS=\"/path/to/dvips\"
–DCONVERT=\"/path/to/convert\"

If you can't (or don't want to) use dvipng, then compile mathTeX with the –DDVIPS and –DCONVERT switches (instead of –DDVIPNG). Then dvips from your TeX distribution, and convert from the ImageMagick package, are used (instead of dvipng) to render latex's dvi output as gif or png images. In this case, your cc command to compile mathTeX looks like
cc mathtex.c \
–DLATEX=\"$(which latex)\" \
–DDVIPS=\"$(which dvips)\" \
–DCONVERT=\"$(which convert)\" \
–o mathtex.cgi
Finally, if all three programs (dvipng and dvips and convert) are installed on your server, you can compile mathTeX with all the –D switches. This defaults to dvipng, but permits users to submit expressions containing the special \dvips and \dvipng directives, regardless of mathTeX's default. So a comprehensive cc command looks like
cc mathtex.c \
–DLATEX=\"$(which latex)\" \
–DDVIPNG=\"$(which dvipng)\" \
–DDVIPS=\"$(which dvips)\" \
–DCONVERT=\"$(which convert)\" \
–o mathtex.cgi
along with any other optional switches you choose from those described below,

Optional switches...

In addition to the –DLATEX and –DDVIPNG switches required on the mathTeX's compile line, as discussed above, you may also include the following optional –D switches, whose functionality is discussed below. Whenever a switch takes a value, its default value is illustrated. An italicized value means there is no default.

–DCACHE=\"mathtex/\"

By default, mathTeX saves each new image it renders to a file in directory mathtex/ (relative to the cgi-bin/ directory where you installed mathtex.cgi). Then, every time it's given the same expression, mathTeX reads that file rather than re-rendering the same image. You can specify any other cache directory with the –DCACHE=\"path/\" switch. Either way, mathTeX's cache directory must be read/writable by it, so set permissions (typically chmod 755) as necessary.
mathTeX occasionally disables caching, e.g., expressions containing \today are always re-rendered since the date may have changed. Otherwise, caching is mandatory and cannot be disabled.
Cached image files are named filename.gif or filename.png, where filename is the 32-character MD5 hash of the LaTeX expression. When caching a new image, mathTeX also updates the file path/mathtex.log containing a timestamp, filename, LaTeX expression, and http referer for each new file created. A sample entry looks like

---------------------------------------------------------------------
2007-10-11:09:00:53am            f8ccc8dd93c8eeb1d9c40b353ef781e0.gif
\LARGE x=\frac{-b\pm\sqrt{b^2-4ac}}{2a}
http://www.forkosh.com/mathtex.html
---------------------------------------------------------------------

–DGIF or –DPNG

mathTeX generates gif or png images. Users can specify which format they want by including a \gif or \png mathTeX directive in submitted expressions. Otherwise, mathTeX's default is specified at compile time by a –DGIF or –DPNG switch. If a submitted expression contains neither directive, and if mathTeX was compiled with neither switch, then gif is the default.

–DDISPLAYSTYLE or –DTEXTSTYLE or –DPARSTYLE

mathTeX's default wraps user expressions inside \[ \], rendering generated images in LaTeX's \displaystyle math mode. The –DTEXTSTYLE switch wraps expressions inside $ $, rendering generated images in LaTeX's \textstyle math mode. And the –DPARSTYLE switch leaves expressions unwrapped, rendering generated images in LaTeX's default paragraph mode. Users can override any compiled default with a mathTeX style directive.

–DFONTSIZE=5

You can specify –DFONTSIZE=1 thru –DFONTSIZE=10 on mathTeX's compile line, corresponding to default LaTeX font sizes \tiny thru \Huge. If no switch is supplied, the default 5 corresponds to \normalsize. Users can override any compiled default with a mathTeX \tiny...\Huge directive.

–DDPI=\"120\"

The –DPI switch changes mathTeX's default screen resolution of \"120\" dots-per-inch, which you enter as a string. Some samples are illustrated above.

–DGAMMA=\"2.5\"

The –DGAMMA switch changes mathTeX's default gamma correction of \"2.5\" (for dvipng), which you enter as a string. Some samples are illustrated above.

–DQUIET or
–DNOQUIET or
–DNQUIET=n

If any "! LaTeX Error:" is emitted while processing your expression, mathTeX's default replies <Enter> to the first three errors, and then replies "x", halting LaTeX before it produces a .dvi file. Compiling mathTeX with –DQUIET replies "q" to the first error, making LaTeX enter batchmode, whereas compiling with –DNOQUIET replies "x" to the first error, halting LaTeX immediately. Compiling mathTeX with –DNQUIET=n replies <Enter> to the first n errors, and then replies "x". User expressions may contain \quiet, \noquiet or \nquiet{n} to override any compiled default.

–DREFERER=\"domain\" or
–DREFERER=\"domain1,domain2,etc\"

If you compile mathTeX without a –DREFERER=\" \" switch, then anyone on the internet can use your mathtex.cgi program by writing a url of the form http://www.yourdomain.com/cgi-bin/mathtex.cgi?x^2+y^2. So you're essentially providing mathTeX as a free web service. I encourage this if you have the compute and disk resources to spare.
Otherwise, if compiled with –DREFERER=\"domain\", then mathTeX performs a case-insensitive search of the environment variable HTTP_REFERER to verify that it contains the authorized domain as a substring.
Or, if given a comma-separated list containing several domain's (second form of the switch), then HTTP_REFERER must contain either domain1 or domain2, or etc, as a (case-insensitive) substring.
If HTTP_REFERER doesn't contain a substring matching any of these domain(s), then mathTeX emits the error message image (reporting HTTP_REFERER on the first line)
$\invalidreferer\small\sqrt{a^2+b^2}$
instead of the requested image.

–DKILLTIME=10

Some expressions can unintentionally (or not) force LaTeX to loop endlessly, causing mathTeX to hang. To avoid this problem, if LaTeX fails to complete within KILLTIME seconds, mathTeX kills it and emits an error. The built-in code for this purpose is in mathTeX's timelimit( ) function, which was adapted from timelimit-1.4. Compiling mathTeX with –KILLTIME=0 places no timelimit restrictions on LaTeX whatsoever; probably not a good idea.

–DTIMELIMIT=\"/path/to/timelimit\"

Rather than using mathTeX's built-in timelimit( ) code to throttle LaTeX (see –DKILLTIME immediately above), you may optionally install a standalone copy of timelimit-1.4 and use that instead. Compiling mathTeX with a switch of the form –TIMELIMIT=\"$(which timelimit)\" uses your installed program instead of mathTeX's built-in timelimit( ) function to throttle LaTeX.

–DMAXMSGLEVEL=999999

If you're running mathTeX as a web service, you should probably compile it with the –DMAXMSGLEVEL=0 switch. This sets the maximum verbosity allowed in a \msglevel{ } directive. At 9 and above, the work directory and files temporarily created by mathTeX to run latex are left in place as a debugging aid. These remain on your file system unless manually removed. And remote users can't access them, anyway.

–DUSEPACKAGE=\"filename\"

The preamble of mathTeX's default LaTeX wrapper script already contains \usepackage[latin1]{inputenc}, \usepackage{amsmath} \usepackage{amsfonts} and \usepackage{amssymb}. All these packages are used with every expression submitted to mathTeX for rendering. And a specific expression may contain one or more \usepackage{ } directive's applied to that expression only. However, if you want additional packages applied to every expression, edit a file containing lines of the form
"\\usepackage{color}\n"
"\\usepackage{bm}\n"
"etc\n"
and place a corresponding –DUSEPACKAGE=\"filename\" switch on mathTeX's compile line. Every line in the file is enclosed in "quotes", contains a \n before the closing quote, and all other backslashes are written as double-backslashes \\. And note that, although \usepackage's are illustrated, you aren't limited to them. All directives from this file are just placed in mathTeX's preamble. So you can modify the preamble any way you like.

–DNEWCOMMAND=\"filename\"

Besides modifying the preamble, you may also want to modify the LaTeX wrapper script's body, particularly with (though not limited to) \newcommand's. Again, edit a file containing lines of the form
"\\newcommand{\\vec}[2]{\\left({#1}_1,\\ldots,{#1}_{#2}\\right)}\n"
"etc\n"
and place a corresponding –DNEWCOMMAND=\"filename\" switch on mathTeX's compile line. The same editing rules apply: every line in the file is enclosed in "quotes", contains a \n before the closing quote, and all other backslashes are written as double-backslashes \\.
\renewcommand's in this file are useful to disable LaTeX commands that might pose security risks in mathTeX. For example, although Unix's /etc/passwd file doesn't actually contain passwords, you probably don't want users submitting expressions like \input{/etc/passwd}. MathTeX already disables \input with
"\\renewcommand{\\input}[1]{\\mbox{[[$\\backslash$input\\{#1\\} illegal]]}}\n"
which just displays [[\input{file} illegal]] when the user tries to \input{file}. You may want to disable other commands as well.

Advertising switches...

The next three switches set up a mathTeX web service that embeds advertising messages along with rendered images. See mathTeX web service above for further discussion.

–DADFREQUENCY=0

If ADFREQUENCY is defined as a positive number n, then one request out of every n submitted to mathTeX is randomly selected to be displayed along with a pre-defined "advertisement". For example, if your expression is \large\int_0^xe^{-x^2}dx, then the default advertisement displays
$\advertisement \int_0^xe^{-x^2}dx$ instead of just $\int_0^xe^{-x^2}dx$
See the –DADVERTISEMENT switch below for instructions to define your own advertisement replacing my default.

–DHOST_SHOWAD=\"\\000\"

Advertisement messages are usually displayed randomly, in one request to mathTeX out of every n, as defined by the –DADFREQUENCY switch above. But if a HOST_SHOWAD string is also defined, then advertisements are only displayed when mathTeX is running on a host whose HTTP_HOST (or SERVER_NAME) environment variable contains that string. For example, –DHOST_SHOWAD=\"mathsite\" displays advertisements on www.mathsite.com but never on www.mathhouse.com . The default HOST_SHOWAD value is an empty string, which displays advertisements on any host.

–DADVERTISEMENT=\"filename\"

To define your own advertisement, replacing my default illustrated immediately above, edit a file containing lines of the form
"\\begin{center}\n"
"\\fbox{$\\mbox{\\footnotesize\\LaTeX{} rendering courtesy of}\n"
"\\atop \\mbox{\\scriptsize http://www.forkosh.com/mathtex.html}$}\\\\ \n"
"\\vspace*{-4mm}\n"
" %%beginmath%% %%expression%% %%endmath%% \n"
"\\end{center}\n"
Use the same editing rules as –DUSEPACKAGE and –DNEWCOMMAND above: every line in the file is enclosed in "quotes", contains a \n before the closing quote, and all other backslashes are written as double-backslashes \\. Note \\\\ at the end of the third line, which LaTeX sees as \\. The entire example shows how my default advertisement is defined.
Your advertisement may consist of any valid LaTeX commands you like. But it must somewhere contain the line
" %%beginmath%% %%expression%% %%endmath%% \n"
which is replaced by the user's expression, surrounded by whatever math mode delimiters it specifies. The document remains in paragraph mode, allowing $ $ and \[ \] to be placed wherever you like.
Once mathTeX is compiled with your advertisement, test it by submitting an expression like \advertisement x^2+y^2 containing the special mathTeX \advertisement directive, which forces that expression to be rendered with your advertisement. In this case (and with my default advertisement message) we see
$\advertisement x^2+y^2$ instead of just $\png x^2+y^2$
regardless of your ADFREQUENCY value.

Running mathTeX from the shell...

MathTeX is usually run by your web server as a cgi program, obtaining its input expression from the query-string of an html <img> tag. But you can also run mathTeX from your Unix shell, supplying all input on the command line. For example, ./mathtex.cgi "x^2+y^2" –o equation1 renders an image of x^2+y^2 in file equation1.gif. And with the –m 9 switch, it's also useful for testing.

The complete command-line syntax for mathTeX is

   ./mathtex.cgi "expression"     expression in quotes, e.g., "x^2+y^2",
               | -f input_file    or read (unquoted) expression from input_file
               [ -o output_file ] write image to ouput_file instead of cache
               [ -m msglevel ]    verbosity of debugging message level
               [ -c cache_directory ]   path to cache directory

   "expression"    Either place LaTeX expression directly on
        the command line, between "quotes", with no -switch
        preceding it, or.....

   -f input_file   .....read (unquoted) expression from input_file.
        The input_file may contain the expression on one line
        or spread out over many lines.  If -o is not also given,
        it defaults to the same filename, e.g., -f expression.tex
        produces output file expression.tex.gif unless an
        explicit -o switch is given.

   -o output_file  write output gif or png image to this filename,
        with .gif or .png extension added to it.  If you want the
        image file written in a directory other than your pwd,
        then specify  -o path/output_file  instead.

   -m msglevel     0-99, controls verbosity/message level for
        debugging output.  If msglevel>=9 then the temporary
        directory containing latex-dvips-convert output is
        not removed.  This is your major debugging aid.

   -c cache_directory  If you specify  -o output_file  then no
        cache directory is used (-c is ignored even if you supply it).
        But if you don't specify  -o output_file  then mathTeX writes
        the rendered image to a filename in its usual cache directory
        path.  This switch maintains the standard mathTeX filename
        convention, but writes files into the specified cache directory
        instead.

   Test or Debugging Example:

     ./mathtex.cgi "\Large\frac1{\sqrt{x^2+y^2}}" -o equation1 -m 9
        creates file equation1.gif and saves all the intermediate
        work in temp subdirectory 673d88e172f77f0aafabf6d72e5777ba/
        which is the MD5 hash of the input expression.

     After the copyright notice, screen output from the above command
     should look something like
        mathTeX> running image:     ./mathtex.cgi
        mathTeX> input expression:  "\Large\frac1{\sqrt{x^2+y^2}}"
        mathTeX> working directory: 673d88e172f77f0aafabf6d72e5777ba/
        mathTeX> output image file: equation1.gif

   Production Example (same as above, but without -m 9):

     ./mathtex.cgi "\Large\frac1{\sqrt{x^2+y^2}}" -o equation1
        creates file equation1.gif containing an image of
        the expression (all intermediate work files are removed).

     After the copyright notice, screen output from the above command
     should look something like
        mathTeX> input expression:  "\Large\frac1{\sqrt{x^2+y^2}}"
        mathTeX> output image file: equation1.gif
     Redirect stdout to /dev/null if you don't want to see it.

(5) GPL License

"My grandfather once told me there are two kinds of people:
Those who do the work and those who take the credit.
He told me to try to be in the first group; there was much less competition."
Indira Gandhi, the late Prime Minister of India

MathTeX's copyright is registered by me with the US Copyright Office, and I hereby license it to you under the terms and conditions of the GPL. There is no official support of any kind whatsoever, and you use mathTeX entirely at your own risk, with no guarantee of any kind, in particular with no warranty of merchantability.

By using mathTeX, you warrant that you have read, understood and agreed to these terms and conditions, and that you possess the legal right and ability to enter into this agreement and to use mathTeX in accordance with it.

Hopefully, the law and ethics regarding computer programs will evolve to make this kind of obnoxious banter unnecessary. In the meantime, please forgive me my paranoia.

To protect your own intellectual property, I recommend (both pdf) Copyright Basics from The Library of Congress, in particular Circular 61, Copyright Registration for Computer Programs. Very briefly, download Form TX and follow the included instructions. In principle, you automatically own the copyright to anything you write the moment it's on paper. In practice, if the matter comes under dispute, the courts look _very_ favorably on you for demonstrating your intent by registering the copyright. For example, courts will stop unauthorized use of unregistered material, but monetary damages are awarded _only_ if you register the copyright before infringement occurs.

Concluding Remarks

I hope you find mathTeX useful. If so, a contribution to your country's TeX Users Group, or to the GNU project, is suggested, especially if you're a company that's currently profitable.

$\blue{\small\rm You're the } \Large\counter[mathtexcounters.log] {mathtexcounters.txt:mathtex.html}\\[0] {\small\rm visitor to this page.}$