MDL-30070 message: Optimised search for users over multiple courses
[moodle.git] / filter / tex / README.mimetex
2  --------------------------------------------------------------------------
3  September 6, 2008                                             Version 1.70
5                   m i m e T e X   R e a d m e   F i l e
7  Copyright(c) 2002-2008, 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 3 or later,
16           as published by the Free Software Foundation. See
17                    http://www.gnu.org/licenses/gpl.html
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.
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
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.)
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.
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
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
110   Or, for an executable that emits gif images without
111   anti-aliasing,
112             cc -DGIF mimetex.c gifsave.c -lm -o mimetex.cgi
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
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.
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.
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.
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.
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   09/06/08  J.Forkosh      version 1.70 released.
183   11/30/04  J.Forkosh      version 1.60 released
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
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 ===========================