Annotation of loncom/cgi/mimeTeX/README, revision 1.2

1.1       albertel    1: 
                      2:  --------------------------------------------------------------------------
1.2     ! riegler     3:  September 6, 2008                                             Version 1.70
1.1       albertel    4: 
                      5:                   m i m e T e X   R e a d m e   F i l e
                      6: 
1.2     ! riegler     7:  Copyright(c) 2002-2008, John Forkosh Associates, Inc. All rights reserved.
1.1       albertel    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
1.2     ! riegler    15:           of the GNU General Public License, version 3 or later,
1.1       albertel   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)
1.2     ! riegler    94:        COPYING        GPL license, under which you may use mimeTeX
1.1       albertel   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: ------------------------------------------------------------------------
1.2     ! riegler   179:   A more detailed account of mimeTeX's revision history
        !           180:   is maintained at  http://www.forkosh.com/mimetexchangelog.html
        !           181:   ---
        !           182:   09/06/08  J.Forkosh      version 1.70 released.
        !           183:   11/30/04  J.Forkosh      version 1.60 released
1.1       albertel  184:   10/02/04  J.Forkosh      version 1.50 released on CTAN with various new
                    185:                            features and fixes, and updated documentation.
                    186:   07/18/04  J.Forkosh      version 1.40 re-released on CTAN with minor
                    187:                            changes, e.g., \mathbb font and nested \array's
                    188:                            now supported.
                    189:   03/21/04  J.Forkosh      version 1.40 released on CTAN, with improved
                    190:                            LaTeX compatibility, various new features and
                    191:                            fixes, including fix to work under Windows.
                    192:   12/21/03  J.Forkosh      version 1.30 released on CTAN, with improved
                    193:                            LaTeX compatibility and anti-aliasing, various new
                    194:                            features, and thoroughly updated documentation.
                    195:   10/17/03  J.Forkosh      version 1.20 released on CTAN, adding picture
                    196:                            environment and various other changes (e.g.,
                    197:                            more delimiters arbitrarily sized) and fixes.
                    198:   07/29/03  J.Forkosh      version 1.10 released on CTAN, completely replacing
                    199:                            mimeTeX's original built-in fonts with thinner and
                    200:                            more pleasing fonts, and adding one larger size.
                    201:   06/27/03  J.Forkosh      version 1.01 released on CTAN, adding lowpass
                    202:                            anti-aliasing for gifs, and http_referer checks,
                    203:                            and fixing a few very obscure bugs.
                    204:   12/11/02  J.Forkosh      version 1.00 released on CTAN, fixing \array bug
                    205:                            and adding various new features.
                    206:   10/31/02  J.Forkosh      version 0.99 released on CTAN
                    207:   09/18/02  J.Forkosh      internal beta test release
                    208: 
                    209: 
                    210: V.  CONCLUDING REMARKS
                    211: ------------------------------------------------------------------------
                    212:   I hope you find mimeTeX useful.  If so, a contribution to your
                    213:   country's TeX Users Group, or to the GNU project, is suggested,
                    214:   especially if you're a company that's currently profitable.
                    215: ========================= END-OF-FILE README ===========================
                    216: 

FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>