<oXygen/> User Guide

Déboguer vos documents

La spécification XML du W3C déclare qu'un programme ne doit pas continuer à traiter un document XML si il y trouve une erreur de validation. La raison en est que les logiciels XML doivent être aisés à écrire, et que tous les documents XML doivent être compatibles. Avec HTML il était possible de créer des documents avec de nombreuses erreurs (comme quand vous oubliez une balise de fermeture). Une des raisons pour lesquelles les navigateurs HTML sont si gros et incompatibles est qu'ils ont leurs propres façons de deviner à quoi le document devrait ressembler quand ils rencontrent une erreur HTML. Avec XML ceci ne devrait pas être possible.

Malgré tout, lors de la création d'un document XML, des erreurs sont très aisément introduites. En travaillant avec des grands projets ou de nombreux fichiers, la probabilité que des erreurs surviennent est encore plus élevée. Vous assurer que votre projet ne contient aucune erreur peut prendre beaucoup de temps et être même frustrant. Pour cette raison oXygen offre des fonctions qui permettent une identification et une localisation aisées des erreurs.

Vérifier la forme XML

XML avec une syntaxe correcte est "XML bien formé" et possède une syntaxe XML correcte.

Un document "XML bien formé" est un document qui se conforme aux règles syntaxiques du XML.

  • Tous les éléments XML doivent avoir une balise de fermeture.

  • Les balises XML sont sensibles à la casse.

  • Tous les éléments XML doivent être correctement emboîtés.

  • Tous les documents XML doivent avoir un élément root.

  • Les valeurs des attributs doivent toujours être entre guillemets.

  • Avec XML, l'espace blanc est préservé.

Utiliser la fonction Vérifier la forme XML vérifie votre projet pour la moindre déviation à une de ces règles. Si une erreur est trouvée, le résultat est retourné au panneau message. Chaque erreur est un enregistrement dans la liste des résultats et est accompagniée par un message d'erreur. Cliquer sur l'enregistrement va ouvrir le document contenant l'erreur et surligner l'endroit approximatif.

Exemple 4.4. Message d'erreur vérifier la forme XML

Dans notre exemple nous utiliserons le cas où une balise de fermeture est manquante dans un élément item d'une liste (listitem) DocBook. Dans ce cas exécuter Vérifier la forme XML va retourner l'erreur suivante :

F L'élément type "listitem" doit
                            être fermé par la balise de fermeture correspondante "</listitem>".

Pour résoudre cette erreur, click in the result list record which will locate and highlight the errors approximate position. Review the "listitems", identify which is missing an end tag and insert </listitem>.

Valider des documents

Un document XML "Valide" est un document XML "Bien formé", qui se conforme aussi aux règles d'une Document Type Definition (DTD) ou d'un schéma XML, qui définit les éléments légaux d'un document XML.

L'objet d'une DTD est de définir les blocs de construction légaux d'un document XML. Elle définit la structure du document avec une liste d'éléments légaux.

La fonction Valider XML de oXygen assure que votre document est compatible avec les règles définies par une DTD ou un schéma XML associé.

Exemple 4.5. Message d'erreur Valider XML

Dans notre exemple nous utiliserons le cas où un élément listitem DocBook ne correspond pas aux règles de la docbookx.dtd. Dans ce cas lancer Valider XML va retourner l'erreur suivante.

E Le contenu de l'élément type
                            "listitem" doit correspondre
                                à"(calloutlist|glosslist|itemizedlist|orderedlist|segmentedlist|
                                simplelist|variablelist| caution|important|note|tip|warning|
                                literallayout|programlisting|programlistingco|screen|
                                screenco|screenshot|synopsis|cmdsynopsis|
                                funcsynopsis|classsynopsis|fieldsynopsis| constructorsynopsis|
                                destructorsynopsis|methodsynopsis|formalpara|para|simpara|
                                address|blockquote|graphic|graphicco|mediaobject|
                                mediaobjectco|informalequation| informalexample|
                                informalfigure|informaltable|equation|example|
                                figure|table|msgset|procedure|sidebar|qandaset|anchor|
                                bridgehead|remark|highlights|abstract|authorblurb|epigraph| indexterm|beginpage)+".

Comme vous pouvez le voir, ce message d'erreur est un peu plus compliqué à comprendre, donc la compréhension de la syntaxe ou des règles de traitement pour l'élément "listitem" de la DTD XML de DocBook est nécessaire. Néanmoins le message d'erreur nous donne une idée sur la source du problème, indiquant que "Le contenu de l'élément type "listitem" doit correspondre à".

Heureusement la plupart des standards basés sur des DTD et des schémas XML sont livrés avec une documentation. Cela permet de chercher l'élément et d'en lire la présentation. Dans ce cas nous voudrons apprendre sur les éléments fils de "listitem" et leurs règles. Une fois que l'élément fils requis est correctement inséré en accord avec les règles XML, le document va être valide lors du prochain test de validation.

Lors de la validation XML, oXygen indique la référence de spécification pour les erreurs XML Schema. Les messages d'erreur contiennent un champ Info qui, lorsqu'il est cliqué, va ouvrir le navigateur sur la spécification "XML Schema Part 1:Structures" au point exact où l'erreur est décrite, vous permettant ainsi de comprendre la raison de cette erreur.

Figure 4.17. Lien vers la spécification pour les erreurs XML Schema

Lien vers la spécification pour les erreurs XML Schema

Navigation rapide dans le document avec les signets

Le concept du signet est le même que dans les autres : l'utilisateur peut marquer une position dans un document édité afin d'y retourner rapidement après l'édition et la navigation à travers un ou plusieurs documents ouverts en même temps. Jusqu'à neuf signets distincts peuvent être placés dans n'importe quel document ouvert. Des raccourcis claviers configurables sont disponibles pour placer des signets et pour retourner rapidement aux positions marquées.

Les raccourcis clavier peuvent être configurés depuis Options-> Préférences->Raccourcis clavier du menu.

Un signet peut être placé depuis Édition-> Signets->Créer, depuis Édition-> Signets->Création rapide de signets et en cliquant dans la marge de la zone d'édition, à gauche de la zone du numérotage des lignes, réservée aux signets.

On peut passer rapidement à une position marquée par un signet via Édition-> Signets->Aller à.