# Documentation pour les utilisateurs finaux

Auteur: Damien Guillaume

- Principe de XML
- La définition du langage
- Lancement de Jaxe
- Utilisation de Jaxe
- Syntaxe des équations dans Jaxe
- Préférences

# 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