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.
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.
Example :
<unclear>abc</unclear>
== to be displayed as « abc (?) » with abc in italics. In html code it would be:<span class=‘italics’>abc</span> (?)
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)
I created a htm-teiunclear.xsl that imports teiunclear.xsl
In that new file, I wrote that template with choose / when / otherwise that introduce my customization with the leiden-style parameter ‘kcachette’.
What do you think? Is that how you would do it too? Do you see possible improvements?
@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.
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/
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.
Bumped -> Future.
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.
This is not a current EDAG priority. Deferring the ticket for now.