Jump to content

texvc/en

From mediawiki.org
Translate this page
Languages:

Warning: Display title "texvc/en" overrides earlier display title "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 

$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 a 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.

Setup

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)

Installation

From a package

Debian and Ubuntu packages of texvc are available, see User:Legoktm/Packages/texvc.

sudo apt-get install texvc

On older systems the package might be named mediawiki-math-texvc.

On FreeBSD, this is provided by the print/texvc port. 

    # Through packages
    $ pkg install texvc
    
    # Through ports
    $ cd /usr/ports/print/texvc
    $ make install

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 "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.

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:

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 gs, latex, dvips and convert (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

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 texvc sources (included in the math directory of the MediaWiki distribution)
  • a Make utility (for example mingw32-make, included in MinGW)
  • an 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 math\render.ml so it looks like the file found here (updated).

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

Configuring MediaWiki to use texvc

In LocalSettings.php, uncomment or insert: 

$wgUseTeX = true;

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 texvc executable path to the root path of Wiki, by inserting this line in LocalSettings.php: 

$wgTexvc = "texvc.exe"; # Location of the texvc binary

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: 

function __construct( $tex, $params=array() ) {
    if ( wfIsWindows() ) {
        $tex = str_replace( "\n", ' ', $tex );
    }
    $this->tex = $tex;
    $this->params = $params;
}

In "function render()";

Make "$wgMathDirectory" accessible by changing 

function render() {
    global $wgTmpDirectory, $wgInputEncoding;

into 

function render() {
    global $wgTmpDirectory,$wgMathDirectory, $wgInputEncoding;

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

$cmd = $wgTexvc . ' ' .
    escapeshellarg( $wgTmpDirectory ).' '.
    escapeshellarg( $wgTmpDirectory ).' '.
    escapeshellarg( $this->tex ).' '.
    escapeshellarg( $wgInputEncoding );

with 

$cmd = $wgTexvc . ' ' .
    escapeshellarg( $wgTmpDirectory ).' '.
    escapeshellarg( $wgMathDirectory ).' '.
    escapeshellarg( $this->tex ).' '.
    escapeshellarg( $wgInputEncoding );

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. 

/*if ( wfIsWindows() ) {
    # Invoke it within cygwin sh, because texvc expects sh features in its default shell
    $cmd = 'sh -c ' . wfEscapeShellArg( $cmd );
}*/

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

wfDebug( "TeX: $cmd\n" );

with the lines 

 $cmd=str_replace("'","\"",$cmd); # replace single quotes by double quotes
 $cmd=str_replace("/","\\",$cmd); # replace slash by backslash for windows so texvc can work with it
 wfDebug( "TeX: $cmd\n" );

Finally replace 

if( !file_exists( "$wgTmpDirectory/{$this->hash}.png" ) ) {

by 

if( !file_exists( "$wgMathDirectory/{$this->hash}.png" ) ) {

and 

if( filesize( "$wgTmpDirectory/{$this->hash}.png" ) == 0 ) {

by 

if( filesize( "$wgMathDirectory/{$this->hash}.png" ) == 0 ) {

and 

if( !rename( "$wgTmpDirectory/{$this->hash}.png", "$hashpath/{$this->hash}.png" ) ) {
    return $this->_error( 'math_output_error' );
}

by 

if (!file_exists("$hashpath/{$this->hash}.png")) {
    if( !rename( "$wgMathDirectory/{$this->hash}.png", "$hashpath/{$this->hash}.png" ) ) {
        return $this->_error( 'math_output_error' );
    }
}

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 rename().

The suggested solution is obviously a workaround for problems located in the specific texvc executable (except for 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 texvc. 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 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 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
  1. install the complete 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 ImageMagick in D:\wikitex\imagick (ensure there are no spaces in the path you choose)
  3. install 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)
  5. 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)
  6. 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!
  7. open a command line (start -> execute -> cmd.exe)
  8. verify that the following commands are working:
latex
dvips
convert (not the Microsoft convert)
gs
Settings

(your wiki directory = $)

  • replace the file $/includes/Math.php with 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:
function renderMath($latex_formula) {

To this 

static function renderMath($latex_formula) {
  • uncomment or insert in $/LocalSettings.php:
$wgUseTeX= true;
  • insert in $/LocalSettings.php:
#ImageMagick
$wgImageMagickConvertCommand    = 'D:\wikitex\imagick\convert.exe';
$wgImageMagickIdentifyCommand   = 'D:\wikitex\imagick\identify.exe';
#Tex
$wgLaTexCommand                 = 'D:\wikitex\miktex\miktex\bin\latex.exe';
$wgDvipsCommand                 = 'D:\wikitex\miktex\miktex\bin\dvips.exe';
  • reboot if needed so that paths variables are updated for your services too
Verifications
  • 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:
<math>\sqrt{2}</math>
  • 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: 

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

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: 

$wgMathPath         = "{$wgUploadPath}/math";
$wgMathDirectory    = "{$wgUploadDirectory}/math";
$wgTmpDirectory     = "{$wgUploadDirectory}/tmp";

like this: 

 #$wgMathPath         = "{$wgUploadPath}/math";
 #$wgMathDirectory    = "{$wgUploadDirectory}/math";
 #$wgTmpDirectory     = "{$wgUploadDirectory}/tmp";

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:

Files to modify:

  • Math.php with class LatexRender, after modification renaming to MathLatexRender.php
  • Math.php from extension Math (add $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 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)[reply]

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) 

$wgUseTeX = true;
$wgLaTexCommand = "insert\path\here\latex.exe";
$wgDvipngCommand = "insert\path\here\dvipng.exe";

3) Try it. My test is usually <math>E=mc^2</math> :) 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)[reply]
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!!!

Another simple solution which extends the MathTexvc Class, and works with portable versions of LaTex

The extension of the MathTexvc class was made based on the code for Extension:MathLaTeX .

The changes made to the MathRenderer.php and extension.json (V1.27), as well as the additional file MathLatexRender.php can be found in the following commit in GitHub

The lines added to the LocalSettings.php file are: 

wfLoadExtension( 'Math' );
$wgUseTeX= true; 
$wgLatexOnWindows = true;
$wgPdfLaTexCommand = "D:\\texlive\bin\win32\pdflatex.exe"; 
$wgDvipngCommand = "D:\\texlive\bin\win32\dvipng.exe"; 
$wgMathDisableTexFilter = true;

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 MinGW)
  • an OCaml compiler
  • Latex and dvips (using the Miktex package for Windows)
  • GhostScript for its Postscript libraries ([2]) (Caution! in newer versions the gswin32c.exe has to be renamed or linked to gs.exe)
  • 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

  • the texvc 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

in upper manual is written how to build this

Edit localconfig 

$wgUseTeX           = true;
$wgTexvc = "c:/wamp/www/wiki/math/texvc.exe";

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

/*  if ( wfIsWindows() ) {
	# Invoke it within cygwin sh, because texvc expects sh features in its default shell
	$cmd = 'sh -c ' . wfEscapeShellArg( $cmd );
	}
*/

debug 

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 <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 Extension:Math/Syntax.

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

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 beginning 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: 

<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

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

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.

Retrieved from "https://www.mediawiki.org/w/index.php?title=Texvc/en&oldid=6745007"