Difference between revisions of "Enabling math markup"

From Organic Design wiki
m
(SimpleMathJax)
 
(28 intermediate revisions by 3 users not shown)
Line 1: Line 1:
−
{{procedure
+
We've always used Latex for this, but the installation can be complicated and it requires over a GB (yes a Gigabyte!) of packages to be installed that we don't use for anything else. But now client side rendering is possible, or server-side via the new Mathoid node.js service both of which are vastly preferable. See [[MW:Extension:Math]] for more detail about installation options.
−
|description = Use this procedure to enable a particular wiki instance in the Wikia for using <math> tags.
+
 
−
|role = Sysop
+
The easiest way to get math rendering up and running now is just to install the [[MW:Extension:SimpleMathJax|SimpleMathJax extension]]. It has no dependencies as all rendering is completely client-side, and it has no need for any configuration options.
−
|status = in use
+
 
−
}}
+
== Older versions of MediaWiki ==
−
{{info|This procedure is only required to be run on platforms which were not installed with the [[install a new server]] procedure as maths markup should already be enabled after running that procedure. Also math markup is enabled in all [[OD/Wikia|Organic Design wikia]] by default too.}}
+
As of MediaWiki version 1.18 the math rendering has been put into the [[MW:Extension:Math|Math extension]]. See [[MW:Manual:Math]] for more details. To download the latest version of the extensions, use:
 +
<source lang="bash">
 +
git clone https://gerrit.wikimedia.org/r/p/mediawiki/extensions/Math.git
 +
</source>
 +
Note that as of MediaWiki 1.19, the extension repository has become out of sync with the codebase and a specific version needs to be used which you can download from [http://www.mediawiki.org/wiki/Special%3aExtensionDistributor?extdist_extension=Math&extdist_version=branches/REL1_19&extdist_submit=Continue].
 +
 
 +
== Build the texvc binary ==
 +
Enabling math markup requires latex, dvips, gs, and convert. OCaml 3.06 or later from [http://caml.inria.fr caml.inria.fr] is required to compile ''texvc''. On Debian-based systems the requirements can be installed with the following packages:
 +
<source>
 +
apt-get install dvipng cjk-latex ocaml
 +
</source>
 +
*Run ''make'' from within the MediaWiki's ''math'' directory to build the ''texvc'' binary on your system.
 +
*Make sure the directories ''tmp'' and ''math'' under 'images' exist and are writable.
 +
*{{h|'''Note:''' on Debian 7 we also required the '''texlive-latex-extra''' package.}}
  
−
Enabling math markup requires the following binaries [[W:LaTeX|latex]], [[W:dvips|dvips]], [[W:Ghostscript|gs]], and [[W:ImageMagick|ImageMagicks]] convert . These must all be available in $PATH.
+
== Example ==
−
The binary ''texvc'' must also be available, either as a binary or source installation.
+
The following maths code:
−
==Installation of texvc==
+
<source>
−
===From source===
+
<math>
−
#Note: 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 apt-get commands <code>apt-get install dvipng tetex-extra cjk-latex ocaml</code> (documented in [[Debian Post Install]]) install OCaml.
+
e^x = \sum_{n = 0}^{\infty} {x^n \over n!} = 1 + x + {x^2 \over 2!} + {x^3 \over 3!} + {x^4 \over 4!} + \cdots
−
#Inside each mediawiki instance ./math directory there is a README file which documents the process involved to make an executable from source called ''texvc''. Basically from in the math directory you type <code>make</code> and check that texvc has been compiled.
+
</math>
 +
</source>
  
−
===Binary===
 
−
The <code> apt-get install mediawiki-math</code> creates the texvc executable in /usr/local/bin.
 
  
 +
Should give the following output:
 +
{{code|
 +
<math>e^x = \sum_{n = 0}^{\infty} {x^n \over n!} = 1 + x + {x^2 \over 2!} + {x^3 \over 3!} + {x^4 \over 4!} + \cdots</math>
 +
}}
  
−
You should then test that it works from the command line for example;
+
== Nginx ==
 +
After we changed over from [[Apache]] to [[Nginx]] I spent many hours trying to figure out why the ''texvc'' binary wouldn't produce the PNG file. The binary was being executed properly by ''shell_exec'' in ''MathTexvc.php'', but for some reason would not build the image.
  
−
  texvc /tmp /var/www/mediawiki-1.12.0/math "y=x+2" iso-8859-1
+
I couldn't find anything logged about a problem anywhere, and there were no differences in PHP configuration that I could find. I tried adjusting ''render.ml'' to leave the temporary files so I could analyse those (by removing the lines deleting then from the ''unlink_all'' function then running ''name clean'' and ''make'' to rebuild the ''texvc'' binary, but it wouldn't produce any of the files except the ''.tex'' one.
  
−
should create a file in /var/www/mediawiki-1.12.0/math.
+
The only working solution I could come up with was to run the ''texvc'' as root using ''sudo'' by changing line '''123''' of '''MathTexvc.php''' as follows:
 +
{{code|1=<tt>$contents = wfShellExec( "{{h|sudo}} $cmd" );</tt>}}
  
  
−
Make sure the directories 'tmp' and 'math' under 'images' exist and are writable.
+
To allow the web-server to have ''sudo'' access without compromising security the following line can be added to the sudoers file using ''visudo''.
 +
<source>
 +
www-data ALL=NOPASSWD: /path/to/wiki/extensions/Math/math/texvc
 +
</source>
  
−
==LocalSettings.php customization==
+
'''Update:''' On my most recent server installation, math wasn't rendering, and the server was delivering messages about a security problem whenever math formulas tried to render. I didn't need to modify any files, as ''texvc'' was already being called as root, so I just added the binary path to the ''sudoers'' file and it worked.
−
The following lines need to be added;
 
−
{{code|<PHP>
 
−
$wgUseTex = true;              # and
 
−
$wgTexvc  = 'usr/bin/texvc';  # alternative location from 'sudo apt-get install mediawiki-math' installation
 
−
$wgMathDirectory = "$IP/images/math"; # optional
 
−
</PHP>
 
−
}}
 
  
−
==See also==
+
== See also ==
−
*[http://www.mwusers.com/forums/showthread.php?t=8168&highlight=math Thread on mwusers]
+
*[[MW:Manual:Math]]
 +
*[[MW:Extension:Math]]
 +
*[[MW:Manual:Enable TeX]]
 +
*[[MW:Manual:Running MediaWiki on Debian GNU/Linux#TeX_Support]]
 +
*[[MW:Manual:Troubleshooting math display errors]]
 +
*There was a problem extracting the database on 13/11 due to duplicate entries in the math table, see [[13 November 2006]].
 +
[[Category:Maths]]

Latest revision as of 12:47, 17 January 2016

We've always used Latex for this, but the installation can be complicated and it requires over a GB (yes a Gigabyte!) of packages to be installed that we don't use for anything else. But now client side rendering is possible, or server-side via the new Mathoid node.js service both of which are vastly preferable. See MW:Extension:Math for more detail about installation options.

The easiest way to get math rendering up and running now is just to install the SimpleMathJax extension. It has no dependencies as all rendering is completely client-side, and it has no need for any configuration options.

Older versions of MediaWiki

As of MediaWiki version 1.18 the math rendering has been put into the Math extension. See MW:Manual:Math for more details. To download the latest version of the extensions, use: 

git clone https://gerrit.wikimedia.org/r/p/mediawiki/extensions/Math.git

Note that as of MediaWiki 1.19, the extension repository has become out of sync with the codebase and a specific version needs to be used which you can download from [1].

Build the texvc binary

Enabling math markup requires latex, dvips, gs, and convert. OCaml 3.06 or later from caml.inria.fr is required to compile texvc. On Debian-based systems the requirements can be installed with the following packages: 

apt-get install dvipng cjk-latex ocaml
  • Run make from within the MediaWiki's math directory to build the texvc binary on your system.
  • Make sure the directories tmp and math under 'images' exist and are writable.
  • Note: on Debian 7 we also required the texlive-latex-extra package.

Example

The following maths code: 

<math>
e^x = \sum_{n = 0}^{\infty} {x^n \over n!} = 1 + x + {x^2 \over 2!} + {x^3 \over 3!} + {x^4 \over 4!} + \cdots
</math>


Should give the following output:

[math]e^x = \sum_{n = 0}^{\infty} {x^n \over n!} = 1 + x + {x^2 \over 2!} + {x^3 \over 3!} + {x^4 \over 4!} + \cdots[/math]

Nginx

After we changed over from Apache to Nginx I spent many hours trying to figure out why the texvc binary wouldn't produce the PNG file. The binary was being executed properly by shell_exec in MathTexvc.php, but for some reason would not build the image.

I couldn't find anything logged about a problem anywhere, and there were no differences in PHP configuration that I could find. I tried adjusting render.ml to leave the temporary files so I could analyse those (by removing the lines deleting then from the unlink_all function then running name clean and make to rebuild the texvc binary, but it wouldn't produce any of the files except the .tex one.

The only working solution I could come up with was to run the texvc as root using sudo by changing line 123 of MathTexvc.php as follows:

$contents = wfShellExec( "sudo $cmd" );


To allow the web-server to have sudo access without compromising security the following line can be added to the sudoers file using visudo. 

www-data ALL=NOPASSWD: /path/to/wiki/extensions/Math/math/texvc

Update: On my most recent server installation, math wasn't rendering, and the server was delivering messages about a security problem whenever math formulas tried to render. I didn't need to modify any files, as texvc was already being called as root, so I just added the binary path to the sudoers file and it worked.

See also

Retrieved from "https://organicdesign.nz/wiki/index.php?title=Enabling_math_markup&oldid=120809"