'; 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 ## (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){\footnotesizeds$}} \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){\footnotesizeds}} \put(.6,.5){\makebox(0,0){\footnotesizex=0}} \put(3.36,.5){\makebox(0,0){\footnotesizex=\ell}} \dottedline{.05}(1.0,.575)(1.0,1.10) \put(1.0,.5){\makebox(0,0){\footnotesizex}} \dottedline{.05}(1.5,.575)(1.5,1.40) \put(1.5,.5){\makebox(0,0){\footnotesizex+dx}} \put(1.22,.65){\makebox(0,0){\footnotesizedx}} \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){\footnotesizeT}} \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){\footnotesizeT}} \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 $$...$$ 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 $${TEXT}$$   with the HTML replacement <img src="/cgi-bin/mathtex.cgi?{TEXT}" align=middle>   Now you can also write $$...$$ 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 $\small f(x)=\int\limits_{-\infty}^xe^{-t^2}dt$ doesn't look as good as the same image $\small 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,'" ';
–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}$
–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\"
"\\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.
$\advertisement x^2+y^2$     instead of just     $\png x^2+y^2$

### 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,

-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

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

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

 Copyright © 2007-2012, John Forkosh Associates, Inc. email: john@forkosh.com $\blue{\small\rm You're the } \Large\counter[mathtexcounters.log] {mathtexcounters.txt:mathtex.html}\\[0] {\small\rm visitor to this page.}$