math/README

   1 == About texvc ==
   2
   3 texvc takes LaTeX-compatible equations and produces formatted output in
   4 HTML, MathML, and (via LaTeX/dvips/ImageMagick) rasterized PNG images.
   5 Input data is parsed and scrutinized for safety, and the output includes
   6 an estimate of whether the code is simple enough that HTML rendering will
   7 look acceptable.
   8
   9 The program was written by Tomasz Wegrzanowski for use with MediaWiki;
  10 it's included as part of the MediaWiki package (http://wikipedia.sf.net)
  11 and is under the GPL license.
  12
  13 Please report bugs at:
  14 http://sourceforge.net/tracker/?group_id=34373&atid=411192
  15
  16 == Setup ==
  17
  18 === Requirements ===
  19
  20 OCaml 3.06 or later is required to compile texvc; this can be acquired
  21 from http://caml.inria.fr/ if your system doesn't have it available.
  22
  23 The makefile requires GNU make.
  24
  25 Rasterization is done via LaTeX, dvips, and ImageMagick. These need
  26 to be installed and in the PATH: latex, dvips, convert
  27
  28 To work properly with rendering non-ASCII Unicode characters, a
  29 supplemental TeX package is needed (cjk-latex in Debian)
  30
  31 === Installation ===
  32
  33 Run 'make' (or 'gmake' if GNU make is not your default make). This should
  34 produce the texvc executable.
  35
  36 If you're using MediaWiki's install.php and have enabled $wgUseTeX in your
  37 LocalSettings.php, the installer will try to copy texvc into place, in the
  38 'math' subdirectory under where wiki.phtml is installed.
  39
  40
  41 == Usage ==
  42
  43 Normally texvc is called from MediaWiki's Math.php modules and everything
  44 Just Works. It can be run manually for testing or for use in another app.
  45
  46 === Command-line parameters ===
  47
  48     texvc <temp directory> <output directory> <TeX code> <encoding>
  49
  50 Be sure to properly quote the TeX code!
  51
  52 Example:
  53
  54     texvc /home/wiki/tmp /home/wiki/math "y=x+2" iso-8859-1
  55
  56 === Output format ===
  57
  58 Status codes and HTML/MathML transformations are returned on stdout.
  59 A rasterized PNG file will be written to the output directory, named
  60 for the MD5 hash code.
  61
  62 texvc output format is like this:
  63     +%5         ok, but not html or mathml
  64     c%5%h       ok, conservative html, no mathml
  65     m%5%h       ok, moderate html, no mathml
  66     l%5%h       ok, liberal html, no mathml
  67     C%5%h\0%m   ok, conservative html, with mathml
  68     M%5%h\0%m   ok, moderate html, with mathml
  69     L%5%h\0%m   ok, liberal html, with mathml
  70     X%5%m       ok, no html, with mathml
  71     S           syntax error
  72     E           lexing error
  73     F%s         unknown function %s
  74     -           other error
  75
  76  \0 - null character
  77  %5 - md5, 32 hex characters
  78  %h - html code, without \0 characters
  79  %m - mathml code, without \0 characters
  80
  81
  82 == Troubleshooting ==
  83
  84 Unforunately, many error conditions with rasterization are not well reported.
  85 texvc will return as though everything is successful, and the only obvious
  86 sign of problems for the user is a big X on a wiki page where an equation
  87 should be.
  88
  89 Try running texvc from the command line to ensure that the software it relies
  90 upon is all set up.
  91
  92 Ensure that the temporary and math directories exist and can be written to by
  93 the user account the web server runs under; if you don't control the server,
  94 you may have to make them world-writable.
  95
  96 ...
  97