Running the test suite:
-----------------------
Do this at a Unix prompt:

 cd to/the/test/directory/
 ./runtests.sh

Zero output means everything passed.
Otherwise you get a diff of everything that failed.
If any output is invalid OSIS, you will also get validation error messages.

Requirements
------------
The test suite requires:
- Bash, or shell
- 'xml2' suite -- this turns XML into a line oriented format that is much
  more convenient for TDD.
- 'xsltproc' for running the XSLT
- For validating the OSIS produced: validator.pl from the Perl-Xerces
  package, (Debian package libxml-xerces-perl) or alternatively 'xmlstarlet' 
  (the former is preferred, see below).

All of these could probably be replaced with alternatives for different
platforms.  If you are on Windows, and want to do significant development of
this project, the first task would be to rewrite the script that runs the
test suite with a more portable version. (Or, upgrade to a proper operating
system ;-) Probably the most profitable avenue would be to rewrite in
Python, which is free, portable and has good enough XML handling for the
job.

Strategy
--------
The essential test strategy performed by runtests.sh is this:
 - for each foo.thml, use the xslt file to generate the OSIS file
 - save the OSIS file as foo.osis
 - Flatten this file using xml2, saving in a temporary file tmp.flat
 - compare tmp.flat with the reference foo.osis.flat
 - Validate the foo.osis file

TDD routine:
------------
1) update one of the test.osis.flat files to reflect the new functionality
   that is to be added
2) Run runtests.sh to ensure that you have added what you think you've added
3) Implement functionality in XSLT
4) Run runtests.sh to check results
5) Repeat 3 and 4 until it works correctly

Sometimes hand editing the .osis.flat files will be tedious, either when a
single change affects lots of tests files, or when the change or addition is
very simple and easy to confirm as correct.  In this case, update_test.sh
can be used to recreate the .osis.flat files *once you are sure that the
XSLT file is producing correct output*.

After each feature is added, tests and the XSLT file should be committed to
source control.


BUGS
----
xmlstarlet does not print correct line numbers for errors on lines greater
than 65535 (it just prints 65535). See:

http://sourceforge.net/tracker/index.php?func=detail&aid=1219072&group_id=66612&atid=515106
http://bugzilla.gnome.org/show_bug.cgi?id=409707

For this reasons, the Xerces validator is preferred (it also has much more
compact and readable error messages).