filter/tex/README.mimetex

   1
   2  --------------------------------------------------------------------------
   3  March 31, 2012                                                Version 1.74
   4
   5                   m i m e T e X   R e a d m e   F i l e
   6
   7  Copyright(c) 2002-2012, 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 3 or later,
  16           as published by the Free Software Foundation. See
  17                    http://www.gnu.org/licenses/gpl.html
  18
  19           MimeTeX is discussed and illustrated online at
  20           its homepage
  21                     http://www.forkosh.com/mimetex.html
  22           Or you can follow the Quick Start instructions below
  23           (or the more detailed instructions in Section III)
  24           to immediately install mimeTeX on your own machine.
  25           Then point your browser to
  26                     http://www.yourdomain.com/mimetex.html
  27           for a demo/tutorial and reference.
  28                Installation problems?  Point your browser to
  29           mimeTeX's homepage
  30                     http://www.forkosh.com/mimetex.html
  31           then click its "full mimeTeX manual" link and see
  32           Section II.
  33
  34
  35 I.  QUICK START
  36 ------------------------------------------------------------------------
  37   To compile and install mimeTeX
  38        * unzip mimetex.zip in any convenient working directory
  39        * to produce an executable that emits anti-aliased
  40          gif images (recommended)
  41               cc -DAA mimetex.c gifsave.c -lm -o mimetex.cgi
  42          -or- for gif images without anti-aliasing
  43               cc -DGIF mimetex.c gifsave.c -lm -o mimetex.cgi
  44          -or- to produce an executable that emits mime xbitmaps
  45               cc -DXBITMAP mimetex.c -lm -o mimetex.cgi
  46          (For Windows, see "Compile Notes" in Section III below.)
  47        * mv mimetex.cgi  to your server's cgi-bin/ directory
  48        * mv mimetex.html to your server's htdocs/  directory
  49        * if the relative path from htdocs to cgi-bin isn't
  50          ../cgi-bin then edit mimetex.html and change the
  51          few dozen occurrences as necessary.
  52   Then, to quickly learn more about mimeTeX
  53        * point your browser to www.yourdomain.com/mimetex.html
  54   Any problems with the above?
  55        * read the more detailed instructions below,
  56          or see http://www.forkosh.com/mimetex.html
  57
  58
  59 II.  INTRODUCTION
  60 ------------------------------------------------------------------------
  61   MimeTeX, licensed under the gpl, lets you easily embed LaTeX math in
  62   your html pages.  It parses a LaTeX math expression and immediately
  63   emits the corresponding gif image, rather than the usual TeX dvi.
  64        And mimeTeX is an entirely separate little program that doesn't
  65   use TeX or its fonts in any way.  It's just one cgi that you put in
  66   your site's cgi-bin/ directory, with no other dependencies.
  67   So mimeTeX is very easy to install.  And it's equally easy to use.
  68   Just place an html <img> tag in your document wherever you want to
  69   see the corresponding LaTeX expression.  For example,
  70     <img src="../cgi-bin/mimetex.cgi?f(x)=\int_{-\infty}^x~e^{-t^2}dt"
  71      border=0 align=absmiddle>
  72   generates and displays the corresponding gif image on-the-fly,
  73   wherever you put that <img> tag.  MimeTeX doesn't need intermediate
  74   dvi-to-gif conversion, and it doesn't clutter your filesystem with
  75   separate little gif files for each converted expression.  (Optional
  76   image caching does store gif files, and subsequently reads them as
  77   needed, rather than re-rendering the same images every time a page
  78   is reloaded.)
  79
  80
  81 III.  COMPILATION AND INSTALLATION
  82 ------------------------------------------------------------------------
  83   I've built and run mimeTeX under Linux and NetBSD using gcc.
  84   The source code is ansi-standard C, and should compile
  85   and execute under all environments without any change whatsoever.
  86   Build instructions below are for Unix. Modify them as necessary
  87   for your particular situation.  Note the -DWINDOWS switch if
  88   applicable.
  89
  90   Unzip mimetex.zip in any convenient working directory.
  91   Your working directory should now contain
  92        mimetex.zip    your gnu zipped mimeTeX distribution containing...
  93        README         this file (see mimetex.html for demo/tutorial)
  94        COPYING        GPL license, under which you may use mimeTeX
  95        mimetex.c      mimeTeX source program and all required functions
  96        mimetex.h      header file for mimetex.c (and for gfuntype.c)
  97        gfuntype.c     parses output from  gftype -i  and writes bitmap data
  98        texfonts.h     output from several gfuntype runs, needed by mimetex.c
  99        gifsave.c      gif library by Sverre H. Huseby <sverrehu@online.no>
 100        mimetex.html   sample html document, mimeTeX demo and tutorial
 101   Note: all files in mimetex.zip use Unix line termination,
 102   i.e., linefeeds (without carriage returns) signal line endings.
 103   Conversion for Windows, Macs, VMS, etc, can usually be accomplished
 104   with unzip's -a option, i.e.,  unzip -a mimetex.zip
 105
 106   Now, to compile a mimeTeX executable that emits anti-aliased gif
 107   images (recommended for most uses), type the command
 108             cc -DAA mimetex.c gifsave.c -lm -o mimetex.cgi
 109
 110   Or, for an executable that emits gif images without
 111   anti-aliasing,
 112             cc -DGIF mimetex.c gifsave.c -lm -o mimetex.cgi
 113
 114   Alternatively, to compile a mimeTeX executable that emits
 115   mime xbitmaps, just type the command
 116             cc -DXBITMAP mimetex.c -lm -o mimetex.cgi
 117
 118   Compile Notes:
 119      * If (and only if) you're compiling a Windows executable
 120        with the -DAA or -DGIF option (but not -DXBITMAP), then
 121        add -DWINDOWS also.  For example,
 122             cc -DAA -DWINDOWS mimetex.c gifsave.c -lm -o mimetex.cgi
 123        The above Unix-like syntax works with MinGW (http://www.mingw.org)
 124        and djgpp (http://www.delorie.com/djgpp/) Windows compilers, but
 125        probably not with most others, where it's only intended as a
 126        "template".
 127      * Several additional command-line options that you may find
 128        useful are discussed in Section IId (href="#options")
 129        of your mimetex.html page.
 130
 131   That's all there is to building mimeTeX.  You can now test your
 132   mimetex.cgi executable from the Unix command line by typing, e.g.,
 133        ./mimetex.cgi "x^2+y^2"
 134   which should emit two ascii rasters something like the following
 135     Ascii dump of bitmap image...     Hex dump of colormap indexes...
 136     ........**..................**..  .......1**1................1**1.
 137     .......*..*.....*..........*..*.  .......*23*.....*..........*23*.
 138     ..........*.....*.............*.  ..........*.....*.............*.
 139     .***......*.....*....**.*.....*.  .***1....2*.....*....**3*....2*.
 140     .**.*....*......*....**.*....*..  .**.*...1*......*....**.*...1*..
 141     ..*.....*.*..******...*.*...*.*.  ..*....2*.*..******...*.*..2*.*.
 142     **.*...****.....*....*.*...****.  **.*...****.....*....*.*2..****.
 143     ****............*.....**........  ****............*....1**........
 144     ................*......*........  ................*......*........
 145     ................*....**.........  ................*....**1........
 146                                   The 5 colormap indexes denote rgb...
 147                                  .-->255 1-->196 2-->186 3-->177 *-->0
 148   The right-hand illustration shows asterisks in the same positions as
 149   the left-hand one, along with anti-aliased grayscale colormap indexes
 150   assigned to neighboring pixels, and with the rgb value for each
 151   index.  Just typing ./mimetex.cgi without an argument should produce
 152   ascii rasters for the default expression f(x)=x^2.  If you see the
 153   two ascii rasters then your binary's good, so mv it to your server's
 154   cgi-bin/ directory and set permissions as necessary.
 155
 156   Once mimetex.cgi is working, mv it to your server's cgi-bin/ directory
 157   (wherever cgi programs are expected), and chmod/chown it as necessary.
 158   Then mv mimetex.html to your server's htdocs/ directory.  Now point
 159   your browser to www.yourdomain.com/mimetex.html and you should see
 160   your mimeTeX user's manual reference page.
 161
 162   Install Notes:
 163      * These two directories are typically of the form
 164        somewhere/www/cgi-bin/  and  somewhere/www/htdocs/
 165        so I set up mimtex.html to access mimetex.cgi from
 166        the relative path ../cgi-bin/   If your directories
 167        are non-conforming, you may have to edit the few dozen
 168        occurrences of ../cgi-bin/mimetex.cgi in mimetex.html
 169        Sometimes a suitable symlink works.  If not, you'll
 170        have to edit.  In that case, globally changing
 171        ../cgi-bin/mimetex.cgi  often works.
 172      * Either way, once mimetex.html displays properly, you can
 173        assume everything is working, and can begin authoring html
 174        documents using mimetex.cgi to render your own math.
 175
 176
 177 IV.  REVISION HISTORY
 178 ------------------------------------------------------------------------
 179   A more detailed account of mimeTeX's revision history
 180   is maintained at  http://www.forkosh.com/mimetexchangelog.html
 181   ---
 182   03/31/12  J.Forkosh      version 1.74 released.
 183   08/24/11  J.Forkosh      version 1.72 released.
 184   09/06/08  J.Forkosh      version 1.70 released.
 185   11/30/04  J.Forkosh      version 1.60 released
 186   10/02/04  J.Forkosh      version 1.50 released on CTAN with various new
 187                            features and fixes, and updated documentation.
 188   07/18/04  J.Forkosh      version 1.40 re-released on CTAN with minor
 189                            changes, e.g., \mathbb font and nested \array's
 190                            now supported.
 191   03/21/04  J.Forkosh      version 1.40 released on CTAN, with improved
 192                            LaTeX compatibility, various new features and
 193                            fixes, including fix to work under Windows.
 194   12/21/03  J.Forkosh      version 1.30 released on CTAN, with improved
 195                            LaTeX compatibility and anti-aliasing, various new
 196                            features, and thoroughly updated documentation.
 197   10/17/03  J.Forkosh      version 1.20 released on CTAN, adding picture
 198                            environment and various other changes (e.g.,
 199                            more delimiters arbitrarily sized) and fixes.
 200   07/29/03  J.Forkosh      version 1.10 released on CTAN, completely replacing
 201                            mimeTeX's original built-in fonts with thinner and
 202                            more pleasing fonts, and adding one larger size.
 203   06/27/03  J.Forkosh      version 1.01 released on CTAN, adding lowpass
 204                            anti-aliasing for gifs, and http_referer checks,
 205                            and fixing a few very obscure bugs.
 206   12/11/02  J.Forkosh      version 1.00 released on CTAN, fixing \array bug
 207                            and adding various new features.
 208   10/31/02  J.Forkosh      version 0.99 released on CTAN
 209   09/18/02  J.Forkosh      internal beta test release
 210
 211
 212 V.  CONCLUDING REMARKS
 213 ------------------------------------------------------------------------
 214   I hope you find mimeTeX useful.  If so, a contribution to your
 215   country's TeX Users Group, or to the GNU project, is suggested,
 216   especially if you're a company that's currently profitable.
 217 ========================= END-OF-FILE README ===========================
 218