Balisage Paper: Writing Maintainable XSLT Conversions

Introduction

This project started for pedagogical purposes. The author was going to teach a course on XSLT 3, and the students were all users of Text Encoding Initiative (TEI) texts. By happenstance the author came across a transcription in TEI markup of a book that it had wanted on a Web site it runs. It worked on a transformation and then used the resulting stylesheet as an example in the course.

Having written the transformation from TEI into HTML, the author then came upon fifty-three thousand more texts from the Early English Books Online Text Creation Partnership project. They were all marked up in a deceptively similar manner, but each transcription needed work to make the markup regular. Although the author planned to use only a few of the books from the Early English Books Online project for its Web site, some planning was needed.

This meant reusing parts of the transformation, but with modifications.

And this in turn led to the work described in this paper.

The criteria given here for choosing how to divide the transformation and which tools to use are not absolute: they are in large part subjective. However, the underlying principles are more general.

The files associated with this paper are available for download from the Balisage Web site, and also directly from the author.

About the Book

Before discussing how to make a Web version of this book we should examine the printed book itself. The author does not have access to a physical copy (although it once enjoyed the excitement of holding one in its hands, in the sadly gone bookshop Galloway & Porter in Cambridge), but there are online editions.

The book was written by Thomas à Wood (1632‒1695).

The book title is given as follows in bibliographies (for the first of two volumes; both volumes were used in this project):

Athenæ Oxonienses. Vol. 1. an exact history of all the writers and bishops who have had their education in the most ancient and famous University of Oxford, from the fifteenth year of King Henry the Seventh, Dom. 1500, to the end of the year 1690, representing the birth, fortune, preferment, and death of all those authors and prelates, the great accidents of their lives, and the fate and character of their writings : to which are added, the Fasti, or, Annals, of the said university, for the same time. [Wood 1691]

In the interests of brevity in this paper it is referred to as the Athenæ Oxonienses, or simply Ath. Ox. for short, and, except where indicated, all references are to the entire work, not a specific volume, and to the 1691 edition (1692 for the second volume).

So, after all this, what is it? The Oxford Athens, or Ath. Ox., is, as its length title suggests, a book of short biographies of people associated with Oxford University. It is referenced over 1,700 times from Chalmers’ Biographical Dictionary [Chalmers 1812] and has been described as the first serious attempt at an English biographical dictionary [Encycl. Brit.]. People are listed in alphabetical order grouped by date.

About the Transcription

To give credit to a significant project, and to give necessary context, this section describes the origin of the XML texts that were used.

The Text Creation Partnership started in 1999 with a goal of making the texts of historical books in the English Language available for study, rather than the digital page images in use at the time [TCP 1999]. The Early English Books Online project involved a commercial vendor of page images and over 150 libraries. The texts were keyed in by hand, since optical character recognition was inadequate for the orthographies in use.

The texts, including Ath. Ox., were encoded in SGML according to the guidelines of the Text Encoding Initiative P3 [TEI P3] and later translated to XML; the XML TEI-encoded texts were used for the transformation described in this paper.

Because the texts were hand-keyed by many people working in different institutions, and because the books themselves vary considerably in structure, and because the digital images themselves may have been relatively poor quality compared to the best available today, there are considerable variations in the quality and consistency of transcriptions, both between books and within books. Lacunæ are generally marked; Greek phrases are sometimes labeled as foreign but not transcribed and sometimes simply omitted. However, overall, the quality is certainly high enough to make the texts useful as an adjunct to the Web site run by the author of this Paper, words.fromoldbooks.org and, when combined with links to page images, perhaps for more general use.

The texts are explicitly marked as being in the public domain, a refreshing change from earlier texts often marked as being for academic use only, and hence not clearly available for commercial Web sites, teaching, or other purposes.

Making a Web Edition

The goal of making a Web edition of Ath. Ox. was to be able to refer to it via hyperlink from the Web edition of the Chalmers Biographical Dictionary. This goal suggested a strategy of making a separate Web page for each biographical entry in Ath. Ox. using XSLT.

Separate Web pages for individual biographical entries are more convenient for many users than downloading an entire book. More importantly for the author of this paper, individual Web pages are more focused: Web crawlers can detect a single topic covered with a high degree of relevancy, so the pages can be found more easily with a Web search than an entire book. Bandwidth costs on the server are also reduced, since most visitors do not need the entire book.

The initial transformation was part-written when the idea of using it as a course example arose. This was because it happened that all of the individual participants on the course, each working for a different organisation, were working with TEI-encoded texts.

Software conforming to Version 3 of the XSL Transformations specification [XSLT 3] can generally create HyperText Markup Language (HTML) Version 5 files suitable for modern browser use. It is practical to write a short XSLT transformation stylesheet that an XSLT engine such as Saxon (Saxonica; commercial and open source) can compile and run, and thereby produce multiple HTML files.

The strategy chosen initially was to run a sequence of transformations in a single stylesheet as follows:

The following program listing (an excerpt from prepare.xsl) shows the complete construction of the output. Each step involves applying XSLT templates to the result of the previous step (or to the input), changing one aspect. Each step takes place in a distinct XSLT mode.

                  
  <xsl:template match="/">
    <!--* input is A71276.xml *-->
    <xsl:variable name="combined-inputs" as="document-node()">
      <xsl:apply-templates mode="combineDocs" select="/" />
    </xsl:variable>

    <!--* remove the TEI namespace to make life simpler,
        *-->
    <xsl:variable name="no-namespace" as="document-node()">
      <xsl:apply-templates mode="removeNS" select="$combined-inputs" />
    </xsl:variable>

    <!--* turn ſ into s and ▪ into . *-->
    <xsl:variable name="text-cleaned" as="document-node()">
      <xsl:apply-templates mode="cleanText" select="$no-namespace" />
    </xsl:variable>

    <!--* mark entries for people *-->
    <xsl:variable name="with-people" as="document-node()">
      <xsl:apply-templates mode="withPeople" select="$text-cleaned" />
    </xsl:variable>

    <!--* surround entries for people with wrappers *-->
    <xsl:variable name="wrapped-people" as="document-node()">
      <xsl:apply-templates mode="wrapPeople" select="$with-people" />
    </xsl:variable>

    <!--* Move the person name to its own element *-->
    <xsl:variable name="person-in-title" as="document-node()">
      <xsl:apply-templates mode="personTitle" select="$wrapped-people" />
    </xsl:variable>

    <!--* add id attributes to the Person elements, based on names *-->
    <xsl:variable name="with-ids" as="document-node()">
      <xsl:apply-templates mode="addIDs" select="$person-in-title" />
    </xsl:variable>

    <!--* make id attributes unique *-->
    <xsl:variable name="unique-ids" as="document-node()">
      <xsl:apply-templates mode="uniqueIDs" select="$with-ids" />
    </xsl:variable>

    <!--* make links back to Chalmers *-->
    <!--* NOTE this does not yet take into account multiple
        * people with the same name, allen-thomas-1 etc.
        * It could usefully check for dates in common, but
        * this is likely unreliable for parent/son entries.
        *-->
    <xsl:variable name="with-links" as="document-node()">
      <xsl:apply-templates mode="addLinks" select="$unique-ids" />
    </xsl:variable>

    <!--* generate the final output *-->
    <xsl:sequence select="$with-links" />

    <!--* write a file of id/name mappings for use by Chalmers *-->
    <xsl:apply-templates select="$with-links" mode="writeEntries" />
  </xsl:template>

At this point a reminder about XSLT modes is appropriate, or an introduction for those readers unfamiliar with them. When an XSLT processor reaches an xsl:apply-templates element, it constructs a list of nodes in the tree representation of the input document, and for each node in the list, it chooses the most applicable template, and adds the result of evaluating that template to the output. Thus, if the templates chosen themselves contain xsl:apply-templates elements, a recursive tree-walk is performed. When selecting templates, if the processor is operating in a named mode, only those templates explicitly marked as being applicable to that named mode are selected.

XSLT Modes are used here to keep the processing of each step independent from other steps in the same stylesheet. Later we shall see an approach that uses separate XSLT stylesheets instead of modes, but this requires a little more infrastructure. Modes were used here as part of writing the stylesheet, because they can all be contained in a single file for rapid development. In the experience of the author, this sort of use of modes is common in XSLT work.

The names of the modes here are camelCase words, rather than hyphenated-words; this is because it is not an error in XSLT to try to apply templates with a mode whose name is never defined. Using a single word allows the author to use automatic completion in a specific editor, to avoid possibly typing errors in mode names. A different editor might be able to complete hyphenated names; it is often worth accommodating one’s own tools in one’s style.

There is a draft Version 4 of the XSLT language in which the xsl:mode element can contain all templates for a given mode, improving error checking. At the time of writing, XSLT 4 is still a draft, and therefore should not (in the opinion of this author) be used in production. Element and attribute names added by the stylesheet all have an upper case first letter and are then lower case; this avoids conflict with any TEI names. A namespace could have been used, but this was simpler and sufficient.

In this paper we will not examine the entire stylesheet. However, the alert reader will notice there was no step to generate HTML. The author did this in a separate stylesheet that took the output of prepare.xsl, shown partly in the program listing above, and produced HTML files. This separation greatly facilitates reuse of stylesheets, but it is arbitrary. We will return to this when we consider criteria for designing multi-step transformations.

The following listing shows the definition of one of the modes, the one to add an Entry element wrapper round the biography entry for a single person. The input to this mode has the first paragraph of each entry marked with a Starts attribute having the value person.

                  
  <xsl:mode name="wrapPeople" on-no-match="shallow-copy" />

  <!--* No automatic copying of elements at the entry level: *-->
  <xsl:template mode="wrapPeople"
    match="body//node()[
      preceding-sibling::p[@Starts = 'person']
      and not(@Starts = 'person')
    ]" />

  <xsl:template mode="wrapPeople" match="p[@Starts = 'person']"
                                                as="element(Entry)">
    <Entry>
      <!--* copy the p element except for the Starts attribute *-->
      <p>
        <xsl:apply-templates select="@* except @Starts" />
        <xsl:apply-templates select="node()" />
      </p>

      <xsl:variable name="next" as="element(p)?"
        select="(following-sibling::p[@Starts = 'person'])[1]" />

      <xsl:apply-templates
        select="following-sibling::node()[
          if ($next) then (. << $next) else true()
        ]" />
    </Entry>
  </xsl:template>

The declaration of a mode is optional; the on-no-match attribute instructs the XSLT processor on what to do with nodes not matched explicitly by any template in that mode; shallow-copy means to copy the node to the output and then process any child nodes it may have, in the same fashion. This replaces the older identity template.

Most of the other modes are similarly short. The entire prepare.xsl stylesheet contains fewer than six hundred lines.

Input and Output

This section will give the reader a taste of the transformation; we can then proceed to discuss how it might be done differently, and when, and why.

A snippet of the input:

                  
<p>
 <pb n="47" facs="tcp:56137:17"/>
 <milestone type="tcpmilestone" unit="unspecified" n="61"/> THOMAS ABEL or <hi>Able</hi>
 took the Degrees in Arts, that of Maſter being compleated 1516,
 but what De<g ref="char:EOLhyphen"/>grees
 in Divinity I cannot find. He was afterwards a Servant to
 Qu. <hi>Catherine</hi> the Conſort of K. <hi>Hen.</hi> 8. and is ſaid by
 a certain<note n="t" place="bottom">T<gap reason="illegible" resp="#TECH" extent="1 letter">
       <desc>•</desc>
  </gap>o, Bouchier <hi>in</hi>
  Hiſt. Eccieſ. de Martyrio

The output of prepare.xsl for this snippet:

                  
<Entry Volume="1" id="abel-thomas" Page="46" Year="1540">
 <p Page="46" Milestone="61">
  <Name><span class="csc">Thomas</span> <span class="csc">Abel</span></Name>
  or <hi>Able</hi> took the Degrees in Arts, that of Master being compleated 1516,
  but what Degrees
  in Divinity I cannot find. He was afterwards a Servant to
  Qu. <hi>Catherine</hi> the Consort of K. <hi>Hen.</hi> 8. and is said by
  a certain<note n="t" place="bottom">T<gap reason="illegible" resp="#TECH" extent="1 letter">
        <desc>•</desc> 
   </gap>o, Bouchier <hi>in</hi>
  Hist. Eccies. de Martyrio

Each entry has been surrounded with an Entry element, given Page and Year attributes (the page break marker in the input is after the start of the paragraph here, so the stylesheet gets the wrong page; that would be worth handling in the XSLT. The tcpmilestone elements identified many, but not all, of the starts of entries; in the end the most expedient solution was to add more milestone markers, one for each entry, and to print a message if the numbers were not consecutive. In perhaps a dozen cases they were not consecutive in the printed book.

The tall s (ſ) has been replaced with the more modern version (s), for example in ‘ſaid’ near the end of the seventh line. Explicit hyphenation elements have been replaced by (invisible) soft hyphen Unicode characters.

Figure 1 shows a snippet from the printed book, and also the note (t) at the bottom of the page. The image has been reduced in resolution for this paper, and is somewhat clearer in the full sized version.

Figure 1: Image from Printed Book (1691)

shows part of the final Web page, as of the time of writing this paper, online at words.fromoldbooks.org/Wood-AthenaeOxonienses/abel-thomas.html.

Figure 2: Web edition of the same page

Note that the font used, Junicode by Peter Baker, has been instructed using Cascading Style Sheets to display ligatures and some variant glyphs automatically; unlike the tall s mentioned above, ligatures do not affect searchability because the full text, not a combined ligature character, appears in the generated HTML files.

Strategies for Transformation

In the preceding sections we saw that a sequence of largely independent steps was used to represent the transformation. The order in which the steps are performed is important, but the steps do not otherwise interact. Each takes an XML document (or tree representation) as input and uses XSLT to produce an XML document (or tree representation) as output.

There are many different ways to process a sequence of such steps. Some of these are:

In following sections we will explore each of these strategies, some in more depth than others, and along the way take note of strengths and weaknesses of each. We will then be in a position to consider more general guidelines for writing future transformations.

Not discussed here are some additional steps such as copying CSS stylesheets, font files, and other items into the output folder and then copying the folder and its contents onto a Web server. In the case of Ath. Ox. these can all be accomplished with a publish.sh batch shell script as part of a larger Website framework.

A Single Stylesheet

This is the simplest to understand: put each step into an XSLT mode, as illustrated in earlier sections.

Disadvantages include:

Advantages include:

using transform()

This approach puts the templates for each step into a separate XSLT stylesheet. A single controlling stylesheet calls the transform() function for each step, perhaps still using the same basic structure with temporary variables.

The XPath and XQuery transform() function, formally fn:transform, takes as input an XSLT stylesheet and a node or URL to transform, along with other parameters as needed, and returns the result of evaluating (running) the given stylesheet on the given node or resource.

An advantage of using fn:transform over modes are that there is no interference: a step using one mode cannot accidentally involve apply-templates with no mode, for example, and use default templates the author did not intend.

An advantage of fn:transform over using separate XSLT invocations for each step is that there’s no need to start a new Java Virtual Machine for each transformation, and any memory used by the invoked transformation is likely to be reclaimed when fn:transform returns. There is also no need for a separate orchestration mechanism to run the transformations outside XSLT.

The Ath. Ox. transformation using fn:transform looks like this:

                  
    <xsl:template match="/">

    <!--* input is A71276.xml *-->
    <xsl:variable as="document-node()" name="combined-inputs"
      select="lq:transform(/, 'modules/join-docs.xsl', 'combineDocs')" />

    <!--* remove the TEI namespace to make life simpler,
        *-->
    <xsl:variable name="no-namespace" as="document-node()"
      select="lq:transform($combined-inputs, 'modules/remove-ns.xsl', 'removeNS')" />

    <!--* turn ſ into s and ▪ into . *-->
    <xsl:variable name="text-cleaned" as="document-node()"
	select="lq:transform($no-namespace, 'modules/clean-text.xsl', 'cleanText')" />

    <!--* mark entries for people *-->
    <xsl:variable name="with-people" as="document-node()"
	select="lq:transform($text-cleaned, 'modules/with-people.xsl', 'withPeople')" />

    <!--* surround entries for people with wrappers *-->
    <xsl:variable name="wrapped-people" as="document-node()"
	select="lq:transform($with-people, 'modules/wrap-people.xsl', 'wrapPeople')" />

    <!--* Move the person name to its own element *-->
    <xsl:variable name="person-in-title" as="document-node()"
	select="lq:transform($wrapped-people, 'modules/person-title.xsl', 'personTitle')" />

    <!--* add id attributes to the Person elements, based on names *-->
    <xsl:variable name="with-ids" as="document-node()"
	select="lq:transform($person-in-title, 'modules/add-ids.xsl', 'addIDs')" />

    <!--* make id attributes unique *-->
    <xsl:variable name="unique-ids" as="document-node()"
      select="lq:transform($with-ids, 'modules/unique-ids.xsl', 'uniqueIDs')" />

    <!--* make links back to Chalmers *-->
    <!--* NOTE this does not yet take into account multiple
        * people with the same name, allen-thomas-1 etc.
	* It could usefully check for dates in common, but
	* this is likely unreliable for parent/son entries.
	*-->
    <xsl:variable name="with-links" as="document-node()"
      select="lq:transform($unique-ids, 'modules/add-links.xsl', 'addLinks')" />

    <xsl:sequence select="$with-links" />

    <!--* write a file of id/name mappings for use by Chalmers *-->
    <xsl:sequence
      select="lq:transform($with-ids, 'modules/write-entries.xsl', 'writeEntries')" />

    </xsl:template>

The lq:transform function is defined for convenience as follows:

                  
  <xsl:function name="lq:transform" as="document-node()">
    <xsl:param name="input" as="document-node()" />
    <xsl:param name="stylesheet" as="xs:string" />
    <xsl:param name="mode" as="xs:string" />

    <xsl:sequence select='transform(
      map {
	"stylesheet-location": $stylesheet,
	"source-node": $input,
	"initial-mode": QName("", $mode),
	"stylesheet-params": map {
	  QName("", "chalmers"): $chalmers,
	  QName("", "chalmersTOP"): $chalmersTOP
	}
      }
    )?output' />

  </xsl:function>

Wrapping fn:transform up in this way reduces repetition in the main template, making it easier to read. The stylesheet parameters are passed to every module, even if not needed, for simplicity; they are a list of ID strings for creating cross references, and the published URL of the Chalmers dictionary.

This approach still uses temporary variables for each intermediate result. In XPath 3 there is a “simple map operator” [W3C XPath 3.1], using the character !, such that for each item in the (possibly singleton or empty) sequence on its left, evaluates the expression to its right with the context item (“.”) set to that value. We can use that operator to make a “streaming” version of the template that uses fn:transform, without the need for explicit temporary storage:

                  
  <xsl:template match="/">

    <!--* input is A71276.xml *-->
    <xsl:variable as="document-node()" name="combined-inputs"
      select="lq:transform(/, 'modules/join-docs.xsl', 'combineDocs')" />

    <xsl:variable name="with-links" as="document-node()" select="
      (: remove the TEI namespace to make life simpler :)
      lq:transform($combined-inputs, 'modules/remove-ns.xsl', 'removeNS')
      !
      (: turn ſ into s and ▪ into . :)
      lq:transform(., 'modules/clean-text.xsl', 'cleanText')
      !  (: mark entries for people :)
      lq:transform(., 'modules/with-people.xsl', 'withPeople')
      ! (: surround entries for people with wrappers :)
      lq:transform(., 'modules/wrap-people.xsl', 'wrapPeople')
      ! (: Move the person name to its own element :)
      lq:transform(., 'modules/person-title.xsl', 'personTitle')
      ! (: add id attributes to the Person elements, based on names :)
      lq:transform(., 'modules/add-ids.xsl', 'addIDs')
      !  (: make id attributes unique :)
      lq:transform(., 'modules/unique-ids.xsl', 'uniqueIDs')
      !  (: make links back to Chalmers :)

	 (: NOTE this does not yet take into account multiple
	  : people with the same name, allen-thomas-1 etc.
	  : It could usefully check for dates in common, but
	  : this is likely unreliable for parent/son entries.
	  :)
      lq:transform(., 'modules/add-links.xsl', 'addLinks')
    " />

    <xsl:sequence select="$with-links" />

    <!--* write a file of id/name mappings for use by Chalmers *-->
    <xsl:sequence
      select="lq:transform($with-links, 'modules/write-entries.xsl', 'writeEntries')" />

  </xsl:template>

The version using a single XPath expression and the “!” operator runs (on the computer the author uses) in approximately 37 seconds, using 51 seconds of CPU time. It is very slightly faster, or about the same speed as, the version using transform and temporary variables, and used approximately 2% less memory, so between these two versions the best is that one that’s easiest to maintain and reuse.

Disadvantages include:

Advantages include:

An XProc Pipeline

XProc is a language with an XML syntax designed for exactly scenarios such as this: performing multiple steps in sequence. Unfortunately, XProc implementations have had problems, not least of which has been a reputation for cryptic error messages. XProc Version 3 was introduced to try to make XProc easier to use, however. The following listing shows part of an XProc 3 pipeline that can be used to run this transformation: here it runs the entire XSLT transformation, using the XSLT version with modes, then generates HTML and writes out the generated files:

                  
<p:declare-step xmlns:p="http://www.w3.org/ns/xproc" version="3.0">

  <!--* XProc 3 pipeline to convert TEI Ath. Ox. to HTML.
      *
      * We have two input files to process.
      * ideally we would first remove the "out" folder.
      *-->
      
  <p:input port="source"/>
  <p:output port="result" pipe="result@create-secondary-documents" />

  <p:xslt>
    <p:with-input port="stylesheet" href="prepare.xsl" />
  </p:xslt>

  <p:xslt name="create-secondary-documents">
    <p:with-input port="stylesheet" href="teiplus2html.xsl" />
  </p:xslt>

  <p:for-each>
    <p:with-input pipe="secondary" />
    <p:store href="{base-uri(/)}" />
  </p:for-each>

</p:declare-step>

The individual steps here are still modes in prepare.xsl, but can clearly be taken out into individual files.

Disadvantages include:

Advantages include:

A batch script

Consider the following Unix shell script (for use on Linux, MacOS, or Windows with the Linux subsystem installed):

                  
#! /bin/sh
saxon-ee A71276.xml prepare.xsl > tmp1.xml
saxon-ee tmp1.xml teiplus2html.xsl
# copy auxiliary files:
test -d out/. &&
    cp -a athox.css awesomplete.css out/ &&
    cp -a junicode out/

This is reasonably simple to understand. It does make a temporary file, tmp1.xml, although at least on Unix or Linux systems the data in the temporary file will generally be read from memory by the second Saxon run, not from long-term storage media.

There are only two XSLT runs here; if there were twenty, temporary file management would become harder. On the other hand, having the temporary files around and perhaps given more useful names can facilitate debugging.

This approach has some disadvantages:

This approach also has advantages:

A Unix Makefile

The make command came from Unix in the late 1970s. It has its own syntax, with the arcane property that indented lines must use tab characters and not spaces. The reason people still use this tool is that it computes a dependency graph based on file timestamps, and only runs the minimum set of commands needed to produce the result. It can also run programs in parallel, although that does not apply to a sequence of steps.

The following program listing shows a Makefile for Ath. ox.:

                  
# Makefile to show a way to run processes
# if you edit this remember indented lines must start with
# a single TAB character and NOT spaces.

SAXON="saxon-ee"

install: all
	cp -a athox.css awesomplete.css out/
	cp -a junicode out/

all: tmp1.xml teiplus2html.xsl
	$(SAXON) tmp1.xml teiplus2html.xsl

tmp1.xml: A71276.xml prepare.xsl
	$(SAXON) A71276.xml prepare.xsl > tmp1.xml

This Makefile says that the target install depends on all; the target all n turn depends on the files tmp1.xml and teiplus2html.xsl; tmp1.xml in turn depends on A71276.xml and prepare.xsl. So if teiplus2html.xsl is changed and you run the make command, Saxon will be run on tmp1.xml using teiplus2html.xsl, but the last rule, building tmp1.xml, will not be needed as it will be unchanged from the previous run of make.

A similar dependency graph based on intermediate files can be created by other tools, including Calabash (an XProc implementation), ant, and for the more development-inclined, meson and ninja.

The approach using make has disadvantages:

There are also advantages:

Using ant

Ant is an XML-based replacement for make. Like XProc, it is much less widely used than bash, batch scripts, or make. Also like XProc, it is in XML, and implemented in Java.

The following build.xml file for ant is complete (using a single XSLT file prepare.xsl rather than individual steps for brevity of exposition) except for the part that pushes the result to the live Web site, which is the same for all the solutions here, and uses ssh.

                  
<!--* build file for use with ant *-->
<project name="Ath. Ox." default="publish" basedir=".">
  <description>
    Make Ath. Ox. Web site and push it
  </description>

  <xslt in="A71276.xml"
        style="prepare.xsl"
	out="ant-tmp.xml"
	classpath="saxon-ee/saxon9ee.jar:saxon-ee/"
	>

    <factory name="com.saxonica.config.EnterpriseTransformerFactory" />
   </xslt>

  <xslt in="ant-tmp.xml"
        style="teiplus2html.xsl"
	classpath="saxon-ee/saxon9ee.jar:saxon-ee/"
	out="ant-out"
        >
    <factory name="com.saxonica.config.EnterpriseTransformerFactory" />
   </xslt>
  
  <copy file="athox.css" todir="out" />
  <copy file="awesomplete.css" todir="out" />
  <copy todir="out/junicode" >
    <!--* have to use a resource collection to copy a directory *-->
    <fileset dir="junicode" />
  </copy>
</project>

Ant disadvantages include:

Ant shares some advantages with XProc and some with make:

Which to choose

In this section we try to derive some more general observations and guidelines.

Documentation

Comments are all well and good, but will they mean anything ten years later? The author once had to maintain a body of code whose primary comments were /* XXX */. Splitting a transformation into steps lets you give a name to each step, and lets you put an explanatory comment about purpose at the start of each step.

Comments before each template take discipline to keep up to date. A comment inside a template, but at the start, is easier, because you’re forced to look at it every time you look at the template. And a comment, as in the examples in this paper, before calling a transformation step, can go a long way to making clear what is happening.

Code that cannot easily be read cannot be fixed. Code that can be read but that is wrong can be fixed. Therefore, it is more important to write clear code than it is to write correct code.

Conclusions

A full decision tree for designing a transformation would depend on the people and the context, on the input and the intended output. This paper has shown some things to consider, some of which, in the experience of the author, are often not considered.

If you are writing a new transformation in XSLT, consider writing it as a series of steps, even if those steps are initially all contained in the same XSLT file; it is much easier then to separate them out later for reuse.

Tools such as make, XProc, ant, and even shell or batch scripts if they are kept simple and readable, can help separate out the orchestration and interface to the surrounding environment from the actual transformation; this separation can facilitate debugging, resource management, and reuse.