Installing the MathDox Player

In this section the download, compilation and deployment process of the MathDox Player is described. First the prerequisites are discussed followed by download instructions, configuration, compilation, deployment and information about OpenMath Phrasebooks.

Prerequisites

In order to run the MathDox Player a few software packages need to be installed first. In this section all packages are mentioned and if necessary extra remarks concerning installation are made. One should have the third-party software installed prior to installing the MathDox Player, if it is not stated as optional.

  • Java version 1.5 (5.0). Follow instructions at http://java.sun.com, make sure also to configure the Java plug-in in your browser.

  • Apache Tomcat version 5.5. (JBoss or any other Java Servlet container will work as well.) Follow instructions at http://tomcat.apache.org.

  • Apache Ant. Download and install version 1.6.5 or higher from http://ant.apache.org. (Ant Apache Regexp and Ant Trax are also required)

  • eXist 1.0.1. This package is optional. By default the filesystem is used as source location for MathDox documents. It is however possible to store the documents in a XML database like eXist and use the benefits a database has to offer. Download eXist from http://exist.sourceforge.net. Follow the instructions to obtain a exist.war file and copy this file to the webapps directory of your Tomcat installation, or the deployment directory of another Java Servlet container of choice. It is also possible to run exist outside a Java container. Refer to the eXist documentation for more information on the package or on its configuration.

  • A Computer Algebra System, with an OpenMath Phrasebook and its accompanying service program. These are not needed but highly recommended when one wants to perform (more complex) computations. Follow the instructions given in section Phrasebooks.

Download of sources

The sources of the MathDox Player are available for download. The latest stable release can be found at http://mathdox.org/player. A zip-file with the MathDox Player can be downloaded at http://mathdox.org/download/player/. Unzip the downloaded file in a location of your choice. After downloading the zip file, the file should be unzipped.

Alternatively, the latest development version of the MathDox Player can be checked out from subversion. One first needs to install the version control utility Subversion. Using the command line tool svn in Linux or Windows, checking out the needed package is done as follows. svn checkout https://mathdox.org/svn/repos/public/mathdoxplayer No username or password is required. Configuration of the MathDox Player is only needed if the default configuration parameters are not suitable. Follow the instructions in the next section to see how to do this.

Configuration

The MathDox Player has some settings that can be changed. These settings can be found in the properties.xml file located in the configuration folder. Each setting (or property) has the following form: 

<property 
  name='org.mathdox.storage.url' 
  value='oxf:/player/manual'
  as='xs:string'/>

The following properties can be configured:

  • org.mathdox.storage.url Location of MathDox documents, this points by default to the manual that is included with the MathDox Player, but this value can be changed to point to any path, e.g. value='file:/home/username/mathdox'

  • org.mathdox.phrasebook.default Default OpenMath Phrasebook used to send OpenMath queries too.

  • org.mathdox.phrasebook.mathematica.host Location of Mathematica only needed when Mathematica is used.

  • org.mathdox.phrasebook.mathematica.port The port where Mathematica can be reached.

  • org.mathdox.phrasebook.maxima.host Location of Maxima, only needed when Maxima is used.

  • org.mathdox.phrasebook.maxima.port The port where Maxima can be reached.

  • org.mathdox.phrasebook.gap.host Location of GAP, only needed when GAP is used.

  • org.mathdox.phrasebook.gap.port The port where GAP can be reached.

  • org.mathdox.phrasebook.wiris.endpoint The location where the WIRIS OpenMath Phrasebook can be reached.

Compilation and deployment

At this point it is assumed that you have either a development version downloaded from Subversion or the zip file and this file has been unzipped. It is also assumed that any changes to the settings have been done. The next step is to compile the MathDox Player and deploy it in a Java Servlet container. This can be done with the help of the build tool Ant, by means of the following steps:

  • Type ant war, at the top level of the MathDox Player directory. Keep in mind that building a war file may take several minutes to finish (with BUILD SUCCESSFUL). Afterwards the mathdoxplayer.war file can be found in the build/war directory.

  • Copy the mathdoxplayer.war file into the deploy directory of your Java Servlet container, like JBoss or Tomcat.

    Typically, this will be the webapps directory of your Tomcat.

  • (Re)start your Java servlet container.

    The MathDox Player should then be available at http://localhost:8080/mathdoxplayer.

Known issues

The following problems are known to exist in this version of the MathDox Player.

  • Files with names that contain spaces or other 'unconventional' characters are not displayed. This appears to be a bug in the xforms handling code of Orbeon Presentation Server 3.5M1.

  • OpenMath and MathML expressions that are embedded in an <xforms:label> tag (for instance to produce a radio button choice between a number of mathematical expressions) are not displayed correctly. This appears to be a problem in the xforms standard (markup is not allowed in an <xforms:label> tag).

  • It may take ant a long time to compile the mathdoxplayer.war file. This is mainly due to the fact that approximately 20.000 font files from jsMath need to be included in the war file.