63ce8b39e9b306ed16d2ebc9648790a27c6a3b9b
[moodle.git] / filter / tex / README.mimetex
2  --------------------------------------------------------------------------
3  January 11, 2004                                              Version 1.40
5                   m i m e T e X   R e a d m e   F i l e
7  Copyright(c) 2002-2004, John Forkosh Associates, Inc. All rights reserved.
8  --------------------------------------------------------------------------
10                             by: John Forkosh
11                   john@forkosh.com     www.forkosh.com
13           This file is part of mimeTeX, which is free software.
14           You may redistribute and/or modify it under the terms
15           of the GNU General Public License, version 2 or later,
16           as published by the Free Software Foundation. See
17                    http://www.gnu.org/licenses/gpl.html
19           Follow the Quick Start instructions immediately below
20           or the detailed instructions in Section III to install
21           mimeTeX on your machine, and then point your browser to
22                   http://www.yourdomain.com/mimetex.html
23           for a complete discussion, including demo/tutorial and
24           reference.  Installation problems?  Point your browser
25           to my page at
26                     http://www.forkosh.com/mimetex.html
27           then click its "full mimeTeX manual" link and see
28           Section II.
31 I.  QUICK START
32 ------------------------------------------------------------------------
33   To compile and install mimeTeX
34        o unzip mimetex.zip in any convenient working directory
35        o to produce an executable that emits anti-aliased gif images
36               cc -DAA mimetex.c gifsave.c -lm -o mimetex.cgi
37          -or- for gif images without anti-aliasing
38               cc -DGIF mimetex.c gifsave.c -lm -o mimetex.cgi
39          -or- to produce an executable that emits mime xbitmaps
40               cc -DXBITMAP mimetex.c -lm -o mimetex.cgi
41        o mv mimetex.cgi  to your server's cgi-bin/ directory
42        o mv mimetex.html to your server's htdocs/  directory
43        o if the relative path from htdocs to cgi-bin isn't
44          ../cgi-bin then edit mimetex.html and change the
45          few dozen occurrences as necessary
46   To quickly learn about mimeTeX
47        o point your browser to www.yourdomain.com/mimetex.html
48   Any problems with the above?
49        o read the more detailed instructions in Section III below,
50          or see www.forkosh.com/mimetex.html
53 II.  INTRODUCTION
54 ------------------------------------------------------------------------
55   MimeTeX is licensed under the gpl.  It parses LaTeX math expressions,
56   emitting either gif images or mime xbitmaps of them, rather than the
57   usual TeX dvi's.  And mimeTeX is an entirely separate little program
58   that doesn't use TeX in any way.  Therefore, mimeTeX images are easily
59   inserted directly into html documents using a standard html <img> tag,
60        <img src="../cgi-bin/mimetex.cgi?f(x)=\int_{-\infty}^x~e^{-t^2}dt"
61         border=0 align=absmiddle>
62   without intermediate dvi-to-gif conversion, and without storing lots
63   of little gif image files, one file for each converted expression.
64   This makes your web site and html documents more easily maintained.
66   Thus, mimeTeX is primarily intended to help you write native html
67   documents containing math.  In this sense it's a kind of "lightweight"
68   alternative to MathML, with the advantage that mimeTeX preserves LaTeX
69   syntax, and works with any browser and server.
72 III.  COMPILATION AND INSTALLATION
73 ------------------------------------------------------------------------
74   I've comnpiled and run mimeTeX under Linux and NetBSD using gcc.
75   The source code is entirely ansi-standard C, and should compile
76   and execute under all environments without any change whatsoever.
77   Build instructions below are for Unix.  Modify them as necessary
78   for your particular situation.
80   Unzip mimetex.zip in any convenient working directory.
81   You should now have files
82        mimetex.zip    your gnu zipped mimeTeX distribution containing...
83        README         this file (see mimetex.html for demo/tutorial)
84        LICENSE        GPL license, under which you may use mimeTeX
85        mimetex.c      mimeTeX source program and all required functions
86        mimetex.h      header file for mimetex.c (and for gfuntype.c)
87        gfuntype.c     parses output from  gftype -i  and writes bitmap data
88        texfonts.h     output from several gfuntype runs, needed by mimetex.c
89        gifsave.c      gif library by Sverre H. Huseby <sverrehu@online.no>
90        mimetex.html   sample html document, mimeTeX demo and tutorial
91   Note: all files in mimetex.zip use Unix line termination,
92   i.e., linefeeds (without carriage returns) signal line endings.
93   Conversion for Windows, Macs, VMS, etc, can usually be accomplished
94   with unzip's -a option, i.e.,  unzip -a mimetex.zip
96   Now, to produce an executable that emits anti-aliased gif images
97        (which is how the "official" www.forkosh.com/mimetex.html page
98        is displayed), compile mimetex with the command
99           cc -DAA mimetex.c gifsave.c -lm -o mimetex.cgi
101        Or, to produce an executable that emits gif images
102        without anti-aliasing, compile mimetex with the command
103           cc -DGIF mimetex.c gifsave.c -lm -o mimetex.cgi
105        Alternatively, for an executable that emits mime xbitmaps,
106        just compile mimetex with the command
107           cc -DXBITMAP mimetex.c -lm -o mimetex.cgi
109        Several additional command-line options that you may find
110        useful are discussed in Section IIc (href="#options")
111        of mimetex.html .
113   That's all there is to building mimeTeX.  You can now test mimetex.cgi
114   from the Unix command line by typing, e.g.,
115        ./mimetex.cgi x^2+y^2
116   which should emit an ascii raster something like the left-hand
117   illustration.  And if you've compiled mimeTeX with the anti-aliasing
118   -DAA option, then you'll also see the right-hand illustration.
119   It shows asterisks in the same positions as the left-hand illustration,
120   and anti-aliased grayscale colormap indexes assigned to neighboring
121   pixels.  And you'll also be shown the actual rgb value for each index.
122     Ascii dump of bitmap image...     Hex dump of colormap indexes...
123     ........**..................**..  .......1**1................1**1.
124     .......*..*.....*..........*..*.  .......*23*.....*..........*23*.
125     ..........*.....*.............*.  ..........*.....*.............*.
126     .***......*.....*....**.*.....*.  .***1....2*.....*....**3*....2*.
127     .**.*....*......*....**.*....*..  .**.*...1*......*....**.*...1*..
128     ..*.....*.*..******...*.*...*.*.  ..*....2*.*..******...*.*..2*.*.
129     **.*...****.....*....*.*...****.  **.*...****.....*....*.*2..****.
130     ****............*.....**........  ****............*....1**........
131     ................*......*........  ................*......*........
132     ................*....**.........  ................*....**1........
133                                   The 5 colormap indexes denote rgb...
134                                  .-->255 1-->196 2-->186 3-->177 *-->0
135   If you get much fancier than x^2+y^2, remember that many characters have
136   to be escaped from the Unix command line, e.g., x\<y or f\(x\)=x^2, etc.
137   Of course, you won't need these extra escapes when running mimetex from
138   a browser.
140   Once mimetex.cgi is working (and you're done playing with it),
141   mv it to your server's cgi-bin/ directory, where cgi programs
142   are expected (and chmod/chown it if necessary).  Then mv
143   mimetex.html to your server's htdocs/ directory.  Now point
144   your browser to www.yourdomain.com/mimetex.html , and it should
145   be rendered exactly like my page at www.forkosh.com/mimetex.html .
146        One "gotcha":  the two directories are typically of the form
147   somewhere/www/cgi-bin/ and somewhere/www/htdocs/ ,  so I set up
148   mimtex.html to get mimetex.cgi from the relative path ../cgi-bin/ .
149   If your directories are non-conforming, you may have to edit the
150   few dozen occurrences of ../cgi-bin/mimetex.cgi in mimetex.html
151   (globally changing ../cgi-bin/mimetex.cgi should work).
152   Sometimes a suitable symlink works; if not, you'll have to edit.
154   Either way, once mimetex.html displays properly, and you've reviewed
155   the tutorial it contains, you can begin writing html documents using
156   mimetex.cgi to render your math.
159 IV.  REVISION HISTORY
160 ------------------------------------------------------------------------
161   01/11/04  J.Forkosh      version 1.40 beta released on www.forkosh.com
162                            LaTeX compatibility and various new features
163   12/21/03  J.Forkosh      version 1.30 released on CTAN, with improved
164                            LaTeX compatibility and anti-aliasing, various new
165                            features, and thoroughly updated documentation.
166   10/17/03  J.Forkosh      version 1.20 released on CTAN, adding picture
167                            environment and various other changes (e.g.,
168                            more delimiters arbitrarily sized) and fixes.
169   07/29/03  J.Forkosh      version 1.10 released on CTAN, completely replacing
170                            mimeTeX's original built-in fonts with thinner and
171                            more pleasing fonts, and adding one larger size.
172   06/27/03  J.Forkosh      version 1.01 released on CTAN, adding lowpass
173                            anti-aliasing for gifs, and http_referer checks,
174                            and fixing a few very obscure bugs.
175   12/11/02  J.Forkosh      version 1.00 released on CTAN, fixing \array bug
176                            and adding various new features.
177   10/31/02  J.Forkosh      version 0.99 released on CTAN
178   09/18/02  J.Forkosh      internal beta test release
181 V.  CONCLUDING REMARKS
182 ------------------------------------------------------------------------
183   I hope you find mimeTeX useful.  If so, a contribution to your
184   country's TeX Users Group, or to the GNU project, is suggested,
185   especially if you're a company that's currently profitable.
186   
187   If you also like mimeTeX's source, I'm an independent contractor
188   incorporated in the US as John Forkosh Associates, Inc.  A resume
189   is at www.forkosh.com or email john@forkosh.com
190 ========================= END-OF-FILE README ===========================