m a t h T e X   m a n u a l
( for mathTeX version 1.01 )
Click for:   download mathTeX

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


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

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, if you're using phpBB3, 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>   Then you can simply write [tex] ... [/tex] to obtain mathTeX images of the enclosed expression.
      Similarly, if you're using phpBB2, then Jameson contributed the following one-line mod that also 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);

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
Wikimedia   "mimeTeX alternative"
MathWiki   "mimeTeX Parser"
PunBB   mimeTeX plugin
Movable Type   mimeTeX plugin
WordPress   mimeTeX plugin

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.

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.dreamhost.com/mathtex.cgi?c=\sqrt{a^2+b^2}"
   alt="" border=0 align=middle>

displays 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.dreamhost.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.dreamhost.com/mathtex.cgi
http://www.cyberroadie.org/cgi-bin/mathtex.cgi
http://www.problem-solving.be/cgi-bin/mathtex.cgi

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

(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.

First enter your own LaTeX expression, or Click any example...

     
Now click Submit to see it rendered below...

You should see   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)            
(2)
definition of derivative
(3) illustrating \left\{...\right.
and note the accents
(4) \overbrace{}^{} and \underbrace{}_{}
(TeXbook page 181, Exercise 18.41)
(5)
\begin{array}
(6) 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,

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 .
      But the expression   "\textstyle \int_0^1 f(x)dx"   is wrapped as   $ \int_0^1 f(x)dx $,   rendering 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   .   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 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 .   LaTeX's \normalsize default renders .   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
120
160
200
\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  is , whereby  becomes blacker and  becomes whiter. The convert program appears to follow this convention, whereas dvipng applies 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
0.50
1.0
2.0
4.0
\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
mathTeX's default runs LaTeX in "quiet" mode, i.e., replying "q" to any LaTeX error prompt emitted during processing. But if your expression contains   \noquiet,   then LaTeX halts after any error, without generating a dvi. However, if mathtex.cgi was compiled with the –DNOQUIET switch, then \noquiet is the default, and you may write   \quiet   in your expression to run LaTeX in "quiet" mode.
\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{dvipng}
\which{dvips}
\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 instead. But mathTeX may also display , 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
 ,
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): 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".
\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}  
 
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}  

(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...

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

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

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.
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.
Traps any otherwise unidentified error condition.
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.
Same problem as message 3 above, except this time mathTeX can't create a temporary work directory under cgi-bin/.
Unanticipated error. MathTeX should be able to cd to a directory it just created.
Unanticipated error. MathTeX should be able to open a file (for write) in a directory it just created.
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.
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.
Either dvipng is not installed, or your –DDVIPNG path to it is incorrect. Also see the remark in message 7.
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.
Either dvips is not installed, or your –DDVIPS path to it is incorrect. Also see the remark in message 7.
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.
Either convert is not installed, or your –DCONVERT path to it is incorrect. Also see the remark in message 7.
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.
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.
–DNOQUIET
If you don't specify   –DNOQUIET,   then mathTeX's usual default runs LaTeX in "quiet" mode, i.e., replying "q" to any LaTeX error prompt emitted during processing. If you do specify it, then LaTeX halts after any error, without generating a dvi. User expressions may contain either \noquiet or \quiet to override either 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)
     
instead of the requested image.
–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 two 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
          instead of just    
See the –DADVERTISEMENT switch immediately below for instructions to define your own advertisement replacing my default.
–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
          instead of just    
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 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.

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