--------------------------------------------------------------------------
October 11, 2002 Version 0.99
m i m e T e X R e a d m e F i l e
Copyright (c) 2002, John Forkosh Associates, Inc. All rights reserved.
--------------------------------------------------------------------------
by: John Forkosh
john@forkosh.com www.forkosh.com
This file is part of mimeTeX, which is free software.
You may redistribute and/or modify it under the terms
of the GNU General Public License, version 2 or later,
as published by the Free Software Foundation.
Your mimeTeX distribution should contain a copy of
the GNU General Public License. If not, write to the
Free Software Foundation, Inc, 59 Temple Place, Suite
330, Boston, MA 02111-1307 USA
QUICK START
------------------------------------------------------------------------
To compile and install mimeTeX
o unzip mimetex.zip in any convenient working directory
o to produce an executable that emits mime xbitmaps
cc -DXBITMAP mimetex.c -lm -o mimetex.cgi
o or, to produce an executable that emits gif images
cc -DGIF mimetex.c gifsave.c -lm -o mimetex.cgi
o mv mimetex.cgi to your server's cgi-bin/ directory
o mv mimetex.html to your server's htdocs/ directory
o if the relative path from htdocs to cgi-bin isn't
../cgi-bin then edit mimetex.html and change the
dozen or so occurrences as necessary
To quickly learn about mimeTeX
o point your browser to www.yourdomain.com/mimetex.html
and it should display the same demo/tutorial
as on my site at www.forkosh.com/mimetex.html
Problems with the above?
o read the more detailed instructions below
CONTENTS
------------------------------------------------------------------------
I .................... INTRODUCTION
II .................... FILELIST
III .................... COMPILATION AND INSTALLATION
IV .................... MIMETEX SYNTAX REFERENCE
V .................... GPL LICENSE
APPENDIX I ............. MIMETEX FONTS
CONCLUDING REMARKS
I. INTRODUCTION
------------------------------------------------------------------------
MimeTeX, licensed under the gpl, parses LaTeX math expressions,
emitting either mime xbitmaps or gif images of them, which can be used
in html documents in the form, e.g.,
allowing you to embed math directly in html, reducing the need
for lots of external gif images, and making your html documents
more readable and easily maintained.
Several other non-MathML solutions besides mimeTeX also embed
LaTeX math into html. Two that you might want to look at are
textogif
and gladTeX .
Both require separate setup procedures that use TeX to help
generate external gif (or png) images of your equations, which
are later included in your html document as it's being rendered.
MimeTeX, as far as I know, is the only such non-MathML package
that has its own built-in rendering engine, entirely independent
of TeX, and therefore requires no setup procedure or external images
whatsoever. It renders realtime, on-the-fly images directly from
your LaTeX math embedded in html documents.
You can think of mimeTeX as kind of a lightweight MathML,
with somewhat less functionality but also with fewer requirements.
MimeTeX's syntax is very TeX-like (though not exactly), requiring
only a short learning curve (maybe 30 minutes) for a (La)TeX-aware
user to learn the occasional exceptions. And mimeTeX should work
with almost any (graphical) browser and server.
MimeTeX's ease of use thus makes your html documents more
readable and easily maintained. It's possible that textogif,
gladTeX, or other similar tools can be modified to work as easily.
Or perhaps mimeTeX's ease-of-use features won't prove compelling.
In any case, mimeTeX becomes one more available tool in your toolbox.
Point your browser to www.forkosh.com/mimetex.html for an immediate
demo and tutorial, which shows some examples and also tells you how
to type in your own expressions to see how they're rendered.
The rendering isn't "seamless" with surrounding text, but should
be adequate for many purposes. Also, only a subset of TeX math
is available, but what is available should, again, be adequate
for many purposes.
II. FILELIST
------------------------------------------------------------------------
mimetex.zip gnu zipped mimeTeX distribution containing...
README this file (and see mimetex.html for demo/tutorial)
LICENSE GPL license, under which you may use mimeTeX
mimetex.c mimeTeX source program and all required functions
mimetex.h header file for mimetex.c (and for gfuntype.c)
gfuntype.c parses output from gftype -i and writes bitmap data
texfonts.h output from several gfuntype runs, needed by mimetex.c
gifsave.c gif library by Sverre H. Huseby
mimetex.html sample html document, mimeTeX demo and tutorial
Note: all files in mimetex.zip use Unix line termination,
i.e., linefeeds (without carriage returns) signal line endings.
Conversion for Windows PC's, Macs, VMS, etc, can usually be
accomplished by unzip's -a option, i.e., unzip -a mimetex.zip
III. COMPILATION AND INSTALLATION
------------------------------------------------------------------------
I've comnpiled and run mimeTeX under Linux and OpenBSD using gcc.
The source code is entirely ansi-standard C, and should compile
and execute under all environments without any change whatsoever.
Build instructions below are for Unix; modify them as necessary
for your particular situation.
Unzip mimetex.zip in any convenient working directory.
Then, to produce an executable that emits mime xbitmaps,
just compile mimetex with the command
cc -DXBITMAP mimetex.c -lm -o mimetex.cgi
Alternatively, to produce an executable that emits gif
images, compile mimetex with the command
cc -DGIF mimetex.c gifsave.c -lm -o mimetex.cgi
The gfuntype program is only needed if you're planning to
change the font information in texfonts.h, as explained in
the Fonts section below. Compile gfuntype with the command
cc gfuntype.c mimetex.c -lm -o gfuntype
That's all there is to building mimeTeX. You can now test
mimetex.cgi from the Unix command line by typing, e.g.,
./mimetex.cgi x^2+y^2
which should emit an ascii raster something like
..........**...............**...
.........*..*.............*..*..
............*...*............*..
....*.*.....*...*...**..*....*..
...*.*.*...*....*...**..*...*...
.....*....*.*.*****..*..*..*.*..
..*.*.*..****...*...*..*..****..
...****.........*....***........
................*......*........
....................***.........
except a little larger (type ./mimetex.cgi 0\$x^2+y^2
to get the size shown). If you get much fancier than
x^2+y^2, just remember that many characters have to
be escaped from the Unix command line, e.g., x\
renders f(x)=x^2 in font size 3.
You'll soon observe that exponents and \frac's and \atop's
are automatically rendered one size smaller than their base
expressions. For example, "3$y=e^{x^2}" renders "y=e" in
font size 3, the "x" in font size 2, and the "2" in font size 1.
If you get below font size 0, the font size remains 0.
Parentheses and Braces: \left( and \right) are written \( and \)
Ditto for \[ \] and \< \> and \{ \}, although unescaped {}'s
aren't displayed at all (as usual) and escaped \{\}'s are always
sized to fit.
\right. is written \. And you can also write \. to mean
\left. (mimeTeX correctly interprets your intention if you
correctly balance delimiters).
Unescaped ()'s, []'s and <>'s don't need to be balanced
since mimeTeX treats them like ordinary characters without
any special significance. Unescaped {}'s must be balanced as
usual, and they have the usual significance. Escaped \(\)'s,
\[\]'s, \<\>'s and \{\}'s must all be correctly balanced.
The other delimiters, i.e., floor's, ceil's, arrow's, etc,
can't (yet) be sized to fit.
Whitespace: your browser may or may not handle embedded blanks
properly. Use tilde's (a ~) when blanks are required,
e.g., \sqrt~x or \frac~y2 or \alpha~z, etc.
Your browser also may or may not allow line breaks
in the middle of a long mimeTeX expression. For example,
breaks its long query_string over two lines. If your browser
permits line breaks like this, then mimeTeX renders it correctly.
If your browser doesn't permit it, then you'll have to enter
long expressions on one big long line.
Accents and Math Spaces: \hat{} \bar{} \tilde{} \dot{} and \ddot{}
are the only accents currently supported, and they're all "wide".
You can write \widehat{} if you like, but there's absolutely no
difference either way. (I know you want \vec. It's on my list.)
The three math spaces \, \: \; are the only ones supported;
there's no negative space.
Abbreviations: \ga displays \gamma, but just \g displays \gg (>>).
That is, mimeTeX selects the shortest character or command
which begins with whatever you type. This can help shorten
an otherwise very long line, but may be a bit dangerous.
Modes: mimeTeX is always in math mode, so don't surround your
expressions with $'s. In fact, $'s are used for other
purposes (see font sizes above, and \array below). There's no
displaymath mode yet, i.e., limits can't be rendered directly
over and under their operator.
MimeTeX has a text-like mode entered by the LaTeX-2.09-like
command {\rm~anything~at~all} which renders anything~at~all
in roman (font family cmr10) and respects spaces between words
(the required space after \rm is still ignored).
{\rm~...} isn't really text mode because you can render
any math expression at all while in it. The only effect \rm has
is that A-Z,a-z are rendered in cmr10, and spaces are respected.
For example, \sqrt{a^2+{\rm~b^2}+c^2} renders the "b" in cmr10.
Or \sqrt{a^2+b^2+\rm~c^2} renders the "c" in cmr10.
Binding Exceptions: x^\alpha and \frac12 work okay as usual,
but x^\frac12 must be written x^{\frac12}. Ditto for similar
combinations of commands, e.g., you must write
\sqrt{\frac\alpha\beta}, etc.
Command Syntax Exceptions: \atop's syntax is like \frac's, e.g.,
for {a+b \atop c+d} you must write \atop{a+b}{c+d} .
Note that there is no \choose, but you can write \(\atop~nk\)
for the binomial coefficient {n \choose k}.
MimeTeX's array-like "environment" is discussed immediately
below, and is also just a bit different than you're accustomed to.
Array "environment": \atop works for two items only. So mimeTeX
provides the command \array{lcr$a&b&c\\d&e&f\\etc} for vectors
and matrices, to align equations, etc, all in the usual way.
But \hline's, \cline's and vertical bars (in the l|c|r sense)
are not yet implemented. And there's a maximum of 16 columns
and 16 rows.
The default font size is unchanged in array, but you have
the option to explicitly control it as follows. Instead of the
lcr$ at the beginning, you can write, e.g., 3,lcr$ to render
the array in font size 3. Moreover, if you precede your number
by a + or - then it acts as a "delta" to the font size of the base
expression. For example, -1,lcr renders the array one font size
smaller than current.
\overbrace and \underbrace: mimeTeX provides \overbrace{}^{} and
\underbrace{}_{} which both work in the usual way. But there
aren't yet any kinds of \box's like you're probably accustomed
to using for annotations. Instead, you can use the
{\rm~...} command discussed above to render them.
Character Sets: For complete information about the characters
available to you in mimeTeX, you'll have to look through the
bottom 500-or-so lines of mimetex.h . Generally speaking,
I've tried to encode the cmmi10, cmsy10, cmr10 and cmex10
families with "names" (e.g., \alpha \beta \forall \sqcup, etc)
identical to your LaTeX expectations (note that "\alpha"
is written "\\alpha" in mimetex.h due to C syntax rules).
But there are various omissions and exceptions vis-a-vis LaTeX.
Two of these are:
o Write \calA \calB ... \calZ rather than \cal{A}, etc.
o "Large" operators like \int are typically available in
three sizes: \int \bigint \Bigint, and similarly for \sum
\prod \cup \cap, etc. If you find a \Bigxxx in mimetex.h
then there'll typically also be a \bigxxx and an \xxx.
I haven't exhaustively checked all my name-number matchings for
the hundreds of symbols in minetex.h . You can eaily correct
any minor mistake you find in what I hope is an obvious manner.
The Fonts section below provides additional information.
That's all you probably need to know. Anything else that still
doesn't behave like you expect is probably just not implemented.
You might also want to browse your mimetex.html demo and tutorial
page, which reviews some of the above information, and shows some
additional examples that illustrate what is implemented.
And you can always try out anything from the command line,
as mentioned in the preceding section, to quickly see whether
or not it works.
V. GPL LICENSE
------------------------------------------------------------------------
MimeTeX'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, as enumerated in the accompanying LICENSE file.
There is no official support of any kind whatsoever,
and you use mimeTeX entirely at your own risk, with no guarantee
of any kind, in particular with no warranty of merchantability.
By using mimeTeX, you warrant that you have read, understood
and agreed to these terms and conditions, and that you are at least
18 years of age and possess the legal right and ability to enter
into this agreement and to use mimeTeX 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.
APPENDIX I: MIMETEX FONTS
------------------------------------------------------------------------
The font information mimeTeX uses to render characters is
derived from .gf font files (usually generated by metafont
running against .mf files), which are then run through
gftype -i and finally through my gfuntype program
(supplied with your mimeTeX distribution).
The final output from each such sequence of three runs
(metafont > gftype -i > gfuntype) gives mimeTeX the information
it needs to render one particular font family at one particular
size. The file texfonts.h supplied with your mimeTeX
distribution collects the output from 20 such (sequences of)
runs, representing four font families at five sizes each.
This collection of information in texfonts.h is
"wired" into mimeTeX through tables maintained in mimetex.h .
To change mimeTeX's fonts, you'll have to modify (or totally
replace) texfonts.h using your own gfuntype output, and then
change mimetex.h to reflect your texfonts.h modifications.
This section provides a brief description of the above
process, though you'll probably need at least some previous
C programming experience to confidently accomplish it.
Your motivation might be to add the rsfs (or any other) fonts
to mimeTeX, to change the font sizes I chose or to add more
font sizes, etc. MimeTeX's design permits all this to be
easily done once you understand the process.
Running metafont to generate a .gf file from .mf source
will usually be your very first step. A typical such run
might be
mf '\mode=pcscreen; mag=magstep(.75); input cmmib10'
which in this case generates output file cmmib10.135gf
(which is mimeTeX's font size 3 for the cmmi family).
Given the cmmib10.135gf file from this metafont run
(or substitute any other .gf file you like), next run
gftype -i cmmib10.135gf > typeout
where typeout can be any temporary filename you like.
Finally, run gfuntype against the typeout file
you just generated with the command
gfuntype -n cmmib135 typeout cmmib135.h
to generate the final output file cmmib135.h
(or any filename you supply as the last arg). This
contains the cmmi data in an array whose name is taken
from the -n arg you supplied to gfuntype.
The above sequence of three runs resulted in output file
cmmib135.h, containing the font information mimeTeX needs
for one font family (cmmi) at one font size. Repeat the
sequence of runs for each font size and each font family.
Then pull all the output files into one big texfonts.h file
(or write a small texfonts.h which just #include's them all).
For your information, the 20 sequences of runs represented
in the texfonts.h file supplied with your mimetex.zip distribution
correspond to the following five inital metafont runs for cmr10
size=0 (.78gf) mf '\mode=vs; input cmr10'
1 (.100gf) mf '\mode=nextscrn; input cmr10'
2 (.118gf) mf '\mode=pcscreen; input cmr10'
3 (.135gf) mf '\mode=pcscreen; mag=magstep(.75); input cmr10'
4 (.155gf) mf '\mode=pcscreen; mag=magstep(1.5); input cmr10'
Then ditto for the three other font families cmmib10, cmsy10, cmex10.
All the subsequent gftype and gfuntype runs just follow the usual
format described above.
To incorporate all this font information you just generated into
mimeTeX, edit your mimetex.h file and find the table that looks
like
static fontfamily fonttable[] =
{ /* ----------------------------------------------------------
family footnote small normal large Large
------------------------------------------------------------- */
{ CMR10, { cmr78, cmr100, cmr118, cmr135, cmr155 } },
{ CMMI10, { cmmib78, cmmib100, cmmib118, cmmib135, cmmib155 } },
{ CMSY10, { cmsy78, cmsy100, cmsy118, cmsy135, cmsy155 } },
{ CMEX10, { cmex78, cmex100, cmex118, cmex135, cmex155 } },
{ -999, { NULL, NULL, NULL, NULL, NULL } }
} ; /* --- end-of-fonttable[] --- */
Note the 20 names cmr78...cmex155 in the table. These must correspond
to (or must be changed to) the names following the -n switch you
specified for your gfuntype runs.
If you want more than five font sizes, first build up texfonts.h
with all the necessary information. Then change LARGESTSIZE (and
probably NORMALSIZE) in mimetex.h, and edit the above fonttable[]
by extending the columns in each row up to your largest size.
You can also add new rows by #define'ing a new family,
and then adding a whole lot of character definitions at the bottom
of mimetex.h, all in the obvious way. A new row would be required,
for example, to make the rsfs fonts available in mimeTeX.
CONCLUDING REMARKS
------------------------------------------------------------------------
I hope you find mimeTeX 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.
If you also like mimeTeX's source, I'm an independent contractor
incorporated in the US as John Forkosh Associates, Inc. A resume
is at www.forkosh.com or email john@forkosh.com
========================= END-OF-FILE README ===========================