/**
\mainpage XSLT Chain Translator Documentation

\author Andrew J.A. Vick 
\version X.Y
\date    2006-2007

\par Overview
XsltChain provides classes for:
    - Handling a graph of version number conversions, where the nodes (Strings) represent
      version identifiers and the edges (Strings) represent the conversions
    - Loading a series (a \e chain) of XSLT files which will be applied in series to an
      input XML file.
    - A top level application that can open ALMA OT files (\e zip files), and translate 
      the contents to a given version using a table of translations and the relevant XSLT
      files.
      
See the \ref UG1 "User Guide" for an overview.
*/

/**

\page UG1 User Guide


XsltChain is a system designed to provide chained XSLT transltors to provide version
update facilities for XML documents. 

\section classes Classes
\image html xsltchain_001.jpg
\image latex xsltchain_001.eps "XsltChain top level hierachy" width=10cm

The XsltChain package contains the following top level classes

\par ConvertZip

ConvertZip (uk.ac.roe.ukatc.xsltchain.ConvertZip) is the application main class, it provides a command line interface for translating Alma OT (AOT) files
using a table of translators between versions. \a ConvertZip can use URLs to get hold of data (translation 
tables and XSLT files) from a remote source. ConvertZip also contains the functionality necessary to 
include the functionality inside another application via the Converter method. See \ref application for 
instructions on installing and running \a ConvertZip.

\par VersionTable

VersionTable (uk.ac.roe.ukatc.xsltchain.VersionTable) is an interface to \ref UGraph that provides methods for handling a table of versions. The functionality 
provided by \a VersionTable is replicated, since \a XsltChain actually contains the sme code, but VersionTable provides 
the functionality in a "bare" form suitable for other applications.

\par XsltChain
XsltChain (uk.ac.roe.ukatc.xsltchain.XsltChain) provides the main API for the package, and provides the following functionality;
\li Loading and processing version tables (using \a UGraph)
\li Loading and chaining XSLT files
\li Returning a chained translator to the top level

\par ChainTranslator
ChainTranslator (uk.ac.roe.ukatc.xsltchain.ChainTranslator) objects are returned from XsltChain to represent a series of chained XSLT translations, and can 
be used to apply mutliple translations to one (or a number of) XML documents.


\par AlmaPckg 
\a AlmaPckg is a utility class which allows access to Alma OT files (.aot files, which are zipped 
collections of XML files). It does not depend on any Alma software.

\par ApplicationOptions
ApplicationOptions (uk.ac.roe.ukatc.xsltchain.ApplicationOptions) is a utility class which provides an OO interface to getopt like functionality.

\par UGraph
UGraph (uk.ac.roe.ukatc.xsltchain.UGraph) is an unweighted directed graph algorythm, which provides the functionality for handling
list of versions and translations to \a XsltChain and \a VersionTable. The class provides for holding 
version strings as nodes in the graph, and translations on the edges, and can return an "optimum" list of 
translations between two versions.
(Optimum here means minimum number of translations, not minimum complexity).


\section application The ConvertZip application

The application takes an AOT file, a translation table and a version identifier as input. The version identifiers
are handled as strings thorughout - there is no assumed order at all. Using the translation table it attempts to
convert the contents of the AOT file to the given version, it does this by;

   -# Opening the AOT file as a ZIP file
   -# For each XML file contained in the XML file;
      -# Identifies the Schema of the XML file
      -# If the Schema is a known AOT Schema (one of 
      
      
\subsection The translation table
The translation table specifies translators between version identifiers on a per-schema basis. The file
format is a simple white-space separated table of values, one translation per row. Blank rows, or
rows commented with an initial # are ignored. Each line specifying a translator has the format
\code
XML-Schema-Name   Starting-Version-Identifer  Final-Version-Identifer   XSLT-Translation
\endcode
and specifies that XML files with a Schema of XML-Schema-Name and a current version of Starting-Version-Identifer
can be translated to the version Final-Version-Identifer using the translator XSLT-Translation.
See \ref baseurl "Base URL usage" for how the BASE_URL can be used to find a local or remote files.

Translation table example.
\code
# Convert 1.60.6.3 to 1.62
SchedBlock 1.60.6.3 1.62 SchedBlock16063-162.xslt
ObsProject 1.60.6.3 1.62 ObsProject16063-162.xslt
ObsProposal 1.60.6.3 1.62 ObsProposal16063-162.xslt
ObsReview 1.60.6.3 1.62 ObsReview16063-162.xslt
# Convert 1.59 to 1.62
SchedBlock 1.59 1.62 SchedBlock159-162.xslt
ObsProject 1.59 1.62 ObsProject159-162.xslt
ObsProposal 1.59 1.62 ObsProposal159-162.xslt
ObsReview 1.59 1.62 ObsReview159-162.xslt
\endcode      

This example specifies two groups of translations, those for version 1.60.6.3 to version 1.62 and those
for version 1.59 to 1.62. Translations exist for the Schemas \e SchedBlock, \e ObsProject, \e ObsProposal and
\e ObsReview.
      

\subsection baseurl BASE_URL usage
You should have (as part of the SVN import) a top level directory called ConvertZip. In there there is a version table file and some XSLT stylesheets. To make it easy to use, you can edit the BASE_URL field in .convertrc (which should also have been created, in the root dir) to point at the ConvertZip directory. If you can figure out what that means you'll be able to do this; 
ConvertZip --input=/path/to/my.zip --output=whatever --table=versiontable.txt --version=1.58

versiontable.txt will have the value of BASE_URL added to it (as will all the XSLT references inside versiontable.txt).
*/