# This is based on the idea of LatexRender.
# About as much a hack as it is, really:)
#
# WARNING: The fact that this evaluates arbitrary TeX is both a feature and a security issue.
# Know what this means, and use at your own risk.
#
# Requirements
# - PHP >=4.3.0 (for the sha1() function)
# - tetex (latex, dvips), and the implied ghostscript
# - imagemagick (for 'convert')
#
#
# Features
# - Caches generated images (like LatexRender).
# - Generates PNGs because there's little reason for another format.
# - It doesn't trust dvips' bounding box accuracy (like LatexRender does) and just relies on imagemagick's -trim.
# - Allows:
#   - Specifying a document-wide font size, a text color and background color.
#     (default: black on white, 17pt. Pt has no absolute meaning b)
#   - Specifying a resolution 
#     (note that the TeX 'pt' size has no absolute meaning; it's relative to are render resolution at 90dpi)
# - 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-styles to lowers the image a little, so that simple words with and without a dip look vaguely okay
#   when in the middle of text. There is no robust solution based on just images, though.
#
#
# Caveats
# - The cache assumes no collisions in the 16-bit keyspace. This could mean one mis-returned image, ever.
# - You can only use this from within PHP, and so assumes that its user knows not to do stupid things.
#   There is NO abuse/hack checking. The latex run runs under php, i.e. as the web server user, and
#   can read any file it can.
#   If you break your server, accidentally give the ability for people to list all your files through LaTeX,
#   then it's your doing.
# - If the intermediate postscript file is large and/or the resolution is very high, the image convert may 
#   well fail, or use huge amounts of memory. This is *not* meant for more than one page.
# - Generation takes a while (there's probably a few-seconds involved in TeX-stuff loading), 
#   so viewing pages right after you clear the cache will take a while.
#   - If you have an execution time limit and a lot of TeX bits, not all images may be generated 
#     on the first load. Reload a few times if that's so.
# - Needs work. I haven't checked all error codepaths, for one.
#
#
# Setup/Installation
# - install tetex or imagemagick if they are missing. Modern unices tend to have both.
#   - Executable paths are absolute and hardcoded; check below if they are right, look for 'exec('
#     (use 'which dvips', etc. in a shell to see what these should be for your system) 
# - put phptex.php in a server directory, allow access to this directory
# - In the directory you will be *calling* the script from, create subdirecties 'tmp' and 'images' and make
#   sure files can be created in both by php. I haven't tested it in safe mode. 
#   Without that, 
#   - mkdir tmp images
#   - chown apache:apache tmp images
#   should be enough.
#   - ...where apache:apache is the web server user and group. This could also be "www-user", "apache2",
#     or others, depending on your distro.
#   - Yes, you should do this once for/in each directory you want to use this from - each has a separate 
#     tmp and images cache. Sort of a caveat, but relative paths make life a little simpler.
#
# Maintenance
# - It is faily safe to empty the tmp directory. Ideally it should be, when nothing is being processed.
# - It is fairly safe (it may disturb running generation) and a good idea to clear the images directory
#   every now and then to remove stuff that's never used. I should probably supply a script that uses find -atime.
#
#
# Use
# - Include it with something like:  include_once('phplatex/phplatex.php')
# - call texify(tex, ptsize, r,g,b, br,bg,bb, extraprelude).
#   Only the tex-string is required. Hand it TeX, often surrounded by a $single$ or $$double$$ for math mode)
#   and it will return an <img src="..."> string you can usually just print to the document.
#   It caches based on the hash of the string, so asking for the same TeX twice will only cause a sha1() and
#   a filesystem exists-check and not a TeX-dvips-and-convert run - so it's fairly cheap to leave calls
#   embedded in your php.
#
#   Options:
#   ptsize:        The optional ptsize allows you to specify the base font size. Since 'extarticle' is used,
#                  you get 8,9,14,17 and 20pt on top of the standard 10,11 and 12pt.
#   r,g,b:         text color, each from 0.0 to 1.1. Default is black: 0.0 for each
#   br,bg,bb:      background color. Default is white, 1.0 for each
#   extraprelude:  This gets pasted verbatim in the predule. Useful to include extra packages.
#

