Manual:Troubleshooting math display errors

In case your users encounter problems with LaTeX equations on your wiki, the following troubleshooting steps might help.

Preliminaries

 * 1) Have you compiled texvc? see the math/ directory
 * 2) Do you have LaTeX, dvips, gs and convert (ImageMagick)?
 * 3) Is your LaTeX installation correct?
 * 4) Are the math formulas correct latex?  Try a simple formula like $$0$$
 * 5) Are the file permissions correct?  Can your image directories, include images/math and images/tmp be written to by your webserver's user?

If none of these help, you might have to start rolling up your sleeves. From here on, we assume that you have some access to the web server, specifically that you are at the directory where you installed MediaWiki, for example:

cd /whatever/htdocs/w

Raw $$$$ Tags
Check LocalSettings.php for: $wgUseTeX = true;

Linux
Check your LocalSettings.php for the following global variables: $wgMathPath        = "{$wgUploadPath}/math"; $wgMathDirectory   = "{$wgUploadDirectory}/math"; $wgTmpDirectory    = "{$wgUploadDirectory}/tmp"; and make sure those directories are all writable by your webserver.

The tmp directory is located inside the image directory. chmod 777 tmp to make writeable.

Linux
Make sure each of the required programs are executable by the webserver and in the webserver's PATH ls -lH `which gs` `which latex` `which dvips` `which convert`

Identify the error
Grep the error string in your mediawiki installation directory. For example, since I am working on a French wiki, I do something like: grep -r "La conversion en PNG" languages

This should tell you something useful, that is, an error code. Here, for example, we see that what we are dealing with is a math_image_error: languages/LanguageFr.php:"math_image_error"    => "La conversion en PNG a échouée, vérifiez l'installation de Latex, dvips, gs et convert",

Localise the error
Next you want to hunt the error down. Look in includes/Math.php and locate the bit of source code where your error code occurs. Following the example above, we see if( !file_exists( "$wgMathDirectory/{$this->hash}.png" ) ) { return $this->_error( 'math_image_error' ); }

Ah-hah. It only returns math_image_error if it can't find the png file in the math directory.

''Missing link between these sections ("Localise the error" and "Debug the heck out of things")

Debug the heck out of things
Put the following line in LocalSettings.php. Don't forget to make the file writable (a+w helps) $wgDebugLogFile = "/tmp/wiki.log";

You'll want to look for lines that begin with TeX:. What it will tell you is the command that it used to run texvc.

Try running that command yourself! If you run into problems, then you're on the right track. Does fixing these problems solve the errors? If not...

Hack texvc
One useful way to see where things go wrong is to edit the texvc source code. For example, you could replace the following line in texvc.ml like so

Before: | Render.ExternalCommandFailure s -> After: | Render.ExternalCommandFailure s -> print_string ("-Render Error-" ^ s ^ "-/Render Error-")

Go to the /math folder and run the make command again to recompile the things that were changed. Then, when you look in /tmp/wiki.log you might get more information as to which part of the process went wrong.

You could also edit the file render.ml. The following line, for example, could be modified to send errors to some temporary file instead of /dev/null: let cmd_convert tmpprefix finalpath = "convert -quality 100 -density 120 " ^ tmpprefix ^ ".ps " ^ finalpath ^ " >/dev/null 2>/dev/null"

The 2 is for stderr output. Change the line to

let cmd_convert tmpprefix finalpath = "convert -quality 100 -density 120 " ^ tmpprefix ^ ".ps " ^ finalpath ^ " >/dev/null 2>/tmp/wiki_convert_error"

and run make. Edit an equation again, and look at the file /tmp/wiki_convert_error. For example, mine says

sh: line 1: convert: command not found

even though I can run convert from the command line and it works. So I ran which convert and it told me it was in /usr/local/bin/, and I changed the line to read

let cmd_convert tmpprefix finalpath = "/usr/local/bin/convert -quality 100 -density 120 " ^ tmpprefix ^ ".ps " ^ finalpath ^ " >/dev/null 2>/tmp/wiki_convert_error"

Now at least I've changed the error in /tmp/wiki_convert_error:

sh: line 1: gs: command not found sh: line 1: gs: command not found convert: no decode delegate for this image format '/home/httpd/vhosts/exampleproblems.com/httpdocs/wiki/images/tmp/25921_8a419822395bff99de2663af8c7d7dda.ps'.

I looked for but couldn't find a place where gs was run. I don't know if it helped, but I installed AFPL Ghostscript 8.51. (I had been using GPL 8.15).

http://www.cs.wisc.edu/~ghost/doc/AFPL/get851.htm

The error message stayed the same. Then, as root, I copied /usr/local/bin/gs to /usr/bin/gs and it works now!

Which latex, dvips, convert ...
Instead of filling up your /usr/bin/ directory and complicating OS updates, a more universal fix is to change render.ml to use the env shell command in each of the let cmd_ ... = statements. let cmd_dvips tmpprefix = "env dvips ... let cmd_latex tmpprefix = "env latex ... let cmd_convert tmpprefix finalpath = "env convert ...

Then run make in the math directory again. You may need to restart Apache.

Errors with convert
For those of you who are having problems with convert, something like "Unable to temporary file", it seems to be convert, for some odd reason, trying to create its temporary files in the directory in which it was run. You can fix this by prefixing the convert command with instructions to work in the /tmp directory.

let cmd_convert tmpprefix finalpath = "cd /tmp; convert -quality 100 -density 120 " ^ tmpprefix ^ ".ps " ^ finalpath ^ " >/dev/null 2>/dev/null" -- I have been pulling my hair out trying to get the math working on a windows 2000 installation. I have followed the above suggestions. It works when run with texvc command from the command line -- a .png file is created. However, when run from the Math.php script, it created the .tex, .dvi, .ps, but fails to perform the convert. I've hacked the texvc executable to hardcode all the paths because that gave me some trouble in a previous installation that I was able to get working.

I guess my question is: what does 'convert' need to work? Why does it work from the command line but not when run from within the script?

The answer is probably that 'convert' delegates some of its work to other software like 'ghostscript' (gs). If the Apache path does not include the gs directory convert won't work correctly when called from a PHP script. The solution that works fine under MacOSX is to modify the 'delegates.xml' file in the 'config' directory of ImageMagick (wherever it is under Windows) and to replace all "gs" occurences by " /gs".