math/README

   1 == About texvc ==
   2
   3 texvc takes LaTeX-compatible equations and produces formatted output in HTML,
   4 MathML, and (via LaTeX/dvipng) rasterized PNG images.
   5 Input data is parsed and scrutinized for safety, and the output includes an
   6 estimate of whether the code is simple enough that HTML rendering will look
   7 acceptable.
   8
   9 The program was written by Tomasz Wegrzanowski for use with MediaWiki; it's
  10 included as part of the MediaWiki package (http://www.mediawiki.org) and is
  11 under the GPL license.
  12
  13 Please report bugs at: https://bugzilla.wikimedia.org/
  14 with "MediaWiki extensions" as product and "texvc" as component.
  15
  16 == Setup ==
  17
  18 === Requirements ===
  19
  20 OCaml 3.06 or later is required to compile texvc; this can be acquired from
  21 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, dvipng. These need to be installed and in
  26 the PATH: latex, dvipng
  27
  28 AMS* packages for LaTeX also need to be installed. Without AMS* some equations
  29 will render correctly while others won't render. Most distributions of TeX
  30 already contain AMS*. In Debian/Ubuntu you need to install tetex-extra.
  31
  32 To work properly with rendering non-ASCII Unicode characters, a supplemental TeX
  33 package is needed (cjk-latex in Debian)
  34
  35 === Installation ===
  36
  37 Run 'make' (or 'gmake' if GNU make is not your default make). This should
  38 produce the texvc executable.
  39
  40 Then you'll need to set $wgUseTeX to true in your LocalSettings.php. By default,
  41 MediaWiki will search in this directory for texvc, if you moved it elsewhere,
  42 you'll have to modify $wgTexvc and set it to the path of the texvc executable.
  43
  44 == Usage ==
  45
  46 Normally texvc is called from MediaWiki's Math.php modules and everything
  47 Just Works. It can be run manually for testing or for use in another app.
  48
  49 === Command-line parameters ===
  50
  51     texvc <temp directory> <output directory> <TeX code> <encoding>
  52
  53 Be sure to properly quote the TeX code!
  54
  55 Example:
  56
  57     texvc /home/wiki/tmp /home/wiki/math "y=x+2" iso-8859-1
  58
  59 === Output format ===
  60
  61 Status codes and HTML/MathML transformations are returned on stdout.
  62 A rasterized PNG file will be written to the output directory, named
  63 for the MD5 hash code.
  64
  65 texvc output format is like this:
  66     +%5         ok, but not html or mathml
  67     c%5%h       ok, conservative html, no mathml
  68     m%5%h       ok, moderate html, no mathml
  69     l%5%h       ok, liberal html, no mathml
  70     C%5%h\0%m   ok, conservative html, with mathml
  71     M%5%h\0%m   ok, moderate html, with mathml
  72     L%5%h\0%m   ok, liberal html, with mathml
  73     X%5%m       ok, no html, with mathml
  74     S           syntax error
  75     E           lexing error
  76     F%s         unknown function %s
  77     -           other error
  78
  79  \0 - null character
  80  %5 - md5, 32 hex characters
  81  %h - html code, without \0 characters
  82  %m - mathml code, without \0 characters
  83
  84
  85 == Troubleshooting ==
  86
  87 Unforunately, many error conditions with rasterization are not well reported.
  88 texvc will return as though everything is successful, and the only obvious
  89 sign of problems for the user is a big X on a wiki page where an equation
  90 should be.
  91
  92 Try running texvc from the command line to ensure that the software it relies
  93 upon is all set up.
  94
  95 Ensure that the temporary and math directories exist and can be written to by
  96 the user account the web server runs under; if you don't control the server,
  97 you may have to make them world-writable.
  98
  99 If some equations render correctly while others don't, you probably don't have
 100 AMS* packages for LaTeX installed. Most distributions of TeX come with AMS*.
 101 In Debian/Ubuntu AMS* is in tetex-extra package.
 102 To check if that is the problem you can try those two equations:
 103     x + y
 104     x \implies y
 105 The first uses only standard LaTeX, while the second uses symbol \implies from AMS*.
 106 If the first renders, but the second doesn't, you need to install AMS*.
 107
 108 == Hacking ==
 109
 110 Before you start hacking on the math package its good to know the workflow,
 111 which is basically:
 112
 113 1. texvc gets called by includes/Math.php (check out the line begining with "$cmd")
 114 2. texvc does its magic, which is basically to check for invalid latex code.
 115 3. texvc takes the user input if valid and creates a latex file containing it, see
 116    get_preface in texutil.ml
 117 4. dvipng(1) gets called to create a .png file
 118    See render.ml for this process (commenting out the removal of
 119    the temporary file is useful for debugging).