mathtex-1.03/ 0000755 0000000 0000000 00000000000 11304541772 011611 5 ustar root root mathtex-1.03/README 0000644 0000000 0000000 00000021067 11154115711 012470 0 ustar root root
--------------------------------------------------------------------------
March 6, 2009 Version 1.02
m a t h T e X R e a d m e F i l e
Copyright(c) 2007-2009, John Forkosh Associates, Inc. All rights reserved.
--------------------------------------------------------------------------
by: John Forkosh
john@forkosh.com www.forkosh.com
This file is part of mathTeX, which is free software.
You may redistribute and/or modify it under the terms
of the GNU General Public License, version 3 or later,
as published by the Free Software Foundation. See
http://www.gnu.org/licenses/gpl.html
mathTeX is discussed and illustrated online by
the mathTeX manual at its homepage
http://www.forkosh.com/mathtex.html
Or you can follow the Installation instructions in
Section II below to immediately install mathTeX on
your own server.
I. 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 ![]()
tag in your document wherever you want
to see the corresponding LaTeX expression. For example,
=\int_{-\infty}^xe^{-t^2}dt)
immediately displays the corresponding gif image wherever you put
that ![]()
tag.
There's no inherent need to repeatedly write the cumbersome ![]()
tag
illustrated above. 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
Then users can just type
[tex] f(x)=\int_{-\infty}^xe^{-t^2}dt [/tex]
in their posts to see a gif image of the enclosed expression.
MathTeX uses the latex and dvipng programs, along with all necessary
fonts, etc, from your TeX distribution. If dvipng is not available,
you can compile mathTeX to use dvips from your TeX distribution, and
convert from the ImageMagick package, instead. Links to online sources
for all these dependencies are on http://www.forkosh.com/mathtex.html
and several are listed below.
II. INSTALLATION
------------------------------------------------------------------------
Note: The current release of mathTeX only runs under Unix-like
operating systems. To compile and install mathTeX on your own
Unix server...
+---
| Install mathTeX's dependencies and download mathTeX
+----------------------------------------------------
* First, make sure you have a recent LaTeX distribution
http://www.latex-project.org/ftp.html
installed on your server. Ask your ISP or sysadmin
if you have any installation problems or questions.
Or see http://www.forkosh.com/mimetex.html if you
can't install latex.
Besides latex, mathTeX uses dvipng, which recent
LaTeX distributions typically include. If you can't
install dvipng, see http://www.forkosh.com/mathtex.html
for instructions to use dvips and convert instead of dvipng.
* Then, download http://www.forkosh.dreamhost.com/mathtex.zip
and unzip mathtex.zip in any convenient working
directory. Your working directory should now contain
mathtex.zip your downloaded gnu zipped mathTeX distribution
README this file (see mathtex.html for demo/tutorial)
COPYING GPL license, under which you may use mathTeX
mathtex.c mathTeX source program and all functions
mathtex.html mathTeX users manual
+---
| Compile and Install mathTeX
+----------------------------
* To compile an executable that emits
default gif images
cc mathtex.c -DLATEX=\"$(which latex)\" \
-DDVIPNG=\"$(which dvipng)\" \
-o mathtex.cgi
For default png images, add the -DPNG switch. Additional
command-line switches that you may find useful are
discussed at http://www.forkosh.com/mathtex.html
* Finally,
mv mathtex.cgi to your server's cgi-bin/ directory,
chmod its permissions as necessary (typically 755),
making sure mathtex.cgi can rw files in cgi-bin/,
and you're all done.
+---
| Test installed image
+---------------------
* To quickly test your installed mathtex.cgi, 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 the same image that you see at
http://www.forkosh.com/cgi-bin/mathtex.cgi?x^2+y^2
If you see the same image from your own domain link,
then you've completed a successful mathTeX installation.
* Optionally, to install a copy of the mathTeX manual
on your server,
mv mathtex.html to your server's htdocs/ directory.
And, if the relative path from htdocs to cgi-bin
isn't ../cgi-bin, then edit mathtex.html and change
the few dozen occurrences as necessary. Now,
http://www.yourdomain.com/mathtex.html
should display your own copy of the mathTeX manual.
Any problems with the above?
Read the more detailed instructions on mathTeX's homepage
http://www.forkosh.com/mathtex.html
III. REVISION HISTORY
------------------------------------------------------------------------
See http://www.forkosh.com/mathtexchangelog.html for a detailed
discussion of mathTeX revisions.
o 11 Oct 2007 -- mathTeX version 1.00 released.
o 12 Oct 2007 -- optional \usepackage[arg]{package} argument
now recognized correctly (initial release neglected to
handle optional [arg] following \usepackage).
o 12 Oct 2007 -- html &#nnn; now translated during preprocessing,
e.g., [ or [ becomes [ (left square bracket) before
it's submitted to latex.
o 12 Oct 2007 -- special mathTeX directives like \time
are now checked for proper command termination, i.e., non-alpha
character. (In particular, LaTeX \times had been incorrectly
interpreted as mathTeX \time followed by an s.)
o 12 Oct 2007 -- url "unescape" translation, i.e.,
%20-to-blank, etc, repeated (done twice) for
Now click Submit to see it rendered below...
|
You should see
=\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) |
^n)
|
|
(2) |
\ =
\lim_{\Delta x\to0}\frac{f(x+\Delta x)-f(x)}{\Delta x}) |
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,
- <img src="/cgi-bin/mathtex.cgi?\png x^2">
renders x^2 as a png image
instead
of the default gif format.
- <img src="/cgi-bin/mathtex.cgi?\usepackage{color}\color{blue}x^2">
renders
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
dx)
.
But the expression
"\textstyle \int_0^1 f(x)dx" is wrapped
as $ \int_0^1 f(x)dx $,
rendering
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
.
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 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".
-
\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
 = not found})
instead.
But mathTeX may also display
 = /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
,
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".
-
\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}
|
 |
-
\environment
- Submitting the expression \environment
to mathTeX renders
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...
(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
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
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.
|
| |
 |
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.
-
–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)
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 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.
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.
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.