DHQ Tools page: methods, techniques, tools and toolkits

If you have an editor or toolset you have successfully used to create or process DHQauthor documents, and would be willing to serve as a technical reference for that tool, list it here. Use superlatives in your description, if it deserves it. (Also let us know on dhq-tech list so we can track developments.)

Note that DHQauthor is being developed (see our Technical Commitments? ) using openly specified technologies: XML (W3C? Rec 1998), Relax NG, Schematron, XSLT and so forth. You should be able to find yourself a wealth of resources for working with these technologies.

Learn more:

• XML and XSLT: http://w3.org (or just about anywhere)
• Relax NG: http://www.relaxng.org/
• Schematron: http://www.schematron.com/

Tools and toolkits

oXygen from syncROsoft (editing, validating and styling)

oXygen is an inexpensive and versatile XML developer's environment with good support for validating documents using Relax NG, rendering documentation from the schema to provide assistance in tagging, and applying Schematron assertion sets. Additionally, it provides XSLT processing support so you can try transformations over your DHQauthor after you've tagged it.

As of version 9, oXygen also offers "near-WYSIWYG" editing, with a CSS stylesheet. Return to DownloadCentral to acquire suitable CSS.

Visit the oXygen web site at http://www.oxygenxml.com/. For new users, a one-month trial period is offered. For purchasers, academic and other discounts are available. The truly penurious should contact the DHQ editors as further discounts may be possible (courtesy of the oXygen developers).

XML Mind (editing and validating)

XML Mind (see http://www.xmlmind.com/xmleditor/) is a free, styled-in-view XML editor that uses CSS for pretty page display, similar to oXygen 9. While it is perhaps not as easy to learn and use as oXygen, its price recommends it.

Emacs (editing and validating)

There are several versions of Emacs around. We need someone to write up Emacs. Please let us know if you are able to do this or you need it done!

Jing (validating)

Any programmer's text editor can be useful for editing XML, and this is a cheap but viable alternative to a preconfigured environment. Many of the more full-featured text editors can be asked to run a command-line tool from the editor itself. If you already have such an editor (such as TextPad? , BBEdit, Notetab, JEdit etc.) but it does not have built-in support for Relax NG,

This is an option that should be considered by developers or users familiar with Java and command-line processing in general. These instructions assume you have basic competence in setting up and running Java applications and (probably) shell scripts or batch files for your operating system.

Jing is an open source Java application; download it from [http://thaiopensource.com/relaxng/jing.html]. It is a Java program, so you will need a JDK, JRE or other Java VM already installed to run it.

A typical DOS batch file for running Jing from a DOS (Windows) command line might look like this:

@echo off
echo Jing validating %1 to %2
java -jar C:\bin\jclark\jing-20030619\jing.jar %2 %1
echo ...no news is good news...

Call this batch file rngvalidate.bat, place it on your system path, adjust its internals as necessary, and invoke it with the command

rngvalidate myDHQdocument.xml DHQauthor.rng

where myDHQdocument.xml is your XML DHQ author document and DHQauthor.rng is available in the current subdirectory (with its submodules).

The reason this batch script echoes "no news is good news" when it completes is that Jing reports nothing when a file runs without errors.

XSLT styling how-to

Applying stylesheets to XML documents is "bread and butter" for document creation and management in XML, and there are numerous free XSLT engines available that can be used to apply stylesheets to XML documents to create styled results (as HTML web pages, PDF documents or in other formats). Examples include Saxon (in Java), MSXML (Windows), XSLProc and others; the range of possibilities is wide because different methods and tools are appropriate for different platforms and operating environments.

If, having done the research, you need further assistance making a choice and getting started with styling XML with XSL, please let us know and we'll be happy to offer assistance or guidance.

In general there are three architectures that support transformation:

In the browser

By technologists this is commonly called "client-side processing" since the work of transformation occurs on the client (in this case, the browser). Many commonly available web browsers now support styling of XML using XSLT, including Mozilla, MS Internet Explorer, Opera and Safari. In general, once the "wiring" is in place this is done simply by opening the XML document in the browser.

In order for the browser to find and apply the correct stylesheet, an XML processing instruction must be placed at the head of the XML document, like so:

<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="../XSL/DHQarticle-proof-html.xsl"?>
<DHQarticle xmlns="http://digitalhumanities.org/DHQ/namespace"
  xmlns:cc="http://web.resource.org/cc/"
  xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">

The example shown demonstrates how a DHQarticle document is wired with the DHQarticle-proof-html.xsl stylesheet. The href setting in the processing instruction is a URI pointing to the stylesheet; if this resolves correctly (in this case the stylesheet file would have to be in the ../XSL subdirectory relative to the XML document), the web browser will render the file styled accordingly.

Note that styling a document successfully using one of our stylesheets does ''not'' warrant that the document is correct and fit for submission to DHQ or processing in our system. Validation of the document against our schema is still required. See Getting Started with DHQauthor for more information.

In a standalone process

This is often called "batch mode" since it emulates "batch production" in publishing systems. One advantage of batch mode is that many XML documents can be converted at once.

Since this is actually the simplest architecture and requires the lowest overhead (no browser), just about any XSLT engine can be set up to do it. An XML developer's kit or editor will commonly offer this facility, but it can also be done from a command line on your system. The result of the transformation (typically an HTML file) will be written to your file system where it can be moved, modified and browsed just like any other file.

Your first choice of tool for doing this will probably be an XML editor or developer's kit such as oXygen from sycROsoft (see above).

If you are on a tight budget, other (free) alternatives are also available. Typically these require a bit of setting up: * Saxon (in Java): download from http://saxon.sourceforge.net/. Use Saxon 6.5.5 for XSLT 1.0 transformations. (A more current version of Saxon from http://saxonica.com supports XSLT 2.0.) * MSXML, using the MSXSL.exe command line tool. Requires some XML expertise to use properly, though not Java. (Google for "msxsl.exe" to locate the download site.) * libxslt, part of XSLProc, an XML processing package in C (use from the command line). This is part of the Gnome project (Linux based) but is also available for other platforms, including Windows (on cygwin, Unix tools for Windows). See http://xmlsoft.org/ and http://www.cygwin.com/.

(If you have a favorite tool you think should also be listed here, please let us know.)

The specifics of how the process is run will depend on your engine and operating system. If you are learning how to work with XML and XSLT this will be bread and butter to you; if you are just starting and can't figure it out from the numerous tutorials and manuals on line (check the documentation of your chosen processor), please ask us for assistance. We recommend you explore and experiment.

In a server

Technologists call this "server-side processing". The idea here is that an HTML document is created from your XML source on a web server and then delivered as HTML to a client (browser). The receiving client never needs to know the document started life as XML.

DHQ plans at some point to be able to offer a service whereby you upload a document and our server returns to you the result of an XSLT transformation as HTML (which looks like an ordinary web page). This is on the drawing board. (When we do offer this service it will probably be, first, for accepted papers currently being revised.)

Conversion tools and stylesheets

TEI display stylesheet

We are hoping and expecting to receive submissions in TEI, which may come without their own display stylesheets. Occasionally we'll need to see this stuff in a web browser, requiring an HTML conversion. But it does no good to customize a general-purpose suite of TEI stylesheets, since our input is too open-ended: we don't know what flavor of TEI it may be. We need something lightweight, which works most of the time for most basic things, and which is easily customizable, adaptable and extensible to new structures.

This stylesheet:

• Is fairly lightweight
• Supports a great diversity of input fairly gracefully
• Can be easily tuned, modified or extended at either CSS or XSLT layers

Note that it also includes code to handle one of the more difficult problems in TEI to HTML conversion, namely the divergence in modeling between TEI's "rhetorical paragraph" and HTML's "presentational paragraph". This divergence is evident in HTML's rule that p may not contain lists, whereas TEI p may. This presents the conversion specialist with a problem for which XSLT 1.0 has no useful native constructs (solutions are possible, but are both cumbersome to build and maintain, and difficult to extend). This XSLT 2.0 stylesheet uses XSLT's grouping constructs to solve this problem more easily and cleanly.

Developed and tested with Saxon 8. Jarom McDonald? contributed to the development of this stylesheet.

• TEItoHTMLdisplay.xsl: Rough-and-ready TEI to HTML display stylesheet (in XSLT 2.0)

• DHQ-TEI-html.css: CSS to enhance display of HTML results from TEItoHTMLdisplay? .xsl

-- WendellPiez - 23 Jun 2008