=========================================
Fichiers d'echange de l'application (XML)
=========================================

:Authors: Saint-Genest Gwenael (Hooligan0)
:Version: 1.0-p1 22/01/2004

---------------
1. Introduction
---------------

Dans de nombreux cas, l'application doit echanger des donnees avec d'autres
logiciels. Il s'agira par exemple de pouvoir importer un nouveau schema de
la base de donnees, de pouvoir exporter des listes de mails vers des carnets
d'adresse, ou tout simplement des operations de sauvegarde et de
restauration. Pour des raisons de perenite et d'universalite, le format de 
fichier et de donnees qui a ete retenu pour realiser ces echanges est le XML. 
Il est simple a partir de ce format et de feuilles de styles d'obtenir tous 
les autres formats qui pourraient etre necessaires ou utiles.

Ce document precise ce que peut ou non contenir les fichiers generes ou
importes ainsi que la facon de les exploiter. 

---------------------------------------
2. Contenu et organisation des fichiers
---------------------------------------

2.1 Structure minimale
^^^^^^^^^^^^^^^^^^^^^^

Au moment de l'ecriture de ce document, la version de XML utilisee est la 
1.0 [1]_ Le codage utilise est UTF-8. Un document XML correctement forme ne
doit avoir qu'un seul element racine [2]_. Le nom utilise pour la racine est
GASELL.

Il en ressort le squelette minimum de document suivant : ::

	<?xml version="1.0"encoding="UTF-8"?>
	<gasell>
	(...)
	</gasell>

.. [1] http://www.w3.org/TR/REC-xml
.. [2] http://www.w3.org/TR/REC-xml#sec-well-formed

2.2 Sections de premier niveau
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Les tags present immediatement apres le <gasell> (ci apres nommes tags de
niveau 1) representent les donnees des grandes parties de l'application.
Deux parties sont necessaire au fonctionnement interne (database et config),
les autres sont utilisees dans les operations de sauvegarde/restauration ou
d'import/export vers d'autres applications.

- database    : Structure de toute ou partie de la base de donnees
- config      : La configuration de l'application
- exercices   : Tout ce qui tourne autour d'un exercice (entre autres, les
  types d'adhesion)

- commissions : Les commissions et le(s) bureaux
- personnes   : Toutes les infos sur les personnes (contacts, adhesions,
  competences, ...) (objets ?)

- interventions [3]_ : Ce qui touche aux interventions (TODO: a definir)
- comptabilite [3]_  : La nebuleuse gestion de la compta

.. [3] Non disponible actuellement.

----------------------------------
3. Structure de la base de données
----------------------------------

L'un des premiers besoin de l'application est de pouvoir représenter sa base
de donnees. Elle est constituee d'un enssemble de tables qui ont des
proprietes ainsi que des contraintes et des liens entre elles. Le tag de
niveau 1 *database* permet de representer cette structure a un niveau tres
proche de la base de donnees.

* Un tag database_ permet de representer la structure de la base de données.
* A l'intérieur de celui-ci, un ou plusieurs elements *table* representent
  chacun une table (nommée par un attribut *name*).
* Chaque *table*, contient des elements *column* (représentant les colonnes).

Voici un exemple de structure : ::

	<?xml version="1.0"encoding="UTF-8"?>
	<gasell>
	  <database>
            <table name="table1">
              <column name="t1_col1" type="int" constraint="primary"/>
              <column name="t1_col2" type="varchar"/>
            </table>
            <table name="table2">
              <column name="t1_col1" type="int" constraint="references" references="table1 on update cascade"/>
              <column name="t2_col2" type="varchar"/>
            </table>
          </database>
	</gasell>

----------------
4. Configuration
----------------

...

---------------------------
Reference des tags utilises
---------------------------

5.1 config
^^^^^^^^^^

plop

5.2 column
^^^^^^^^^^
Cet element contenu dans un element "table" definit le format d'une colone.

Il possede deux parametres obligatoires : "name" qui represente le nom de la
colone et "type" qui represente le format des données qu'elle contient. Il
possede egalement deux paramètres optionnels : "constraint" qui precise les
contraintes de la colone ('primary' pour une clef primaire ou 'references' 
pour une clef etrangere) et "references" qui permet dans le cas d'une clef
etrangere de preciser vers ou se fait le lien (ex: 'tab1 on update cascade'
pour preciser que le lien se fait vers la table tab1)

5.3 commissions
^^^^^^^^^^^^^^^
plop

5.4 comptabilite
^^^^^^^^^^^^^^^^

plop

.. _database:

5.5 database
^^^^^^^^^^^^

Tag de niveau 1 qui contient des informations sur la structure de la base de
donnes. Il n'y a aucun parametre obligatoire ni aucun parametre optionnel a
ce tag.

Il peut contenir aucun ou plusieurs tags "table".

5.6 exercices
^^^^^^^^^^^^^

plop

5.7 gasell
^^^^^^^^^^
Ce tag est la racine de tout le document. Pour respecter le standard XML, il
doit etre unique.

Cet element prend deux attributs optionnels : version, qui precise le numero
de version de l'application qui l'a genere; dbversion, qui precise le numero
de version de la base de donnees.

5.8 interventions
^^^^^^^^^^^^^^^^^

plop

5.9 personnes
^^^^^^^^^^^^^

plop

5.10 table
^^^^^^^^^^
Ce tag est contenu dans un element database (cf 5.5). Il permet de definir
le format et les relations d'une table de la base. Il y a un parametre
obligatoire "name" qui definit le nom de la table dans la base.

Cet element peut contenir un ou plusieurs tags "column".