filter/tex/README.mimetex

   1
   2  --------------------------------------------------------------------------
   3  January 11, 2004                                              Version 1.40
   4
   5                   m i m e T e X   R e a d m e   F i l e
   6
   7  Copyright(c) 2002-2004, John Forkosh Associates, Inc. All rights reserved.
   8  --------------------------------------------------------------------------
   9
  10                             by: John Forkosh
  11                   john@forkosh.com     www.forkosh.com
  12
  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
  18
  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.
  29
  30
  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
  51
  52
  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.
  65
  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.
  70
  71
  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.
  79
  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
  95
  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
 100
 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
 104
 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
 108
 109        Several additional command-line options that you may find
 110        useful are discussed in Section IIc (href="#options")
 111        of mimetex.html .
 112
 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.
 139
 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.
 153
 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.
 157
 158
 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
 179
 180
 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 ===========================
 191