This document is the tutorial for how to use XMLGUS prepared by Yi Jia, jiayi@ittc.ku.edu.
There are several steps to learn our software.

1. The First Stage: familiar with Simple GUS XML

The XMLGUS is developed based on GUS(The Genomics Unified Schema) system. 
So users who want to use this toolkit should firstly be familiar with Simple
GUS XML.This XML format is dependent on GUS Schema,which is organized into XML
formated descriptive file named gus_schema.xml. This description file is
provided in GUS package. 

Here is the sample format of Simple GUS XML.

--------------------------------------

<?xml version="1.0" ?> 
<gus> 
  <TABLE_NAME>
    <ELEMENT_1>...</ELEMENT_1>
	.
	.
	.
    <ELEMENT_n>...</ELEMENT_n>	
  </TABLE_NAME>
	.
	.
	.
  <TABLE_NAME>
       ...
  </TABLE_NAME>
	
</gus> 

--------------------------------------
All the TABLE_NAME and ELEMENT are coming from GUS Schema. So we suggest that
the best way to learn GUS database Schema is to acquire information from GUS
Schema Browser(available in www.gusdb.org).


2. The Second Stage: example practice 

There are short examples for users to practise the processing procedure of
XMLGUS. They are included in the link:

http://flora.ittc.ku.edu/XMLGUS.0/examples/Short_Examples/

Users also could create their own Simple GUS XML examples to try. All the
software source code are put in the link:

http://flora.ittc.ku.edu/XMLGUS.0/source/

There are detailed README files in each sample example and software functional
components. 

3. The Third Stage: understand new features in XMLGUS2.0

Compared with its previous version, XMLGUS2.0 added several new features. They are
  
(1) Key constraint resolving
The foreign key relations in Simple GUS XML are resolved automatically in
XMLGUS2.0. So users need not to know the complicated key constraints in GUS Schema. 
Here is one example showing the format in SIMPLE GUS XML, which user can use to represent the key
relations.

 <sequence_type_id constraint="0">
  <name>DNA</name> 
 </sequence_type_id>  
 
The sequence_type_id needs to be resolved from another table dots_sequencetype. But such kind of
resolving work will be dealt with by XMLGUS. All the information is acquired from GUS Schema description.
So the Simple GUS XML could keep consistent with GUS Schema.    

 
(2) Addtitional attribute "contraint = <integer>"
This attribute works as an indicator to improve the performance of XMLGUS processor. 
This is to retain one important feature in XMLGUS version 1 where invariant objects that 
are initialized once can be reused. Users who are interested in this performance issue
can refer to the paper in the link http://flora.ittc.ku.edu/xmlgus2.0/documents/ for
details. 

The exact use of this attribute is like this:

 The 'constraint='0'' means the common way of inserting key constraint
 table without any optimization.

 When users prefer optimization, only the foreign key in the first transaction contains 
 the resolving contents. The attribute 'constraint="1" '. And the following transactions 
 referring the same key constraint only give the attribute 'constraint="2" '.

optimization directory in supplement show how this attribute works.

----------------------------------
ROAD MAP FOR XMLGUS V2.0 DIRECOTY |
----------------------------------

/help.txt 		---------------    	user tutorial

/source 		---------------		XMLGUS.pm processor, Grammar generator with sample 
						grammar, and components of key straints retriving.

/documents		---------------		all the related documental materials

/examples 		---------------		applications from toy tests to production 

/systemComponents	---------------		required components for XMLGUS.pm

/supplement		---------------		optimization and specilized processing samples