# README for PHPLaTeX 0.4
# Renders LaTeX into images by calling LaTeX itself from PHP. Rather a hack that way:)
#
# WARNING: You can pass through arbitrary TeX, which is both a feature and a security issue.
#          Know exactly what this means and/or use at your own risk.
#
# Requirements
# - PHP >=4.3.0 (for the sha1() function)
# - tetex and ghostscript (for latex, dvips)
# - imagemagick (for convert)
#
#
# Features
# - Caches generated images
# - Generates PNGs.  (Could also generate GIFs; I seem to remember a minor practical problem with it)
# - It doesn't trust dvips' bounding box accuracy and just relies on imagemagick's -trim.
# - Allows specifying:
#   - a rendering resolution (default:90dpi. The pt size is 12). Capped at 300dpi for memory reasons.
#   - a text color and background color (default: black on white)
#   - extra TeX packages to load
# - 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.
#
# Arguables
# - Uses extarticle, includes color,amsmath,amsfont,amssymb. This is more flexible in terms of writing, 
#   but you do need a recent and fairly complete (packetwise) LaTeX installation.
# - Uses nonstopmode, meaning latex will try to fix errors with its best guesses instead of prompting 
#   you (which would be meaningless and actually bad in this context), so you can get away with somewhat 
#   illegal TeX.
# - At relatively low resolutions the default Computer Modern fonts don't render as well as, say, the
#   pslatex ones (Times, Helvatica, Courier), apparently due to thickness and antialiasing. Change 
#   font set to taste. Sharpening helps only a little, and looks worse when colours or shades are
#   involved. (I tried -unsharp 1x1+1+0)
# 
# Caveats
# - The cache assumes no collisions in the 160-bit keyspace. This could possibly mean one mis-returned
#   image, ever.
# - Assumes that its user avoids bad things securitywise, such as allowing external input into the TeX.
#   There is NO abuse/hack checking. TeX runs runs under php, meaning 'as the web server user', and
#   can read any file it can.   If you break your server or, 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 fail, or use huge amounts of memory; this is why there is a DPI cap, but this is *not* meant 
#   for any large amount of text or a huge resolution.
# - Initial generation takes a while, there's on the order of a second involved in TeX and its 
#   dependencies (and perhaps half a second immediately after because of caching) 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 
#   this can mean not all images are generated on the first load. Reload a few times if that's the case.
# - Needs work. I haven't checked all error codepaths, so it may leave behind temporary files on bad TeX.
#
#
# Setup/Installation
# - Install latex (probably tetex), imagemagick, ghostscript (implied in dvips) and such if they are 
#   missing. Modern unices tend to just have these.
#   - Executable paths are absolute and hardcoded; check the PHP lines in phplatex.php that mention 
#    'exec(' against where e.g. 'which dvips' (run from a shell) tells you that executable is on your
#    system.
# - Put phplatex.php in a served directory. It doesn't matter where, as long as you can include it.
# - In the 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.
#   - mkdir tmp images
#   - chown apache:apache tmp images
#   ...should be enough.  (I haven't tested this in PHP's safe mode; more details may apply) 
#   Notes:
#   - Yes, you should do this once for (and directly in) each directory you want to use this from;
#     each will need a separate tmp and images cache. Sort of a caveat, but relative paths make 
#     life a little simpler.
#   - The above apache:apache is the web server user and group. This could be different on your 
#     system, say "www-user", "apache2", or others, depending mostly on your *nix distribution.
#
# Use
# - Include it with something like:  include_once('phplatex/phplatex.php')
# - call texify(texstring, ptsize, r,g,b, br,bg,bb, extraprelude).
#   Only the tex-string is required, which is basically just pasted in a template LaTeX document,
#   meaning you can hand it arbitrary TeX snippets, e.g. math surrounded by a $single$ or $$double$$
#   dollars)
#   It will return an <img src="..."> string you can usually just print to the document.
#   It caches based on the hash of the (document) string, so asking for the same TeX twice will only
#   cause a hash call and a filesystem exists-check, and not a TeX-dvips-and-convert run - so it's
#   pretty resource-cheap to leave calls embedded in your php, which is handy for page maintenance.
#
#   Options:
#     dpi:           Control of output size through the rendering resolution.       Default: 90
#     r,g,b:         text color, each from 0.0 to 1.0.          Default is black (0.0, 0.0, 0.0)
#     br,bg,bb:      background color.                          Default is white (1.0, 1.0, 1.0)
#     extraprelude:  This gets pasted verbatim in the predule. Useful to include extra packages.
#
#
# Maintenance
# - You can empty the tmp directory. 
#   Note that it may cause a generation to fail if the script was busy at the time.
# - You can empty the images directory, which can be useful if you suspect there are unused files.
#   (Check with ls -l --time=access)   If someone is loading your page right after it will be slow,
#   and if they were loading exactly as you were deleting it's possible an image isn't displayed 
#   (race with the cache lookup)



