Add some actual information to the README. :)

diff --git a/math/README b/math/README
index 1f0f5e4..ea49c8e 100644 (file)
--- a/math/README
+++ b/math/README
@@ -1,4 +1,65 @@
-texvc output format is like that:
+== About texvc ==
+
+texvc takes LaTeX-compatible equations and produces formatted output in
+HTML, MathML, and (via LaTeX/dvips/ImageMagick) rasterized PNG images.
+Input data is parsed and scrutinized for safety, and the output includes
+an estimate of whether the code is simple enough that HTML rendering will
+look acceptable.
+
+The program was written by Tomasz Wegrzanowski for use with MediaWiki;
+it's included as part of the MediaWiki package (http://wikipedia.sf.net)
+and is under the GPL license.
+
+Please report bugs at:
+http://sourceforge.net/tracker/?group_id=34373&atid=411192
+
+== Setup ==
+
+=== Requirements ===
+
+OCaml 3.06 or later is required to compile texvc; this can be acquired
+from http://caml.inria.fr/ if your system doesn't have it available.
+
+The makefile requires GNU make.
+
+Rasterization is done via LaTeX, dvips, and ImageMagick. These need
+to be installed and in the PATH: latex, dvips, convert
+
+To work properly with rendering non-ASCII Unicode characters, a
+supplemental TeX package is needed (cjk-latex in Debian)
+
+=== Installation ===
+
+Run 'make' (or 'gmake' if GNU make is not your default make). This should
+produce the texvc executable.
+
+If you're using MediaWiki's install.php and have enabled $wgUseTeX in your
+LocalSettings.php, the installer will try to copy texvc into place, in the
+'math' subdirectory under where wiki.phtml is installed.
+
+
+== Usage ==
+
+Normally texvc is called from MediaWiki's Math.php modules and everything
+Just Works. It can be run manually for testing or for use in another app.
+
+=== Command-line parameters ===
+
+    texvc <temp directory> <output directory> <TeX code> <encoding>
+
+Be sure to properly quote the TeX code!
+
+Example:
+
+    texvc /home/wiki/tmp /home/wiki/math "y=x+2" iso-8859-1
+
+=== Output format ===
+
+Status codes and HTML/MathML transformations are returned on stdout.
+A rasterized PNG file will be written to the output directory, named
+for the MD5 hash code.
+
+texvc output format is like this:
     +%5                ok, but not html or mathml
     c%5%h      ok, conservative html, no mathml
     m%5%h      ok, moderate html, no mathml
@@ -12,11 +73,25 @@ texvc output format is like that:
     F%s                unknown function %s
     -          other error
 
-\0 - null character
-%5 - md5, 32 hex characters
-%h - html code, without \0 characters
-%m - mathml code, without \0 characters
+ \0 - null character
+ %5 - md5, 32 hex characters
+ %h - html code, without \0 characters
+ %m - mathml code, without \0 characters
+
+
+== Troubleshooting ==
+
+Unforunately, many error conditions with rasterization are not well reported.
+texvc will return as though everything is successful, and the only obvious
+sign of problems for the user is a big X on a wiki page where an equation
+should be.
+
+Try running texvc from the command line to ensure that the software it relies
+upon is all set up.
 
+Ensure that the temporary and math directories exist and can be written to by
+the user account the web server runs under; if you don't control the server,
+you may have to make them world-writable.
 
+...
 
-(GNU make is required to compile; if 'make' fails, try 'gmake'.)