# README for PHPLaTeX 0.5
# Renders LaTeX into images by calling LaTeX itself from PHP. Rather a hack that way...
#
#
# Requirements
# - PHP    (>=4.3.0, for the sha1() function)
# - tetex and ghostscript  (for latex, dvips)
# - imagemagick    (for the image conversion)
#
#
# Setup/Installation
# - Have latex (probably tetex), imagemagick, ghostscript installed. 
#   (paths to these are currently hardcoded and absolute; check them against e.g. "which dvips" ) 
# - Put phplatex.php somewhere from which you can include it.
# - In each directory you will be *calling* the script from, create subdirecties 'tmp' and 'images' 
#   and make sure files can be created by PHP (or rather, apache) in both. It should be enough to do:
#   - mkdir tmp images
#   - chown apache:apache tmp images     
#     (may also be www-user, apache2, or some other user/groupname)
#
# Use
# - Include it with something like   include('phplatex/phplatex.php')
# - call texify(texstring, dpi, r,g,b, br,bg,bb, extraprelude)
#   Only the tex-string is required, which is pasted in a template LaTeX document.
#   This means you can use almost arbitrary TeX, including $math$, tables and such.
#   It will return an string containing <img src="...">, which you can PHP-print
#   to the document to show the image.
#
# Maintenance
# - You can empty the tmp and image directory at will, since tmp sometimes contains a few leftovers,
#   and images may contain old images that are never accessed.
#
#
# Features
# - Allows specifying rendering resolution (default:90, capped at 300 for memory reasons) 
# - Allows use of colors. (default: black on white, specifically 0.0,0.0,0.0 on 1.0,1.0,1.0)
# - Allows inclusion of extra TeX packages (that is, extra prelude text)
# - Caches generated images (based on document string) so asking for already-generated TeX is
#   just a filesystem check; you can leave the texify() calls in the PHP as this is pretty cheap.
# - Generates PNGs.  (Could also generate GIFs; I seem to remember a minor practical problem with it)
# - Relies on image trimming instead of trusting dvips' bounding box.
# - The background color is made transparent in the png. Since text is antialiased, small differences 
#   between this and your actual html background color don't matter much.
# - CSS-based image lowering to have inline text show up halfway decently.
#
# Caveats
# - Initial generation takes a while, perhaps a second per image. (hence the image cache)
#   If you hit the PHP time limit, you may need to refresh a few times before everything is built.
# - Fails for very large images (hence the resolution cap)
# - Fails when you include TeX that typesets as two pages or more (try \small and/or a higher resolution)
#
# Arguables
# - You can use arbitrary tex. This is a feature as well as a security issue.
#   Know exactly what this means and/or use at your own risk.
#   Like (non-safe-mode) PHP, the processes can do everything the web server user can.
# - Requires recent TeX version as it uses extarticle and includes color, amsmath, amsfont, and amssymb.
# - Uses \nonstopmode, meaning latex will fix errors it can, so you can get away with some bad TeX.
# - The (default) Computer Modern fonts don't render as well at relatively low resolutions as, say,
#   pslatex fonts (Times, Helvatica, Courier), due to thickness and antialiasing, so change fontset to taste.
#   Sharpening helps only a little, and can look worse when colours or shades are involved 
#   (I tried -unsharp 1x1+1+0).
#



