Texvc

From MediaWiki.org
Jump to: navigation, search

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 Manual:Enable TeX.

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

\mathcal W/extensions/Math/math/texvc

where \mathcal W 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 \mathcal W/math/README ; that file already has the wiki-format, and it is copypasted below:

About texvc[edit | edit source]

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.

Setup[edit | edit source]

Requirements[edit | edit source]

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

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

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

Installation[edit | edit source]

In Ubuntu, texvc can be installed by typing

sudo apt-get install mediawiki-math

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

sudo chown your-username .


Then, run make (or gmake 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[edit | edit source]

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[edit | edit source]

   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[edit | edit source]

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[edit | edit source]

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[edit | edit source]

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[edit | edit source]

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[edit | edit source]

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[edit | edit source]

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:

<math>\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                }</math>

end of file README[edit | edit source]

also, that directory contains files \mathcal W/extensions/Math/math/texvc_test.ml and \mathcal W/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.