Difference between revisions of "Enabling math markup"

From Organic Design wiki
(→‎Transparency (not working on current versions): different for new versions)
(SimpleMathJax)
 
(23 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|Use this procedure to add math rendering support which is not included in the [[install a new server]] procedure by default as it requires many additional program libraries (about 200MB worth)}}
+
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.}}
  
 
== Example ==
 
== Example ==
−
The following maths code
+
The following maths code:
−
{{code|<pre><math>
+
<source>
 +
<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
 
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></pre>}}
+
</math>
 +
</source>
  
−
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>}}
 
  
−
== Build the texvc binary ==
+
Should give the following output:
−
OCaml 3.06 or later from [http://caml.inria.fr caml.inria.fr] is required to compile ''texvc''
+
{{code|
−
{{code|<pre>
+
<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>
−
apt-get install dvipng tetex-extra cjk-latex ocaml
+
}}
−
</pre>}}
+
 
 +
== 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.
  
−
Run ''make'' from within the MediaWiki's ''math'' directory to build the ''texvc'' binary on your system.
+
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.
  
−
Make sure the directories ''tmp'' and ''math'' under 'images' exist and are writable.
+
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>}}
  
−
== LocalSettings.php customization ==
 
−
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>
 
−
}}
 
  
−
== Transparency (not working on current versions) ==
+
To allow the web-server to have ''sudo'' access without compromising security the following line can be added to the sudoers file using ''visudo''.
−
The ''/wiki/math/render.ml'' script has notes about swtches that can be added to the ''convert'' and ''dvips'' commands to give transparency, but these images will not work correctly in Microsoft browsers prior to IE7. After making changes to ''render.ml'', you must rebuild the ''texvc'' executable by issuing a '''make clean && make'''.
+
<source>
 +
www-data ALL=NOPASSWD: /path/to/wiki/extensions/Math/math/texvc
 +
</source>
  
−
For older codebases, we used the following ''render.ml'' hack instead.
+
'''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.
−
{{code|<pre>
 
−
let cmd_convert tmpprefix finalpath = "convert -quality 100 -density 480 " \
 
−
    ^ tmpprefix ^ ".ps -negate -unsharp 8 -resize 25% " ^ finalpath ^ " >/dev/null 2>/dev/null \
 
−
    && convert " ^ finalpath ^ " -fill black -colorize 100% " ^ finalpath ^ ".png \
 
−
    && composite -compose CopyOpacity " ^ finalpath ^ " " ^ finalpath ^ ".png " ^ finalpath
 
−
</pre>}}
 
  
 
== See also ==
 
== See also ==
−
*[http://www.mwusers.com/forums/showthread.php?t=8168&highlight=math Thread on mwusers]
+
*[[MW:Manual:Math]]
−
*[[:Category:Articles containing maths|Articles containing maths]]
+
*[[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]].
 
*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"