This project is a collection of Web services that can be run in a Java application server to provide mathematical equation processing features.
We have a filter (not yet publicly released) for the Moodle virtual learning environment platform which uses these services so that users can view equations as images in a user-selected size and colour, or directly to the browser as MathML if they have a supported browser, regardless of whether the equations were initially entered as TeX or MathML.
The latest version of this system uses the mathjax-node-sre project (server-side MathJax) to render equations. At present it also includes older methods, but we may phase these out.
The service names all begin with WebMaths. They are:
Tex: Converts a subset of AMS LaTeX to MathML 2. Converts the same subset back from MathML 2 to AMS LaTeX. (The subset is documented in misc/supported.tex.commands.xml.)
English: Converts MathML 2 into English text suitable for using as 'alt' text. Warning: The results of this service are presently not very good.
Image: Renders MathML 2 using the JEuclid library. Size and colour can be selected.
ImageTex: For MathML that was originally converted from TeX using the above converter, renders it using latex and dvipng software. For other MathML, uses JEuclid as above.
MathJax: Uses mathjax-node-sre backend to render both TeX and MathML. Can convert multiple equations at once and can provide SVG as well as PNG format files.
The MjEnglish, MjTex, and MjImage servlets are implementations of the
above contracts using this MathJax backend.Image and ImageTex are plug-in compatible (they use the same WSDL, so you can use a different one by changing the URL in your service client). ImageTeX can produce prettier images, but requires 'latex' and 'dvipng' to be installed on the server. Image is pure Java; it requires no extra installation, and also performs better, but the images can be a bit ugly.
MathJax and the Mj* servlets requires mathjax-node-sre to be installed in the server; the default location is /opt/mathjax_node_sre, or you can configure it (see web.xml).
All contents of this repository including code and data are copyright 2012-2015 The Open University and are released under the GNU Public License version 3 (see LICENSE), except:
JEuclid and dependencies in lib/jeuclid folder: http://jeuclid.sourceforge.net/ Released under Apache Software License version 2.
Apache FOP, Batik, and dependencies in lib/fop folder: http://xmlgraphics.apache.org/fop/ http://xmlgraphics.apache.org/batik/ Released under Apache Software License version 2.
Apache Commons libraries in lib/commons folder: http://commons.apache.org/ Released under Apache Software License version 2.
TeX to MathML conversion code (two Java files in uk.ac.open.lts.webmaths.tex) Modified and ported-to-Java version of code by Steve Cheng: http://www.gold-saucer.org/mathml/greasemonkey/dist/display-latex Released under custom license (see relevant source files).
UTF-8 converter (misc/utf8.inc) Henri Sivonen, Netscape Communications Corporation http://iki.fi/hsivonen/php-utf8/
MathML entity data files (text files) Based on entity files provided by W3C as part of MathML 2, with note: (C) International Organization for Standardization 1991 Permission to copy in any form is granted for use with conforming SGML systems and applications as defined in ISO 8879, provided this notice is included in all copies.
Quivira font in lib/extrafonts http://www.quivira-font.com/ 'Quivira is free to use for any purpose, including commercial usage. You may also redistribute Quivira freely, but please do not alter it and do not claim it to be your own work'. (C) Alexander Lange
Allura font in lib/extrafonts http://code.google.com/p/googlefontdirectory/source/browse/allura/ This Font Software is licensed under the SIL Open Font License, Version 1.1. Copyright (c) 2011 TypeSETit, LLC (typesetit@att.net)
1) Run the ant build script with the 'wsdlgen' target. This will create the 'gen' folder based on the WSDL files. -> In Eclipse, right-click build.xml and choose 'Run as > Ant build...', then select the wsdlgen target and deselect others.
2) If you want your IDE to compile the project: a) Refresh the project if necessary to see the 'gen' folder. -> In Eclipse, right-click the project root and choose Refresh. b) Add the 'gen' and 'test' folders to your IDE's source path. (The 'src' folder has probably been included by default, but if not, add that too.) You can also add 'analysis' if you like. -> In Eclipse, right-click the folder and choose Build path / Use as source folder. c) Add all the library .jar files in 'lib' to the IDE's build path. -> In Eclipse, right-click and choose Build path / Add to build path.
3) You can now run some of the services locally on the built-in Java 6+ test server by running uk.ac.open.lts.webmaths.DevServer -> In Eclipse, right-click this file and choose Run as / Java application.
4) You can also run unit tests by running JUnit on the 'test' folder. -> In Eclipse, right-click this folder and choose Run as / JUnit test.
5) To build the web application to a running Tomcat, run the ant script with the 'tomcatdeploy' target. You will need to set the variables tomcat-url, tomcat-username and tomcat-password. The specified username needs to have the manager-script role (note that the default admin user in Tomcat doesn't).
6) To build the web application as a .war file, run ant script with the 'war' target. You can set the Ant property war.location to the folder where you want to put the .war file.
7) Once you have installed the application, you can test it is running by going to its root URL. This will take you to a status page.
To get the JAX-WS information page for any service once you have installed it on your server, go to http://your.server.example.com/webmaths/ and follow the 'Web services' link - you'll get a list of all eight services together with the WSDL files that should be all you need in order to write software that uses the services. The WSDL files contain documentation for all parameters and return values.
The WSDL files are WS-I compliant so should be usable from all programming languages.
If you are writing new software and can install node.js and MathJax.node on the server, I would recommend using only the 'mathjax' service. The other services may be phased out eventually.