#103 Testing procedure for changes in the XSLT stylesheets

[Emmanuelle Morlock]

A testing regime for XSLT stylesheet is becoming to be more and more crucial.
All XSLT ones should have one.
Also, it's important to parametrise any XLST change when possible to minimize the impact on others.

Perhaps some discussion of "best practices" memos would be a possible place to start.
Some tools like oXgen editor offer unit testing functionalities (cf. https://www.oxygenxml.com/xml_editor/xslt_unit_testing.html). Cheatsheets for doing that or easy tutorials might be useful.

[Emmanuelle Morlock]

Having to customize the example stylesheet for the Karnak Cachette project, I will describe here how I proceeded, so I can have some feedback and idea for recommended practice.

1. I asked the project’s director to fill in a copy of the EpiDoc cheat sheet that is used in training workshop. For each feature in that document, he described the display he wanted for the edition.

Example :
<unclear>abc</unclear> == to be displayed as « abc (?) » with abc in italics. In html code it would be:<span class=‘italics’>abc</span> (?)

1. I created a new parameter in ‘global-parameters.xml’ with @on :

<parameter>
    <name>leiden-style</name>
    <value on=‘yes’>kcachette</value>
    (…)
</parameter>

1. I went through teiunclear.xsl but didn’t modify anything as I considered that the changes have to be made on the display layer (htm-XXX.xls) and not on the syntactic layer (teiXXX.xsl)

2. I created a htm-teiunclear.xsl that imports teiunclear.xsl

3. In that new file, I wrote that template with choose / when / otherwise that introduce my customization with the leiden-style parameter ‘kcachette’.

<?xml version="1.0" encoding="UTF-8"?>
<!-- $Id: htm-teiunclear.xsl  2016-07-19 01:32:41Z morlock $ -->
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:t="http://www.tei-c.org/ns/1.0" exclude-result-prefixes="t" version="2.0">
    <!-- Imported templates can be found in teiunclear.xsl -->
    <xsl:import href="teiunclear.xsl"/>
    <xsl:template match="t:unclear">
        <xsl:param name="parm-leiden-style" tunnel="yes" required="no"/>
        <xsl:choose>
            <xsl:when test="$parm-leiden-style = ('kcachette')">
                <span class="italic">
                    <xsl:apply-imports/>
                </span>
                <xsl:text> (?) </xsl:text>
            </xsl:when>
            <xsl:otherwise>
                <xsl:apply-imports/>
            </xsl:otherwise>
        </xsl:choose>
    </xsl:template>
</xsl:stylesheet>

1. finally I modified the includes in the start-edition.xsl: I commented the inclusion of the teiunclear.xsl to deactivate it and include my new htm-teiunclear.xsl

What do you think? Is that how you would do it too? Do you see possible improvements?

[BODARD Gabriel]

@Emmanuelle: some work on this testing suite has already been done as part of the EFES work, see ticket https://github.com/EpiDoc/EFES/issues/19 . Do you think this is a (partial) solution to this ticket? If so, it would be good to discuss and document it here for release 9.0, rather than simply punting the ticket for the future.

[Emmanuelle Morlock]

Yes, it seems a good start.

As far as I understand it, the test operates on the full html output for the following edition structure mentionned in the test as a string straight string comparison.

Currenttly the structures given in the script are : ('default', 'dol', 'edak', 'inslib', 'iospe', 'sigidoc', 'spes').
If I get it right, the result will also depend on the leiden-style and other parameters that are chosen in the xml parameters file.

Should the test be enhanced with all the possible parameters implemented, especially for $leiden-style. Or just the default one (panciera), letting the users run the tests for other the styles they are modifying? (see list of parameters here: https://sourceforge.net/p/epidoc/wiki/Parameters/

[BODARD Gabriel]

I think anyone who is actively using this test suite should add their Leiden-style (app-style, end-struct etc.) parameters to the test document, but any use of large numbers of XML files should probably only be added off-line for their own testing.

In principle, when we make changes that are potentially risky, we ask the rest of EDAG and Markup communities to test their local files, using this suite or their own prefered method/eyeballs, with a particular view to (e.g.) square brackets regression.

I'd be interested in any feedback on the suitability/functionality/efficiency of the current suite, which was created in haste for the EFES project. We'd be happy to see it improved/replaced if anyone thinks they can do better.

[Scott Vanderbilt]

Bumped -> Future.

[BODARD Gabriel]

We're not entirely happy with the extensibility and scaling of the existing testing suite, which could potentially flag hundreds of benign changes with any given commit. We would need a volunteer to design and build a replacement.

The alternative (lacking a volunteer for the above) is to write a robust "good practice" making sure that people test on an example EpiDoc file with shitloads of code instances in it before and after any change they commit.

[BODARD Gabriel]

This is not a current EDAG priority. Deferring the ticket for now.