MDL-19832 new mimeTeX binaries v1.70
[moodle.git] / filter / tex / README.mimetex
index 63ce8b3..dd94231 100644 (file)
@@ -1,10 +1,10 @@
 
  --------------------------------------------------------------------------
January 11, 2004                                              Version 1.40
September 6, 2008                                             Version 1.70
 
                   m i m e T e X   R e a d m e   F i l e
 
- Copyright(c) 2002-2004, John Forkosh Associates, Inc. All rights reserved.
+ Copyright(c) 2002-2008, John Forkosh Associates, Inc. All rights reserved.
  --------------------------------------------------------------------------
 
                             by: John Forkosh
 
           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,
+          of the GNU General Public License, version 3 or later,
           as published by the Free Software Foundation. See
                    http://www.gnu.org/licenses/gpl.html
 
-          Follow the Quick Start instructions immediately below
-          or the detailed instructions in Section III to install
-          mimeTeX on your machine, and then point your browser to
-                  http://www.yourdomain.com/mimetex.html
-          for a complete discussion, including demo/tutorial and
-          reference.  Installation problems?  Point your browser
-          to my page at
+          MimeTeX is discussed and illustrated online at
+          its homepage
+                    http://www.forkosh.com/mimetex.html
+          Or you can follow the Quick Start instructions below
+          (or the more detailed instructions in Section III)
+          to immediately install mimeTeX on your own machine.
+          Then point your browser to
+                    http://www.yourdomain.com/mimetex.html
+          for a demo/tutorial and reference.
+               Installation problems?  Point your browser to
+          mimeTeX's homepage
                     http://www.forkosh.com/mimetex.html
           then click its "full mimeTeX manual" link and see
           Section II.
 I.  QUICK START
 ------------------------------------------------------------------------
   To compile and install mimeTeX
-       o unzip mimetex.zip in any convenient working directory
-       o to produce an executable that emits anti-aliased gif images
+       * unzip mimetex.zip in any convenient working directory
+       * to produce an executable that emits anti-aliased
+         gif images (recommended)
               cc -DAA mimetex.c gifsave.c -lm -o mimetex.cgi
          -or- for gif images without anti-aliasing
               cc -DGIF mimetex.c gifsave.c -lm -o mimetex.cgi
          -or- to produce an executable that emits mime xbitmaps
               cc -DXBITMAP mimetex.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
+         (For Windows, see "Compile Notes" in Section III below.)
+       * mv mimetex.cgi  to your server's cgi-bin/ directory
+       * mv mimetex.html to your server's htdocs/  directory
+       * if the relative path from htdocs to cgi-bin isn't
          ../cgi-bin then edit mimetex.html and change the
-         few dozen occurrences as necessary
-  To quickly learn about mimeTeX
-       o point your browser to www.yourdomain.com/mimetex.html
+         few dozen occurrences as necessary.
+  Then, to quickly learn more about mimeTeX
+       * point your browser to www.yourdomain.com/mimetex.html
   Any problems with the above?
-       o read the more detailed instructions in Section III below,
-         or see www.forkosh.com/mimetex.html
+       * read the more detailed instructions below,
+         or see http://www.forkosh.com/mimetex.html
 
 
 II.  INTRODUCTION
 ------------------------------------------------------------------------
-  MimeTeX is licensed under the gpl.  It parses LaTeX math expressions,
-  emitting either gif images or mime xbitmaps of them, rather than the
-  usual TeX dvi's.  And mimeTeX is an entirely separate little program
-  that doesn't use TeX in any way.  Therefore, mimeTeX images are easily
-  inserted directly into html documents using a standard html <img> tag,
-       <img src="../cgi-bin/mimetex.cgi?f(x)=\int_{-\infty}^x~e^{-t^2}dt"
-        border=0 align=absmiddle>
-  without intermediate dvi-to-gif conversion, and without storing lots
-  of little gif image files, one file for each converted expression.
-  This makes your web site and html documents more easily maintained.
-
-  Thus, mimeTeX is primarily intended to help you write native html
-  documents containing math.  In this sense it's a kind of "lightweight"
-  alternative to MathML, with the advantage that mimeTeX preserves LaTeX
-  syntax, and works with any browser and server.
+  MimeTeX, licensed under the gpl, lets you easily embed LaTeX math in
+  your html pages.  It parses a LaTeX math expression and immediately
+  emits the corresponding gif image, rather than the usual TeX dvi.
+       And mimeTeX is an entirely separate little program that doesn't
+  use TeX or its fonts in any way.  It's just one cgi that you put in
+  your site's cgi-bin/ directory, with no other dependencies.
+  So mimeTeX is very easy to install.  And it's equally easy to use.
+  Just place an html <img> tag in your document wherever you want to
+  see the corresponding LaTeX expression.  For example,
+    <img src="../cgi-bin/mimetex.cgi?f(x)=\int_{-\infty}^x~e^{-t^2}dt"
+     border=0 align=absmiddle>
+  generates and displays the corresponding gif image on-the-fly,
+  wherever you put that <img> tag.  MimeTeX doesn't need intermediate
+  dvi-to-gif conversion, and it doesn't clutter your filesystem with
+  separate little gif files for each converted expression.  (Optional
+  image caching does store gif files, and subsequently reads them as
+  needed, rather than re-rendering the same images every time a page
+  is reloaded.)
 
 
 III.  COMPILATION AND INSTALLATION
 ------------------------------------------------------------------------
-  I've comnpiled and run mimeTeX under Linux and NetBSD using gcc.
-  The source code is entirely ansi-standard C, and should compile
+  I've built and run mimeTeX under Linux and NetBSD using gcc.
+  The source code is 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.
+  Build instructions below are for Unix. Modify them as necessary
+  for your particular situation.  Note the -DWINDOWS switch if
+  applicable.
 
   Unzip mimetex.zip in any convenient working directory.
-  You should now have files
+  Your working directory should now contain
        mimetex.zip    your gnu zipped mimeTeX distribution containing...
        README         this file (see mimetex.html for demo/tutorial)
-       LICENSE        GPL license, under which you may use mimeTeX
+       COPYING        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
@@ -93,32 +103,35 @@ III.  COMPILATION AND INSTALLATION
   Conversion for Windows, Macs, VMS, etc, can usually be accomplished
   with unzip's -a option, i.e.,  unzip -a mimetex.zip
 
-  Now, to produce an executable that emits anti-aliased gif images
-       (which is how the "official" www.forkosh.com/mimetex.html page
-       is displayed), compile mimetex with the command
-          cc -DAA mimetex.c gifsave.c -lm -o mimetex.cgi
-
-       Or, to produce an executable that emits gif images
-       without anti-aliasing, compile mimetex with the command
-          cc -DGIF mimetex.c gifsave.c -lm -o mimetex.cgi
-
-       Alternatively, for an executable that emits mime xbitmaps,
-       just compile mimetex with the command
-          cc -DXBITMAP mimetex.c -lm -o mimetex.cgi
-
-       Several additional command-line options that you may find
-       useful are discussed in Section IIc (href="#options")
-       of mimetex.html .
-
-  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 the left-hand
-  illustration.  And if you've compiled mimeTeX with the anti-aliasing
-  -DAA option, then you'll also see the right-hand illustration.
-  It shows asterisks in the same positions as the left-hand illustration,
-  and anti-aliased grayscale colormap indexes assigned to neighboring
-  pixels.  And you'll also be shown the actual rgb value for each index.
+  Now, to compile a mimeTeX executable that emits anti-aliased gif
+  images (recommended for most uses), type the command
+            cc -DAA mimetex.c gifsave.c -lm -o mimetex.cgi
+
+  Or, for an executable that emits gif images without
+  anti-aliasing,
+            cc -DGIF mimetex.c gifsave.c -lm -o mimetex.cgi
+
+  Alternatively, to compile a mimeTeX executable that emits
+  mime xbitmaps, just type the command
+            cc -DXBITMAP mimetex.c -lm -o mimetex.cgi
+
+  Compile Notes:
+     * If (and only if) you're compiling a Windows executable
+       with the -DAA or -DGIF option (but not -DXBITMAP), then
+       add -DWINDOWS also.  For example,
+            cc -DAA -DWINDOWS mimetex.c gifsave.c -lm -o mimetex.cgi
+       The above Unix-like syntax works with MinGW (http://www.mingw.org)
+       and djgpp (http://www.delorie.com/djgpp/) Windows compilers, but
+       probably not with most others, where it's only intended as a
+       "template".
+     * Several additional command-line options that you may find
+       useful are discussed in Section IId (href="#options")
+       of your mimetex.html page.
+
+  That's all there is to building mimeTeX.  You can now test your
+  mimetex.cgi executable from the Unix command line by typing, e.g.,
+       ./mimetex.cgi "x^2+y^2"
+  which should emit two ascii rasters something like the following
     Ascii dump of bitmap image...     Hex dump of colormap indexes...
     ........**..................**..  .......1**1................1**1.
     .......*..*.....*..........*..*.  .......*23*.....*..........*23*.
@@ -132,34 +145,50 @@ III.  COMPILATION AND INSTALLATION
     ................*....**.........  ................*....**1........
                                   The 5 colormap indexes denote rgb...
                                  .-->255 1-->196 2-->186 3-->177 *-->0
-  If you get much fancier than x^2+y^2, remember that many characters have
-  to be escaped from the Unix command line, e.g., x\<y or f\(x\)=x^2, etc.
-  Of course, you won't need these extra escapes when running mimetex from
-  a browser.
-
-  Once mimetex.cgi is working (and you're done playing with it),
-  mv it to your server's cgi-bin/ directory, where cgi programs
-  are expected (and chmod/chown it if necessary).  Then mv
-  mimetex.html to your server's htdocs/ directory.  Now point
-  your browser to www.yourdomain.com/mimetex.html , and it should
-  be rendered exactly like my page at www.forkosh.com/mimetex.html .
-       One "gotcha":  the two directories are typically of the form
-  somewhere/www/cgi-bin/ and somewhere/www/htdocs/ ,  so I set up
-  mimtex.html to get mimetex.cgi from the relative path ../cgi-bin/ .
-  If your directories are non-conforming, you may have to edit the
-  few dozen occurrences of ../cgi-bin/mimetex.cgi in mimetex.html
-  (globally changing ../cgi-bin/mimetex.cgi should work).
-  Sometimes a suitable symlink works; if not, you'll have to edit.
-
-  Either way, once mimetex.html displays properly, and you've reviewed
-  the tutorial it contains, you can begin writing html documents using
-  mimetex.cgi to render your math.
+  The right-hand illustration shows asterisks in the same positions as
+  the left-hand one, along with anti-aliased grayscale colormap indexes
+  assigned to neighboring pixels, and with the rgb value for each
+  index.  Just typing ./mimetex.cgi without an argument should produce
+  ascii rasters for the default expression f(x)=x^2.  If you see the
+  two ascii rasters then your binary's good, so mv it to your server's
+  cgi-bin/ directory and set permissions as necessary.
+
+  Once mimetex.cgi is working, mv it to your server's cgi-bin/ directory
+  (wherever cgi programs are expected), and chmod/chown it as necessary.
+  Then mv mimetex.html to your server's htdocs/ directory.  Now point
+  your browser to www.yourdomain.com/mimetex.html and you should see
+  your mimeTeX user's manual reference page.
+
+  Install Notes:
+     * These two directories are typically of the form
+       somewhere/www/cgi-bin/  and  somewhere/www/htdocs/
+       so I set up mimtex.html to access mimetex.cgi from
+       the relative path ../cgi-bin/   If your directories
+       are non-conforming, you may have to edit the few dozen
+       occurrences of ../cgi-bin/mimetex.cgi in mimetex.html
+       Sometimes a suitable symlink works.  If not, you'll
+       have to edit.  In that case, globally changing
+       ../cgi-bin/mimetex.cgi  often works.
+     * Either way, once mimetex.html displays properly, you can
+       assume everything is working, and can begin authoring html
+       documents using mimetex.cgi to render your own math.
 
 
 IV.  REVISION HISTORY
 ------------------------------------------------------------------------
-  01/11/04  J.Forkosh      version 1.40 beta released on www.forkosh.com
-                           LaTeX compatibility and various new features
+  A more detailed account of mimeTeX's revision history
+  is maintained at  http://www.forkosh.com/mimetexchangelog.html
+  ---
+  09/06/08  J.Forkosh      version 1.70 released.
+  11/30/04  J.Forkosh      version 1.60 released
+  10/02/04  J.Forkosh      version 1.50 released on CTAN with various new
+                           features and fixes, and updated documentation.
+  07/18/04  J.Forkosh      version 1.40 re-released on CTAN with minor
+                           changes, e.g., \mathbb font and nested \array's
+                           now supported.
+  03/21/04  J.Forkosh      version 1.40 released on CTAN, with improved
+                           LaTeX compatibility, various new features and
+                           fixes, including fix to work under Windows.
   12/21/03  J.Forkosh      version 1.30 released on CTAN, with improved
                            LaTeX compatibility and anti-aliasing, various new
                            features, and thoroughly updated documentation.
@@ -183,9 +212,5 @@ V.  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 ===========================