# Jaxe, votre éditeur XML

Auteur: Damien Guillaume

- Documentation pour les utilisateurs finaux
  - Principe de XML
  - La définition du langage
  - Lancement de Jaxe
  - Utilisation de Jaxe
  - Syntaxe des équations dans Jaxe
  - Préférences
- Editeur de Fichiers de Config de Jaxe
  - Créer/Editer un fichier de config
  - Choix de langues
  - Choix du schéma
  - Choix des racines
  - Menu principal
  - Autre configuration
  - Enregistrement des fichiers
  - Menus
  - Affichage des noeuds
  - Types d'affichage
  - Exports
  - Textes
  - Sauvegarde du fichier de Config
- Fichiers de configuration de Jaxe
  - Introduction
  - Définition du langage XML
  - Enregistrement des fichiers
  - Menus
  - Affichage des noeuds
  - Types d'affichage
  - Exports
  - Chaînes de caractères
  - Plugins
- Documentation pour les développeurs
  - Introduction
  - Utilisation de Jaxe au sein d'une autre application
  - Création de nouveaux éléments Jaxe
  - Ajout d'une fonction
- Le langage XPAGES
  - Introduction
  - La structure des documents
  - Informations
  - Eléments de bloc
  - Eléments mélangés au texte
  - Exercices
  - Référence du langage

# Jaxe, votre éditeur XML

In English

Jaxe sur SourceForge

## Fonctionnalités

Vous cherchez un éditeur XML adaptable à votre langage XML ? Jaxe est la solution. La dernière version intègre les fonctionnalités suivantes:

- configurable avec un schéma XML et un fichier de configuration de l'interface graphique
- adapté aux documents XML narratifs structurés
- validation à l'insertion des éléments
- multi-plateforme (Java 1.5+)
- logiciel libre et gratuit
- ajout possible de modules Java pour des interfaces graphiques personnalisées
- exports vers HTML, XML et PDF avec des feuilles de style XSLT ou XSL-FO
- panneaux affichant le document sous forme d'arbre, listant les éléments autorisés à l'emplacement du curseur, et permettant d'éditer les attributs de l'élément courant
- menu contextuel
- annulations multiples
- affichage du code source
- validation complète des documents
- exemples de fichiers de configuration pour les schémas XML, XHTML strict, Docbook, DITA, XPAGES, et un schéma pour des présentations
- utilisable en français, anglais, allemand, russe, portugais brésilien ou espagnol (prenant la langue du système par défaut)
- correcteur orthographique, avec des dictionnaires disponibles en français, anglais et allemand
- éditeur d'équations
- aide en ligne basée sur le schéma XML
- recherche XPath

Ce que Jaxe ne fait pas (voilà une rubrique que l'on ne trouve pas sur des sites commerciaux, mais qui pourrait vous faire gagner du temps!) :

- Jaxe ne permet pas d'éditer des fichiers XML sans fichier de configuration pour le langage. Il est peut-être préférable d'utiliser un éditeur de texte adapté à XML comme Mex pour éditer des fichiers XML quelconques.
- Jaxe n'est pas "WYSIWYG" (What You See Is What You Get), il est "WYSIWYM" (What You See Is What You Mean). Comme avec tout bon éditeur XML, l'affichage est une opération indépendante de l'entrée des données.
- Jaxe n'est pas une applet Java: on ne peut pas l'utiliser dans un navigateur. On peut cependant intégrer la zone d'édition XML de Jaxe à l'intérieur d'une applet. Cette solution est utilisée par WebJaxe, un CMS écrit en PHP et basé sur l'édition de documents XML avec Jaxe.
- Jaxe ne gère pas toutes les fonctionnalités des schémas XML. Pour savoir exactement ce que Jaxe gère, regarder le fichier config/SimplerSchema.xsd: c'est un sous-ensemble du schéma des schémas correspondant à ce que Jaxe comprend. Dans la dernière version, presque toutes les fonctionnalités sont cependant gérées.
- Jaxe ne gère pas bien les très grands documents XML. En effet, il utilise des composants Java Swing en mémoire pour représenter les éléments XML, de manière à ce que l'on puisse facilement créer de nouvelles représentations d'éléments XML. Le problème, c'est que que ces composants prennent beaucoup d'espace mémoire.

## Configuration requise

Un système (Mac, UNIX, Windows ou autre) avec une version de récente de Java (au moins 1.5). Pour tester la version de java de votre système, vous pouvez taper "`java -version`" sous la ligne de commande.

## Installation

- Télécharger Jaxe (existe en version Mac, Windows, et UNIX/Linux)
- Décompacter le fichier. Il suffit en général de double-cliquer dessus sur MacOS X, ou de faire un clic droit et de choisir "décompacter ici" sur Windows, mais il peut être nécessaire d'utiliser par exemple la commande "`tar xvzf jaxe.tar.gz`" sur UNIX, ou encore 7-Zip sur Windows.
- Placer le dossier résultant sur le disque dur, par exemple dans `/Applications` sous MacOS X, ou `Program Files` sous Windows.
- Dans le répertoire de Jaxe, taper "`./jaxe.sh`" sous UNIX, ou double-cliquer sur l'application sous MacOS X ou Windows.

## Comment utiliser Jaxe

Jaxe peut s'utiliser en tant qu'administrateur, pour définir un fichier de configuration pour un langage XML donné, ou comme utilisateur final avec les fichiers de configuration de l'administrateur. Les développeurs peuvent aussi ajouter des composants Swing pour les éléments, et utiliser Jaxe à l'intérieur d'autres applications.

- Guide utilisateur
- Administrateurs: Editeur de configuration, Syntaxe des fichiers de configuration. Petit exemple : Comment créer un langage XML et son éditeur en 5 minutes
- Guide développeur

## Copies d'écran

Jaxe

Dans cette copie d'écran, on peut voir un dialogue d'édition d'attributs, le panneau d'insertion des éléments, et la zone de texte comportant plusieurs affichages possibles pour les éléments.

Une application de Bodo Tasche utilisant Jaxe

Le deuxième exemple montre Jaxe intégré à l'intérieur d'une autre application Java, avec des affichages personnalisés pour les éléments.

## Forums de discussion

Aide - Discussion ouverte

## Licence

GPL

## Auteurs

- Damien Guillaume
- Soufiane Ayadi
- Bodo Tasche
- Oliver Kykal
- Cyril Dedieu
- Léa Guillon
- Bertrand Delacretaz
- Sven Kitschke

## Testeur officiel

- Gilles Bessou

## Bibliothèques utilisées

- Xerces (jusqu'à Jaxe 2.3, et aussi à partir de Jaxe 3.4)
- Xalan (jusqu'à Jaxe 2.3, et aussi à partir de Jaxe 3.0)
- Jazzy
- Oro ou Regexp (jusqu'à Jaxe 2.3)
- PngEncoder (jusqu'à Jaxe 2.4)
- JEuclid
- JSmooth ou launch4j
- FOP (à partir de Jaxe 3.0)
- Jing (à partir de Jaxe 3.2)
- Saxon (à partir de Jaxe 3.4)
- XSLTC (à partir de Jaxe 3.4)

## Nouvelles versions

La fonctionnalité permettant de se tenir informé des nouvelles versions a disparu de sourceforge. Il n'est plus possible d'être mis au courant par un mail d'une nouvelle version de Jaxe. On peut à la place utiliser un fil RSS.

## Contributions

Jaxe progresse avec les apports de chacun. Si vous avez amélioré Jaxe (par exemple en créant un fichier de propriétés pour une langue donnée, ou avec un plugin pour éditer certains types de données), n'hésitez pas à rendre disponible vos fichiers.

Ce site a été créé avec Jaxe et XPAGES.

# Documentation pour les utilisateurs finaux

Auteur: Damien Guillaume

# Principe de XML

XML est une syntaxe, mais c'est surtout une philosophie dans l'écriture de documents qui consiste à expliciter le sens des informations par opposition à la forme. On écrira par exemple:

    <TITRE>XML</TITRE>

au lieu de:

    <GRAS><ITALIQUE><CENTRE>XML</CENTRE></ITALIQUE></GRAS>

Ce principe permet à la fois des traitements automatiques (par exemple l'extraction de tous les titres pour construire une table des matières), et la possibilité de définir plusieurs affichages pour un même contenu (par exemple un affichage sur le web et un autre sur papier).

Comme le contenu est bien séparé de la forme, les éditeurs XML comme Jaxe ne sont pas WYSIWYG ("What you see is what you get"). Pour ceux habitués aux traitements de texte comme Word, il faut faire attention à ne pas utiliser de styles comme gras ou italique quand il est possible d'indiquer le sens du texte à la place. Il ne faut pas non plus se fier à l'aperçu, étant donné qu'il peut y avoir plusieurs affichages possibles. Attention donc à utiliser des éléments correspondant à des paragraphes ou des sections plutôt que des éléments "saut de ligne", étant donné que l'espacement entre les paragraphes dépend de l'affichage et peut être un peu plus ou un peu moins qu'une ligne.

# La définition du langage

Un langage XML est défini de façon formelle, de manière à permettre la vérification automatique de la syntaxe. Cette description formelle comprend les noms des éléments du langage, les imbrications possibles entre les éléments, l'ordre autorisé des éléments, et leurs attributs (les attributs étant optionnels ou obligatoires).

Jaxe facilite la création des documents XML en utilisant les règles du langage pour proposer des éléments à insérer là où c'est possible. Cela permet de créer des documents valides (c'est à dire se conformant aux règles du langage) beaucoup plus facilement qu'avec un simple éditeur de texte. Cette introduction est générale pour tous les langages qui peuvent être utilisés, mais chaque utilisateur final doit apprendre un ou plusieurs langages XML particuliers, qui ne sont pas détaillés ici.

En plus des fichiers décrivant les langages XML (les `schémas`), Jaxe utilise des fichiers de configuration qui définissent la barre de menus et la façon d'afficher les éléments du langage. Ces fichiers se trouvent dans le répertoire `config`, et leur nom se termine en `_config.xml`.

# Lancement de Jaxe

Jaxe nécessite Java 1.5 ou une version ultérieure pour fonctionner. Pour savoir quelle version de Java est installée, il suffit de taper `java -version` sous la ligne de commande.

Jaxe se lance différemment suivant le système d'exploitation. Sur MacOS, il suffit de double-cliquer sur l'application, qui doit se trouver dans le répertoire Jaxe. Sur Windows, on lance Jaxe avec l'exécutable `Jaxe.exe` ou avec le script `run.bat`, et sur UNIX avec le script `run.sh`. Ces scripts peuvent être modifiés pour définir un fichier de configuration à utiliser par défaut.

Sur Windows on peut lancer le script `assocXMLJaxe.bat` pour associer l'extension "`.xml`" à Jaxe. Cela permet d'ouvrir les fichiers XML directement en double-cliquant dessus. Ce script ne fonctionne que si on a les droits pour modifier les associations de fichiers, et il faut donc être administrateur.

Sur MacOS X on peut choisir Jaxe plutôt qu'un autre programme pour ouvrir un fichier XML par un double-clic en choisissant le menu "Lire les informations" d'un fichier XML, en choisissant Jaxe dans "Ouvrir avec", et en cliquant sur "Tout modifier" pour que tous les fichiers XML s'ouvrent avec.

Il est aussi possible de lancer Jaxe avec les scripts `jaxe.bat` et `jaxe.sh`, en ajoutant le nom d'un fichier à ouvrir, par exemple en tapant `./jaxe.sh essai.xml`.

Jaxe charge les fichiers XML en mémoire, et cela peut être difficile quand ils ont beaucoup de grandes images. Il est possible d'augmenter la mémoire allouée à Jaxe, suivant le système:

- sur Windows et UNIX, en modifiant le fichier run.bat ou run.sh: remplacer `java` par `java -Xms128m -Xmx512m` pour allouer 128 Mo de mémoire initialement, et autoriser un l'utilisation d'un maximum de 512 Mo.
- sur MacOS, éditer Jaxe/Jaxe.app/Contents/Info.plist, et ajouter les lignes `<key>VMOptions</key>` et `<string>-Xms=128m -Xmx=512m</string>` après les lignes `<key>Java</key>` et `<dict>`.

Jaxe utilise par défaut la langue du système, sachant que dans Jaxe 3.4 les seules langues définies sont le français, l'anglais, l'allemand, le portugais brésilien, le russe et l'espagnol. Si le système utilise une autre langue, Jaxe se lance en français. Pour changer la langue utilisée, on peut ajouter l'option `-Duser.language=xx` après la commande `java` dans les scripts, ou comme valeur de la clé `VMOptions` sur MacOS X. `xx` est un code correspondant à la langue, par exemple `en` pour l'anglais.

# Utilisation de Jaxe

## Fichiers de configuration

Au lancement, Jaxe ouvre un nouveau document XML avec la configuration par défaut s'il n'existe qu'un seul fichier de configuration. Sinon, il propose de choisir un fichier de configuration correspondant à un langage XML.

Pour vérifier que le langage XML utilisé dans un document ouvert est bien celui que l'on veut utiliser, il suffit de regarder les menus: la barre de menus des éléments se trouve en-dessous de la barre des menus de Jaxe (qui est en haut de l'écran sur MacOS). Si le langage n'est pas le bon, on peut créer un nouveau document XML avec le menu "Nouveau" qui propose un choix de fichiers de configuration quand il y en a plusieurs d'installés. Quand un fichier XML déjà créé est ouvert, il utilise automatiquement le fichier de configuration correspondant à son langage (s'il existe).

Jaxe inclut des exemples de fichiers de configuration pour XHTML strict, Docbook, Docbook simplifié, XPAGES, et un langage pour faire des présentations. Votre administrateur a normalement préparé un autre fichier de configuration pour le langage XML que vous allez utiliser.

## Affichage des éléments

Jaxe permet d'afficher les éléments XML de multiples façons, et il est même possible de créer de nouveaux affichages. La façon dont les éléments sont affichés est définie dans le fichier de configuration Jaxe du langage utilisé. Certains affichages d'éléments sont cependant plus populaires que d'autres. Un affichage classique consiste en une balise de début, suivie du contenu de l'élément, et se terminant par une balise de fin. Par exemple, une date s'affiche comme cela :

Avec cet affichage d'élément, quand un élément a des attributs, des boutons s'affichent sur les balises pour permettre leur modification dans un dialogue. Si les icônes de validation sont activées dans les préférences, les balises contiennent aussi une icône indiquant si l'élément est valide ou pas (un élément peut par exemple être invalide s'il manque des sous-éléments obligatoires à l'intérieur). Ces icônes ne sont cependant pas indispensables, étant donné que les balises changent aussi de couleur quand un élément n'est pas valide.

D'autres types d'affichage sont par exemple des listes, des tables, des images (pour représenter des éléments pointant vers des fichiers d'images), ou des formulaires.

## Insertion des éléments

A l'ouverture d'un fichier de configuration, Jaxe prépare un nouveau document, et insère automatiquement l'élément racine (dans le cas où les documents n'ont qu'un élément racine), en affichant un dialogue pour ses attributs s'il a des attributs. La barre des menus correspond aux éléments du langage, et on peut l'utiliser pour insérer des éléments. Une autre façon d'insérer des éléments est le panneau d'insertion, qui apparaît à gauche de la zone avec le document XML. Il liste les éléments qui peuvent être insérés dans le texte à l'endroit où se trouve le curseur. Cette liste peut aussi s'obtenir avec le menu contextuel, qui s'affiche avec un control-clic sur Mac ou avec un clic droit avec des souris à plusieurs boutons. On peut aussi l'afficher en tapant cmd-D (sur Mac) ou ctrl-D (Linux/Windows), ce qui permet de ne pas quitter ses mains du clavier.

Il est possible d'insérer un élément autour d'un texte ou d'un ensemble d'éléments déjà entrés. Il suffit de sélectionner cet ensemble, et d'insérer le nouvel élément comme on le ferait normalement.

## Suppression des éléments

Pour supprimer un élément, il suffit de mettre le curseur après l'une des balises (ou un autre élément graphique si l'élément n'est pas affiché avec des balises de début et de fin) et d'utiliser la touche d'effacement. Attention, cela supprime tout l'élément, avec tout ce qu'il y a dedans ! En cas de catastrophe, ne pas oublier que le menu annuler est là pour ça.

## Attributs

Certains éléments peuvent avoir des attributs. L'insertion d'un nouvel élément avec des attributs provoque l'affichage d'un dialogue permettant de choisir leurs valeurs. Pour les changer plus tard, il suffit de cliquer sur le bouton d'attributs de la balise de départ, ou de mettre le curseur à l'intérieur de l'élément et de regarder le panneau Attributs. Les attributs optionnels ont leur nom en vert, alors que les attributs obligatoires s'affichent en rouge.

## Images

Il existe dans de nombreux langages XML des éléments correspondant à des images. Il est alors possible de coller une image dans Jaxe, qui se charge de créer automatiquement le fichier de l'image correspondant à côté du fichier XML, et de créer un élément XML correspondant à l'image, avec la référence vers le fichier nouvellement créé. Le dialogue de modification des attributs possède deux boutons supplémentaires, Sélectionner un fichier... et Copier un fichier.... Cela permet de choisir un fichier pour l'image, et si le bouton Copier a été choisi de recopier le fichier de l'image à côté du fichier XML. Il faut en général éviter les références absolues vers les fichiers, comme `/Users/toto/x.gif`, et utiliser des chemins relatifs au dossier contenant le fichier XML. Par exemple, il est bien de créer un répertoire pour chaque fichier XML, et de créer un répertoire à l'intérieur pour contenir les images référencées par le fichier XML. La référence vers le fichier de l'image devient alors `images/x.gif`.

## Equations

Jaxe possède un petit éditeur d'équations, qui permet d'insérer et de modifier facilement des équations. Il s'ouvre avec des éléments correspondant à des équations. L'éditeur comprend deux zone: celle du bas, où on tape l'équation sous forme de texte, et celle du haut, où s'affiche la représentation graphique de l'équation au fur et à mesure. Par exemple, si on tape `racine(2)/3`, l'image de l'équation s'affiche : . La syntaxe de l'éditeur est détaillé sur la page suivante.

## Recherches

Jaxe permet de rechercher et remplacer des mots dans le texte avec le menu Rechercher du menu Edition. Il est possible de faire des recherches avancées en utilisant la syntaxe XPath pour sélectionner des éléments XML en utilisant leur nom et les valeurs des attributs. Il n'est pas nécessaire de connaître XPath pour utiliser cette fonctionnalité, puisqu'un dialogue permet de construire des requêtes simples. On peut par exemple facilement rechercher un élément `SECTION` ayant un attribut `titre` donné.

## Correcteur orthographique

Jaxe inclut Jazzy, un correcteur orthographique. Avant de l'utiliser, vérifiez que vous avez bien téléchargé un dictionnaire et qu'il est bien placé dans le répertoire dicos. Le dictionnaire de français se compose de deux fichiers, `francais.dico` et `francais.phon`. Sélectionnez ensuite un dictionnaire à partir des préférences de Jaxe, en choisissant le fichier `.dico`. Il suffit alors de choisir le menu Orthographe... dans le menu Edition.

## Affichage du code source

Il est possible d'afficher le code source du fichier XML tel qu'il sera enregistré, avec le menu Source XML. La fenêtre qui s'affiche alors n'est pas éditable pour éviter des problèmes de mise à jour.

## Validation

Jaxe permet d'éviter de faire des fichiers XML invalides, mais il se peut que l'on prépare un fichier qui n'est pas encore valide (parce-qu'un élément obligatoire n'a pas encore été ajouté, auquel cas l'élément parent doit s'afficher en orange, ce qui indique le problème mais ne le résout pas), ou que l'on ouvre un fichier créé autrement qu'avec Jaxe et qui n'est pas valide. Dans ce cas, on peut lancer une validation, qui est effectuée à partir du schéma XML (la validation n'est pas utile si la syntaxe simplifiée a été utilisée pour définir le langage). Cela se fait avec le menu Validation. S'il y a des erreurs, leur liste s'affiche, et un clic sur une erreur permet de voir où elle se trouve dans la fenêtre XML.

## Aperçu HTML

Un aperçu HTML peut être créé si une feuille de style a été créée pour le langage utilisé. L'aperçu est généré avec le menu Fenêtre HTML. Il est affiché avec Jaxe, mais pas forcément très bien si CSS est utilisé (Java Swing ne sait afficher pour l'instant que du HTML 3 !). Il peut donc être nécessaire d'ouvrir le fichier HTML avec un navigateur, ce qui se fait facilement avec un bouton de la fenêtre HTML après que le navigateur ait été défini dans les préférences de Jaxe. Dans la dernière version de Jaxe, l'aperçu s'ouvre directement dans le navigateur web choisi dans les préférences.

# Syntaxe des équations dans Jaxe

Un éditeur d'équation a été spécialement conçu pour Jaxe, afin d'ajouter et de modifier facilement des équations. Il fonctionne avec une zone de texte, où l'on entre une équation avec une syntaxe particulière, et l'image correspondant à l'équation s'affiche en temps réel au-dessus.

Avant de passer à la syntaxe, voici quelques règles à suivre pour entrer des équations :

- Ne pas utiliser d'espaces (ils sont ignorés dans le meilleur des cas).
- Ecrire l'équation comme si elle allait être interprétée mathématiquement et qu'un résultat numérique allait être calculé. Il faut donc toujours indiquer les opérateurs que l'on utilise, même lorsqu'ils ne doivent pas être affichés.
- Utiliser des parenthèses pour préciser l'ordre des opérations s'il ne correspond pas à l'ordre d'évaluation mathématique.

Contrairement à la plupart des éditeurs d'équations, cet éditeur interprète le sens mathématique de l'équation. Il contruit ensuite l'image à partir de là. Cela permet d'obtenir un résultat graphique uniforme pour toutes les équations. Par contre, il n'est pas possible de spécifier de contrainte d'affichage, par exemple pour obtenir un espace supplémentaire entre deux caractères : l'utilisateur donne le sens de l'équation, et c'est l'éditeur qui se charge de trouver le meilleur affichage.

- Addition et soustraction

  opérateurs '`+`' et '`-`'

- Multiplication

  Opérateur '`*`', affiché seulement quand deux nombres sont multipliés.

  Exemple: `2*3*sin(1,5*pi)` s'affiche :

- Division

  Opérateur '`/`' (affiché sous forme de fraction) et fonctions '`slash`' et '`fraction`'.

  Exemple: `slash(a;b)/c` s'affiche :

- Fonction

  Le séparateur des arguments est le point virgule pour dinstinguer ce caractère de la virgule, utilisée pour les décimales: `nomfonction(arg1;arg2;...)`

  Exemple: `f(x;y)` s'affiche :

- Exposant

  Opérateur '`^`'.

  Exemple: `x^y` s'affiche :

- Indice

  Opérateur '`_`'.

  Exemple: `x_(ab)` s'affiche :

- Exposant et indice

  Fonction '`subsup`' avec le premier terme, et les éléments à mettre en indice et en exposant.

  Exemple: `subsup(A;1;2)` s'affiche :

- Racine carrée

  Fonction '`racine`' ou '`sqrt`'.

  Exemple: `racine(x/2)` s'affiche :

- Racine n-ième

  Fonction '`racine`' avec le degré de la racine en deuxième argument.

  Exemple: `racine(x;3)` s'affiche :

- Valeurs absolues

  Fonction '`abs`'.

  Exemple: `abs(x^3)` s'affiche :

- Puissance de e

  Fonction '`exp`'.

  Exemple: `exp(x^2)` s'affiche :

- Intégrale

  Fonction '`intégrale`', avec 4 arguments: la fonction à intégrer, la variable d'intégration, la borne minimum et la borne maximum.

  Exemple: `intégrale(f(x);x;0;infini)` s'affiche :

- Somme et produit

  Fonctions '`somme`' et '`produit`', avec 3 arguments: la fonction à sommer, la borne minimum et la borne maximum.

  Exemple: `somme(ln(k)/k;k=1;10)` s'affiche :

- Matrice

  Fonction '`matrice`', avec les lignes en argument sous forme de fonction '`ligne`'.

  Exemple: `matrice(ligne(1;2;3);ligne(4;5;6))` s'affiche :

- Lettres grecques

  Variables avec le nom de la lettre, avec une majusucle au premier caractère du nom pour obtenir une lettre grecque majuscule.

  Exemple: `alpha*Delta*thetasym*upsih*piv` s'affiche :

- Caractères spéciaux

  Variable avec le nom du caractère spécial.

  `soleil|étoile|terre|planck|infini|angström|petitl|chapeau|barre|astérisque|grandg|...`

  Exemple: `M_soleil/M_terre=3,329*10^5` s'affiche :

- Opérateurs spéciaux

  Code spécial. Il vaut mieux éviter les espaces, mais quand l'opérateur est un mot, un espace peut améliorer la lisibilité de l'équation (sans changer l'affichage).

  `!=|~=|<=|>=|<<|>>|->|quelquesoit|ilexiste|drond|nabla|prop|croix|plusoumoins|cap|cup`

  Exemple: `quelquesoit a ilexiste b<<c~=d>=e!=f` s'affiche :

- Accents

  Fonction '`accent`' avec la lettre et l'accent à ajouter par-dessus.

  Exemple: `accent(AB;->)+accent(ABC;chapeau)+accent(x;barre)` s'affiche :

- Dérivée par rapport au temps

  Fonction '`dtemps`' avec la variable et le nombre de points à mettre au-dessus.

  Exemple: `dtemps(theta;2)` s'affiche :

- Vecteurs

  Fonction '`vecteur`' avec le nom du vecteur.

  Exemple: `vecteur(u_theta)` s'affiche :

- Produit scalaire

  Fonction '`pscalaire`' avec les deux vecteurs en paramètre.

  Exemple: `pscalaire(vecteur(AB);vecteur(CD))` s'affiche :

- Norme

  Fonction '`norme`' avec le vecteur en paramètre.

  Exemple: `norme(vecteur(AB))` s'affiche :

- Fonctions sans parenthèses

  Certaines fonctions s'affichent sans parenthèses quand elle n'ont qu'un argument avec une variable.

  Exemple: `sin(a)*sin(b)` s'affiche :

- Système d'équations

  Fonction '`système`', avec les lignes en argument.

  Exemple: `système(x+y=2;x-2*y=3)` s'affiche :

- Unités

  Fonction '`unité`', avec l'unité en deuxième argument.

  Exemple: `grandg=unité(6,67259*10^(-11);m^3*kg^(-1)*s^(-2))` s'affiche :

  Notez que les unités s'affichent avec un style de caractères normal, alors qu'une variable comme s'affiche en italique.

- Factorielles

  Fonction '`factorielle`'.

  Exemple: `factorielle(x)` s'affiche :

- Moyenne

  Fonction '`moyenne`'.

  Exemple: `moyenne(M_B)` s'affiche :

# Préférences

## Fenêtres visibles par défaut

On peut choisir les fenêtres visibles à gauche de la zone d'édition XML qui sont visibles par défaut.

- L'arbre affiche la structure du document. Un clic sur un élément permet de s'y rendre directement dans la fenêtre XML.
- Le panneau d'insertion liste les éléments que l'on peut insérer à l'endroit du curseur, et donne un accès pratique à l'aide pour les éléments.
- Le panneau d'attributs permet d'éditer les attributs de l'élément contenant le curseur dans la fenêtre XML.

## Navigateur

Il s'agit du navigateur lancé quand on clique sur le bouton "Navigateur" dans la fenêtre de l'aperçu HTML. Quand on choisit "Définir" ou quand on clique sur le bouton "Navigateur" pour la permière fois, un dialogue s'ouvre demandant de localiser le programme du navigateur sur le disque dur. Il se trouve par exemple généralement dans le dossier "Applications" sur MacOS X, ou dans le dossier "Program Files" sur Windows.

## Conserver les indentations

Cette option permet de conserver tous les espaces du document XML édité, et en particulier les indentations des éléments XML. Par défaut, Jaxe efface automatiquement les espaces servant d'indentation, ce qui n'est pas gênant quand un document est toujours édité avec Jaxe (parce-que les indentations sont remises pour l'édition), mais peut poser problème quand un document peut aussi être édité avec un autre éditeur XML.

## Icône de validation

Permet l'affichage d'une icône sur les balises pour indiquer si l'élément est valide ou pas. Un élément peut ne pas être valide quand il requiert par exemple un certain nombre de sous-éléments et qu'ils n'ont pas tous été insérés.

## Toujours afficher le dialogue d'attributs à la création d'un élément

Cette option permet de choisir si on préfère voir le dialogue d'attributs systématiquement quand on crée des éléments qui ne comportent pas d'attribut obligatoire. Le dialogue des attributs est toujours affiché s'il y a au moins un attribut obligatoire. Il peut par exemple être utile de décocher l'option quand on utilise des langages avec des attributs facultatifs peu fréquemment utilisés sur tous les éléments.

## Dictionnaire

Un certain nombre de dictionnaires sont téléchargeables pour Jaxe. Il faut les placer dans le répertoire `dicos` du répertoire de Jaxe. On peut ensuite sélectionner le fichier avec l'extension `.dico` correspondant au dictionnaire que l'on veut utiliser pour la correction orthographique.

## Processeur XSLT

Choix du processeur XSLT :

- par défaut : utilise le processeur XSLT par défaut de la machine Java (en général XSLTC, mais un autre peut être défini avec la propriété système `javax.xml.transform.TransformerFactory`, que l'on peut spécifier dans le fichier `lib/jaxp.properties` de la machine Java)
- Xalan
- XSLTC
- Saxon, le seul qui gère XSLT 2.0

# Editeur de Fichiers de Config de Jaxe

Auteur: Soufiane Ayadi

# Editeur de Fichiers de Config de Jaxe

Cet éditeur permet de créer un fichier de configuration afin de définir un environnement d'édition des éléments du langage XML. Grâce à son interface graphique simplifiée l'utilisateur peut facilement créer ou éditer des fichiers de config.

## Configuration requise

Un système (Mac, UNIX, Windows ou autre) avec une version de récente de Java (au moins 1.5). Pour tester la version de java de votre système, vous pouvez taper "`java -version`" sous la ligne de commande.

## Lancement de l'application

Il suffit en général de double-cliquer dessus sur MacOS X et Windows, ou de faire un clic droit et de choisir "Ouvrir avec Sun Java Runtime" sur Linux.

## Comment utiliser l'Editeur de fichiers de config

- Guide utilisateur

## Licence

GPL

# Créer/Editer un fichier de config

Menu initial
Ouvrir un fichier de config

Nouveau: créer un nouveau fichier de config

Ouvrir: ouvrir et éditer un fichier de config existant. Accédez au menu principal.

Quitter: quitter l'application

# Choix de langues

Définir une ou plusieures langues
Ajout d'une langue
Liste des langues

Il faut ajouter au moins une langue

# Choix du schéma

Choix d'un type de schéma
Sélection d'un schéma xml dans le dossier config

Choisissez un type de schéma W3C, sélectionnez le fichier dans votre dossier config.

# Choix des racines

Choix d'une ou plusieures racines

La liste à gauche représente les éléments parents qui peuvent être des racines possibles. Sélectionnez un et ajoutez le dans la liste des racines. N'oubliez pas de valider les modifications en cliquant sur OK.

En cas d'ouverture d'un fichier de config existant, vous verrez les racines existantes dans la liste des Racines.

Il est nécessaire d'indiquer un ou plusieurs éléments racine utilisables pour les nouveaux documents.

# Menu principal

Menu principal

Ce menu principal permet d'accéder aux différentes parties de l'éditeur:

- Racine : Choisir un ou plusieurs racines possibles pour votre fichier de config
- Enregistrement : Editer l'élément l'Enregistrement de votre document XML
- Editeur de Menus : Editer les menus, les menus d'insertion et les menus de fonction
- Editeur des Eléments : Editer les éléments XML
- Editeur des Exports : Editer un ou plusieurs exports en utilisant une ou plusieurs transformations XSLT successives
- Editeur des Textes Géneral : Editer les textes (appelés aussi chaînes de caractères ou strings) de l'interface créée avec la configuration

# Autre configuration

Choix d'un autre fichier de configuration

Une autre configuration Jaxe, à utiliser en plus de celle-là.

# Enregistrement des fichiers

Enregistrement des fichiers

## Définition des champs

- `Encodage`

  Encodage des caractères à utiliser pour les nouveaux documents. Jaxe utilise ISO-8859-1 par défaut si rien n'est spécifié.

- `Doctype`

  Définition de type de document, si une DTD doit être spécifiée dans les documents.

- `Schema Location`

  Enregistrement de l'emplacement du schéma XML dans les fichiers XML.

- `Préfixe espace`

  Spécification d'un préfixe à utiliser pour un espace de noms donné. Il est possible d'en spécifier plusieurs.

# Menus

Créer un nouveau menu
Créer un nouveau menu
Ajout d'un menu d'insertion
Créer un nouveau menu de fonction
Créer un nouveau menu de fonction
Editer les textes d'un menu
Editer les textes d'un menu d'insertion

Les menus définis dans les fichiers de config s'affichent au-dessus de la zone de texte de Jaxe. Ils ne sont pas mélangés avec la barre de menus de Jaxe, qui se trouve au-dessus (en haut de l'écran sur Mac).

## L'interface

La liste à droite affiche des éléments XML recupérés depuis le shéma XML. On peut filtrer ces éléments grâce au champ de texte. En cas d'ouverture du fichier de config existant, la liste n'affiche que les éléments restants.

## Définition des champs

- `Nouveau Menu`

  Crée un menu principal, contenant potentiellement des sous-menus.

- `Menu insertion`

  Grace aux boutons 'Ajouter' et 'Retirer', on peut ajouter ou supprimer un menu d'insertion (permettant d'insérer un noeud XML). Il faut spécifier le nom du noeud et le type de noeud (élément par défaut). Il est aussi possible de définir un raccourci clavier, avec la touche correspondante.

- `Menu fonction`

  Menu permettant d'exécuter une fonction à partir de sa classe Java. La seule fonction prédéfinie dans Jaxe est `jaxe.FonctionNormal`, qui permet de retirer tous les styles à une zone du texte. D'autres fonctions peuvent être ajoutées sous forme de plugin.

- `Paramètre`

  Un paramètre à transmettre à la fonction.

- `Editer les textes`

  On peut éditer les textes d'un menu sélectionné en cliquant sur le bouton Editer les textes. Définissez un titre et une documentation pour chaque langue (prédéfinie auparavant).

# Affichage des noeuds

Edition d'un élément sélectionné
Edition des textes d'un élément
Filtrer la liste des éléments
Valeurs suggérées pour un attribut
Paramètre d'affichage
Edition des textes d'un attribut

Une fonctionnalité essentielle de Jaxe est la possibilité d'afficher et d'éditer les éléments XML de diverses façons, quelque soient leurs types dans le schéma XML. On pourra par exemple choisir d'afficher un élément représentant une table sous forme de table, ou un élément pointant vers une image sous forme d'image. L'objectif étant de faciliter l'édition des documents, sans pour autant perdre de vue leur aspect sémantique : on ne cherchera pas à afficher les éléments tels qu'on les verra sous forme de page web ou PDF, mais simplement avec une interface facilitant l'édition et mettant en évidence le sens des différents éléments.

## Définition des champs

- `Type`

  Spécifie le type d'affichage d'un élément.

- `Valeur suggérée`

  Valeur proposée à l'utilisateur quand le schéma ne fixe pas les valeurs autorisées.

  On peut spécifier les valeurs suggérées d'un élément seulement si le type d'affichage est typesimple ou plugin

- `Affichage d'attribut`

  Permet de suggérer des valeurs pour un attribut.

- `Paramètre`

  Un paramètre d'affichage, en fonction du type d'affichage.

- `Editer les textes`

  On peut éditer les textes d'un élément sélectionné en cliquant sur le bouton Editer les textes. Définissez un titre et une documentation pour chaque langue (prédéfinie auparavant).

  Pour les textes d'un attribut, vous pouvez éventuellement définir le titre pour valeur.

# Types d'affichage

Type | Description | Affichage
--- | --- | ---
`division` | Deux barres allant jusqu'au bout de la fenêtre à droite, permettant de bien séparer de grandes parties du document. |
`zone` | Deux balises et des retours à la ligne, pour séparer des parties plus petites qu'avec `division`. |
`string` | Deux balises pour identifier une petite chaîne de caractères, sans retour à la ligne. |
`vide` | Une seule balise, typiquement pour un élément vide. |
`tableau` | Affichage de tableau de type tableur (avec le composant Swing JTable). Pratique pour des tableaux de nombres, mais ne permet pas d'utiliser des élements XML à l'intérieur des cellules (utiliser `tabletexte` pour cela). |
`tabletexte` | Affichage d'une table permettant d'utiliser des éléments XML dans les cellules. Gère aussi les attributs rowspan et colspan pour regrouper les cellules verticalement et horizontalement. |
`style` | A utiliser dans le cas (très rare si le langage XML code le sens par opposition à la forme) où un élément XML ne donne qu'une information de style. Affiche les caractères dans le style choisi (gras, italique, ...), sans aucune balise. Une alternative est d'utiliser le type `string`, qui permet aussi de choisir un style, mais affiche les balises. |
`fichier` | Affiche une image à partir de son chemin sur le disque issu d'un attribut de l'élément XML (à préciser). Il est possible de faire des copier/coller d'images et Jaxe créera automatiquement l'élément XML et le fichier de l'image sur le disque, en utilisant le premier élément de type `fichier`. |
`symbole` | Permet de choisir une image parmi un ensemble d'images situé dans un dossier. |
`liste` | Pour un élément correspondant à une liste à points ou numérotée. Le sous-élément doit utiliser le type `item`. S'affiche comme `zone`, avec un bouton '+' pour créer de nouveaux éléments de la liste. |
`item` | Elément d'une liste affichée avec le type `liste`. S'affiche avec des points ou des numéros, en fonction du type de liste. |
`typesimple` | Affiche un élément ayant une simple valeur, dans une petite zone particulière. Utilisable uniquement pour les éléments ayant un type simple dans le schéma XML. L'affichage précis (zone de texte, menu ou boîte à cocher) et la validation se fait en utilisant les contraintes du schéma XML. |
`equation` | Affiche l'image d'une équation. L'équation peut être éditée par un simple clic dessus, avec un dialogue présentant en même temps le texte de l'équation (avec une syntaxe très simple propre à Jaxe) et l'image correspondante. |
`formulaire` | Affiche un élément et tous ses sous-éléments possibles sous la forme d'un formulaire, avec un champ par sous-élément. Attention à ne pas utiliser ce type avec des éléments pouvant avoir un sous-arbre infiniment profond ! |
`plugin` | Si vous voulez définir votre propre élément Jaxe, c'est possible ! Voir la partie Création de nouveaux éléments Jaxe de la documentation pour les développeurs pour plus de précisions. En outre, certains plugins sont téléchargeables depuis cette page. |

Des paramètres peuvent être utilisés, en fonction des types d'affichage, avec l'élément `PARAMETRE` sous `AFFICHAGE_ELEMENT`.

Les affichages de type `division` et `zone` peuvent avoir un paramètre indiquant le nom de l'attribut à utiliser comme titre pour l'affichage.

Les affichages de type `fichier` et `symbole` doivent avoir un paramètre indiquant l'attribut repérant le nom du fichier.

Les affichages de type `tableau` et `tabletexte` doivent avoir des paramètres indiquant les éléments repérant les lignes et les cellules.

Les affichages de type `style` doivent avoir un paramètre indiquant le style.

Les affichages de type `zone` et `string` peuvent avoir un paramètre indiquant le style, un paramètre avec la police de caractères, et un paramètre avec la taille des caractères.

Les affichages de type `equation` doivent avoir des paramètres indiquant les attributs à utiliser pour le texte de l'équation et le nom de l'image.

Voilà la liste complète des paramètres possibles:

type | nom du paramètre | description
--- | --- | ---
division et zone | titreAtt | attribut pour le titre
division, zone, string et vide | attributsVisibles | affiche tous les attributs sur la balise de début (true|false)
tableau et tabletexte | trTag | élément pour une ligne
tableau et tabletexte | tdTag | élément pour une cellule
tableau et tabletexte | thTag | élément pour une cellule d'entête
tabletexte | colspanAttr | attribut de fusion des colonnes
tabletexte | rowspanAttr | attribut de fusion des lignes
tabletexte | alignAttr | attribut d'alignement du texte
liste | typeListe | type de liste (`POINTS|NUMEROS`)
style, zone et string | style | `GRAS|ITALIQUE|EXPOSANT|INDICE|SOULIGNE|BARRE`
zone et string | police | police de caractères
zone et string | taille | taille de caractères
fichier et symbole | srcAtt | attribut avec le nom du fichier
plugin | classe | classe Java dérivée de JaxeElement
item | image1 | première image de pastille
item | image2 | deuxième image de pastille
equation | srcAtt | attribut avec le nom de l'image
equation | texteAtt | attribut avec le texte de l'équation

# Exports

Ajout d'un autre export
Choisir un fichier XSL pour l'export

## Définition des champs

- `Export`

  Un export possible à partir des documents, en utilisant une ou plusieurs transformations XSLT successives. Un export vers un fichier HTML provoquera l'apparition d'un menu "Aperçu HTML" dans le menu Fenêtres de Jaxe. Les autres exports sont accessibles depuis le menu Fichier de Jaxe.

- `Fichier XSL`

  Un fichier XSL à utiliser pour la transformation (XSLT 1.0). Doit générer du XHTML ou HTML pour la sortie `HTML`, et du XSL-FO pour la sortie `PDF`.

- `Parametre`

  Un paramètre de la feuille de style. Il existe des noms magiques qui font que Jaxe va remplir automatiquement les valeurs avant la transformation (ces valeurs sont impossibles à obtenir autrement depuis XSLT) :

  - `jaxe-fichier-xml`

    Le chemin vers le fichier XML

  - `jaxe-uri-xml`

    L'URI vers le fichier XML

  - `jaxe-fichier-xsl`

    Le chemin vers le fichier XSL

  - `jaxe-uri-xsl`

    L'URI vers le fichier XSL

# Textes

Editer les textes d'un menu
Editer les textes d'un élément
Editer les textes d'un export
Ajout d'une langue
Edition des textes pour l'ensemble de langues

On peut souhaiter modifier tous les textes (appelés aussi chaînes de caractères ou strings) de l'interface créée avec la configuration. Soit pour améliorer la lisibilité sans avoir à modifier le schéma, soit pour fournir une interface dans une autre langue pour le même schéma. On peut aussi souhaiter fournir les textes pour un ensemble de langues, de manière à ce que les utilisateurs puissent éditer les mêmes documents, avec la même configuration Jaxe, mais avec une interface entièrement dans leur langue.

- Vous pouvez ajouter une langue en cliquant sur Ajouter. La langue est ajoutée avec les mêmes menus que les autres langues. Il vous suffit de traduire.
- Pour supprimer une langue, il vous suffit de la séléctionner et cliquer sur Retirer.

## Définition des champs

- `Description Config`

  Ligne décrivant la configuration, affichée dans le dialogue de création de nouveaux documents de Jaxe.

- `Textes pour Menu`

  Les chaînes de caractères associées à un menu, dont on sélectionne le nom

- `Titre`

  Un titre

- `Documentation`

  Une documentation

- `Textes pour Element`

  Les chaînes de caractères associées à un élément XML. Utilisées pour afficher l'élément, mais aussi pour le menu d'insertion de cet élément si aucun texte n'est spécifié pour le menu.

- `Titre pour valeur`

  Un titre à utiliser pour une valeur d'élément ou d'attribut

- `Textes pour attribut`

  Les chaînes de caractères associées à un attribut

- `Textes pour Export`

  Les chaînes de caractères associées à un export

# Sauvegarde du fichier de Config

Sauvegarde du fichier XML
Enregistrer le chemin du schéma
Enregistrement du chemin du schéma

Cliquer sur Enregistrer et choisissez le chemin de votre dossier config. Saisissez le nom du fichier (sans _config) sans l'extension .xml

Un dialogue vous demande d'enregistrer le chemin du schéma. le fichier de config et le schéma W3C doivent être dans le même dossier config.

Si vous quitter sans enregistrer votre fichier XML, un dialogue vous suggérera de le faire.

# Fichiers de configuration de Jaxe

Auteur: Damien Guillaume

# Introduction

Lors de la création d'un nouveau document avec Jaxe, il est nécessaire de choisir un fichier de config.

Les fichiers de config de Jaxe permettent de spécifier l'interface d'édition des documents XML avec Jaxe pour un langage XML donné. Ceci recouvre les informations sur le langage XML, les options d'enregistrement, les menus (notamment pour insérer les éléments), les types d'affichage des éléments, les exports possibles, et toutes les chaînes de caractères utilisées dans l'interface, en fonction de la langue de l'utilisateur.

Les fichiers de config se trouvent dans le répertoire `config` de Jaxe, et leurs noms se terminent par "_config.xml". Les anciens fichiers de config (avant Jaxe 3.0) avaient un nom se terminant en "_Jaxe_cfg.xml". On peut les convertir dans la nouvelle version à partir d'un menu d'export dans le menu Fichier.

Il est possible d'ouvrir un schéma XML dans Jaxe et d'"exporter" vers un fichier de config. Cela crée automatiquement un fichier de config qui permettra l'édition dans Jaxe pour ce schéma, mais les choix automatiques pour les types d'affichage sont souvent mauvais ou insuffisants : cet export ne doit pas être considéré comme une méthode de création des fichiers de config, mais peut servir pour commencer la création d'un fichier de config à partir d'un schéma particulièrement complexe.

# Définition du langage XML

## Définition des éléments

- `FICHIER_SCHEMA`

  Lors de la création d'un nouveau fichier de config, la première chose à faire est de définir le langage XML correspondant. Cela se fait en général en indiquant un fichier de schéma XML existant. Les schémas doivent utiliser la syntaxe du W3C (WXS) ou celle des schémas Relax NG (en XML).

- `SCHEMA_SIMPLE`

  Les schémas WXS étant assez complexe, il existe une alternative permettant de définir un langage très simple dans Jaxe, à l'intérieur du fichier de configuration. L'élément `SCHEMA_SIMPLE` permet de définir les éléments XML du langage, leurs attributs, et les relations hiérarchiques entre les éléments. Il n'est pas possible avec ces schéma de spécifier par exemple un ordre de sous-éléments dans un élément donné, ou encore des types pour les éléments et les attributs. Mais cela peut servir pour faire un prototype rapide, ou lorsque les besoins sont très simples.

  - `ELEMENT`

    Définition d'un élément XML pour les schémas simples.

  - `SOUS-ELEMENT`

    Un sous-élément possible (qui doit être défini par ailleurs).

  - `SOUS-ENSEMBLE`

    Un ensemble de sous-éléments possibles (l'ensemble doit être défini ailleurs).

  - `ATTRIBUT`

    Attribut d'élément.

  - `VALEUR`

    Valeur possible pour un attribut.

  - `ENSEMBLE`

    Définition d'un ensemble d'éléments (utilisable ensuite pour ne pas avoir à répéter les mêmes sous-éléments pour de nombreux éléments).

- `RACINE`

  Après avoir défini le langage XML, il est nécessaire d'indiquer à Jaxe un ou plusieurs éléments racine utilisables pour les nouveaux documents. On indique pour chaque racine possible le nom de l'élément avec l'élément `RACINE`.

- `AUTRE_CONFIG`

  Enfin, il est possible d'indiquer d'autres fichiers config à utiliser en parallèle avec celui décrit avec l'élément `AUTRE_CONFIG`, de manière à pouvoir mélanger 2 langages XML dans un document. Ceci est par exemple utilisé pour la création de documents XSLT.

## Arbre des éléments

Arbre des éléments sous l'élément `LANGAGE` :

- `LANGAGE (FICHIER_SCHEMA | SCHEMA_SIMPLE, RACINE+, AUTRE_CONFIG*)`
  - `FICHIER_SCHEMA @nom`
  - `SCHEMA_SIMPLE (ELEMENT | ENSEMBLE)+`
    - `ELEMENT @nom @texte (SOUS-ELEMENT | SOUS-ENSEMBLE | ATTRIBUT)*`
      - `SOUS-ELEMENT @element`
      - `SOUS-ENSEMBLE @ensemble`
      - `ATTRIBUT @nom @presence (VALEUR*)`
        - `VALEUR`
    - `ENSEMBLE @nom (SOUS-ELEMENT | SOUS-ENSEMBLE)+`
      - `SOUS-ELEMENT @element`
      - `SOUS-ENSEMBLE @ensemble`
  - `RACINE @element`
  - `AUTRE_CONFIG @nom`

# Enregistrement des fichiers

## Définition des éléments

- `ENCODAGE`

  Encodage des caractères à utiliser pour les nouveaux documents. Jaxe utilise ISO-8859-1 par défaut si rien n'est spécifié.

- `DOCTYPE`

  Définition de type de document, si une DTD doit être spécifiée dans les documents.

- `PREFIXE_ESPACE`

  Spécification d'un préfixe à utiliser pour un espace de noms donné. Il est possible d'en spécifier plusieurs.

## Arbre des éléments

Arbre des éléments sous l'élément `ENREGISTREMENT` :

- `ENREGISTREMENT (ENCODAGE?, DOCTYPE?, PREFIXE_ESPACE*)`
  - `ENCODAGE`
  - `DOCTYPE @publicid @systemid`
  - `PREFIXE_ESPACE @uri @prefixe`

# Menus

Les menus définis dans les fichiers de config s'affichent au-dessus de la zone de texte de Jaxe. Ils ne sont pas mélangés avec la barre de menus de Jaxe, qui se trouve au-dessus (en haut de l'écran sur Mac).

## Définition des éléments

- `MENU`

  Un menu principal, contenant potentiellement des sous-menus.

- `MENU_INSERTION`

  Un menu permettant d'insérer un noeud XML à l'endroit du curseur. Il faut spécifier le nom du noeud et le type de noeud (élément par défaut). Il est aussi possible de définir un raccourci clavier, avec la touche correspondante.

- `MENU_FONCTION`

  Menu permettant d'exécuter une fonction à partir de sa classe Java. La seule fonction prédéfinie dans Jaxe est `jaxe.FonctionNormal`, qui permet de retirer tous les styles à une zone du texte. D'autres fonctions peuvent être ajoutées sous forme de plugin.

- `PARAMETRE`

  Un paramètre à transmettre à la fonction.

- `SEPARATEUR`

  Séparateur de menu.

## Arbre des éléments

Arbre des éléments sous l'élément `MENUS` :

- `MENUS (MENU+)`
  - `MENU @nom (MENU | MENU_INSERTION | MENU_FONCTION | SEPARATEUR)+`
    - `MENU_INSERTION @nom @type_noeud (element|instruction|commentaire|CDATA) @raccourci`
    - `MENU_FONCTION @nom @classe @raccourci`
      - `PARAMETRE @nom @valeur`
    - `SEPARATEUR`
    - `MENU`

# Affichage des noeuds

Une fonctionnalité essentielle de Jaxe est la possibilité d'afficher et d'éditer les éléments XML de diverses façons, quelque soient leurs types dans le schéma XML. On pourra par exemple choisir d'afficher un élément représentant une table sous forme de table, ou un élément pointant vers une image sous forme d'image. L'objectif étant de faciliter l'édition des documents, sans pour autant perdre de vue leur aspect sémantique : on ne cherchera pas à afficher les éléments tels qu'on les verra sous forme de page web ou PDF, mais simplement avec une interface facilitant l'édition et mettant en évidence le sens des différents éléments.

## Définition des éléments

- `AFFICHAGE_ELEMENT`

  Spécifie le type d'affichage d'un élément.

- `PARAMETRE`

  Un paramètre d'affichage, en fonction du type d'affichage (voir plus bas pour une liste).

- `VALEUR_SUGGEREE`

  Valeur proposée à l'utilisateur quand le schéma ne fixe pas les valeurs autorisées.

- `AFFICHAGE_ATTRIBUT`

  Permet de suggérer des valeurs pour un attribut.

- `PLUGIN_INSTRUCTION`

  Plugin à utiliser pour les instructions de traitement (processing instructions).

- `PLUGIN_COMMENTAIRE`

  Plugin à utiliser pour afficher les commentaires XML.

## Arbre des éléments

Arbre des éléments sous l'élément `AFFICHAGE_NOEUDS` :

- `AFFICHAGE_NOEUDS (AFFICHAGE_ELEMENT | PLUGIN_INSTRUCTION | PLUGIN_COMMENTAIRE)+`
  - `AFFICHAGE_ELEMENT @element @type (PARAMETRE | VALEUR_SUGGEREE | AFFICHAGE_ATTRIBUT)*`
    - `PARAMETRE @nom @valeur`
    - `VALEUR_SUGGEREE`
    - `AFFICHAGE_ATTRIBUT @attribut (VALEUR_SUGGEREE+)`
      - `VALEUR_SUGGEREE`
  - `PLUGIN_INSTRUCTION @cible (PARAMETRE+)`
    - `PARAMETRE @nom @valeur`
  - `PLUGIN_COMMENTAIRE (PARAMETRE+)`
    - `PARAMETRE @nom @valeur`

# Types d'affichage

Type | Description | Affichage
--- | --- | ---
`division` | Deux barres allant jusqu'au bout de la fenêtre à droite, permettant de bien séparer de grandes parties du document. |
`zone` | Deux balises et des retours à la ligne, pour séparer des parties plus petites qu'avec `division`. |
`string` | Deux balises pour identifier une petite chaîne de caractères, sans retour à la ligne. |
`vide` | Une seule balise, typiquement pour un élément vide. |
`tableau` | Affichage de tableau de type tableur (avec le composant Swing JTable). Pratique pour des tableaux de nombres, mais ne permet pas d'utiliser des élements XML à l'intérieur des cellules (utiliser `tabletexte` pour cela). |
`tabletexte` | Affichage d'une table permettant d'utiliser des éléments XML dans les cellules. Gère aussi les attributs rowspan et colspan pour regrouper les cellules verticalement et horizontalement. |
`style` | A utiliser dans le cas (très rare si le langage XML code le sens par opposition à la forme) où un élément XML ne donne qu'une information de style. Affiche les caractères dans le style choisi (gras, italique, ...), sans aucune balise. Une alternative est d'utiliser le type `string`, qui permet aussi de choisir un style, mais affiche les balises. |
`fichier` | Affiche une image à partir de son chemin sur le disque issu d'un attribut de l'élément XML (à préciser). Il est possible de faire des copier/coller d'images et Jaxe créera automatiquement l'élément XML et le fichier de l'image sur le disque, en utilisant le premier élément de type `fichier`. |
`symbole` | Permet de choisir une image parmi un ensemble d'images situé dans un dossier. |
`liste` | Pour un élément correspondant à une liste à points ou numérotée. Le sous-élément doit utiliser le type `item`. S'affiche comme `zone`, avec un bouton '+' pour créer de nouveaux éléments de la liste. |
`item` | Elément d'une liste affichée avec le type `liste`. S'affiche avec des points ou des numéros, en fonction du type de liste. |
`typesimple` | Affiche un élément ayant une simple valeur, dans une petite zone particulière. Utilisable uniquement pour les éléments ayant un type simple dans le schéma XML. L'affichage précis (zone de texte, menu ou boîte à cocher) et la validation se fait en utilisant les contraintes du schéma XML. |
`equation` | Affiche l'image d'une équation. L'équation peut être éditée par un simple clic dessus, avec un dialogue présentant en même temps le texte de l'équation (avec une syntaxe très simple propre à Jaxe) et l'image correspondante. |
`formulaire` | Affiche un élément et tous ses sous-éléments possibles sous la forme d'un formulaire, avec un champ par sous-élément. Attention à ne pas utiliser ce type avec des éléments pouvant avoir un sous-arbre infiniment profond ! |
`plugin` | Si vous voulez définir votre propre élément Jaxe, c'est possible ! Voir la partie Création de nouveaux éléments Jaxe de la documentation pour les développeurs pour plus de précisions. En outre, certains plugins sont téléchargeables depuis cette page. |

Des paramètres peuvent être utilisés, en fonction des types d'affichage, avec l'élément `PARAMETRE` sous `AFFICHAGE_ELEMENT`.

Les affichages de type `division` et `zone` peuvent avoir un paramètre indiquant le nom de l'attribut à utiliser comme titre pour l'affichage.

Les affichages de type `fichier` et `symbole` doivent avoir un paramètre indiquant l'attribut repérant le nom du fichier.

Les affichages de type `tableau` et `tabletexte` doivent avoir des paramètres indiquant les éléments repérant les lignes et les cellules.

Les affichages de type `style` doivent avoir un paramètre indiquant le style.

Les affichages de type `zone` et `string` peuvent avoir un paramètre indiquant le style, un paramètre avec la police de caractères, et un paramètre avec la taille des caractères.

Les affichages de type `equation` doivent avoir des paramètres indiquant les attributs à utiliser pour le texte de l'équation et le nom de l'image.

Voilà la liste complète des paramètres possibles:

type | nom du paramètre | description
--- | --- | ---
division et zone | titreAtt | attribut pour le titre
division, zone, string et vide | attributsVisibles | affiche tous les attributs sur la balise de début (true|false)
tableau et tabletexte | trTag | élément pour une ligne
tableau et tabletexte | tdTag | élément pour une cellule
tableau et tabletexte | thTag | élément pour une cellule d'entête
tabletexte | colspanAttr | attribut de fusion des colonnes
tabletexte | rowspanAttr | attribut de fusion des lignes
tabletexte | alignAttr | attribut d'alignement du texte
liste | typeListe | type de liste (`POINTS|NUMEROS`)
style, zone et string | style | `GRAS|ITALIQUE|EXPOSANT|INDICE|SOULIGNE|BARRE`
zone et string | police | police de caractères
zone et string | taille | taille de caractères
fichier et symbole | srcAtt | attribut avec le nom du fichier
plugin | classe | classe Java dérivée de JaxeElement
item | image1 | première image de pastille
item | image2 | deuxième image de pastille
equation | srcAtt | attribut avec le nom de l'image
equation | texteAtt | attribut avec le texte de l'équation

# Exports

## Définition des éléments

- `EXPORT`

  Un export possible à partir des documents, en utilisant une ou plusieurs transformations XSLT successives. Un export vers un fichier HTML provoquera l'apparition d'un menu "Aperçu HTML" dans le menu Fenêtres de Jaxe. Les autres exports sont accessibles depuis le menu Fichier de Jaxe.

- `FICHIER_XSL`

  Un fichier XSL à utiliser pour la transformation (XSLT 1.0). Doit générer du XHTML ou HTML pour la sortie `HTML`, et du XSL-FO pour la sortie `PDF`.

- `PARAMETRE`

  Un paramètre de la feuille de style. Il existe des noms magiques qui font que Jaxe va remplir automatiquement les valeurs avant la transformation (ces valeurs sont impossibles à obtenir autrement depuis XSLT) :

  - `jaxe-fichier-xml`

    Le chemin vers le fichier XML

  - `jaxe-uri-xml`

    L'URI vers le fichier XML

  - `jaxe-fichier-xsl`

    Le chemin vers le fichier XSL

  - `jaxe-uri-xsl`

    L'URI vers le fichier XSL

## Arbre des éléments

Arbre des éléments sous l'élément `EXPORTS` :

- `EXPORTS (EXPORT+)`
  - `EXPORT @nom @sortie (FICHIER_XSL+)`
    - `FICHIER_XSL @nom (PARAMETRE+)`
      - `PARAMETRE @nom @valeur`

# Chaînes de caractères

On peut souhaiter modifier tous les textes (appelés aussi chaînes de caractères ou strings) de l'interface créée avec la configuration. Soit pour améliorer la lisibilité sans avoir à modifier le schéma, soit pour fournir une interface dans une autre langue pour le même schéma. On peut aussi souhaiter fournir les textes pour un ensemble de langues, de manière à ce que les utilisateurs puissent éditer les mêmes documents, avec la même configuration Jaxe, mais avec une interface entièrement dans leur langue.

Pour ces raisons, l'élément `STRINGS` représente un ensemble de textes pour une langue et un pays donné, et il est possible d'en spécifier plusieurs dans le même fichier de config. On mettra par exemple `langue="pt" pays="BR"` pour le portugais brésilien, ou juste `langue="fr"` pour spécifier la langue française sans précision sur le pays.

## Définition des éléments

- `DESCRIPTION_CONFIG`

  Ligne décrivant la configuration, affichée dans le dialogue de création de nouveaux documents de Jaxe.

- `STRINGS_MENU`

  Les chaînes de caractères associées à un menu, dont on spécifie le nom

- `TITRE`

  Un titre

- `DOCUMENTATION`

  Une documentation

- `STRINGS_ELEMENT`

  Les chaînes de caractères associées à un élément XML. Utilisées pour afficher l'élément, mais aussi pour le menu d'insertion de cet élément si aucun texte n'est spécifié pour le menu.

- `TITRE_VALEUR`

  Un titre à utiliser pour une valeur d'élément ou d'attribut

- `STRINGS_ATTRIBUT`

  Les chaînes de caractères associées à un attribut

- `STRINGS_EXPORT`

  Les chaînes de caractères associées à un export

## Arbre des éléments

Arbre des éléments sous l'élément `STRINGS` :

- `STRINGS @langue @pays (DESCRIPTION_CONFIG | STRINGS_MENU | STRINGS_ELEMENT | STRINGS_EXPORT)+`
  - `DESCRIPTION_CONFIG`
  - `STRINGS_MENU @menu (TITRE?, DOCUMENTATION?, STRINGS_MENU*)`
    - `TITRE`
    - `DOCUMENTATION`
    - `STRINGS_MENU @menu`
  - `STRINGS_ELEMENT @element (TITRE?, DOCUMENTATION?, TITRE_VALEUR*, STRINGS_ATTRIBUT*)`
    - `TITRE`
    - `DOCUMENTATION`
    - `TITRE_VALEUR @valeur`
    - `STRINGS_ATTRIBUT @attribut (TITRE?, DOCUMENTATION?, TITRE_VALEUR*)`
      - `TITRE`
      - `DOCUMENTATION`
      - `TITRE_VALEUR @valeur`
  - `STRINGS_EXPORT @export (TITRE?, DOCUMENTATION?)`
    - `TITRE`
    - `DOCUMENTATION`

# Plugins

## Remarque

Les plugins sous forme de fichiers jar ne sont gérés qu'à partir de Jaxe 3.0.

## Installation

Pour installer un plugin, il suffit de placer son fichier .jar dans le dossier `plugins` du dossier de Jaxe. Les nouvelles fonctionnalités du plugin (types d'affichage ou fonctions) peuvent alors être utilisées dans les fichiers de config.

Liste
Nom du plugin | Type | Objectif | Config requise | Téléchargement | Code source
--- | --- | --- | --- | --- | ---
JEEquaTeX | élément Jaxe | Editer des équations TeX avec une prévisualisation | Un serveur avec le script tex.php, ou latex dvips et convert installés chez les utilisateurs | JEEquaTeX.jar | JEEquaTeX.tar
ImportationTableau | fonction | Importer un tableau du presse-papier au format texte automatiquement vers un élément Jaxe de type tabletexte | - | ImportationTableau.jar | ImportationTableau.java
EnvoiContrib | fonction | Envoi d'un dossier contenant un fichier XML (de même nom) et des fichiers liés sur un serveur FTP | - (la bibliothèque JavaFTP est incluse) | EnvoiContrib.jar | EnvoiContrib.tar
JEChemin | élément Jaxe | Représente un chemin vers un fichier ou un répertoire. | - | JEChemin.jar | JEChemin.java

Si vous avez d'autres plugins à proposer, n'hésitez pas !

# Documentation pour les développeurs

Auteur: Damien Guillaume

# Introduction

On supposera ici que le lecteur a déjà lu les documentations utilisateur, administrateur et sur les fichiers de configuration, et qu'il est familier de la programmation en Java.

Cette documentation explique comment utiliser Jaxe au sein d'une autre application, et comment lui ajouter des extensions pour l'affichage des éléments.

# Utilisation de Jaxe au sein d'une autre application

La classe de lancement de Jaxe est (sans surprise) `jaxe.Jaxe`. Cette classe rassemble la gestion des évènements externes à l'application (ouverture de fichier, fermeture, etc...), et on peut donc y jeter un œil pour voir comment un nouveau document Jaxe est créé ou comment un document est ouvert.

Une autre classe importante est `jaxe.JaxeFrame`. Cette classe correspond à une fenêtre de document XML. Elle utilise la classe `jaxe.JaxeMenuBar` pour la gestion de la barre de menus, celle-ci étant malheureusement (à cause d'une limitation de Java) liée à la fenêtre.

Le plus simple, pour utiliser Jaxe dans une autre application, est probablement de se servir de la classe `jaxe.JaxeTextPane`, qui correspond à la zone de texte dans la fenêtre XML. Comme cette classe est dérivée de `java.swing.JTextPane`, elle peut facilement être ajoutée où on le souhaite selon le layout de l'application hôte. Le constructeur requiert un `JaxeDocument` (lié au DOM) et une `JFrame` (la fenêtre parent).

L'objet de classe `jaxe.JaxeDocument` doit être initialisé avec un fichier de configuration de Jaxe (géré par la classe `jaxe.Config`) et éventuellement avec un fichier XML ou avec un objet DOM.

Pour récapituler, voilà une série d'instructions permettant d'incorporer une zone de texte Jaxe dans un `Container` `parent` se trouvant dans une fenêtre `frame`:

    JaxeDocument jaxeDoc = new JaxeDocument("monlangage_config.xml");
    JaxeTextPane jaxeTextPane = new JaxeTextPane(jaxeDoc, frame);
    jaxeDoc.lire(urlFichierXML);
    // ou jaxeDoc.setDOMDoc(documentDOM);
    parent.add(jaxeTextPane);

Les éléments peuvent être insérés avec le menu contextuel, ou avec des actions `jaxe.ActionInsertionBalise`. Le constructeur de `ActionInsertionBalise` demande le document Jaxe, et l'élément DOM correspondant à la définition de l'élément dans le fichier de configuration de Jaxe.

On peut plus tard enregistrer le document avec la méthode `JaxeDocument.ecrire(File f)`.

# Création de nouveaux éléments Jaxe

On appelle élément Jaxe une classe dérivée de la classe `jaxe.JaxeElement`, décrivant un affichage pour un élément XML donné. Les éléments Jaxe standard sont regroupés dans le package `jaxe.elements`. Ils correspondent à des types d'affichage des fichiers de configuration (par exemple, le type `string` correspond à l'élément Jaxe `jaxe.elements.JEString`).

La création d'un nouvel élément Jaxe se fait en créant une nouvelle classe dérivée de `jaxe.JaxeElement`. Il peut ensuite être utilisé dans un fichier de configuration avec le type `plugin`, en précisant la classe à utiliser. Par exemple:

    <AFFICHAGE_ELEMENT element="BOUBOULE" type="plugin">
      <PARAMETRE nom="classe" valeur="JEBooleen"/>
    </AFFICHAGE_ELEMENT>

Deux méthodes doivent impérativement être définies dans l'élément Jaxe: `init` et `nouvelElement`. Deux autres ne sont utiles que si on utilise des balises de début et de fin (comme expliqué plus loin): `insPosition` et (si l'élément a des attributs) `majAffichage`.

`init` est utilisé pour l'initialisation et l'insertion du composant Swing dans la zone de texte. On trouve en paramètres la position à laquelle l'élément doit être inséré, et le nœud DOM. A partir de ces paramètres, il faut insérer le composant avec la méthode `JaxeElement.insertComponent(Position pos, JComponent comp)`.

Les choses se compliquent si on veut utiliser un composant pour une balise de départ et un composant pour une balise de fin, en laissant Jaxe traiter récursivement les sous-éléments. Il faut alors récupérer la position dans le texte après l'insertion de la balise de départ (elle est retournée par `insertComponent`), ajouter les enfants avec `creerEnfants(Position)`, puis insérer la balise de fin avec un nouvel appel à `insertComponent` (avec l'objet `Position` passé en paramètre à `creerEnfants`. Il faut ensuite mettre à jour le style des caractères pour les balises et le texte des enfants, ce qui nécessite d'avoir conservé la position de départ avant le premier `insertComponent`. Voilà un exemple:

    int offsetdebut = pos.getOffset();
    Position newpos = insertComponent(pos, composantBaliseDebut);
    creerEnfants(newpos);
    insertComponent(newpos, composantBaliseFin);
    if (newpos.getOffset() - offsetdebut - 1 > 0) {
      SimpleAttributeSet style = attStyle(null);
      if (style != null)
        doc.setCharacterAttributes(offsetdebut, newpos.getOffset() - offsetdebut - 1, style, false);
    }

La méthode `nouvelElement` est appelée quand l'utilisateur insère un nouvel élément. Elle doit éventuellement demander des informations à l'utilisateur (comme par exemples les attributs), et renvoyer l'élément DOM correspondant. On peut se servir de `jaxe.DialogueAttributs` pour demander les attributs à l'utilisateur.

`insPosition` peut être appelée pour obtenir la position à laquelle sera placé le curseur après l'insertion d'un nouvel élément. Par défaut le curseur sera placé après l'élément, mais il peut être utile de le placer entre les balises de début et de fin quand celles-ci sont utilisées.

Enfin, `majAffichage` est appelée pour mettre à jour l'affichage quand les attributs ont été modifiés dans le panneau d'attributs.

## Exemple

Le fichier suivant est un élément Jaxe utilisable pour un booléen, qui utilise une case à cocher pour l'affichage: JEBooleen.java. Il peut être compilé et placé dans un fichier jar pour être utilisable comme nouveau plugin de Jaxe, comme ceux disponibles sur la page des plugins.

# Ajout d'une fonction

On peut facilement ajouter un menu opérant une fonction particulière au lieu d'une insertion d'élément. Il suffit pour cela de créer une classe dérivant de `jaxe.Fonction` et implémentant la méthode `appliquer`, qui fournit le document Jaxe sur lequel on travaille, et les positions de début et de fin de la sélection dans le texte.

    public void appliquer(JaxeDocument doc, int start, int end)

On peut obtenir le document DOM à partir du document Jaxe en utilisant `doc.DOMdoc`. On peut aussi obtenir un élément Jaxe à partir d'une position du texte avec `doc.elementA(int pos)`, ou les éléments dans l'intervalle [start,end] avec `rootJE.elementsDans(start, end)`. Le noeud DOM correspondant est obtenu avec `JaxeElement.noeud`.

## Exemple

L'exemple suivant permet d'ajouter un menu donnant des statistiques sur le document.

- Télécharger le fichier FonctionStatistiques.java.
- Le mettre dans un dossier `pluginsjaxe` (c'est le nom du package).
- Le compiler. A partir de l'endroit où se trouve le dossier pluginsjaxe, il suffit de taper sous la ligne de commande : `javac -encoding ISO-8859-1 -classpath .:lib/Jaxe.jar pluginsjaxe/FonctionStatistiques.java` (en supposant que le fichier `Jaxe.jar` se trouve dans un dossier `lib` dans le répertoire courant). Cela doit créer un fichier `FonctionStatistiques.class` dans le dossier `pluginsjaxe`.
- Créer un fichier jar à partir du dossier `pluginsjaxe`, et le placer dans le dossier `plugins` de Jaxe.
- Modifier le fichier de configuration du langage utilisé pour ajouter un menu avec un appel à la fonction:

    <MENU nom="plugins">
      <MENU_FONCTION classe="pluginsjaxe.FonctionStatistiques" nom="Statistiques"/>
    </MENU>

# Le langage XPAGES

Auteur: Damien Guillaume

# Introduction

XPAGES permet de créer rapidement et facilement des sites web. Le principe sur lequel repose XPAGES est la séparation du contenu et de la forme : avec XPAGES, on spécifie un contenu (texte, images, animations), et on le structure en donnant un sens à chaque partie. A l'édition, on ne préoccupe absolument pas de la façon dont le contenu sera affiché plus tard, ce qui permet de gagner du temps et de ne pas mélanger le sens avec la forme. La façon dont le contenu sera affiché est spécifié séparément, par des feuilles de style. Il est ainsi possible de changer l'affichage indépendamment de l'édition.

XPAGES est un langage XML, c'est à dire un ensemble d'éléments et de règles permettant de structurer un texte. Des feuilles de style associées permettent de transformer automatiquement des documents XPAGES en fichiers HTML pour qu'ils puissent être consultés sur le web. Les documents XPAGES peuvent être édités avec Jaxe et WebJaxe grâce à un fichier de configuration décrivant une interface d'édition.

XPAGES est un langage très simple, et facile à apprendre : il ne comporte que 59 éléments (46 sans les exercices), à comparer par exemple aux 91 éléments de HTML, aux 390 éléments de DocBook, ou aux 526 éléments de OpenDocument.

# La structure des documents

Les documents XPAGES comportent un élément racine, `XPAGES`, qui est utilisé dans tous les documents comme élément de premier niveau. Sous cet élément, on trouve les éléments `INFORMATIONS`, `PAGE`, `REFXPAGES` et `XPAGES`.

- `INFORMATIONS` est un bloc de métadonnées, c'est à dire des informations sur le document. Il est décrit plus loin.
- `PAGE` correspond à une page web, et comporte un titre et un label permettant de faire des liens vers la page.
- `REFXPAGES` correspond à un référence (via le label) vers un autre document XPAGES, qui doit être inclus à l'endroit de l'élément. Ceci permet de créer un site avec plusieurs niveaux : on peut par exemple créer un site avec une page d'introduction, et plusieurs ensembles de pages. Pour cela on crée un document XPAGES pour le site, contenant la page d'introduction et des références `REFXPAGES` vers les ensembles de pages qui constituront le site.
- `XPAGES` sous `XPAGES` permet d'ajouter un niveau à l'arborescence, comme avec REFXPAGES, mais sans créer de nouveau document.

A l'intérieur d'une page, il est possible de créer des sections avec l'élément `SECTION`. Cet élément comporte un titre, un rôle qui spécifie le sens de la section et peut permettre un affichage différent en fonction, et une importance qui permet de mettre en valeur la section si celle-ci est importante.

Le texte est ajouté à l'intérieur de paragraphes, avec l'élément `PARAGRAPHE`. Il est facile d'insérer un nouveau paragraphe avec le raccourci-clavier commande-P ou contrôle-P dans Jaxe.

Il possible de créer plusieurs contributions, chacune comprenant un fichier XML XPAGES et les fichiers attachés (images, applets Java, ...). Chaque contribution doit alors correspondre à un dossier dont le nom est égal au label donné dans le bloc `INFORMATIONS` du fichier XML. Ce dossier contient le fichier XML et les fichiers associés.

# Informations

Le bloc d'informations renseigne sur le document, et permet aussi de choisir un habillage pour les pages qui seront générées. Il est obligatoire, et se place au début du document. Il comporte les éléments suivants :

- `LABEL` : un nom permettant de référencer ensuite le document avec l'élément `REFXPAGES`, pour l'inclure dans un ensemble plus grand. Le label est obligatoire, et doit correspondre au nom du fichier XML sans l'extension ".xml". Dans WebJaxe, le label doit être le nom de la contribution.
- `TITRE` : le titre du document (obligatoire).
- `AUTEUR` : un auteur du document. Il est bien sûr possible d'en spécifier plusieurs, en mettant plusieurs éléments `AUTEUR`.
- `DATECRE` : la date de création du document, sous la forme `JJ/MM/AAAA`.
- `DATEMAJ` : la date de mise à jour du document, sous la forme `JJ/MM/AAAA`.
- `LOGO` : chemin vers un fichier d'image avec un logo à utiliser pour l'affichage du site. L'image doit être dans un format standard du web (JPEG, PNG ou GIF). Il est possible d'ajouter un lien à utiliser si l'on clique sur le logo.
- `INTERFACE` : choix d'un habillage pour les pages qui seront générées pour le document.
- `RUBRIQUES` : permet de choisir si on veut afficher des boutons en haut des pages pour naviguer vers les sous-ensembles référencées avec `REFXPAGES`.
- `LANGUE` : le code de la langue du document (`fr` pour Français).

# Eléments de bloc

Les éléments de bloc sont les éléments XML que l'on peut insérer directement à l'intérieur d'un élément `PAGE`. Ils permettent de structurer le document, mais ne sont pas mélangés à du texte : il est ainsi impossible d'insérer du texte directement sous `PAGE`, le texte devant être placé à l'intérieur d'un élément de bloc.

XPAGES comporte les éléments de bloc suivants :

- `SECTION` : permet d'identifier une zone à l'intérieur d'une page, en lui donnant un titre, un rôle sémantique et une importance. Le rôle est facultatif, mais est important pour donner du sens aux différentes parties du document. Il peut aussi être utilisé plus tard pour afficher les sections ayant un même rôle d'une même façon, pour les différencier visuellement.
- `PARAGRAPHE` : un paragraphe est une suite de phrases. Pour "sauter une ligne" (cette idée correspondant plus à la forme qu'au contenu, elle est mise entre guillemets), il faut créer un nouveau paragraphe.
- `LISTE` : une liste d'éléments (`ITEM`). Les éléments de la liste peuvent contenir du texte, mais aussi des paragraphes ou des sous-listes.
- `TABLEAU` : un tableau constitué d'un certain nombre de lignes et de colonnes. Il est possible de spécifier une ligne de titres (la première ligne du tableau). On peut aussi fusionner des cellules, et spécifier un alignement à l'intérieur des cellules.
- `ENVIMAGE` : une zone regroupant les informations liées à une image, et le fichier de l'image. En plus de l'image, on peut spécifier le crédit (l'origine de l'image, obligatoire de nos jours), et la légende. Il est également possible de spécifier un lien sur l'image, pour qu'un clic dessus redirige vers une autre partie du site ou une page externe.
- `APPLET` : une applet Java, par exemple pour des simulations interactives.
- `FLASH` : un objet Flash, qui peut comme une applet Java être utilisé pour ajouter de l'interactivité au site.
- `COMMENTAIRE` : un commentaire de l'auteur qui ne sera pas affiché sur le site. Très utile pour indiquer par exemple des parties à développer ou corriger au moment de la rédaction.
- `CODE` : un bloc de code informatique, donc le formattage doit être préservé.
- `EXERCICE` : un exercice (voir plus loin).
- `QCM` : un QCM (voir plus loin).
- `BIBLIOGRAPHIE` : une liste de références bibliographiques et webographiques.

# Eléments mélangés au texte

Certains éléments de XPAGES peuvent être mélangés avec du texte, par exemple à l'intérieur d'un paragraphe. Ce sont les éléments suivants :

- `LIENPAGE` : lien vers une page du même site. Pour identifier la page vers laquelle on veut pointer, il faut renseigner le label de la contribution, et le label de la page. Si on n'indique que le label de la page, il est supposée qu'elle est dans la même contribution. Si on n'indique que le label de la contribution, le lien pointe vers la première page de cette contribution.
- `LIENWEB` : lien vers une page web externe au site. L'adresse (URL) donnée doit donc commencer par "`http://`".
- `FICHIER` : fichier d'image ou d'animation. Normalement utilisé à l'intérieur d'un élément `ENVIMAGE`, ce qui permet notamment de spécifier une légende, mais peut également être utilisé dans le texte (par exemple pour inclure un symbole qu'il ne serait pas possible de créer avec une équation).
- `SYMBOLE` : lettre grecque ou symbole mathématique.
- `EQUATION` : équation basée sur la syntaxe de l'éditeur d'équations de Jaxe.
- `EQUATEX` : équation basée sur la syntaxe TeX.
- `GLOSSAIRE` : mot qui renvoit au glossaire. On spécifie le mot affiché avec l'attribut `mot`, et la définition de ce mot à l'intérieur des balises `GLOSSAIRE`.
- `EM` : emphase (permet de mettre en valeur un ou plusieurs mots).
- `SUP` : texte en exposant
- `SUB` : texte en indice
- `CODE` : code informatique (généralement affiché avec une police dont toutes les lettres ont la même taille)
- `NBSP` : espace insécable

# Exercices

XPAGES peut être utilisé pour de nombreuses applications, mais il est en particulier pratique pour créer un cours en ligne, et a été créé dans ce contexte. Pour ces raisons, le langage contient des éléments spécifiques à la définition d'exercices, même si ces éléments ne seront pas forcément utiles en-dehors du contexte des cours en ligne.

Il existe deux types d'exercices : les exercices de type question-réponse, et les QCM. Dans les deux cas, un exercice peut avoir un titre (attribut `titre`), un énoncé (élement `ENONCE`), une indication de la difficulté (élément `DIFFICULTE`), une indication du temps nécessaire (élément `TEMPS`), et des questions (élements `QUESTION` et `QUESTIONQCM`).

Chaque question peut avoir un énoncé et une ou plusieurs aides (élement `AIDE`). Les questions des exercices de type question-réponses ont une solution (élément `SOLUTION`) et un nombre de points qui peuvent être accordés si la réponse est correcte (élément `POINTS`). Les questions de QCM ont des réponses possibles (élément `REPONSEQCM`), chaque réponse pouvant être bonne ou pas (attribut `bonne`), avec à chaque fois le texte de la réponse (élément `TEXTEREP`) et un commentaire qui sera affiché si l'utilisateur choisit cette réponse, par exemple pour lui expliquer en quoi la réponse est fausse (élément `COMMENTAIREREP`).

Dans Jaxe, les réponses des exercices d'évaluations ne sont pas ajoutées aux fichiers HTML quand on génère le "site public". Elles ne sont ajoutées que lorsque l'on génère le "site de production". Dans WebJaxe, c'est toujours le site de production qui est généré; il faut donc exporter la contribution et l'ouvrir dans Jaxe pour générer le site public. On peut ainsi, à partir des mêmes fichiers XML, générer un site pour les étudiants, et un site pour les tuteurs d'une formation à distance.

# Référence du langage

Le document suivant présente l'ensemble des éléments du langage XPAGES, avec un index et un arbre des éléments. Il a été généré automatiquement à partir du schéma XML de XPAGES.