# 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 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

## 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> <color>


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 \codes for HTML math character entities (for example, &Sigma;\Sigma) 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 w: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: • 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 .= "\begin{document}\n";
$string .= "$".$latex_formula."$\n";
$string .= "\end{document}\n"; return$string;
}

• and afterwards:
   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;
}


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 }$


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