initial commit

README

+
+ --------------------------------------------------------------------------
+ March 6, 2009                                                 Version 1.02
+
+                  m a t h T e X   R e a d m e   F i l e
+
+ Copyright(c) 2007-2009, John Forkosh Associates, Inc. All rights reserved.
+ --------------------------------------------------------------------------
+
+                            by: John Forkosh
+                  john@forkosh.com     www.forkosh.com
+
+          This file is part of mathTeX, which is free software.
+          You may redistribute and/or modify it under the terms
+          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
+
+          mathTeX is discussed and illustrated online by
+          the mathTeX manual at its homepage
+                   http://www.forkosh.com/mathtex.html
+          Or you can follow the Installation instructions in
+          Section II below to immediately install mathTeX on
+          your own server.
+
+
+I.   INTRODUCTION
+------------------------------------------------------------------------
+  MathTeX, licensed under the GPL, is a cgi program that lets you
+  easily embed LaTeX math in your own html pages, blogs, wikis, etc.
+  It parses a LaTeX math expression and immediately emits the
+  corresponding gif (or png) image, rather than the usual TeX dvi.
+  So just place an html <img> tag in your document wherever you want
+  to see the corresponding LaTeX expression.  For example,
+        <img src="/cgi-bin/mathtex.cgi?f(x)=\int_{-\infty}^xe^{-t^2}dt"
+        alt="" border=0 align="middle">
+  immediately displays the corresponding gif image wherever you put
+  that <img> tag.
+
+  There's no inherent need to repeatedly write the cumbersome <img> tag
+  illustrated above.  For example, if you're using phpBB3, just click
+  Postings from the Administrator Control Panel, and add the Custom BBCode
+        [tex]{TEXT}[/tex]
+  with the HTML replacement
+        <img src="/cgi-bin/mathtex.cgi?{TEXT}" align="middle">
+  Then users can just type
+        [tex] f(x)=\int_{-\infty}^xe^{-t^2}dt [/tex]
+  in their posts to see a gif image of the enclosed expression.
+
+  MathTeX uses the latex and dvipng programs, along with all necessary
+  fonts, etc, from your TeX distribution.  If dvipng is not available,
+  you can compile mathTeX to use dvips from your TeX distribution, and
+  convert from the ImageMagick package, instead.  Links to online sources
+  for all these dependencies are on  http://www.forkosh.com/mathtex.html
+  and several are listed below.
+
+
+II.  INSTALLATION
+------------------------------------------------------------------------
+  Note: The current release of mathTeX only runs under Unix-like
+  operating systems.  To compile and install mathTeX on your own
+  Unix server...
+       +---
+       | Install mathTeX's dependencies and download mathTeX
+       +----------------------------------------------------
+       * First, make sure you have a recent LaTeX distribution
+              http://www.latex-project.org/ftp.html
+         installed on your server.  Ask your ISP or sysadmin
+         if you have any installation problems or questions.
+         Or see  http://www.forkosh.com/mimetex.html  if you
+         can't install latex.
+              Besides latex, mathTeX uses dvipng, which recent
+         LaTeX distributions typically include.  If you can't
+         install dvipng, see http://www.forkosh.com/mathtex.html
+         for instructions to use dvips and convert instead of dvipng.
+       * Then, download  http://www.forkosh.dreamhost.com/mathtex.zip
+         and  unzip mathtex.zip  in any convenient working
+         directory.  Your working directory should now contain
+              mathtex.zip    your downloaded gnu zipped mathTeX distribution
+              README         this file (see mathtex.html for demo/tutorial)
+              COPYING        GPL license, under which you may use mathTeX
+              mathtex.c      mathTeX source program and all functions
+              mathtex.html   mathTeX users manual
+       +---
+       | Compile and Install mathTeX
+       +----------------------------
+       * To compile an executable that emits
+         default gif images
+              cc mathtex.c -DLATEX=\"$(which latex)\"  \
+              -DDVIPNG=\"$(which dvipng)\"  \
+              -o mathtex.cgi
+         For default png images, add the -DPNG switch.  Additional
+         command-line switches that you may find useful are
+         discussed at  http://www.forkosh.com/mathtex.html
+       * Finally,
+              mv mathtex.cgi  to your server's cgi-bin/ directory,
+              chmod its permissions as necessary (typically 755),
+              making sure mathtex.cgi can rw files in cgi-bin/,
+         and you're all done.
+       +---
+       | Test installed image
+       +---------------------
+       * To quickly test your installed mathtex.cgi, type
+         a url into your browser's locator window something like
+              http://www.yourdomain.com/cgi-bin/mathtex.cgi?x^2+y^2
+        which should display the same image that you see at
+              http://www.forkosh.com/cgi-bin/mathtex.cgi?x^2+y^2
+        If you see the same image from your own domain link,
+        then you've completed a successful mathTeX installation.
+       * Optionally, to install a copy of the mathTeX manual
+         on your server,
+              mv mathtex.html  to your server's htdocs/ directory.
+         And, if the relative path from htdocs to cgi-bin
+         isn't ../cgi-bin, then edit mathtex.html and change
+         the few dozen occurrences as necessary.  Now,
+              http://www.yourdomain.com/mathtex.html
+         should display your own copy of the mathTeX manual.
+
+  Any problems with the above?
+        Read the more detailed instructions on mathTeX's homepage
+              http://www.forkosh.com/mathtex.html
+
+
+III. REVISION HISTORY
+------------------------------------------------------------------------
+  See  http://www.forkosh.com/mathtexchangelog.html  for a detailed
+  discussion of mathTeX revisions.
+      o 11 Oct 2007 -- mathTeX version 1.00 released.
+      o 12 Oct 2007 -- optional \usepackage[arg]{package} argument
+        now recognized correctly (initial release neglected to
+        handle optional [arg] following \usepackage).
+      o 12 Oct 2007 -- html &#nnn; now translated during preprocessing,
+        e.g., &#091 or &#091; becomes [ (left square bracket) before
+        it's submitted to latex.
+      o 12 Oct 2007 -- special mathTeX directives like \time
+        are now checked for proper command termination, i.e., non-alpha
+        character.  (In particular, LaTeX \times had been incorrectly
+        interpreted as mathTeX \time followed by an s.)
+      o 12 Oct 2007 -- url "unescape" translation, i.e.,
+        %20-to-blank, etc, repeated (done twice) for
+        <form> input.  (I'm not sure why this is necessary,
+        and can't reproduce the problem myself, but am acting
+        on seemingly reliable reports.)
+      o 20 Oct 2007 -- removed leading and trailing pairs of $$...$$'s
+        from input expressions, interpreting $...$ as \textstyle and
+        $$...$$ as \displaystyle (and $$$...$$$ as \parstyle).
+        Also removed leading and trailing \[...\], interpreting it
+        as \displaystyle.  (Note: \displaystyle is mathTeX's default,
+        so $$...$$'s or \[...\] are unnecessary.  But some people submit
+        expressions containing them, so they're now interpreted.)
+      o 16 Feb 2008 -- more robust test to display the correct
+        error message when a required dependency isn't installed.
+        (Occasionally, the "ran but failed" message was emitted
+        when a dependency was actually "not installed".)
+      o 16 Feb 2008 --  -DDENYREFERER=\"string\"  or
+        -DDENYREFERER=\"string1,string2,etc\"  compile switch added.
+        If compiled with it, mathTeX won't render images for
+        HTTP_REFERER's containing  string (or string1 or string2, etc)
+        as a substring of their url's.
+      o 17 Feb 2008 -- updated (slightly) documentation
+      o 18 Feb 2008 -- mathTeX version 1.01 released.
+      o 05 Mar 2009 -- \environment directive added to display
+        all http environment variables.
+      o 06 Mar 2009 -- mathTeX version 1.02 released.
+
+
+IV.  CONCLUDING REMARKS
+------------------------------------------------------------------------
+  I hope you find mathTeX 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.
+========================= END-OF-FILE README ===========================
+