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

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 [https://bugzilla.wikimedia.org/enter_bug.cgi?product=MediaWiki%20extensions&component=Math+%28texvc%29 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


 * AMS* packages (amscls, amsmath) 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 texlive.


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

From a package
In Ubuntu, texvc can be installed by typing



On FreeBSD, this is provided by the  port.

If your OS isn't in the list, you can build it yourself following the instruction in the next section.

Compile from sources
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  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.

Windows
Getting it up and running on Windows can be somewhat troublesome, as it was developed on and for linux, so it is recommended to use one of the other options found below. The first alternative solution has the highest success rate, assuming you have the correct software installed.


 * Note: Maths support is strictly optional. Your wiki will run fine without it, although you'll need it if you want to enter formulae which are more complicated than a simple subscript.

What you'll need for all solutions:
 * Latex and dvips (using the [http://www.miktex.org/Setup.aspx Miktex package] for Windows)
 * [http://prdownloads.sourceforge.net/ghostscript/ GhostScript] for its Postscript libraries () (Caution! in newer versions the gswin32c.exe has to be renamed or linked to gs.exe)
 * [http://www.imagemagick.org/script/binary-releases.php#windows ImageMagick binaries] for windows

Install these packages to a short directory, preferably one which does not contain spaces. C:\texmf seems to be the most common. You may have to manually add these packages to the path.

Once you have these programs installed, check if the commands,  ,   and   (not the built-in windows-tool!) are working by typing them at the cmd prompt. (Note that you may have to use ctrl-c to quit them as they take input from the console if no arguments are supplied). If they're not found you'll have to modify your PATH variable and restart your operating system. (For some reason Apache or PHP doesn't update its PATH until reboot, a service stop-start does not work)

Option A - Using texvc
is the tool that is included with MediaWiki, but it is written for Linux / Unix. Getting this to work in Windows can be challenging.

Building texvc on Windows
This is a quick and dirty hack to make texvc work under Windows.

What you'll need:
 * the  sources (included in the math directory of the MediaWiki distribution)
 * a Make utility (for example mingw32-make, included in [http://www.mingw.org/download.shtml MinGW])
 * an [http://caml.inria.fr/download.en.html OCaml compiler]

If you use a pre-compiled binary you can skip this section, however you will still have to make the edits to Math.php and LocalSettings.php as described below.

Before we compile texvc, we need to modify some of the files to reflect certain differences between Windows and Unix/Linux (mainly filesystem differences).

Modify  so it looks like the file found here (updated).

If you have Visual C++ and MASM installed, make the optimized  by running the make utility in the math directory. If you do not have Visual C++ and MASM, make the bytecode version  (by typing for example   in the math directory) and rename it to. If an error occurs by do it via command line, restart your machine and try it again.

Configuring MediaWiki to use texvc
In, uncomment or insert:

to activate texvc functionality.

If you are using MediaWiki with IIS then you should replace "REQUEST_URI" with "SCRIPT_NAME" in all files.

And finally, set the  executable path to the root path of Wiki, by inserting this line in  :

Let me know how this works for you in the discussion page.

Troubleshooting
I have experienced several problems with this method in connection with math.php as of MediaWiki version 1.10.0 (I have no experience with earlier versions) and the above texvc executable (1.4.7) by Fernando. I chose the latter one because it required neither cygwin nor ocaml runtimes. Here's what I figured out:


 * 1) only the directory "$wgTmpDirectory" is passed to both the temp and the math directory that texvc expects on its command line. This somehow seems to cause unwanted deletion of the generated image.
 * 2) the math.php relies on the cygwin shell "sh" to be installed on the system, which is not the case on my system.
 * 3) "$wgTmpDirectory" and "$wgMathDirectory" contain some slashes instead of backslashes as is common for windows. This seems to mess something up for the texvc executable so the image file does not get generated. Surprisingly, if I copy the very same command-line from the MediaWiki debug logfile to a shell window, the file gets generated.
 * 4) after execution of texvc, the math.php looks for the image file in "$wgTmpDirectory" which is consistent with the call of texvc

The following steps to change math.php were necessary for me to get it working.

The constructor:

In " ";

Make "$wgMathDirectory" accessible by changing

into

Then change the target directory for the texvc call into wgMathDirectory by replacing

with

Now comment out the lines that try to use cygwin shell, if your system happens to be devoid of cygwin. Cmd.exe seems to be perfect for this anyway.

To solve the slash problem (if not already done) replace the line

with the lines

Finally replace

by

and

by

and

by

so the generated file will be found where it has been saved. And if the image already exists at the final destination don't error when calling.

The suggested solution is obviously a workaround for problems located in the specific texvc executable (with the exception of the probably missing cygwin shell). Perhaps it would be a cleaner solution to compile a texvc that does not have these problems, but personally I did not want to delve into the rather involved procedure of fixing and building texvc.

Permissions
If the math still is not working, turn on the debug log and find the command string that calls. For example:

TeX: C:\inetpub\wwwroot\w\math\texvc "C:\inetpub\wwwroot\w\images\tmp" "C:\inetpub\wwwroot\w\images\math" "\begin{align} y = & \frac{1}{2} + \frac{1}{3}x^2 + \\ & \frac{1}{4}x^3\end{align}" "utf-8"

Try the command in the console. If it works, you may have a permission problem. Try:
 * 1) Setting the images directory to Everyone; and
 * 2) Setting the internet user to a local profile (Application pools in IIS).
 * 3) Run [http://technet.microsoft.com/en-nz/sysinternals/bb896645(en-us).aspx</> Process Monitor] on the server, look for "ACCESS DENIED" status errors.  The path and user of the event will show which user needs permissions and what directories they need permission on.

Option B - Using LatexRender
You may find compiling texvc to be very complicated or simply not working. Here is another solution (Using LatexRender, thanks to Benjamin Zeiss, completed by [<tvar|sharp>http://www.metasharp.net/</> MetaSharp]). The directories given here are examples, use your owns. This method has been successfully tested up to MediaWiki 1.10.0, 1.13.1 and on MediaWiki 1.15.1.

Installation
latex dvips convert (not the Microsoft convert) gs
 * 1) install the complete [<tvar|miktex>http://www.miktex.org/Setup.aspx</> MikTeX] (not the basic one, use the network installer) in D:\wikitex\miktex
 * 2) install the static (to be sure dependencies are embed) binary of [<tvar|imagemagick>http://www.imagemagick.org/script/binary-releases.php#windows</> ImageMagick] in D:\wikitex\imagick (ensure there are no spaces in the path you choose)
 * 3) install [<tvar|afpl-ghost>http://prdownloads.sourceforge.net/ghostscript/</> AFPL GhostScript] in D:\wikitex\ghostscript
 * 4) copy D:\wikitex\ghostscript\gs8.54\bin\gswin32c.exe to D:\wikitex\ghostscript\gs8.54\bin\gs.exe
 * (8.54 can be different depending on version you install)
 * 1) add to the windows PATH environment variable this path: D:\wikitex\ghostscript\gs8.54\bin
 * (again, 8.54 can be different depending on version you install)
 * 1) If you installed MiKTeX for all users and are running IIS, you may also need to create MiKTeX folders under "C:\Documents and Settings\Default User\Application Data" and "C:\Documents and Settings\Default User\Local Settings\Application Data". Make sure the IIS working process account running PHP (IUSR_[whoever]) has both read and write permissions to these directories!
 * 2) open a command line (start -> execute -> cmd.exe)
 * 3) verify that the following commands are working:

Settings
(your wiki directory = $)
 * replace the file $/includes/Math.php with mathphp>Manual:Running MediaWiki on Windows/math.php</>|this one. Later, if you see error message  Strict standards: Non-static method MathRenderer::renderMath should not be called statically on the wiki page then change this line:

To this


 * uncomment or insert in $/LocalSettings.php :


 * insert in $/LocalSettings.php :


 * reboot if needed so that paths variables are updated for your services too

Verifications
$$\sqrt{2}$$
 * and voilà ;) Now you can try in the sandbox to see whether it works. Enter something like this and hit preview to see if it works:


 * the folders "math" and "tmp" should have been created in the "images" folder automatically.

How to get the latex "picture" package to work
Just put something like this into your wiki page:

$$\setlength{\unitlength}{1cm} \begin{picture}(4,2) \put(1,1){\circle{3}} \put(3,1){\circle*{5}} \end{picture} $$

[<tvar|umdebung>http://www.semibyte.de/wp/informatics/latex/picture_umgebung#kreise</> Here] is the result (modified orders of magnitude!).

Troubleshooting
You might experience some problems with formulas not being displayed if you are not logged in. In such a case comment out the 3 following lines in $/LocalSettings.php :

like this:

or just suppress them. Everything should be working fine now.

You have to give permissions to the webserver to all the folders that need to access. Not just the ones in the wiki image and temporary folders, but also where you installed latex and the other software.

Option C - Using MathLatexRender based on LatexRender of option B
Option C was tested on Windows Server 2008 with MW 1.23 LTS and extension Math REL1-23, because option B does not work in newer MediaWiki versions with the Math extension but only in older versions with the file Math.php in the includes directory.

Requirements: MediaWiki extension Math File man>Special:MyLanguage/Manual:Running MediaWiki on Windows/math.php</>|Math.php with class LatexRender from Benjamin Zeiss, 2003
 * GhostScript
 * ImageMagick
 * MikTex

Files to modify:


 * Math.php with class LatexRender, after modification renaming to MathLatexRender.php


 * Math.php from extension Math (add <tvar|code>$wgAutoloadClasses['MathLatexRender'] = $dir . 'MathLatexRender.php';</>)


 * MathRenderer.php from extension Math (function getRenderer(...) $mode default: $renderer = new MathLatexRender($tex, $params) instead of new Texvc($tex, $params))


 * LocalSettings.php (settings for Math, ImageMagick, MikTeX and $wgUseTeX = true; $wgMathDisableTexFilter = true;)

For more information like modification of MathLatexRender.php see <tvar|url>https://www.mediawiki.org/wiki/Extension_talk:Math#Math_REL-1_23_with_MW1.23LTS_on_Windows_with_ImageMagick.2C_MikTeX.2C_GhostScript_and_class_LatexRender</>.

Simplified solution with dvipng
https://bitbucket.org/FrigoCoder/script/src/tip/MediaWiki

This is a greatly simplified solution of the above, removing all code and comments unrelated to MediaWiki. It uses only LaTeX and dvipng compiled with FreeType, it does not require GhostScript or ImageMagick. MikTeX 2.9 contains these, 2.8 lacks FreeType to my knowledge. Since dvipng wraps the formulas, it does not check for correct image dimensions, though it could be implemented, dvipng can return the image dimensions somehow. It uses \displaystyle for all inline math. You can escape the inline math, but are still subject to the blacklist, so it is not recommended to write entire LaTeX books in it. Very, very verbose error messages revealing your paths and latex version, modify the last return line if you don't like them; I might make a $debug setting, though at the moment I don't see any possibility of exploits. It does not change the current directory, and does not clean up temporary files if some error occurred during rendering, so you can check whether someone tried to feed it something suspicious. Frigo 18:29, 11 April 2011 (UTC)

0) Make sure you have LaTeX and dvipng with FreeType support (e.g. MikTeX 2.9)

1) Copy the file to includes/Math.php

2) Add the following to LocalSettings.php (executable names will suffice if you have them in PATH)

3) Try it. My test is usually $$E=mc^2$$ :)

Comments for the previous, messy version:


 * Comment: This works for me in MediaWiki 1.11.0 except \begin{align}...\end{align} causes the image not to be rendered at all. This causes LaTeX to generate a blank DVI file and complain, "Package amsmath Error: \begin{align} allowed only in paragraph mode". If you comment out the usepackage{ams...} lines in Benjamin Zeiss's Math.php (function wrap_formula), the problem goes away. Maiden taiwan 20:21, 26 October 2007 (UTC)


 * Comment: This works for right out of the box for MediaWiki 1.10.0. The MikTeX installer sets everything up and the basic MikTeK package was enough. Only thing I needed to do, was a reboot after the install was finished. Good stuff. User:florihupf 16:30, 7/July/2007


 * Comment: Very easy and works great for MediaWiki 1.10.0. Why is there no MediaWiki Package with this for Installing Mediawiki with TeX on Windows?, 18.11.2007


 * Comment: This works with MediaWiki 1.11.0. I used texvc 1.4.7, MiKTeX 2.7 (full package), ImageMagick and Ghostscript 8.60. My only gripe is the size of MiKTeX when installed... more than 1 Gigabyte!!!

Alternative Solution with Texvc for experienced users (Mediawiki 1.16.0)
install this


 * wamp (included apache, php5, mysql)
 * a Make utility (for example mingw32-make, included in [<tvar|mingw>http://www.mingw.org/download.shtml</> MinGW])
 * an [<tvar|ocaml>http://caml.inria.fr/download.en.html</> OCaml compiler]
 * Latex and dvips (using the [<tvar|miktex>http://www.miktex.org/Setup.aspx</> Miktex package] for Windows)
 * [<tvar|ghost-forge>http://prdownloads.sourceforge.net/ghostscript/</> GhostScript] for its Postscript libraries (<tvar|ghost></>) (Caution! in newer versions the gswin32c.exe has to be renamed or linked to gs.exe)
 * [<tvar|imagick-win>http://www.imagemagick.org/script/binary-releases.php#windows</> ImageMagick binaries] for windows
 * maybe cygwin i got it

in upper manual is written how to install this 

try somehow build texvc ''Attention!!!!!!! not needed edit render.ml'' in upper manual is written how to build this 
 * the  sources (included in the math directory of the MediaWiki distribution)
 * C:\wamp\www\wiki\math> mingw32-make texvc.bc & mv texvc.bc to texvc.exe

Edit localconfig <pre style="overflow:auto;"> $wgUseTeX          = true; $wgTexvc = "c:/wamp/www/wiki/math/texvc.exe";

Edit include/math.php This must be commented /* ... */

debug

<pre style="overflow:auto;"> c:/wamp/www/wiki/math/texvc.exe "C:\wamp\www\wiki/images/tmp" "C:\wamp\www\wiki/images/tmp" "B^{X^{c + v}}_Y + 121\!\," "UTF-8" "transparent" or c:\wamp\www\wiki\math\texvc.exe "C:\wamp\www\wiki\images\tmp" "C:\wamp\www\wiki\images\tmp" "B^{X^{c + v}}_Y + 121\!\," "UTF-8" "transparent"

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 <TeX code>

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
Unfortunately, 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.