Mediawiki and LaTeX on a host with shell access

From MediaWiki.org
Jump to: navigation, search

There are a number of methods for including mathematical formulae in mediawiki using LaTeX notation. Examples can be seen in LaTeX Rendering Method Examples.

The simplest and universal option: mathtex.cgi[edit | edit source]

Using mathTeX you can test out LaTeX in your web server almost immediately, using the generosity of forkosh.com to render the PNG images for you. See the advice in the section mathTeX web services.

This section will explain, more specifically, how to better integrate mathtex.cgi in your MediaWiki installation. After this step is successful, you can gradually move to using LaTeX on your account, as explained in the following sections.

You will need this file (and embedded instructions):

<?php
# Place this file in extension directory as Mtag.php
# Add the following line to LocalSettings.php:
# include './extensions/Mtag.php';
# Mediawiki will render as LaTeX the code within <m> </m> tags.

$wgExtensionFunctions[] = "wfMtag";

function wfMtag() {
        global $wgParser;
        $wgParser->setHook( "m", "returnMtagged" );
}

function returnMtagged( $code, $argv)
{

# if you have mathtex.cgi installed:
# $txt='<img src="/cgi-bin/mathtex.cgi?'.$code.'">';
# OR if you want to temporarily test a public mathtex.cgi:
 $txt='<img src="http://www.forkosh.com/mathtex.cgi?'.$code.'">';

 return $txt;
}

?>

On a shared host[edit | edit source]

As an alternative method that still doesn't require LaTeX to be installed, see "LaTeX on a shared host" (which should probably be merged to this page).

Installing LaTeX[edit | edit source]

The above setup has the advantage of being simple and quick, but your wiki will depend on another web service being available and responsive. An independent solution will also give you more control.

However, a prerequisite for going solo is to have LaTeX installed. If the shell command which latex does not give you an answer, chances are it is not available at your site, and so you will need to download and install it yourself by following the instructions in this section. On the other hand, if latex is already installed you can safely skip it.

The LaTeX distribution called "TeX Live" is relatively easy to install. Follow the instructions at http://www.tug.org/texlive/acquire.html and http://www.tug.org/texlive/quickinstall.html.

The following sections will try to break it down a little, but if there are any discrepancies follow the above TeX Live installation guides.

Downloading[edit | edit source]

With shell access from the server, from your command line, in a directory of your choice issue the following command

wget http://mirror.ctan.org/systems/texlive/tlnet/install-tl-unx.tar.gz

Unpacking[edit | edit source]

tar -xvzf install-tl-unx.tar.gz

This creates a directory install-tl, with an executable of the same name inside.

Installing[edit | edit source]

Follow the above-mentioned TeX Live installation guide from here. The installation takes about 1 hour. If you get disconnected or the process gets killed for any reason, it is safe to start again.

Compiling your own mathtex.cgi[edit | edit source]

To gain independence from external mathtex web services, or if you want to customise the mathtex setup, you will need to compile it.

Before you do, ensure that mathtex's dependencies (e.g. latex and dvipng executables) are in the PATH. To check that this is the case, enter e.g. which latex and which dvipng in the command line. If this does not output the directory where such executable is found, you will need to add said directory to the PATH environment variable, by adding a line similar to the following to .bashrc in your home directory

PATH=$PATH:$HOME/texlive/2008/bin/x86_64-linux

To compile, customize and install your own mathtex.cgi, at the command line:[1]

cc mathtex.c –DLATEX=\"$(which latex)\"  –DDVIPNG=\"$(which dvipng)\" –o mathtex.cgi 
  • mv mathtex.cgi to your cgi-bin/ directory.
  • chmod permissions as necessary, eg.
chmod 775  mathtex.cgi and chgrp apache  mathtex.cgi
  • Test it from the Unix shell by entering:
./mathtex.cgi "x^2+y^2" –m 9 –o test 

Remember to change the relevant section of the file Mtag.php at the top of this article to point to your local mathtex.cgi.

Custom styles[edit | edit source]

You may want to allow for certain LaTeX commands as defined in your personal style file. Suppose you have a style file mystyle.sty with the command definitions. Depending on where your LaTeX is installed, you should find many directories containing .sty files in:

/home/myaccount/local/teTeX/share/texmf-dist/tex/latex

Within that directory, mkdir mystyle and then move your mystyle.sty into mystyle.

In order for LaTeX to find the newly created mystyle, you need to simply run texhash from the command line.

Here is an example script to compile mathtex:

cc mathtex.c -DLATEX=\"$(which latex)\" -DDVIPNG=\"$(which dvipng)\" -DPNG -DUSEPACKAGE=\"mylittlefile\" -o mathtex.cgi

where within mylittlefile, there could be just one line:

"\\usepackage{mystyle}\n"

texvc[edit | edit source]

This has been in use at Wikipedia for years. LaTeX expressions are entered between <math></math> tags.

In addition to the requirements you needed for mathtex, you will also need to have latex and dvipng in the PATH of the web server process. You will likely also need to compile texvc, for which you will have to install ocaml if it's not already available at your site.

Installing OCaml[edit | edit source]

Objective Caml is obtained from http://caml.inria.fr/. A number of pre-compiled binaries are avaiable, or follow the instructions in the INSTALL file that comes with the tarball. The only thing to be aware of is that, like for the LaTeX install above, in a shared environment where you don't have superuser access you will probably need to change the various directories (during the configuration stage) to subdirectories under your $HOME directory.

After compiling and installing, make sure the binary ocaml is in your $PATH; see above for how to change .bashrc to this effect.

Making texvc[edit | edit source]

Follow the instructions in the README file inside the math subdirectory of your mediawiki installation.

After texvc is compiled, OCaml will not be used again by the wiki for the purpose of rendering TeX formulae.

It is recommended to test texvc from the command line first, and then test it via the wiki interface by using the Preview button. Remember to enter a new expression every time, to avoid the cache getting in the way of your testing. A list of known problems and fixes for texvc is maintained here.

wikitex[edit | edit source]

If you want to extend your LaTeX with AMS-LaTeX or other styles, an alternative to mathtex is wikitex, available from http://wikisophia.org/wiki/Wikitex . Suppose you want to extend wikitex with your own styles, similar to what was described above for mathtex. Here is an example of using <ma>...</ma> tags for that purpose:

  1. cp wikitex.math.inc.tex wikitex.ma.inc.tex
  2. add your command definitions within the preamble of wikitex.ma.inc.tex
  3. alternatively add your package to the list within \usepackage{...
  4. Within wikitex.inc.php, add this line to the definition of $arrRend:
'ma'   => 'strMa',
  1. Within wikitex.php, add this function
function strMa($str)
{
  global $objRend;
  return $objRend->strRend($str, array('class' => 'ma'));
}

It is possible that when the webserver invokes LaTeX, the webserver won't have permissions to make missing fonts, and you will see an error message. In the tmp directory within wikitex you may find long file names, for example cd02e2b844e50595b3d569247d533cc9 without the corresponding cd02e2b844e50595b3d569247d533cc91.png. Entering the shell command latex cd02e2b844e50595b3d569247d533cc9 may give some messages about the missing fonts, and then make the missing fonts. The wiki invocation may now be able to render the PNG.

In order to render a page full of PNGs wikitex will call wikitex.sh for each PNG. A shared host may be very slow in completing the many calls to wikitex.sh, perhaps deliberately by its configuration. PHP may then time out. Use of mathTeX hosted at forkosh.com, avoids this problem.

See also[edit | edit source]

References[edit | edit source]

  1. Instructions at www.forkosh.com