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