Historical Event Markup and Linking Project

For someone used to editing XML or HTML by hand, a favorite text editor might be sufficient. Take one of the documents from this site and change its values by copying and pasting. Internet Explorer, Mozilla and xmllint all can provide XML well-formedness checks, which catch 70% of errors.

Jedit has made great improvements in its XML-Schema driven contextual editing. It can be frustrating, though: it will occasionally provide an attribute name on input which it later complains about while checking validity (xml:lang seems to be a problem).

The best all-round editor for XML-Schema driven documents has to be the commercial XML Spy. My students have worked with it over two summers and have found it ideal for their needs. It is a Windows-only product.

1.2.

How do you make the SVG maps that underlie Heml map views?

These are created by a php script called Nimue. Quite simply, it passes lat/long and colour values to pscoast, a part of the GMT mapping tools; the resulting postscript is converted to SVG with pstoedit; and the SVG document is translated to the origin with a xslt transformation. Nimue is entirely based on free software, and it works well on a RH Linux 7.3 box.

I don't have a dedicated machine for Nimue, so I can't provide an address. The process is so CPU-intensive that it would overwhelm the other uses that a machine was being put to.

1.3.

How does the Heml webapp produce SVG documents with embedded SVG glyphs?

It piggy-backs on the Batik project's code. A full description of the technique, is published on the Cocoon wiki.

2. International Character Sets

2.1. Why is the improper abbreviation used for the Gregorian eras? For instance, in French 'BC' is not commonly used, and 'av. J.-C.' is.

2.1.

Why is the improper abbreviation used for the Gregorian eras? For instance, in French 'BC' is not commonly used, and 'av. J.-C.' is.

HEML generates calendrical text using the Java 1.2 Calendar classes and IBM's International Calendars for Unicode. Where they lack, it lacks as well. In particular, the international text codes for Sun's GregorianCalendar are unusual. We hope that Sun will correct this soon. On the other hand, ICU is quite properly internationalized; as a result the Hebrew and IslamicCivil calendars often produce better localized text than the Gregorian one.

3. Running the Heml Webapp

3.1. I downloaded a recent .war file and placed it in my tomcat's webapps directory. I can see heml's front page however I'm not seeing any local documents show up nor when I click on the examples, timeline of Stalin, am I able to see anything. It seems like I'm getting an exception in Tomcat's log at every http request that I do when accessing a heml webpage. (Paraphrased from Troy Smith)
3.2. How Do I Serve the Heml Webapp from Apache?

3.1.

I downloaded a recent .war file and placed it in my tomcat's webapps directory. I can see heml's front page however I'm not seeing any local documents show up nor when I click on the examples, timeline of Stalin, am I able to see anything. It seems like I'm getting an exception in Tomcat's log at every http request that I do when accessing a heml webpage. (Paraphrased from Troy Smith)

This is typical of a situation where the built-in xalan and xerces (XML and XSLT engines) from the JDK are being used in place of the more up-to-date ones in the webapp.

Copy the xalan*jar xerces*jar and xml-api.jar files from $TOMCAT_HOME/webapps/heml-cocoon/WEB-INF/lib to $TOMCAT_HOME/common/endorsed and restart.

If necessary, remove $TOMCAT_HOME/work and restart.

n my experience, Jetty works out of the box without this fiddling.

3.2.

How Do I Serve the Heml Webapp from Apache?

The easiest way is using Apache 2 and the Jetty servlet engine following the instructions from Pier Fumagalli and others.

Alternatively, you can use one of the many connectors available for Tomcat and Jetty.

4. Using and Customizing the Heml Webapp

4.1. The Heml serves content with the sidebar and view selection menus. How can I produce views in my own site that omit these?
4.2. How does a URL control the Heml Webapp?
4.3. How can I customize the look of the html popups, etc.?

4.1.

The Heml serves content with the sidebar and view selection menus. How can I produce views in my own site that omit these?

The Heml webapp uses 'logical' urls, based not on resource location, but rather on what should appear in the served page. As an example, the url

http://heml.mta.ca/heml-cocoon/with_sidebar/with_browser/timelineRef.html?url=...

requests the 'timelineRef.html' document wrapped with the sidebar and the selection menu, which we call the 'browser'. The url omitting these directories,

http://heml.mta.ca/heml-cocoon/timelineRef.html?url=...

will serve the timelineRef.html document alone.

For each SVG view, there is a corresponding 'Ref.html' document which refers to the SVG document in an EMBED element and provides a jpg backup view for browsers that are not SVG-savvy.

4.2.

How does a URL control the Heml Webapp?

Unless you've changed things drastically, all Heml content is served under http://YOUR_SERVER/heml-cocoon/. From there, a filename and extension tell the webapp what sort of view you want and how you want it encoded, as listed in Table 1, “Graphical Views”. For instance, a static map in the png format would be generated with the URL http://YOUR_SERVER/heml-cocoon/static.png; an animated one in compressed svg from http://YOUR_SERVER/heml-cocoon/animation.svgz.

Table 1. Graphical Views

Filename	Possible File types	Description
timeline	svgz svg png jpg tiff	graphical timeline
map	svgz;svg	dynamic map
animation	svgz svg	animated map
static	svgz svg png jpg tiff	static map
table	html	Table of events
keywordList	html	List of keywords and associated events
participantList	html	List of participants and associated events
locationList	html	List of locations and associcated events

4.3.

How can I customize the look of the html popups, etc.?

The cascading stylesheet files for these are in the heml-cocoon/resources/css directory.

5. Building the Heml Webapp on Windows 95/98

5.1. I receive an out of environment space error in MS-DOS when Tomcat is executed. What does this mean?

5.1.

I receive an out of environment space error in MS-DOS when Tomcat is executed. What does this mean?

This error occurs because the default amount of environment space allocated by MS-DOS is insufficient to run Tomcat. To avoid this error you will need to do the following for both the startup.bat and shutdown.bat files in $TOMCAT_HOME/bin/. In Windows Explorer, right click on the desired batch file and select Properties from the menu. This will open the MS-DOS Prompt Properties window. Choose the Memory tab and set the "initial environment" to 3072 and click OK. This will create a shortcut in $TOMCAT_HOME/bin/ for the chosen batch file. Use these new startup and shutdown shortcuts when starting and shutting down Tomcat.