-*- Mode: Text -*-
    File: $CVSROOT/IDEA-DEV/XIDDL/README
    Info: $CVSROOT/IDEA-DEV/COPYRIGHT
     CVS: $Id: README,v 1.6 2005/12/30 22:48:47 rijsman Exp $

This ReadMe is intended to get you started on having some idea of what
the xml/xsd/xsl and shell scripts in this directory are, and what you
can do with them.

The important xml support files are the ".xsd" and ".xsl" files, plus
the two shell scripts:

XML support files: 

  xiddl2ddl.xsl
  xiddl2modelinfo.xsl
  xiddl2relayinfo.xsl
  xiddl-tests.xsl
  euruopa-tests.xsl
  xiddl.xsd
  xiddl-initial-state.xsd
  xiddl2doc.xsl

Shell scripts:

  build-xiddl
  run-xiddl2ddl

XML Support

  xiddl2ddl.xsl is intended to transform a legal XIDDL file into a
  legal DDL.

  xiddl2doc.xsl generates doxygen documentation from a legal XIDDL
  file.

  xiddl-tests.xsl is intended to perform a (TBD) series of "semantic
  checks" on a legal XIDDL file and produce a "report" which can
  either be read or used to feedback provide to the modeler on where
  their model might need attention.

  xiddl.xsd is schema for XIDDL.  It can be used with an XML editor
  which supports XML schemata to create and validate XIDDL models.

  xiddl-initial-state.xsd is the schema for XIDDL initial states.

  To use these files, run them, with a legal XIDDL file, through a
  compliant XSLT processor (e.g., xsltproc in linux).

  In our standard (Idea) Linux environment, this can be done from this
  directory thus:

  linux% xsltproc -o <output-filename> xiddl2ddl.xsl <input-filename>

  The other transformations can be run in similar ways using the
  appropriate XSL script and input/output file names.

Shell Scripts

  The scripts can be run from an application model directory (e.g.,
  LitaIdea/Models/Mission) which has a subdirectory which is
  symbolically linked to the this xml directory.  Once such a link is
  set up, one can run the transformation which use the above XML
  support files directly.  

  The build-xiddl script takes a "master" xiddl file in, resolves all
  of the includes therein, places the "combined" output in the
  specified file, and, if any errors are encountered along the way,
  puts them in the specified error output file.  This allows one to
  structure one's models in a modular way, share timelines, objects,
  procedures, and so on.  It can be run thus:

  linux% xml/build-xiddl <mater-xiddl-file> <output-xiddl> <error-file>

  The run-xiddl2ddl script does four things.  First it runs the
  "semantic tests" (xiddl-tests.xsl).  If any errors are found, the
  script reports the errors and exits.  If no error are found, it then
  transforms the xiddl file into ddl, a relay info file, and a model
  info file.

  linux% xml/run-xiddl2ddl <xiddl-file-name>

  These scripts are both usable by mere command-line mortals, and by
  application makefiles or scripts.
