Problem XML Files

problem.xml
===========


Abstract
--------

The problem.xml project's goal is the development of an XML format for the
representation of chess problem and of a set of tools that work with that
format and encourage its usage.


This directory contains
-----------------------
- the current version of the DTD (problem.dtd)
- a brief documentation of the elements declared in the DTD (problem.dtd.doc)
- several little, very imperfect tools that work with files in the current
  version of the XML format
- a Makefile that declares some rules that allow you to run the test suites
  of the different tools and to clean up after yourself once you have run
  them
- a gzipped file (pdbsamples.xml.gz) containing 1000 problems from the PDB
  in a valid XML document


Environment and other software needed
-------------------------------------
Sloppily speaking, you need a Unix/Linux like environment to use these tools.
I started writing them on Cygwin (cf. http://cygwin.com/); later I switched
to Linux and ported them. I haven't tried the checked-in versions on Cygwin,
but it is my intention that they can be used on that platform as well.

Apart from that, the tools are known to run with the following programs:
- bash 2.05b (http://www.gnu.org/directory/bash.html)
- Gnu make 3.79.1 (http://www.gnu.org/directory/devel/build/make.html)
- diffutils 2.8.1 (http://www.gnu.org/directory/diffutils.html)
- Tcl 8.3.5 (http://www.tcl.tk/)
- tcllib 1.3 (http://tcllib.sourceforge.net/)
- TclXML 2.5 (http://tclxml.sourceforge.net/)
- rxp 1.2 (XML validator, http://www.cogsci.ed.ac.uk/~richard/rxp.html)

[Currently, cygwin comes with bash, make, diffutils and Tcl (probably in
versions different from what is given above). The installation of packages
of the other programs should be like under Linux (cf. the respective
documentation).]


Running a test suite
--------------------
1. cd into a directory containing a Makefile
2. type "make" (without the quotes) and hit Enter (or carriage return)

This will cause the tested tool(s) to produce output that may be somewhat
confusing (some of the tools will produce error messages in some test cases -
this is their intended behavior!).

If the test suite(s) were not successfully completed, make will generate
some output that is supposed to indicate what went wrong.

The checked in releases of the tools and their test suites are intended to
cause the test suites to complete successfully at all times. So, if
something went wrong when you first try to run the test suite(s), it is
probably because some of the software listed above isn't installed or
accessible to the test suite(s).


Running a tool
--------------

All the tools work as so-called "filters", i.e. they take their input from
"standard input" and write their output to "standard output". To use a tool
to transform a file into some other file, in bash, issue a command of the
form

/path/to/the/tool < /path/to/the/input/file > /path/to/the/output/file

e.g.

/home/maeder/problem.xml/xmlcheck.tcl < test.xml > test.xml-checked

Most of the tools expect (a copy of) problem.dtd to be in the current working
directory.


Bern, May 2003
Thomas Maeder