<oXygen/> XML Editor User Guide

Edition de documents XML

Associez un schéma à un document

Paramétrer un schéma pour Tag-Insight

Dans le cas où vous éditez des fragments d'un document, par exemple les chapitres d'un livre, chacun dans un fichier séparé, vous pouvez activer la Complétion de code pour ces fragments de deux façons :

Paramétrer une schema par défaut

The table available at Options->Preferences -> Tag-Insight/Default contains a set of rules for associating a schema with the current document when no schema is specified within the document. The rules are applied in the order they appear in the table and take into account the local name of the root element, the default namespace and the file name of the document.

[Important]Important

L'éditeur crée les listes Tag-Insight en fonction de la schema spécifiée et du contexte actuel (la position dans l'éditeur). Si vous changez la schema, vous pourrez observer que la liste des balises à insérer change.

Figure 4.14. Tag-Insight driven by a Docbook DTD

Tag-Insight driven by a Docbook DTD
Ajouter une instruction de traitement

Le même effet est obtenu en configurant une instruction de traitement qui spécifie la schema à utiliser. L'avantage de cette méthode est que vous pouvez configurer le TagInsight pour chaque fichier. L'instruction de traitement doit être ajoutée au début du document, juste après le prologue :

<?oxygen RNGSchema="file:/C:/work/relaxng/personal.rng" type="xml"?>

Document+XML Document->Associer schéma... : Ouvre un dialogue pour sélectionner un schéma pour Tag-Insight et validation de document. Le schéma est d'un des types suivants : XML Schema, DTD, Relax NG, NRL, Schematron.

C'est un dialogue aidant l'utilisateur à facilement associer un fichier schéma au document édité. Permet la définition d'un prolog de document XML utilisant l'identifiant système d'un schéma XML, d'une DTD, d'un schéma Relax NG (syntaxe entière ou compacte), d'une schéma NRL (Namespace Routing Language) ou d'un Schematron schema

Figure 4.15. Dialogue Associer schéma

Dialogue Associer schéma

Lors de l'association d'un schéma XML au document édité, si l'élément racine du document définit un namespace URI par défaut avec un attribut "xmlns", l'action "Associer schéma" ajoute un attribut xsi:schemaLocation. Sinon un attribut xsi:noNamespaceSchemaLocation est ajouté.

Learning document structure

En travaillant avec des documents qui ne spécifient pas de DTD, ou pour lesquels la DTD est inconnue ou n'existe pas, <oXygen/> est capable d'apprendre et de traduire en une DTD, qui peut à son tour être sauvée dans un fichier pour offrir une DTD Tag-Insight and document validation. En plus d'être utile pour une création rapide d'une DTD qui sera capable d'offre une source d'initialisation pour l'assistant Tag-insight, cette fonction peut être aussi utilisée pour produire des DTD pour les documents contenants des types d'éléments personnels.

Procédure 4.8. Pour créer une DTD :

  1. Ouvrir le document structuré à partir duquel une DTD sera créée.

  2. Document+XML Document->Apprendre la structure (Ctrl+Shift+L) or click the toolbar button Apprendre la structure pour lire la structure de formatage du document actuel de telle façon qu'elle puisse être sauvée comme DTD en utilisant l'optionEnregistrer la structure. <oXygen/> va apprendre la structure du document, et lorsqu'il aura fini il affichera Apprentissage terminé dans le panneau message de la barre de statut de l'éditeur.

  3. Document+XML Document->Enregistrer la structure (Ctrl+Shift+S) or click the toolbar button Enregistrer la structure pour afficher le dialogue Enregistrer la structure, utilisé pour nommer et créer des documents DTD appris par la fonction Apprendre la structure.

[Note]Note

La DTD résultante n'est uniquement valide que pour les documents contenants les éléments et structures définis par le document utilisé comme entrée pour la création de la DTD. Si les nouveaux types des éléments sont définis dans un document, ils doivent être ajoutés à la DTD afin de réussir la validation.

Optimiser avec Tag-insight

La fonctionnalité Tag-insight intelligente de <oXygen/> est un assistant à l'édition qui permet une identification et une insertion rapide et en ligne d'éléments, d'attributs et dans certains cas leurs options de paramétrage, de langages structurés.

Figure 4.16. Assistant Tag-insight

Assistant Tag-insight

If theTag-Insight assistant is enabled in user preferences (the option Use Tag Insight) il est automatiquement affiché à chaque fois que le caractère < est entré dans un document ou en sélectionnant CTRL+Espace sur un élément partiel ou le nom d'un attribut. Surligner un élément et presser la touche Entrée, insère à la fois les parties d'ouverture et de fermeture de l'élément surligné. Si la fonction Ajouter le contenu de l'élément de Tag-Insight est activé, tous les éléments que le nouvel élément doit contenir, comme spécifié dans la DTD ou le schéma XML, sont insérés automatiquement dans le document . L'assistant Tag-Insight peut aussi ajouter du contenu optionnel et la particule du premier choix, comme spécifié dans la DTD ou le schéma XML, pour l'élément si les deux options sont activées. Après l'insertion, le curseur est positionné directement avant le caractère > de la balise d'ouverture, si l'élément a des attributs, afin de permettre l'insertion rapide de n'importe quel attribut supporté par l'élément, ou après le caractère > de la balise d'ouverture si l'élément n'a pas d'attributs. Appuyer sur la barre d'espace, juste après l'insertion de l'élément, va afficher à nouveau l'assistant. Dans ce cas, les attributs supportés par cet élément seront affichés. Si un attribut support un ensemble fixe de paramètres, l'assistant va afficher la liste des paramètres valides. Si le réglage du paramètre est défini par l'utilisateur, l'assistant sera fermé pour permettre l'insertion manuelle. Les valeurs des attributs peuvent être appris depuis les mêmes éléments dans le document actuel.

L'assistant de contenu peut être appelé à tout moment en pressant CTRL+Espace et la liste sensible au contexte des propositions sera affichée à n'importe quelle position du curseur dans le document édité à l'endroit où l'insertion d'un élément, attribut ou de la valeur d'un attribut a du sens. De tels endroits sont : n'importe où dans le nom d'une balise, ou au début du nom d'une balise dans un document XML, XML Schéma, DTD ou schéma Relax NG (syntaxe complète ou compacte), n'importe où dans le nom d'un attribut ou au début du nom d'un attribut dans tout document XML avec une schema associée, et avec les valeurs d'un attribut ou au début de valeurs d'un attribut dans des documents XML où les listes de valeurs possibles ont été définies pour cet élément dans la schema associée au document.

Le contenu de l'assistant Tag-insight est dépendant de la structure de l'élément donné dans un fichier DTD, schéma XML, schéma Relax NG (syntaxe complète ou compacte) ou NRL donné.

Le nombre et le type des éléments affichés par l'assistant est sensible à la position actuelle du curseur dans le document structuré. Les éléments fils affichés dans un élément donné sont définis par la structure de la DTD, du schéma XML, schéma Relax NG (syntaxe complète ou compacte) ou NRL spécifié. Tous les éléments qui ne peuvent pas être des éléments fils de l'élément actuel sont retirés.

Si le schéma pour le document édité définit des attributs de type ID et IDREF alors l'assistant de contenu affiche pour les attributs IDREF une liste de toutes les valeurs ID déjà présentes dans le document pour un insertion aisée d'une valeur ID valide à la position du curseur dans le document. Cette fonction est disponible pour les documents qui utilisent DTD, XML Schema et Relax NG.

Pour les documents qui utilisent un schéma XML ou Relax NG l'assistant de contenu propose des valeurs pour les attributs et éléments qui ont comme type une énumération de marques.

If the schema for the document is of type XML Schema, Relax NG (full syntax) or DTD and it contains element, attributes or attributes values annotations, these will be presented when the content completion window is displayed, if the option Show annotations is enabled.

In a XML Schema annotations are put in a <xs:annotation> element:

                        <xs:annotation>
                        <xs:documentation>
                        Description of the element.
                        </xs:documentation> 
                        </xs:annotation> 
                    

In a Relax NG schema any element not in the Relax NG namespace (http://relaxng.org/ns/structure/1.0) is handled as annotation and the text content is displayed in the annotation window together with the tag insight window:

Figure 4.17. Schema annotations displayed at Tag Insight

Schema annotations displayed at Tag Insight

Pour les DTD <oXygen/> définit un mécanisme pour les annotations en utilisant commentaires enabled from the option Use DTD comments as annotations. The text of a comment with the following format will be presented on content completion:

 <!--doc:Description de l'élément. --> 

The operation of the Tag-Insight assistant is configured by the options available in the group called Tag Insight Features.

When the content assistant is invoked by pressing CTRL+Space it also presents a list of code templates specific to the type of the active editor. Such a code template provides a shortcut for inserting a small document fragment at the current caret position. <oXygen/> comes with a large set of ready-to use templates for XSL and XML Schema documents.

Exemple 4.1. The XSL code template called Template-Match-Mode

Typing t in a XSL document and selecting tmm in the content assistant pop-up window will insert the following template at the caret position in the document:

                            <xsl:template match="" mode="">
                            
                            </xsl:template>
                        

Other templates can be easily defined by the user. Also the code templates can be shared with other users.

La DTD, le schéma XML, le schéma Relax NG ou NRL utilisé pour remplir l'assistant Tag-insight est spécifié dans les méthodes suivantes, par ordre hiérarchique :

  • Depuis le fichier spécifié dans le sous-ensemble externe du prolog du document. Dans ce cas <oXygen/> lit le prolog et trouve l'emplacement de la DTD, du schéma XML, du schéma Relax NG ou NRL.

  • Depuis le fichier spécifé dans le dialogue Tag-insight de <oXygen/>. <oXygen/> va lire les réglages Tag-insight quand le prolog n'arrive pas à donner ou trouver l'emplacement de la DTD, du schéma XML ou du schéma Relax NG.

Informations about the current element being edited are also available in the Model panel and Attributes panel, located on the left-hand side of the main window. The Model panel and the Attributes panel combined with the powerful Outliner provide spacial and insight information on the edited document.

The Model panel presents the structure of the current edited tag and tag documentation defined as annotation in the schema of the current document.

Figure 4.18. La vue Modèle

La vue Modèle

Le panneau Modèle comprend :

Le panneau de la structure de l'élément.

Le paneau de la structure de l'élément affiche la structure de la balise éditée ou sélectionné dans le format d'un arbre.

Les informations incluent le nom, le modèle et les attributs que la balise actuellement éditée peut avoir. Les attributs autorisés sont affichés avec les restrictions qu'ils peuvent avoir.

Figure 4.19. La vue de la structure de l'élément.

La vue de la structure de l'élément.

La vue annotation.

La vue annotation affiche les annotations qui sont présentes dans le schéma utilisé pour la balise actuellement éditée ou sélectionnée.

Cette information peut être très utile aux personnes apprenant le XML car elle a très peu de définitions disponibles pour chaque balise utilisée.

Figure 4.20. La vue annotation.

La vue annotation.

The Attributes panel presents all the possible attributes of the current element and allows to insert attributes in the current element or change the value of the attributes already used in the element. The attributes already present in the document are painted with a bold font. Clicking on the Value column of a table row will start editing the value of the attribute from the selected row. If the possible values of the attribute are specified as list in the schema associated with the edited document the Value column works as a combo box where you can select one of the possible values to be inserted in the document.

Figure 4.21. La vue Attributes

La vue Attributes

Déboguer documents XML

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é.

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é.

If you select menu Document+XML Document->Contrôler que le document est bien formé (Ctrl+Shift+W) or click the toolbar button Check document form <oXygen/> vérifie votre document courant 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.2. 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, cliquez dans la liste des résultats sur l'entrée qui va localiser et surligner les erreurs à la position approximative. Regardez les "listitems", identifiez lequel n'a pas de balise de fermeture et insérez </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 de validation du document de <oXygen/> assure que votre document est compatible avec les règles définies par une DTD, un schéma XML, un schéma Relax NG ou Schematron associé. Les schémas XML Schema ou Relax NG peuvent comporter des règles Schematron. Pour Schematron il est possible de sélectionner la phase de validation.

Use one of the actions for validating the current document:

  • Document+XML Document->Valider le document (Ctrl+Shift+V) or click the toolbar button Valider le document - renvoie une liste-résultat des erreurs dans le panneau message. Le balisage du document est vérifié pour la conformité avec les règles de la DTD, du schéma XML ou du schéma Relax NG spécifié.

  • Document+XML Document->Validation externe or click the toolbar button Validation externe pour afficher le dialogue de Validation externe, utilisé pour sélectionner les schémas externes (XML, Relax NG, NRL, schéma Schematron) et d'exécuter l'opération de validation sur le document actuel en utilisant les schémas sélectionnés. Retourne une liste d'erreurs dans le panneau des messages. Le balisage du document actuel est vérifié pour sa conformité avec les règles des schémas spécifiés.

    Figure 4.22. Le dialogue Validation externe

    Le dialogue Validation externe
  • Document+XML Document->Ouvrir schéma externe or click the toolbar button Ouvrir schéma externe pour ouvrir le schéma utilisé pour la validation du document actuel dans un nouvel éditeur.

  • Select contextual menu of Project Panel,Validate Selection to validate all selected files.

Also you can select several files in the Project panel and validate them with one click by selecting the action Validate selection or the action Validate selection with ... available from the contextual menu of the Project panel.

Exemple 4.3. Message d'erreur Valider document

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 document 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.23. Lien vers la spécification pour les erreurs XML Schema

Lien vers la spécification pour les erreurs XML Schema
Validating XSLT stylesheets

Validation of documents of XSLT stylesheets is performed with the help of a XSLT processor configurable from user preferences according to the XSLT version: 1.0 or 2.0. For XSLT 1.0 the options are: Xalan, Saxon 6.5.4, Saxon 8B, Saxon 8SA (if the user installs it as additional package), a JAXP transformer specified by the main Java class. For XSLT 2.0 the options are: Saxon 8B, Saxon 8SA (if the user installs it as additional package), a JAXP transformer specified by the main Java class.

Document navigation

Navigating between XML elements located in various parts of the currently edited document is easy due to several powerful features.

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.

Figure 4.24. Les signets de l'éditeur

Les signets de l'éditeur

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 (F7)->Création rapide de signets, by clicking the toolbar button 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 à.

Pliage des éléments XML

Les documents XML sont organisés comme un arbre d'éléments. En travaillant sur un grand document vous pouvez réduire certains éléments en ne laissant dans le focus que ceux que vous voulez éditer. Augmenter et réduire fonctionne sur des éléments individuels : augmenter un élément ne change pas l'élément fils.

Figure 4.25. Pliage d'éléments XML

Pliage d'éléments XML

Une fonction unique de <oXygen/> est le fait que les pliages sont persistants : à la prochaine fois que vous ouvrirez le document, les pliages seront restaurés suivant le dernier étant dans lequel vous les aviez laissé. Vous n'avez donc pas besoin de replier à nouveau les parties qui ne vous intéressent pas.

To toggle the folded state of an element click on the special mark displayed in the left part of the document editor next to the start tag of that element or click on the action Basculer le pliage available from the context menu or from the menu Document+Pliage->Basculer le pliage The element extent is marked with a grey line displayed in the left part of the edited document. The grey line covers always the lines of text comprised between the start tag and end tag of the element where it is positioned the cursor.

Other menu actions related to folding of XML elements are available from the context menu of the current editor or from the menu Document->Pliage:

  • Document+Pliage->Réduire les autres pliages (Ctrl+NumPad+/) : Plie toutes les sections moins l'élément actuel.

  • Document+Pliage->Réduire les pliages enfant (Ctrl+NumPad+-) : Plie les sections indentées à un niveau à l'intérieur de l'élément actuel.

  • Document+Pliage->Augmenter les pliages enfant (Ctrl+NumPad++) : Déplie les sections indentées à un niveau dans l'élément actuel.

  • Document+Pliage->Tout augmenter (Ctrl+NumPad+*) : Déplie toutes les sections à l'intérieur de l'élément actuel.

Panneau Contour

Le panneau Contour possède les fonctions suivantes :

Figure 4.26. Le panneau Sommaire

Le panneau Sommaire
Vue d'ensemble du document XML

Le Contour affiche une vue d'ensemble des balises du document XML actuellement édité. Il affiche aussi les dépendances hiérarchiques entre les éléments de balises, facilitant la vue de la structure du document pour l'utilisateur et la façon dont les balises emboîtées.

Suivi de modification

Lors de l'édition, le Contour suit dynamiquement les modifications introduites par l'utilisateur, affichant dans le milieu du panneau le nœud étant actuellement modifié. Ceci donne à l'utilisateur une meilleure idée de l'endroit où il est positionné et comment la structure du document est affectée par ses modifications.

Modification de la structure du document

Des éléments XML entiers peuvent être déplacés ou copiés dans le document édité en utilisant uniquement la souris dans le panneau Sommaire car ce panneau supporte les opérations de Glisser et Déposer. Si vous glissez un élément XML dans le panneau Sommaire et le déposer sur un autre dans le même panneau, alors l'élément glissé sera placé après l'élément cible. Si vous gardez le pointeur de la souris sur la cible pour un courte période afin le dépôt alors l'élément déposé sera augmenté d'abord puis l'élément glissé sera placé à l'intérieur de la cible après la balise d'ouverture. Si vous gardez appuyé la touche CTRL alors une opération de copie aura lieu à la place d'une opération de déplacement.

Sélection de balise du document

Le Contour peut aussi être utilisé pour chercher l'endroit précis d'une balise et du contenu dans le document édité. Intuitivement, en sélectionnant avec le bouton gauche de la souris la balise désirée dans le panneau Contour, le document défile à la position de la balise sélectionnée. De plus, le contenu de la balise est sélectionné, rendant facile de trouver la partie du document contenue par cette balise spécifique et de copier et coller le contenu de la balise dans d'autres endroits du document ou dans d'autres documents.

Navigation buttons

These buttons are available in editor's main toolbar:

  • Go to last modification : Moves the caret to the last modification in any opened document.

  • Back :Moves the caret to the previous position.

  • Forward :Moves the caret to the next position. Enabled after at least one press of "Back" button.

Utiliser le dialogue Aller à

Le dialogue "Aller à ..." disponible au Rechercher->Aller à ... (Ctrl+L (Cmd+L sur Mac)) vous permet d'aller à un endroit précis du document édité en spécifiant une ligne et une colonne ou en utilisant l'offset relatif du début du fichier.

Figure 4.27. Aller à

Aller à

Compléter le dialogue comme suit:

Ligne

Ligne de destination dans le document actuel.

Colonne

La colonne de destination dans le document actuel.

Offset

L'offset de destination relatif au début du document.

Grouping documents in XML projects

Large Documents

Considérons le cas de la documentation d'un gros projet. Il est fort probable que plusieurs personnes y participent. Le document en résultant peut faire plusieurs mégaoctets. Comment gérer cette masse de données sans affecter le parallélisme du travail ?

Heureusement, XML offre une solution pour cela. Un document maître peut être créé, avec des références vers les autres pièces de document, contenant les sections du document. Les utilisateurs peuvent éditer individuellement les sections, puis appliquer FOP ou XSLT sur le document maître pour obtenir les fichiers résultat, par exemple PDF ou HTML.

Two conditions must be fulfilled:

  • Le document maître doit déclarer la DTD à utiliser et les entités externes - les sections. Un document échantillon est :

    <?xml version="1.0" encoding="UTF-8"?> 
    <!DOCTYPE book SYSTEM "../xml/docbookx.dtd" [ 
    <!ENTITY testing SYSTEM "test.xml" > ]
    > 
    <book> 
    <chapter> ...                
    

    On peut insérer à un certain point dans le document maître l'entité de section "test.xml" :

    ... &test; ...

  • Le document contenant la section ne doit pas définir à nouveau la DTD.

    <section> ... voici le contenu de la section ... </section>

    [Note]Note

    La DTD indiquée et les noms des éléments ( "section", "chapter" ) sont seulement utilisés ici pour illustrer le mécanisme d'inclusion. Vous pouvez utiliser n'importe quels noms de DTD et d'élément dont vous avez besoin.

When splitting a large document and including the separate parts in the master file using external entities, only the master file will contain the Document Type Definition (the DTD) or other type of schema. The included sections can't define again the schema because the main document will not be valid. If you want to validate the parts separately you have to use XInclude for assembling the parts together with the master file.

Créer une pièce incluse

Open a new document of type XML, with no associated schema.

Vérifiez que vous avez choisi la bonne schema dans les préférences Tag-Insight / Défaut. Vous pouvez maintenant taper dans le document édité l'élément racine de votre section. Par exemple, si vous utilisez DocBook ça peut être "<chapter></chapter>" or "<section></section>". Maintenant, si vous déplacez le curseur entre les balises et pressez "<", vous verrez la liste des noms d'éléments insérables.

Figure 4.28. Liste Tag-Insight sur un document sans schema

Liste Tag-Insight sur un document sans schema
[Note]Note

La validation ne va pas fonctionner sur un fichier inclus car aucune DTD n'est paramétrée. La validation ne peut être faite que sur le fichier maître. À ce point vous ne pouvez vérifier que la forme du document.

Utiliser le panneau du projet

The Project panel, located on the left-hand side of the main window, is designed to assist the user in organizing and managing related files grouped in the same XML project. The actions available on the context menu and toolbar associated to this panel enable the creation of XML projects and shortcuts to various operations on the project documents.

Figure 4.29. Project Panel

Project Panel

To create a new project select File->New Project or click the toolbar button New Project

To open an existing project select File->Ouvrir un projet ... (Ctrl+F2) or click the toolbar button Open Project or select Fichier->Réouvrir un projet (affiche une liste des fichiers projet récemment ouverts, sélectionnez un fichier à ouvrir).

To save a project on disk select Fichier->Enregistrer le projet (Ctrl+F3) or click the toolbar button Enregistrer le projet

The files are organized in a XML project usually as a collection of folders. There are two types of folders:

  • Logical folders - they are marked with a blue icon and do not have any connection with folders on the disk, creating and deleting them in <oXygen/> does not affect the filesystem on disk.

  • Linked folders - they are marked with a yellow icon and their name and content mirror a real folder existing in the filesystem on disk.

To create a new logical folder select in the contextual menu New Folder or Import Folders or Import Remote Folders or click the Project panel toolbar button New Folder

You can create linked folders by dragging and dropping a folder from the Windows Explorer / Mac OS X Finder over the project tree or by selecting in the contextual menu Link to External Folders

To add one or more files to a folder, right click on it, and choose Add files or Add Edited File or click the toolabr button Add Edited File or right-click on the title of an opened editor and select from the popup menu Add to project or Add all to project.

La cible par défaut lors de l'ajout de fichiers à un projet est la racine du projet. Sélectionner un dossier change la cible au dossier sélectionné. Les fichiers peuvent avoir plusieurs exemplaires dans le dossier système mais ne peuvent apparaître deux fois dans le même dossier.

To remove one or more files and/or folders select them with the mouse in the project tree, right-click to invoke the contextual menu and select the Remove action or press the DELETE key.

Si un dossier d'un projet contient de nombreux documents, un certain document peut être rapidement trouvé dans l'arbre du projet si l'utilisateur sélectionne avec la souris le dossier contenant le fichier désiré (ou un autre document de ce dossier) et tape les premiers caractères du nom du document. Le document désiré sera automatiquement sélectionné dès que les caractères tapés identifieront son nom dans le dossier. Une fois sélectionné, le document peut être ouvert en pressant la touche ENTRÉE ou en double-cliquant dessus ou il peut être effacé en pressant la touche SUPPR ou en choisissant Enlever depuis le menu contextuel.

Les fichiers du projet entier ou d'un dossier d'un projet peuvent être validés vis-à-vis d'un schéma de type Schematron, XML Schema, Relax NG, NRL, ou une combinaison de ce dernier avec Schematron avec un simple clic sur le bouton Valider la sélection. Ceci avec le support du dossier logique du projet vous permet de grouper vos fichiers et de les valider très facilement.

Le chemin complet de fichiers de projet est caché par défaut. Cliquer sur le bouton Afficher/Masquer chemin pour afficher ou non le chemin.

The files and folders that appear as visible in the Project Panel can be filtered. Click the toolbar button Filters to set filter patterns for the files you do not want to show.

Un clic-droit sur n'importe quel objet dans la vue en arbre affiche le menu projet avec les fonctions qui peuvent être exécutées sur cet objet, ou depuis l'objet sélectionné. Les options disponibles depuis le menu projet sont spécifiques au type d'objet sélectionné dans la vue en arbre.

Including document parts with XInclude

XInclude est un standard pour assembler des instances XML dans un autre document XML via l'inclusion. Il permet de créer dynamiquement des grands documents à partir de documents XML plus petits sans avoir à dupliquer physiquement le contenu des petits fichiers dans le fichier principal. L'avantage d'utiliser XInclude est que, contrairement à la méthode des entités, chaque document assemblé peut contenir une Document Type Declaration (DocType Decl.). Cela signifie que chaque fichier peut être une instance XML valide et peut être indépendamment validé. Cela signifie aussi que le document principal dans lequel sont incluses les plus petites instances peut être validé sans avoir à retirer ou mettre en commentaire la DocType Decl. comme c'est le cas avec les entités externes. Cela rend XInclude plus pratique et efficace pour gérer des instances XML qui doivent être à la fois des documents indépendants et des parties d'un document plus important.

Le principal usage de XInclude est pour les frameworks orientés document comme les manuels et les pages web. L'utilisation de XInclude permet aux auteurs et aux gestionnaires de contenu de gérer le contenu de façon modulaire comme on le fait avec les langages de programmation orientée objet comme Java, C++ ou C#.

Les avantages d'une documentation modulaire sont notamment : les unités de contenu réutilisables, plusieurs fichiers plus petits plus aisés à éditer, un meilleur suivi des versions et la possibilité de travailler à plusieurs auteurs.

Un exemple : creez un fichier chaptire et fichier article dans le dossier samples dans le dossier d'installation de <oXygen/> et incluez le fichier chapitre dans le fichier article en utilisant XInclude.

Fichier chapitre introduction.xml:


<?xml version="1.0"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
<chapter>
    <title>Getting started</title>
    <section>
        <title>Section title</title>
        <para>Para text</para>
    </section>
</chapter>

Fichier principal d'article :


<?xml version="1.0"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
"http://www.docbook.org/xml/4.3/docbookx.dtd"
[ <!ENTITY % xinclude SYSTEM "../frameworks/docbook/dtd/xinclude.mod">
%xinclude;
]>
<article>
    <title>Install guide</title>
    <para>This is the install guide.</para>
    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="introduction.xml">
        <xi:fallback>
            <para>
                <emphasis>FIXME: MISSING XINCLUDE CONTENT</emphasis>
            </para>
        </xi:fallback>
    </xi:include>
</article>

  • La DocType Decl. définit une entité qui fait référence à un fichier contenant les informations pour ajouter le namespace xi à certains éléments définis par la DTD Docbook.

  • L'attribut href de l'élément xi:include spécifie que le fichier introduction.xml va remplacer l'élément xi:include quand le document est traité.

  • Si le fichier introduction.xml ne peut être trouvé, la moulinette va utiliser la valeur de l'élément xi:fallback - un message pour FIXME.

Le support de XInclude est par défaut désactivé dans <oXygen/>. Vous pouvez l'activer en aller à l'entrée Activer le traitement XInclude dans le menu Options->Préférences ...+XML / Options de moulinette XML Une fois activé, <oXygen/> pourra valider et transformer les documents comprenant des pièces XInclus.

Utiliser des catalogues XML

When Internet access is not available or the Internet connection is slow the OASIS XML catalogs present in the list maintained in the XML Catalog Preferences panel will be scanned trying to map a remote system ID (at document validation) or a URI reference (at document transformation) pointing to a resource on a remote Web server to a local copy of the same resource. If a match is found then <oXygen/> will use the local copy of the resource instead of the remote one. This enables the XML author to work on his XML project without Internet access or when the connection is slow and waiting until the remote resource is accessed and fetched becomes inacceptable. Also XML catalogs make documents machine independent so that they can be shared by many developers by modifying only the XML catalog mappings related to the shared documents.

<oXygen/> supports any XML catalog file that conforms to one of:

User preferences related to XML Catalogs can be configured from Options -> Preferences ... +XML / XML Catalog

Converting between schema languages

Le convertisseur Trang permet de convertir une schema de DTD ou Relax NG (syntaxe complète ou compacte) ou un ensemble de fichiers XML vers une schema de XML Schéma, DTD ou Relax NG (syntaxe complète ou compacte). Si une équivalence parfaite est impossible à cause de limitations du langage cible, <oXygen/> va générer une approximation de la schema source.

La fonction de conversion est disponible depuis Outils -> Trang Convertisseur ... (Ctrl+Alt+T) from the Project panel contextual menu - the action Open with->Trang Convertisseur and from the toolbar button Convert to ...

Une schema étant éditée peut être convertie avec un click sur un bouton de la barre d'outils si cette schema peut être le sujet d'une conversion supportée. Par ex. si vous pressez le bouton Convertir vers ... tout en éditant un document DTD, le dialogue suivant s'affichera :

Figure 4.30. Convertir une schema éditée

Convertir une schema éditée

Ici vous pouvez régler le langage cible de la conversion et le nom de la schema cible.

Generating HTML documentation for a XML Schema

Pour générer une documentation HTML d'un document schéma XML similar with the Javadoc documentation for Java classes use the dialog Schema documentation. It is opened with the action Outils-> Documentation de schéma... (Ctrl+Alt+S) and enables the user to configure a large set of parameters of the process of generating the HTML documentation.

Figure 4.31. Le dialogue de documentation de XML Schema

Le dialogue de documentation de XML Schema

The text field of the Input panel must contain the full path to the XML Schema (XSD) file, if the schema is composed of only one file, or the full path to the main XSD file of the XML Schema document, that is the file that includes or imports other modules of the document.

<oXygen/> is able to include images of the XML Schema components in the final HTML result. The supported image formats are PNG and JPG. The image of an XML Schema component contains the graphical representation of that component as it is rendered in the Schema Diagram panel of the <oXygen/>'s XSD editor panel. The parameters related to images are:

Diagrams folder

The folder where the images are going to be saved relative to the output file. If there is no folder specified, the images will be saved in the same directory as the output file.

Full model diagrams

Include in the HTML result the representation of each schema component in the <oXygen/>'s Full Model View of the schema.

Logical model diagrams

Include in the HTML result the representation of each schema component in the <oXygen/>'s Logical Model View of the schema.

Image type

One of the PNG or JPG formats.

The Options panel contain parameters for the level of details included in the documentation:

Title

The title displayed at the beginning of the HTML document and in the title bar of the web browser.

Sort by component

If this parameter is set to "true", the schema components are presented sorted by type and name. Otherwise, they are presented in the order that they appear in the schema. By default, this parameter is set to "true."

Use JavaScript

The generated XHTML document uses JavaScript to hide some details like the underlying schema component XML representation, which can be made to appear with a button press. Since some people have ideological objections to JavaScript, this feature can be turned off. If this parameter is set to "true", JavaScript will be used in the generated documentation. Otherwise, it won't. By default, this parameter is set to "true."

Search Included Schemas

If this parameter is set to "true", xs3p will search for components in "included" schemas when creating links and generating the XML Instance Representation table. When this parameter is set to "true", the "linksFile" parameter must also be set, which is described below. Otherwise, an error will be raised. This search is recursive, so schemas "included" in the current schema's "included" schemas will also be searched.

Search Imported Schemas

If this parameter is set to "true", xs3p will search for components in "imported" schemas when creating links and generating the XML Instance Representation table. The above discussion for the "searchIncludedSchemas" parameter also applies to this parameter. Also, when this parameter is set to "true", the "linksFile" parameter must also be set.

Print all super-types

The type hierarchy of a global type definition is displayed in its section. If this parameter is set to "true", all super-types of the current type are shown in the type hierarchy. Otherwise, only the immediate parent type is displayed. By default, this parameter is set to "true."

Print all sub-types

This parameter has a similar concept as printAllSuperTypes. If it is set to "true", all sub-types of the current type are shown in the type hierarchy. Otherwise, only the direct sub-types are displayed. By default, this parameter is set to "true."

Print legend

If this parameter is set to "true", the Legend section is included. Otherwise, it isn't. By default, this parameter is set to "true."

Print glossary

If this parameter is set to "true", the Glossary section is included. Otherwise, it isn't. By default, this parameter is set to "true."

Print NS prefixes

If this parameter is set to "true", namespace information is provided when displaying sample instances and references. This is done by providing a prefix in front of tags and references, which when clicked, will take the user to the declared namespace. The prefix matches the prefix in the namespace declaration in the schema. If not set to "true", namespace prefixes are not displayed. By default, this parameter is set to "true."

The Output panel contains parameters for the output folder and output file:

Output folder

The path of the folder containing the HTML result and the image files.

Generate chunks (Recommended for large schemas)

If it is true the HTML result is organized as a main file containing only a table of contents with links to other HTML documents containing descriptions of the schema components. If it is false all the documentation will be stored in one HTML file.

Use hash codes for component names

If enabled then the achors and links will be generated using the hashcode of the component identifier instead of using the identifier itself. This is useful when the schema componet names contain characters that are not directly supported by the browsers or by the file system.

Generate documentation also for included and imported schemas

It will be generated HTML documentation also for the XML Schemas included or imported by the schema specified in the Input panel.

Generate documentation only for this schema

It will not be generated HTML documentation for the XML Schemas included or imported by the schema specified in the Input panel.

Output file name

The name of the HTML file containing the documentation of the XML Schema

Links file

the file which maps from file locations of "included" and "imported" schemas to the file locations of their xs3p-generated documentation. This file must be provided if either "searchIncludedSchemas" or "searchImportedSchemas" is set to true. If relative addresses are used to specify the location of external xs3p-generated documentation, they must be relative to documentation file currently generated.

[Note]Note

The external documentation files does not need to exist at the time of generating the documentation for the current schema. The mapping is specified in XML. The dtd and schema for this mapping syntax are "links.dtd" and "links.xsd" respectively.

[Note]Note

The "xmlns" namespace attribute with the correct namespace must be provided in the mapping file for the xs3p stylesheet to work.

If it is true the HTML result will be opened with the default Internet browser set in Preferences or with the system application for HTML files.

Editing XML tree nodes

A well-formed XML document can be viewed and edited in <oXygen/> also as a tree of XML elements. This is possible in the Tree Editor perspective available from Perspective->Éditeur d'Arbre... (Ctrl+T) or the toolbar button Éditeur d'Arbre that provides specially designed views and toolbars and an editable tree allowing you to execute common actions for nodes of a tree like create and delete nodes, edit node names, move nodes with drag and drop.

If you want to be able to edit XML documents that are not well-formed all the time and still have a tree view of the document you should use the Outliner panel in the Editor perspective.

Formater et indenter des documents (Pretty Print)

Dans les langages de formatage structurés, l'espace blanc entre les éléments, qui est créé par l'utilisation de la barre d'espacement , Tab ou l'insertion de multiples sauts de ligne par l'utilisation de Entrée, n'est pas reconnu par les outils d'analyse. Ceci signifie souvent que quand des documents structurés sont ouverts, ils sont arrangés comme une seule ligne sans saut de ligne, qui semble être un simple paragraphe.

Même si c'est une pratique tout à fait acceptable, elle rend l'édition difficile et augmente la probabilité d'erreurs introduites. Elle rend aussi l'identification des positions exactes des erreurs plus difficile. Formater et indenter, aussi appelé Pretty Print, permet d'arranger proprement de tels documents, d'une façon qui est consistente et qui facilite la lecture à l'écran et sur l'impression.

Pretty print n'est en aucun cas associé avec la mise en page ou le formatage qui sera utilisée dans le document transformé. Cette mise en page est livrée avec la feuille de style XSL spécifiée au moment de la transformation.

Procédure 4.9. Pour formater et indenter un document :

  1. Ouvrir ou rendre actif le document qui doit être formaté et indenté.

  2. Sélectionner Document->XML Document->Format and Indent (Ctrl+Shift+P) or click the toolbar button Formater et indenter . Durant la progression le panneau message de la barre de statut de l'éditeur indiquera Pretty print en cours. À la fin, Pretty print terminé sera inscrit et le document sera arrangé.

[Note]Note

Pretty Print peut formater des éléments vides comme une balise auto-fermante (par ex. <a/>) ou comme une balise régulière (par ex. <a></a> ). Il peut préserver l'ordre des attributs ou les classer alphabétiquement. Par ailleurs, l'utilisateur peut spécifier une liste d'éléments pour lesquels les espaces vides sont préservés exactement avant le Pretty print et une liste avec des éléments pour lesquels l'espace vide est éliminé. Tout cela peut être configuré depuis Options-> Préférences+Editeur -> Format.

Pretty Print nécessite que le document structuré soit bien formé. Si le document n'est pas bien formé un message d'erreur est affiché. Le message va habituellement indiquer qu'un problème a été trouvée dans la forme et vous conseillera sur le type de problème. Il ne signalera pas la position générale de l'erreur, pour faire ceci utilisez la fonction bien formé en sélectionnant Document->Contrôler que le document est bien formé (Ctrl+Shift+W).

To change the formatting of just one XML element see the action Pretty print element. To change the indenting of the current selected text see the action Indent selection.

For user preferences related to formatting and indenting like Detect indent on open and Indent on paste see the corresponding Preferences panel.

Making a persistent copy of results

To make a persistent copy of the results displayed in the Results panel from operations like document validation, checking the form of documents, XSLT or FO transformation, find all occurances of a string, applying an XPath expression to the current document use one of the actions:

  • Fichier->Enregistrer les résultats - affiche le dialogue Enregistrer les résultats, utilisé pour savuer la liste des résultats de l'onglet message actuellement actif.

  • Fichier->Imprimer les résultats - affiche le dialogue de mise en page pour définir la taille et les propriétés d'orientation de la page pour l'impression de la liste des résultats de l'onglet message actuel.

Locking and unlocking XML markup

For documents with fixed markup such as forms in which the XML tags are not allowed to be modified but only their text content, editing of the XML tag names can be disabled and re-enabled with an action available from Document+Document XML->Verrouiller/Déverrouiller les balises XML or from the toolbar button Verrouiller/Déverrouiller les balises XML

Adjusting the transparency of XML markup

  • Ajusteur du contraste de la transparence->Transparence : Ajuste le contraste de balisage dans la perspective Éditeur.