JEuler

Introduction

Jeuler (pronounced J-Oy-luhr) is a tool for publishing mathematics on the web. With Jeuler installed on your web server, you can use use elements in your web pages that contain LaTeX expressions. They will automatically display when people visit your site.

How does it look?

Jeuler can typeset equations in display format, each on one line:

Or with inline format that flows with the text:

Here's an inline equation with default font size.

You can see more samples here.

Note that you can see the Latex markup by hovering over the equation with the mouse cursor.

Features of JEuler

What is Latex?

Latex is a popular system for pre-press document preparation. It's especially good for highly formatted technical books and academic journal articles. For people concerned about typographical quality, Latex and it's parent software Tex, "rule."

You can download a book-length introduction on Latex for mathematics here.

A nice one-page LaTeX cheetsheet can be downloaded here.

How does the servlet work?

The servlet parses the input file, recognizing jeuler elements and comparing them to elements stored in a cache on the server. If an element doesn't match its cache entry, a new image is generated. Finally, the input is processed using an xslt stylesheet. The jeuler elements are removed and replaced with img elements that point into the cache.

What happens if the servlet isn't on line?

A visitor can download your site and view any of the documents locally without running the jeuler servlet. The document will display correctly as long as it has been previously processed by the servlet.

How do I write JEuler markup?

You write your webpage in xhtml. Wherever equations go, you use jeuler elements. The file extension of your source files should be .xml, but links to these files should use the extension .jxl for reasons explained below.

Display equations are written inside <eqn> elements:

	<eqn>\int_{0}^{\pi} \sin x\, dx = 2</eqn>

Inline equations are written inside <eqi> elements:

	<p>The equation <eqi>a x^2 + b x + c = 0</eqi> is quadratic</p>

A great deal, but not all, of LaTeX is supported. The JEuler servlet uses the JLaTeXMath typesetting package which you can read about here.

Options

Options are specified using attributes. Currently, font size and color are the only two display options.

	<eqn size="22" color="4444FF">a x^2 + b x + c = 0</eqn>

Color is specified using 3 hexadecimal digit pairs: RRGGBB
Font size is specified in points.

You can define default values for the whole document in a <config> element:

	<config size="22" color="888800"/>

Multiple config elements may appear in the source document, changing the default sizes and/or colors for subsequent equations.

Where are the equations?

The config element is also used to specify a work directory and file prefix used for files created by the servlet. This is done using the prefix attribute. Each of your jeuler documents should contain a config element that specifies a unique prefix. The convention is to use the name of the document. For example, if your document is index.xml, the config element might be:

	<config prefix="equations/index"/>

This specifies that all works files will be created in a subdirectory (relative to your document) called equations. Inside that directory, files will be created with a name that begins with index. For example, after this page is processed by jeuler, the equations directory contains these files:

	index.cache
	index.css
	index_001.png
	index_002.png
	index_003.png
	index_004.png 

The .png files are the images created for each equation. The cache file contains the latex expressions and options used to generate each image file. The servlet uses the cache file to determine if a new image file needs to be created after you've edited one or more of the equations in the source document.

You can have several jeuler documents that share the same top level directory as long as each one specifies a different file name in the config element.

The servlet container must have write+execute access to the work directory. One way to do this is to make the servlet container run under a user account that's in the same group as the web server. Then set the permissions on the work directory so member of the group have write+ execute permissions. On Fedora Linux systems, (for example) after installing the Tomcat servlet container, a tomcat user is created and made a member of the httpd group shared with Apache. So if the working directory equations is specifed, you would set the permissions like this:

	chmod g+rwx equations 

Namespaces

JEuler markup uses a namespace http://www.csparks.com/jeuler which you must specify in your source file. There are several ways to do this. The easiest way is to make this namespace the default for your whole document. To do that, declare it in the root element of your document. The first part of a jeuler/xhtml document using this markup looks like this:

	<?xml version="1.0" encoding="UTF-8"?>
	<?xml-stylesheet type="text/xsl" href="jeuler2.xsl"?>
	<!DOCTYPE html>

	<html xmlns="http://www.csparks.com/jeuler">
	<head>
		<meta http-equiv="Content-Type" content="application/xhtml+xml; charset=utf-8" />	
		<title>JEuler</title>	
		<link rel="stylesheet" type="text/css" href="style.css"/>

		<config prefix="equations/sampler"/>
	</head>
	<body>
	<p>
		Here's a display equation:
		<eqn>e^{i \pi}=-1</eqn>
	</body>
	</html> 

This method is convenient when all of your source is in xhtml except for the jeuler elements. The stylesheet specified in the processing instruction, jeuler2.xsl transforms all non-jeuler elements back to the xhtml namespace. If you study the sample document included in the package: sampler.xml, you will see a complete example of this markup.

A more general approach is to define a prefix for the jeuler namespace and specify the xhtml namespace as the default for the document:

	<?xml version="1.0" encoding="UTF-8"?>
	<?xml-stylesheet type="text/xsl" href="jeuler.xsl"?>
	<!DOCTYPE html>
	
	<html
		xmlns="http://www.w3.org/1999/xhtml"
		xmlns:je="http://www.csparks.com/jeuler"
	>
	
	<head>
		<meta http-equiv="Content-Type" content="application/xhtml+xml; charset=utf-8" />	
		<title>JEuler</title>	
		<link rel="stylesheet" type="text/css" href="style.css"/>

		<je:config prefix="equations/index"/>
	</head> 

	<body>
	<p>
		Here's a display equation:
		<je:eqn>e^{i \pi}=-1</je:eqn>
	</p>
	</body>
	</html> 

This method is best if you plan to mix in markup from other namespaces. The stylesheet jeuler.xsl must be specified in the processing instruction and je: prefixes must be used on all jeuler markup. This is the style used in this source document, index.xml, provided in the distribution.

How do I install JEuler?

JEuler is packaged as a war file. On most servers that support java servlets, all you have to do is copy this file to a special location.

How can I use JEuler documents mixed in with my regular website content?

If you're using the Apache webserver, an efficient way to do this is via mod_proxy. In your Apache configuration file, include these lines:

	<Location /jeuler>
	        ProxyPass         ajp://localhost:8009/jeuler/
	        ProxyPassReverse  ajp://localhost:8009/jeuler/
	</Location> 

This says that any document requested on your site who's path begins with /juler will be sent to the servlet container for processing. In this case, I'm using Tomcat, which listens on port 8009 for ajp protocol connections.

In addition to the proxy, you need a rewrite rule:

	RewriteCond %{REQUEST_URI} !(^/jeuler/.*)
	RewriteRule (.*)\.jxl$ jeuler/content/$1.jxl [P] 

This rule will recognize any document path that ends with the file extension .jxl and insert the /jeuler trigger for the ajp proxy. The Jeuler servlet recognizes this file extension and converts it to .xml when reading the document. Using this rule eliminates the need to write the /jeuler path element in urls. Instead, you create links to jeuler documents using their natural path, but specifying the .jxl file extension instead of the actual .xml file extension.

Note the additional path component /content appended to the trigger by the rewrite rule. After deploying the servlet, you must create a symbolic link named content that points back to your website root directory. The Tomcat servlet container requres a special option to allow this linking, which can be placed in the file META-INF/context.xml:

	<?xml version='1.0' encoding='utf-8'?>
	<Context allowLinking="true">
	        <WatchedResource>WEB-INF/web.xml</WatchedResource>
	        <WatchedResource>WEB-INF/log4j.xml</WatchedResource>
	</Context> 

This context file also tells tomcat to reload the servlet if the web.xml or log4j.xml file are touched.

IMPORTANT: If you use automated tools to undeploy the jeuler servlet (such as the Tomcat Manager webapp) be sure to remove the content symbolic link first or the manager will try to recursively delete your entire website. I learned this the hard way.

History

I resorted to writing Jeuler after trying nearly every open-source math tool for the web. At that time, most of them produced ugly output and all required complex preprocessing tools.

After concluding that Latex made the best looking results, I wanted to have, as far as possible, the ability to write Latex elements in my web pages and have them rendered as if the capability were native to the browser.

The first versions of Jeuler were implemented using the Apache Cocoon servlet configured to work with a complete TexLive installation. Although I used this for many years to publish articles on this site, the method depended on installing and configuring many complex software components. And the setup required different packages and settings depending on the operating system, TeX software version, and servlet container. I never published the software because I felt unprepared to support it properly.

This version of JEuler is a self-contained java servlet. It can can be deployed by installing a single file. I've tested it on Linux and Windows using Tomcat and Jetty (popular servlet containers.) You can also run JEuler proxied though an Apache server, which allows you to mix Jeuler pages with regular web content. (Don't worry about this stuff if it's unfamiliar. The main idea is that Jeuler is likely to work without trouble on your server.

Where can I download the JEuler servlet?

Right here.

Note: Internet Explorer, among its other gruesome habits, likes to rename the jeuler.war file to "jeuler.zip" when you start the download. After you've got the file, just rename it by hand before deploying.

Complaints and sugggestions

Send mail...