Overview
--------

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 MathJax via Node.js to render equations.
If you need the older services (using LaTeX and JEuclid), try the old branch
STABLE_3.


Service
-------

The service is called WebMathsMathJax.

It uses MathJax in Node.js to render both TeX and MathML. Can convert multiple
equations at once and can provide SVG as well as PNG format files.

This requires Node.js (probably about v20+) on the server.


Licensing
---------

All contents of this repository including code and data are copyright
2012-2026 The Open University and are released under the GNU Public License
version 3 (see LICENSE), except:

* 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.


Basic build/setup instructions for testing
------------------------------------------

1) Run 'mvn install'. The .war file webmaths.war will be generated inside the
   'target' folder.

2) Eclipse IDE will automatically compile the project assuming it is recognised
   as a Maven project.

3) To deploy to Tomcat 9, please install or upload the war file manually.

4) 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.

NOTE: This app currently requires Tomcat 9.x.

Manually providing the Node.js app
----------------------------------

Using the basic setup, the app will install its own Node.js application in the
Tomcat user's home directory when it starts up, and update the app if necessary.
This may not be appropriate, especially on production servers, where the Tomcat
user might not have the necessary permissions to run 'npm install' and download
software etc.

You can build the Node.js app manually:

* Copy the files from src/main/resources/ou-mathjax into any suitable directory.
* In that directory, run 'npm install'
* Build the .war file using the command:

  mvn install -Dou-mathjax-location=/opt/ou-mathjax

  (Where /opt/ou-mathjax is replaced by whatever directory you built the app in.)

The included .spec file can be used if you want to build a .rpm to install
ou-mathjax, which is how we deploy it (you will need to make minor modifications
to the file which our build pipeline does).

How to write clients
--------------------

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.