Texvc

texvc is one of many external programs that are necessary for the typing of formulas in mediawiki. This program is mentioned in the manual of the installation of mediawiki, see Extension:Math.

texvc is a shortened version of TeX validator and converter. It validates AMS-LaTeX mathematical expressions and converts them to HTML, MathML, or PNG graphics. It was written by Tomasz Wegrzanowski and integrated into MediaWiki. The MediaWiki functionality that used this external program was moved to Extension:Math in MediaWiki 1.18.

When Extension:Math is installed, texvc is located at $IP/extensions/Math/math/texvc where $IP denotes the directory where mediawiki was installed. texvc in its turn requires three additional programs, ocaml, LaTeX and dvipng. These three programs do not come with the distribution of mediawiki. These programs should be downloaded manually and installed under the special (not default!) names, specific for each server. In particular, if one already has LaTeX installed under any other place, then, by default, it will not be used and the wiki-format of the formulas will not be supported. The process of this installation of texvc, ocaml, LaTeX and dvipng is described in the special text file $IP/extensions/Math/math/README ; that file is copy-pasted below:

About texvc
texvc takes LaTeX-compatible equations and produces formatted output in HTML, MathML, and (via LaTeX/dvipng) 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 and is under the GPL license.

Please report bugs at Bugzilla with "MediaWiki extensions" as product and "Math (texvc)" as component.

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, dvipng. These need to be installed and in the PATH: latex, dvipng

will render correctly while others won't render. Most distributions of TeX already contain AMS*. In Debian/Ubuntu you need to install tetex-extra.
 * AMS* packages (amscls, amsmath) for LaTeX also need to be installed. Without AMS* some equations


 * To work properly with rendering non-ASCII Unicode characters, a supplemental TeX package is needed (cjk-latex in Debian)

Installation
In Ubuntu, texvc can be installed by typing



From the terminal, change to the  sub-directory of your MediaWiki install, and make sure the math directory is writable:



Then, run  (or   if GNU make is not your default make). This should produce the texvc executable.

By default, MediaWiki will search in this directory for texvc; if you moved it elsewhere, you'll have to modify $wgTexvc and set it to the path of the texvc executable.

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 

Be sure to properly quote the TeX code!

Example:

texvc /home/wiki/tmp /home/wiki/math "y=x+2" iso-8859-1 "rgb 1.0 1.0 1.0"

LaTeX syntax
The syntax is documented at m:Help:Formula.

In addition to standard AMS LaTeX, texvc interprets additional syntax such as  for HTML math character entities (for example,   →  ) which have different names in LaTeX.

Output modes
The HTML-code generated by texvc may be in one of three modes:
 * 1) Conservative: the code should look good and work well in most browsers.
 * 2) Moderate: the code should work and look good in reasonably modern browsers.
 * 3) Liberal: the code is HTML, but it is designed for very recent browsers, such as newer versions of Mozilla Firefox. While it should be legible, it might not look very good.

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 l%5%h      ok, liberal html, no mathml C%5%h\0%m  ok, conservative html, with mathml M%5%h\0%m  ok, moderate html, with mathml L%5%h\0%m  ok, liberal html, with mathml X%5%m      ok, no html, with mathml S          syntax error E          lexing error 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

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.

If some equations render correctly while others don't, you probably don't have AMS* packages for LaTeX installed. Most distributions of TeX come with AMS*. In Debian/Ubuntu AMS* is in tetex-extra package. To check if that is the problem you can try those two equations: x + y   x \implies y The first uses only standard LaTeX, while the second uses symbol \implies from AMS*. If the first renders, but the second doesn't, you need to install AMS*.

Hacking
Before you start hacking on the math package it's good to know the workflow, which is basically:


 * 1) texvc gets called by extensions/Math/Math.body.php (check out the line begining with "$cmd")
 * 2) texvc does its magic, which is basically to check for invalid latex code.
 * 3) texvc takes the user input if valid and creates a latex file containing it, see get_preface in texutil.ml
 * 4) dvipng(1) gets called to create a .png file. See render.ml for this process (commenting out the removal of the temporary file is useful for debugging).

Adding support for commutative diagrams
To be able to generate commutative diagrams via the LaTeX package xy-pic, just modify the wrap_formula function in your math.php: function wrap_formula($latex_formula) { $string = "\documentclass{".$this->_latexclass."}\n"; $string .= "\usepackage{amsmath}\n"; $string .= "\usepackage{amsfonts}\n"; $string .= "\usepackage{amssymb}\n"; $string .= "\pagestyle{empty}\n"; $string .= "\begin{document}\n"; $string .= "$".$latex_formula."$\n"; $string .= "\end{document}\n"; return $string; }
 * your function $/includes/Math.php before the change:

function wrap_formula($latex_formula) { $string = "\documentclass{".$this->_latexclass."}\n"; $string .= "\usepackage{amsmath}\n"; $string .= "\usepackage{amsfonts}\n"; $string .= "\usepackage{amssymb}\n"; $string .= "\pagestyle{empty}\n"; $string .= "\input xy\n"; $string .= "\xyoption{all}\n"; $string .= "\begin{document}\n"; $string .= "$".$latex_formula."$\n"; $string .= "\end{document}\n"; return $string; }
 * and afterwards:

Formulas will still work normally as before, as xy-pic is enabled by the \xymatrix{} command. Try this for fun:

$$\xymatrix{U \ar@/_/[ddr]_y \ar@/^/[drr]^x \ar@{.>}[dr]|-{(x,y)}           \\ & X \times_Z Y \ar[d]^q \ar[r]_p & X \ar[d]_f      \\ & Y \ar[r]^g  & Z                }$$

end of file README
also, that directory contains files $IP/extensions/Math/math/texvc_test.ml and $IP/extensions/Math/math/texvc_tex.ml that are also necesary.

The file texvc is not the only file required for the support of mathematical typing. There are many other files necessary; they are mentioned in the Manual:Enable TeX.

The installing of the support of typing mathematics in mediawiki with texvc requires certain programming in a language, pretty different from that used to type the mediawiki documents. This process is not always successful; some problems seem to be not resolved at least for the beginning of year 2011.