stf (https://github.com/MenteaXML/stf) is a XProc pipeline that runs a Schematron test suite on test documents (that you create) and winnows out the expected results and report just the unexpected.  stf uses a processing instruction (PI) in each of a set of (typically, small) test documents to indicate the test’s expected asserts and reports: the expected results are ignored, and all you see is what’s extra or missing.  And when you have no more unexpected results from your test documents, you’re ready to use the Schematron on your real documents.

<?stf?> Processing Instruction

The format of the PI is:

<?stf \s+ ( '#NONE' | ROLE ':' COUNT ( \s+ ROLE ':' COUNT )* ) ?> 

where:

• stf: PI target
• #NONE: No faild assert or successful report expected. Use with ‘go’ tests that should not produce any assert or report messages. If running Schematron on the test produces any asserts or reports, they are reported as an error.
• ROLE: Token corresponding to @role value of an assert or a report in the Schematron. Schematron allows @role to be an arbitrary string, but restricting it to a single token makes it easier to deal with the PI using regular expressions rather than having to parse roles that may contain spaces.
• COUNT: Integer number of expected occurrences of failed asserts or successful reports with @role value matching ROLE. A mismatch between the expected and actual count is reported as an error. A ROLE starting with # does not have its count checked.
• \s: Whitespace character

Examples

<?stf ERROR_FOO:2 ERROR_BAR:1 ?> 

A failed assert or successful report with role="ERROR_FOO" is expected twice in the SVRL from the test document, and either with role="ERROR_BAR" is expected once.

<?stf ERROR_FOO:2 #ERROR_BAR:1 ?> 

A failed assert or successful report with role="ERROR_FOO" is expected twice in the SVRL, and no assert or report with role="ERROR_BAR" is expected since # precedes ERROR_BAR.

<?stf #NONE ?> 

No assert or report are expected for the current document.

Usage

stf requires Ant and Calabash. Calabash (as used here) requires Saxon. All three require Java.

1. Set the properties in properties.xml to match your local setup.
2. Write the tests, including a <?stf?> processing instruction in each.
   One practice is to use a tests directory containing a go subdirectory for tests that are expected to produce no Schematron assert or report messages and a nogo subdirectory for tests that are expected to have errors, but you can organise them any way you like.
3. Run Ant
   You can run the test.schematron from build.xml directly:

   ant -f /path/to/stf/build.xml test.schematron

   or you can import the stf build.xml into your local build.xml:

   <property name="stf.dir" location="/path/to/stf" />
   <import file="${stf.dir}/build.xml" />

   and run the test.schematron target, or you can import the stf build.xml and use the <test.schematron/> macro in a target in your local build.xml:

   <target name="test">
     <test.schematron />
     <xspec xspec.xml="tests.xspec" />
   </target>

Ant Properties

• ${schematron}: Schematron file to test.
• ${tests.dir}: Directory containing test files.
• ${calabash.jar}: Location of Calabash jar.
• ${saxon.jar}: Location of Saxon 9.2 (or later) jar.
• ${resolver.jar}: Location of XML catalog resolver library.
• ${resolver.class}: Class name of XML catalog resolver. Default is org.apache.xml.resolver.tools.CatalogResolver.

XProc Processor

The pipeline currently depends on Calabash extensions.

The version of Calabash used in testing depended on Saxon 9.2 or later.

Running (Not Testing) Schematron

Ant build file also includes schematron macro and run.schematron target to make it easy to run Schematron on real files once you’re sure it works on your tests.

License

Licensed under the terms of a BSD license.

To put it another way:

• If you want different styles in a couple of contexts that depend on the type of several levels of ancestor, then you get to put all those ancestors in the CSS selectors for each of those styles;
• If you want to use the same colour in multiple different styles, then, by golly, you get to enter the same color value in each of them (and if you want to change it later, you get to find them all again to do it); and
• If you want to use the same set of styles in multiple contexts – say, use rounded corners multiple places and with bigger radii on the outermost corners – then you get to repeat the same set of styles while jiggering their values every place that you want them.

The CSS soon gets to the point that only a machine can reliably work out the cascading and so we require tools such as Firebug to make sense of it and present it to us in ways that we can understand.

I have previously implemented a system for a client where the template CSS file is wrapped in an XML element and contains empty elements for each of the values of color properties so the all-XML processing system can ‘skin’ the stylesheet by substituting the preferred color values and outputting proper CSS on the way to making the HTML, but that was adding complexity, not taking it away.

Enter LESS (http://www.lesscss.org/), the “dynamic stylesheet language”. LESS is pretty much CSS as it should have been, since it elegantly solves the gripes listed above, and more besides.

LESS is available as a JavaScript library for client-side translation of .less stylesheets – linked from your HTML with the link’s rel attribute set to “stylesheet/less” – into CSS on the fly and server-side for use with Node. It’s also available as a command-line program that simply converts LESS to CSS that you can save and serve statically.

There are good and succinct examples on the LESS website. Just to be different, here’s an example from my GitHub project for an XML Summer School skin for S5.

Here’s a subset of an old version borrowing what was originally Norman Walsh’s CSS for his project for producing XHTML slides for XML Summer School:

.footer {
    background-color: #fffc84;
    position: relative;
    background-image: url(../images/cc-1024.png);
    background-repeat: no-repeat;
    background-position: 3 3;
    margin-top: -48px; /* negative value of footer height */
    height: 48px;
    bottom: 0px;
    padding-left: 100px;
    clear: both;
}

.footer .content {
    padding-left: 400px;
    height: 0px;
}

.footer .license {
    padding-top: 8px;
    padding-left: 30px;
    font-size: 10pt;
    height: 0px;
}

.footer .foilnumber {
    text-align: right;
    padding-right: 30px;
    padding-top: 14px;
    font-size: 10pt;
    height: 0px;
}

pre {
    font-family: Courier New, Courier, monospaced;
    font-weight: bold;
    border: 1px solid black;
    padding: 10px;
}

.xml {
    background-color: #E6E6E6;
}

.xslt {
    background-color: #FFFDCE;
}

.schema {
    background-color: #E5E7FE;
}

.other {
    background-color: #C7FFFF;
    color: #9E0000;
}

.xml .pi {
    color: #8C35C7;
}

.xml .el {
    color: #001A94;
}

.xml .att {
    color: #FC7F4C;
}

.xml .attval {
    color: #9E2E00;
}

.xml .ent {
    color: #979315;
}

.xml .xslt {
    color: #006AC6;
}

pre .p {
    color: #9E0000;
}

pre .kw {
    color: #001A94;
}

pre .str {
    color: #595837;
}

pre .re {
    color: #FC7F4C;
}

And here’s a old but LESSified version of the same excerpt:

@yellow: #fffc84;

.footer {
    background-color: @yellow;
    position: relative;
    background-image: url(../images/cc-1024.png);
    background-repeat: no-repeat;
    background-position: 3 3;
    margin-top: -48px; /* negative value of footer height */
    height: 48px;
    bottom: 0px;
    padding-left: 100px;
    clear: both;

    .content {
	padding-left: 400px;
	height: 0px;
    }

    .license {
	padding-top: 8px;
	padding-left: 30px;
	font-size: 10pt;
	height: 0px;
    }

    .foilnumber {
	text-align: right;
	padding-right: 30px;
	padding-top: 14px;
	font-size: 10pt;
	height: 0px;
    }
}

pre {
    font-family: Courier New, Courier, monospaced;
    font-weight: bold;
    border: 1px solid black;
    padding: 10px;

    &.xml {
	background-color: #E6E6E6;

	.pi {
	    color: #8C35C7;
	}

	.el {
	    color: #001A94;
	}

	.att {
	    color: #FC7F4C;
	}

	.attval {
	    color: #9E2E00;
	}

	.ent {
	    color: #979315;
	}

	&.xslt {
	    color: #006AC6;
	}
    }

    &.xslt {
	background-color: #FFFDCE;
    }

    &.schema {
	background-color: #E5E7FE;
    }

    &.other {
	background-color: #C7FFFF;
    }

    .p {
	color: #9E0000;
    }

    .kw {
	color: #001A94;
    }

    .str {
	color: #595837;
    }

    .re {
	color: #FC7F4C;
    }
}

Note that:

• The colour @yellow is also used elsewhere in the stylesheet, but I didn’t want to repeat the whole stylesheet here.
• The & combinator concatenates a nested selector to its parent selector instead of the selector acting as a descendent. As the LESS website notes, this is especially important for pseudo-classes like :hover and :focus.
• Code samples in the slides are represented with the <pre> element with a different background colour depending on the code type..
• The class names for styling parts of XML markup in samples are common to both XML and XSLT samples. Since my project includes a stylesheet for translating Norm’s XHTML slide markup to S5-style XHTML, the class names are unchanged from the original and thus there’s a necessity for markup such as <pre class="xml xslt"> for getting the right colour for elements and attributes, etc., in XSLT code samples. If it weren’t for that, it would have been more sensible to use a LESS mixin to handle the repetition between the XML and XSLT code sample styles.

My only gripe with LESS so far is that I’ve yet to get it and the JavaScript from S5 to play nicely together, so I had to back out the use of LESS for the S5 project, which to date was my only publicly visible project to use LESS.

Arguably CSS1 could have introduced something more LESS (you just knew I’d been wanting to write that, didn’t you?) since <div> – the definitive expression of hierarchy in HTML content – was introduced in the HTML 3.0 drafts and CSS 1 refers to HTML 4.0. Hindsight, being the only perfect science, would indicate that is should have been possible, but I really don’t know whether it was technically or politically feasible once there was an installed base of CSS1 engines and web pages that used CSS1 as we knew it. If LESS does now catch on enough that it gets baked into browsers, this ‘native’ LESS would probably require a different, registered rel value or a well-known MIME-type so there’s no conflict on the web pages that currently use LESS stylesheets with the LESS JavaScript library.

Strangely, it was the existence of the xmlroff testing module that got several people most excited. I say ‘strangely’ because I’ve been mentioning it in presentations for years (including three days earlier in the “XSLT/XQuery” track) without it seeming the stand-out feature of any of those talks, yet this time I had someone finding its URL and downloading it before I’d barely finished the slide about it. But I am in no way complaining.  It was good to see such a level of interest, and I hope it works out for him and the others. I’m also hoping to get some new feedback on how well it works, since although I’ve been using it (and tweaking it) for years, it doesn’t garner much feedback from other users.

My other reason for being pleased with the success of the XSLT and XSL-FO talk was that it meant that I’d kept to the high standard of the other talks in the track by Henry Thompson, Norman Walsh, and Sebastian Rahtz. The talks in the “XSLT/XQuery” track by Priscilla Walmsley (track chair) and Michael Kay (and, as always, Jeni’s delivery) and the other Ignite talks were very good, too, but I thought the other “Publishing” track talks were particularly good. Quite an achievement considering that this was the first year that the XML Summer School had a separate “Publishing” track, so credit also goes to Peter Flynn, as track chair, for putting the track together in the first place.

I know the above reads like I’m in a mutual admiration society, but it really was a week of very good talks.

My sessions are but 1/4 of their respective tracks, but I’ll be in the room for the entirety of each track and, indeed, like all Faculty at the XML Summer School, I’ll be around all week.

For the record, the Publishing session is:

XSLT and XSL FO tool­box of tips and tricks

XSLT was designed to trans­form XML into other formats, and its ori­ginal pur­pose was to trans­form XML into the XSL FO vocab­u­lary for format­ting as pages.

Pro­du­cing pages is still close to the heart of many pub­lish­ers, but we also use XSLT to trans­form XML into other XML vocubu­lar­ies, into HTML, and into other non-XML formats.

This ses­sion provides sample tech­niques for using XSLT and XSL FO in pub­lish­ing. We encour­age attendees to put for­ward their pain points with using XSLT and/or XSL FO, either in the ses­sion or before­hand on the LinkedIn group dis­cus­sion, and we’ll add them to the mix as we look at solv­ing the XSLT and XSL FO prob­lems that mat­ter most to people.

and the XSLT and XQuery session with Jeni Tennison is:

Devel­op­ing and Test­ing in XSLT

Unit tests, pro­fil­ing, debug­ging and, increas­ingly, test-driven devel­op­ment are part of the bread and but­ter of work­ing with other pro­gram­ming lan­guages but are not always so with XSLT or XQuery.

In test-driven devel­op­ment, which is a fun­da­mental part of agile approaches to soft­ware devel­op­ment, the developers write tests that describe the desired beha­viour of their applic­a­tion, then write code that meets the tests. This style of devel­op­ment keeps code focused, avoids break­ing exist­ing code and facil­it­ates refactoring.

In this ses­sion, Jeni Ten­nison and Tony Gra­ham will describe both the state of the art in test­ing and debug­ging XSLT and XQuery and how test-driven devel­op­ment applies to XSLT and XQuery devel­op­ment. In par­tic­u­lar, they will focus on the use of the XSpec test­ing framework.

The classic way is using James Clark’s utility.  This involves: (a) working out if you need “Jing” or “Trang” (you need Trang); (b) getting the .jar or the executable; and (c) running it.  Fairly simple, though it’s a pain that although it’s bundled with Ubuntu, etc., it’s not installed by default.  I backup my data between OS re-installs (who doesn’t?) but not the OS-installed programs, so when I need it on a new machine or after a re-install, I, at least, have to go through the Jing/Trang confusion and then fire up the package manager to install it.

I wanted an alternative, but writing a RNG schema loader function for nxml-mode isn’t the work of an afternoon (interesting as it would be to bootstrap it using nxml-mode’s tokenizing of the RNG XML), so I found David Rosenborg’s “RNG to RNC Converter” (http://www.pantor.com/download.html).  The current version works with XSLT 1.0 but not XSLT 2.0 (because it expects the XSLT processor to have a node-set() furnction), but you can add the following to RngToRncProcessorConfig.xsl so the XSLT works with both XSLT 1.0 and XSLT 2.0:

<!-- XSLT 2.0 or later. -->
<xsl:when test="system-property('xsl:version') >= 2">
  <xsl:variable name="body">
    <xsl:for-each select="$schema">
      <xsl:call-template name="make-body"/>
    </xsl:for-each>
  </xsl:variable>
  <xsl:sequence select="$body"/>
</xsl:when>

My only other quibble with the stylesheet is that it doesn’t preserve comments that are in the RNG (more straightforward to do in XSLT 2.0 than XSLT 1.0, I admit).

I don’t yet know if I’ll stick to using RNG to RNC Converter in preference to Trang.  The XSLT is easier to keep with the other stuff that I backup between installs or keep in the Subversion repository for machine configurations, but Trang is easier to use once it is installed and on your path.  The best thing is that now I have the choice of more than one way to do it.

For a more complete list of ways to do it that is maintained by MURATA Makoto, see http://relaxng.org/#conversion.

(defun use-xml-model ()
  "Hook function for `nxml-mode' to use  PI for locating a
RNC schema."
  (interactive)
  (save-excursion
    (goto-char (point-min))
    (if (search-forward "" nil t)
                           (match-beginning 0)))
                 (filename (save-excursion
                             (re-search-forward "href=\"\\([^\"]+\.rnc\\)\""
                                                pi-end t)
                             (match-string 1))))
;;            (message "pi-end: %d; filename: %s
;;                     pi-end filename)
            (if (and filename (file-readable-p filename))
                (rng-set-schema-file filename)))))))

(add-hook 'nxml-mode-hook
          'use-xml-model)

Several people made approving comments about the talk, which was good (some even commented on last year’s talk, which, since this showed they still remembered it, was even better).  The best comment about this year’s though is probably @Innovimax‘s tweet:

Tony is a real 21th century XML Monk! He sponsored the Beer Station at #xmlprague and works on nicely printing bibles. #consideringJoining

(We did discuss his becoming a monk, of any order: I had considered that the asceticism aspect might be a problem, but he considered it to be a non-normative section of the specification.)

The link between the Bible and publishing technology is at least as old as Gutenberg’s press. 400 years after the publication of the King James Bible, we were asked to convert five modern French Bible translations from a widely-used ad hoc TROFF-like markup scheme used to produce printed Bibles to a standard XML vocabulary, and then to EPUB. We opted to use XSLT 2.0 and ant to perform all stages of the conversion process. Along the way we discovered previously unimagined creativity in the original markup, even within a single translation. We cursed the medieval scholars and the modern editors who have colluded to produce several mutually incompatible document hierarchies. We struggled to map various typesetting features to EPUB. E-Reader compatibility made us nostalgic for browser wars of the 90s. The result is osisbyxsl, a soon-to-be open source solution for Bible EPUB origination.

• Zipping an EPUB file so that it retains an uncompressed mimetype file

  <target name="epub.zip"
          description="Package up an EPUB" >
    <delete file="${build.dir}/${epub}.epub" />
    <!-- The 'mimetype' file is supposed to be uncompressed and the
         first thing in the .epub file so the file conforms to the
         (rather long) signature for EPUB files. -->
    <zip destfile="${build.dir}/${epub}.mimetype"
         compress="false"
         encoding="UTF-8">
      <fileset dir="${build.dir}/${epub}" includes="mimetype" />
    </zip>
    <!-- We'd really rather have the rest compressed, thank you. -->
    <zip destfile="${build.dir}/${epub}.zip"
         compress="true"
         encoding="UTF-8"
         level="9">
      <zipfileset dir="${build.dir}/${epub}/META-INF" prefix="META-INF"/>
      <zipfileset dir="${build.dir}/${epub}/OPS" prefix="OPS"/>
    </zip>
    <!-- Putting them together this way is the best way so far found
         for getting only 'mimetype' uncompressed in the .epub. -->
    <zip destfile="${build.dir}/${epub}.epub"
         update="true"
         keepcompression="true"
         encoding="UTF-8">
      <zipfileset src="${build.dir}/${epub}.mimetype" />
      <zipfileset src="${build.dir}/${epub}.zip" />
    </zip>
    <!-- Delete the temporary Zip files. -->
    <delete file="${build.dir}/${epub}.mimetype" />
    <delete file="${build.dir}/${epub}.zip" />
  </target>

• Checking an EPUB with epubcheck

  <macrodef name="epub.check"
            description="Check an epub">
    <attribute name="epub" description="Name of the EPUB" />
    <sequential>
      <java jar="${epubcheck.jar}"
            fork="true">
        <arg value="${build.dir}/@{epub}.epub" />
      </java>
    </sequential>
  </macrodef>
  
  <target name="epub.check.YourEPUB"
          description="Check YourEPUB EPUB">
    <epub.check epub="YourEPUB"/>
  </target>

  (In practice, the epub.check.YourEPUB target is generated by XSLT, but that’s another story.)