Documentation

Introduction

Composition de l'interface

Voici l'interface de exxEditor en utilisation annotée de manière à lister les différents composants de l'interface :

On peut trouver :

La barre d'outils contient des boutons permettant d'effectuer différentes actions (de gauche à droite):

Écrire un XML Schema

XMLSchema est une recommendation du W3C. Si vous connaissez déjà XMLSchema, vous pouvez passer à la section suivante.

Un XMLSchema décrit quel type de balises il peut y avoir dans un fichier XML. On dit qu'un fichier XML est valide suivant un schema, lorsqu'il respecte les contraintes imposées par ce schema.

Par exemple:
<?xml version="1.0"?>
<parameters>
  <simulationName>Simu 1</simulationName>
  <cycle>5</cycle>
  <environmentFactor>8.235</environmentFactor>
  <elements>
	<branch type="0" value="3" />
	<branch type="1" value="5" />
	<branch type="6" value="29" />
  </elements>
</parameters>

Pourrait avoir pour fichier XSD :

<?xml version="1.0"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified">

<xs:element name="parameters">      <!-- XML can contain an element named "parameters" -->
  <xs:complexType>                  <!-- parameters can contain other elements -->
	<xs:sequence>                   <!-- It contain an ordered list of elements -->
	  <xs:element name="simulationName" type="xs:string"/>
	  <xs:element name="cycle" type="xs:int"/>
	  <xs:element name="environmentFactor" type="xs:double"/>
	  <xs:element ref="elements" /> <!-- I decided to declare this element later -->
	</xs:sequence>                  <!-- I could have done it here. -->
  </xs:complexType>
</xs:element>
 
<xs:element name="elements">       <!-- elements is a referenced node -->
  <xs:complexType>
	<xs:sequence>         <!-- minOccurs and maxOccurs specify the number of time a node can append -->
	  <xs:element name="branch" minOccurs="2" maxOccurs="unbounded">
		<xs:simpleType>   <!-- A simple type cannot contain other elements -->
		  <xs:attribute name="type" type="xs:int" /> <!-- But it can contain attributes -->
		  <xs:attribute name="value" type="xs:int" />
		</xs:simpleType>
	  </xs:element>
   <xs:sequence>
 </xs:complexType>
</xs:element>
 
</xs:schema>

Il existe une grande quantité de documentation librement accessible sur le web. Voici quelques exemples : http://en.wikipedia.org/wiki/XML_Schema_(W3C) ; http://www.w3schools.com/Schema/default.asp ; http://www.w3.org/XML/Schema.

Compatibilite avec XML Schema du W3C

Malheureusement, exxEditor est loin d'être capable d'interpréter l'ensemble de la norme.

Balises non suportées

Les balises non suportées et leurs descendants sont ignorés par le logiciel.

Balises partiellement suportées

La structure générale du fichier XSD est supportée par le logiciel. Les balises "element", "attribute", "simpleType", "complexType", "sequence", et "choice" sont supportées. Cependant il y a certaines limitations :

Les "restriction" et les "list" sont supportées, mais peu testées, n'hésitez pas à soumettre des rapports de bug.

Type de données

Les types numériques (int, double etc...) sont supportés dans l'application. Cependant, les limites maximum et minimum, ainsi que la précision définie dans la norme W3C ne sont pas toujours respectées.

Tous les types non supportés sont interprétés comme des chaînes de caractères quelconques.

Deux types non standards peuvent être utilisés : "file" et "color". Pour indiquer qu'un node est de type "file" ou "color" il faut utiliser le système d'annotation du XSD: <xs:annotation><xs:appInfo><restriction type="file" /></xs:annotation></xs:appInfo>

Structure générale

Il est impératif que les fichiers XSD décrivent des fichiers XML dont une seule balise racine contienne toutes les autres.

Aide

En utilisant la balise "documentation" vous pouvez ajouter des messages d'aide visibles dans exxEditor. La première ligne est utilisée comme info bulle, lors du survole d'un paramètre. L'ensemble du contenu de la balise "documentation" est visible dans l'outil d'aide intégré. Pour accéder à cet outil, il faut faire un clic-droit sur un paramètre dont la balise "documentation" n'est pas vide, et sélectionner "help". Le message d'aide peut être formaté en utilisant du html simplifié.

Onglets

Par defaut exxEditor n'affiche qu'un seul onglet, avec tout le fichier XML. On peut activer la gestion des onglets fine, en utilisant le système d'annotation de XML Schema.

Il faut placer : <xs:annotation><xs:appInfo><container recursive="-1" /></xs:annotation></xs:appInfo> sous une balise "element" contenant une séquence, un choix ou des attributs. Cela permet de définir un onglet contenant tout un sous-arbre XML. Le nom de l'onglet sera le nom du node courant. "recursive=-1" indique qu'on veut sélectionner l'ensemble du sous-arbre. Pour ne sélectionner que les éléments simple (simpleType), on aurait mis la valeur 1. Récursive indique ainsi la profondeur du sous-arbre que l'on veux selectionner.

Noms

On peut vouloir faire apparaître des noms plus humainement compréhensible que les noms des éléments présent dans le fichier XML. Pour cela on peut utiliser le système d'annotation du XML Schema, et ajouter à un élément, ou un attribut :

<xs:annotation><xs:appInfo><humanName>Ceci est un nom compréhensible</humanName></xs:annotation></xs:appInfo>

Développeur

N'hésitez pas à contribuer ou demander des informations supplémentaires: contribuer ; contacts.

Pour une documentation technique aller voir la doc doxygen: Reference.

ExxEditor — Licence : AGPL v3 ou supérieur, created from http://perroquet.b219.org