Copyright © 2021 Yves MARCOUX; dernière modification de cette page: 2021-02-24.

INU3011 Documents structurés

Travailler avec un modèleXML3011

Yves MARCOUX – EBSI – Université de Montréal

Introduction

Un modèleXML3011 est une représentation d’un modèle XML suffisamment riche pour qu’il soit possible d’en dériver automatiquement une DTD commentée et un tableau HTML navigable des différents éléments du modèle. La DTD dérivée automatiquement inclut des commentaires doc: qu’oXygen est capable d’utiliser comme infobulles d’aide à la saisie.

Un modèleXML3011 est lui-même un fichier XML valide selon une DTD. Travailler avec un modèleXML3011 est donc faire du XML au « deuxième degré », dans le sens qu’il s’agit d’un document XML (lui-même conforme à une DTD préexistante : la DTD modeleXML3011.dtd) qui décrit un modèle XML : celui que vous êtes en train de mettre au point.

Créer un modèleXML3011

Avant de créer un modèleXML3011, vous devriez d’abord créer un dossier à l’emplacement de votre choix, qui contiendra tous les fichiers gravitant autour de votre modèle. Nous utilisons D:\monModele comme exemple.

Une fois ce dossier créé, il faut y créer à l’aide d’oXygen un nouveau document XML. Faire Fichier → Nouveau, puis choisir Document XML. Cochez la boîte Enregistrer sous:, et comme emplacement de sauvegarde, inscrivez le chemin d’accès du dossier que vous venez de créer, suivi du nom de fichier EPHN.xml, où vous remplacerez EPHN par le nom de l’élément de plus haut niveau que vous envisagez pour votre modèle. Puisqu’il sert ici de nom de fichier, inscrivez le nom de l’élément sans signe diacritique (accents, cédille, etc.). Si nous comptons utiliser l’élément mémo comme élément de plus haut niveau dans notre modèle, nous inscrirons D:\monModele\memo.xml comme emplacement de sauvegarde :

Cliquer ensuite Personnaliser, puis vis-à-vis URL du schéma, coller l’adresse suivante :

https://cours.ebsi.umontreal.ca/INU3011/modeleXML3011-lite/modeleXML3011.dtd

Vis-à-vis Élément racine, choisissez modèleXML3011.

Enfin, cliquez Créer. Le fichier de votre modèleXML3011 est maintenant créé (D:\monModele\memo.xml dans notre exemple).

Si vous voulez que le correcteur orthographique français d’oXygen soit actif pendant la rédaction de votre modèleXML3011, ajoutez la spécification d’attribut xml:lang="fr" à la balise de début de l’élément de plus haut niveau (modèleXML3011). La balise complète se lira donc comme suit :

<modèleXML3011 xml:lang="fr">

Choisir le mode d’édition

Vous pouvez travailler à la rédaction de votre modèle dans oXygen en mode Auteur ou en mode Texte. Le mode Texte vous fait voir le XML brut de votre modèle, alors que le mode Auteur offre une présentation plus conviviale.

Si vous prévoyez travailler en mode Auteur, associez à votre document la feuille de style CSS appropriée, en faisant :

Document → Document XML → Associer une feuille de style XSLT/CSS

puis en sélectionnant l’onglet CSS et en collant l’adresse suivante comme URL :

https://cours.ebsi.umontreal.ca/INU3011/modeleXML3011-lite/modeleXML3011.css

Une fois cette association faite, vous pouvez passer au mode Auteur en faisant :

Document → Mode Édition → Auteur

Vous pouvez en tout temps pendant la rédaction de votre modèle passer d’un mode d’édition à l’autre grâce à cet item de menu.

Conseils valables dans les deux modes d’édition

En travaillant sur votre modèleXML3011, vous pourrez trouver utile d’ouvrir la vue « Sommaire » dans oXygen, qui vous permettra de naviguer plus facilement dans votre modèle :

Fenêtre → Afficher la vue → Sommaire

Vous pouvez fermer la vue projet pour libérer de l’espace horizontal. Le projet sélectionné demeure actif même avec la vue projet fermée.

Vous pouvez aussi fermer d’autres panneaux verticaux pour maximiser la taille de la fenêtre d’édition.

Conseils pour le mode Auteur

Lorsque vous travaillez en mode Auteur sur votre modèleXML3011, vous pourrez trouver utile d’ouvrir la vue « Éléments » dans oXygen :

Fenêtre → Afficher la vue → Éléments

Cette vue vous montrera en tout temps la liste des éléments qu’il serait permis d’insérer comme enfants de l’élément courant (celui où se trouve la position actuelle du curseur). Pour insérer un élément-enfant à la position courante du curseur, double-cliquez sur cet élément dans la vue « Éléments ». Lorsqu’un élément apparaît grisé, c’est qu’il est déjà présent dans le document et n’est pas répétable.

Les réglages suivants sont également recommandés en mode Auteur. Faites d’abord :

Options → Préférences → Éditeur → Modes d’édition → Auteur

puis, à la section Balises, comme « Mode d’affichage des balises », choisissez Toutes les balises, et cochez la boîte « Agencement compact des balises ».

Rédaction du modèle

La première chose à faire est de renseigner l’élément membre visible au début du document avec les prénom, nom et matricule UdeM d’un premier membre de l’équipe. Ajoutez un deuxième élément membre à la suite du premier, puis renseignez-le avec les informations de l’autre coéquipier.

Dans l’élément contexteDuModèle, inscrivez une courte description du contexte de création du modèle : pour le compte de qui il a été développé, dans quel but, quelles en sont les principales caractéristiques. Même si le contexte est fictif, vous le présentez ici comme réel. Vous pouvez structurer la description en paragraphes (para) si nécessaire. Vous pouvez aussi utiliser des listes (liste), mettre l’emphase sur certains passages (em) et inclure des URL (url), qui seront transformées en liens cliquables dans le tableau navigable.

Dans l’élément EPHN, inscrivez le nom de l’élément de plus haut niveau de votre modèle. Normalement, ce nom sera identique au nom du fichier XML que vous venez de créer (moins l’extension .xml et sans nécessité d’éliminer les signes diacritiques). Dans notre exemple, ce sera mémo.

Ensuite, pour chaque élément de votre modèle, renseignez un élément élément. Les informations à fournir sont clairement identifiées et documentées par des infobulles. Le modèleContenuXML est le modèle de contenu tel qu’il devrait se retrouver dans la déclaration ELEMENT de l’élément (y compris les éventuelles parenthèses). Le modèle de contenu n’est pas validé ici; il ne le sera qu’une fois la DTD produite et ouverte dans oXygen. Il peut être une bonne idée de valider le modèle de contenu dans un fichier de DTD de test avant de l’inscrire dans modèleContenuXML.

Les exemplesContenuAttendu (exemples de contenu attendu) sont obligatoires pour les éléments dont le modèle de contenu est mixte ou (#PCDATA). Notez que ceci n’est pas validé par la DTD modeleXML3011.dtd; vous devez donc vous assurer vous-même d’inclure les exemples dans ces cas. Pour les autres éléments, ces exemples sont facultatifs.

Les attributs d’un élément, s’il y en a, sont décrits dans une section facultative attributs, qui est le dernier sous-élément de l’élément élément.

Pour chaque attribut, après son nom et sa description pour infobulle, le type est spécifié en choisissant parmi les sous-éléments NMTOKEN, énuméré et CDATA. Ensuite, la mention de valeur par défaut est spécifiée en choisissant parmi les sous-éléments REQUIRED, FIXED, IMPLIED et valeurParDéfaut. Les exemples de contenu attendu sont obligatoires pour chaque attribut, sauf ceux de type énuméré ou qui ont une valeur fixe (FIXED).

Tant pour un élément que pour un attribut, vous avez la possibilité d’inscrire des commentaires de modélisation (à l’intention de quiconque essaie de comprendre votre modèle, notamment, dans le cadre du cours, le correcteur) dans le sous-élément commentairesDeModélisation. Ces commentaires sont entièrement facultatifs, mais ils peuvent s’avérer utiles pour donner des explications dans le contexte précis d’un élément ou d’un attribut de votre modèle, par exemple la justification d’une décision de modélisation. Vous pouvez structurer vos commentaires en paragraphes (para) si nécessaire. Vous pouvez aussi utiliser des listes (liste), mettre l’emphase sur certains passages (em) et inclure des URL (url), qui seront transformées en liens cliquables dans le tableau navigable.

Produire les fichiers dérivés (DTD et tableau navigable)

Un des avantages de travailler avec un modèleXML3011 est qu’il est possible, à partir de cette source unique, de produire automatiquement une DTD commentée et un tableau navigable des éléments du modèle. Pour dériver ces fichiers, récupérez d’abord le projet oXygen modeleXML3011.xpr à partir de ce lien, et sauvegardez-le dans votre dossier de modèle (D:\monModele dans nos exemples). Ouvrez ensuite ce projet dans oXygen :

Projet → Ouvrir le projet

puis choisir le fichier modeleXML3011.xpr tout juste téléchargé.

Une fois cette opération complétée, pour produire les fichiers dérivés correspondant à votre modèle, sélectionnez l’onglet d’oXygen où se trouve votre modeleXML3011, puis cliquez sur l’outil . La fenêtre de configuration des scénarios de transformation s’ouvre :

Cochez la ou les cases correspondant au(x) fichier(s) dérivé(s) que vous voulez produire (DTD et/ou Table = tableau HTML navigable), puis cliquez sur Appliquer le/les scénario(s) associé(s).

Les fichiers dérivés sont créés dans le même dossier que le modeleXML3011 (c’est-à-dire D:\monModele dans nos exemples). Le nom de fichier est le même que le modèleXML3011 (memo dans nos exemples), mais avec l’extension .dtd pour la DTD et .html pour le tableau navigable.

Annexe – Exemple de modèle et de fichiers dérivés

Le modèleXML3011

Cet exemple se trouve au memo.xml (faites afficher la source pour voir le XML brut) :

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE modèleXML3011 SYSTEM "http://cours.ebsi.umontreal.ca/INU3011/modeleXML3011-lite/modeleXML3011.dtd">
<?xml-stylesheet type="text/css" href="https://cours.ebsi.umontreal.ca/INU3011/modeleXML3011-lite/modeleXML3011.css"?>
<modèleXML3011 xml:lang="fr">
  <équipe>
    <membre>
      <prénom>Charles</prénom>
      <nomFamille>Goldenfarb</nomFamille>
      <matriculeUdeM>12345</matriculeUdeM>
    </membre>
    <membre>
      <prénom>John</prénom>
      <nomFamille>Bozak</nomFamille>
      <matriculeUdeM>23456</matriculeUdeM>
    </membre>
  </équipe>
  <contexteDuModèle>
    <para>Ce modèle définit une structure de mémos pour un système de rédaction, d’envoi
      et de gestion de mémos à l’EBSI <url>http://www.ebsi.umontreal.ca/</url>.</para>
  </contexteDuModèle>
  <EPHN>mémo</EPHN>
  <éléments>
    <élément>
      <idGen>mémo</idGen>
      <descriptionPourInfobulle>Un mémo de l’EBSI.</descriptionPourInfobulle>
      <modèleContenuXML>(priorité, auteur, date?, destinataires, sujet, cc?, corps?)</modèleContenuXML>
      <attributs>
        <attribut>
          <nom>statut</nom>
          <descriptionPourInfobulle>Statut du mémo: en détermine la visibilité.</descriptionPourInfobulle>
          <énuméré>
            <valeurPossible>confidentiel</valeurPossible>
            <valeurPossible>interne</valeurPossible>
            <valeurPossible>public</valeurPossible>
          </énuméré>
          <valeurParDéfaut>interne</valeurParDéfaut>
          <commentairesDeModélisation>Nous avons hésité entre "statut" et "visibilité"
            comme nom d’attribut, mais avons opté pour "statut" car c’est l’appellation la
            plus courante à l’EBSI.</commentairesDeModélisation>
        </attribut>
        <attribut>
          <nom>pj</nom>
          <descriptionPourInfobulle>Nom de fichier d’une éventuelle pièce jointe.</descriptionPourInfobulle>
          <CDATA/>
          <IMPLIED/>
          <exemplesValeurAttendue>
            <exemple>rapport.pdf</exemple>
            <exemple>photo-2019.jpeg</exemple>
          </exemplesValeurAttendue>
        </attribut>
        <attribut>
          <nom>org</nom>
          <descriptionPourInfobulle>Valeur fixe "EBSI" identifie le mémo comme émanant de l’EBSI.</descriptionPourInfobulle>
          <NMTOKEN/>
          <FIXED>EBSI</FIXED>
        </attribut>
      </attributs>
    </élément>
    <élément>
      <idGen>priorité</idGen>
      <descriptionPourInfobulle>Priorité d’envoi du mémo.</descriptionPourInfobulle>
      <modèleContenuXML>( normal | urgent | vrac )</modèleContenuXML>
    </élément>
    <élément>
      <idGen>normal</idGen>
      <descriptionPourInfobulle>Priorité normale d’envoi.</descriptionPourInfobulle>
      <modèleContenuXML>EMPTY</modèleContenuXML>
    </élément>
    <élément>
      <idGen>urgent</idGen>
      <descriptionPourInfobulle>Priorité maximale, pour messages urgents.</descriptionPourInfobulle>
      <modèleContenuXML>EMPTY</modèleContenuXML>
    </élément>
    <élément>
      <idGen>vrac</idGen>
      <descriptionPourInfobulle>Priorité minimale, pour envois en lot.</descriptionPourInfobulle>
      <modèleContenuXML>EMPTY</modèleContenuXML>
    </élément>
    <élément>
      <idGen>destinataires</idGen>
      <descriptionPourInfobulle>Liste des destinataires directs du mémo.</descriptionPourInfobulle>
      <modèleContenuXML>(nom+)</modèleContenuXML>
    </élément>
    <élément>
      <idGen>cc</idGen>
      <descriptionPourInfobulle>Liste des récipiendaires d’une copie conforme du mémo.</descriptionPourInfobulle>
      <modèleContenuXML>(nom+)</modèleContenuXML>
    </élément>
    <élément>
      <idGen>corps</idGen>
      <descriptionPourInfobulle>Corps du mémo (peut être omis si la ligne sujet suffit).</descriptionPourInfobulle>
      <modèleContenuXML>(par+)</modèleContenuXML>
    </élément>
    <élément>
      <idGen>auteur</idGen>
      <descriptionPourInfobulle>Nom de l’auteur du mémo, sous la forme Prénom Nom, sans ponctuation finale.</descriptionPourInfobulle>
      <modèleContenuXML>(#PCDATA)</modèleContenuXML>
      <exemplesContenuAttendu>
        <exemple>Jean K. Vanier</exemple>
        <exemple>Marie Hélène Vanier</exemple>
        <exemple>Gilles-A. Tremblay</exemple>
      </exemplesContenuAttendu>
      <attributs>
        <attribut>
          <nom>courriel</nom>
          <descriptionPourInfobulle>Adresse courriel de l’auteur.</descriptionPourInfobulle>
          <CDATA/>
          <REQUIRED/>
          <exemplesValeurAttendue>
            <exemple>jack.rabbit@ebsi.com</exemple>
            <exemple>jean_valjean@victor.hugo.net</exemple>
          </exemplesValeurAttendue>
          <commentairesDeModélisation>
            <para>L’adresse courriel est exigée pour l’auteur d’un mémo, de sorte que le
              système de gestion des mémos puisse procéder à l’envoi par courriel aux
              récipiendaires dont l’adresse est précisée.</para>
            <para>En effet, les systèmes d’acheminement du courriel <em>exigent</em> de
              connaître l’adresse de l’expéditeur. L’adresse courriel de l’auteur est donc
              essentielle.</para>
          </commentairesDeModélisation>
        </attribut>
      </attributs>
    </élément>
    <élément>
      <idGen>date</idGen>
      <descriptionPourInfobulle>Date de rédaction du mémo, forme AAAA-MM-JJ.</descriptionPourInfobulle>
      <modèleContenuXML>(#PCDATA)</modèleContenuXML>
      <exemplesContenuAttendu>
        <exemple>2020-09-30</exemple>
        <exemple>1970-01-01</exemple>
      </exemplesContenuAttendu>
    </élément>
    <élément>
      <idGen>sujet</idGen>
      <descriptionPourInfobulle>Sujet du mémo (habituellement sans ponctuation finale).</descriptionPourInfobulle>
      <modèleContenuXML>(#PCDATA)</modèleContenuXML>
      <exemplesContenuAttendu>
        <exemple>Convocation à l’assemblée générale</exemple>
        <exemple>Nouvelle recrue</exemple>
        <exemple>Party de Noël !</exemple>
      </exemplesContenuAttendu>
    </élément>
    <élément>
      <idGen>nom</idGen>
      <descriptionPourInfobulle>Nom d’un récipiendaire du mémo, sous la forme Prénom Nom, sans ponctuation finale.</descriptionPourInfobulle>
      <modèleContenuXML>(#PCDATA)</modèleContenuXML>
      <exemplesContenuAttendu>
        <exemple>Jean K. Vanier</exemple>
        <exemple>Marie Hélène Vanier</exemple>
        <exemple>Gilles-A. Tremblay</exemple>
      </exemplesContenuAttendu>
      <attributs>
        <attribut>
          <nom>courriel</nom>
          <descriptionPourInfobulle>Adresse courriel de la personne.</descriptionPourInfobulle>
          <CDATA/>
          <IMPLIED/>
          <exemplesValeurAttendue>
            <exemple>jack.rabbit@ebsi.com</exemple>
            <exemple>jean_valjean@victor.hugo.net</exemple>
          </exemplesValeurAttendue>
        </attribut>
      </attributs>
    </élément>
    <élément>
      <idGen>par</idGen>
      <descriptionPourInfobulle>Un paragraphe de texte; peut contenir des passages en emphase (sous-élément <em>).</descriptionPourInfobulle>
      <modèleContenuXML>(#PCDATA | em)*</modèleContenuXML>
      <exemplesContenuAttendu>
        <exemple>L’Université s’est démarquée aux derniers Jeux du commerce.</exemple>
        <exemple><![CDATA[La situation est jugée <em>très</em> préoccupante.]]></exemple>
      </exemplesContenuAttendu>
    </élément>
    <élément>
      <idGen>em</idGen>
      <descriptionPourInfobulle>Passage en emphase.</descriptionPourInfobulle>
      <modèleContenuXML>(#PCDATA)</modèleContenuXML>
      <exemplesContenuAttendu>
        <exemple>ATTENTION :</exemple>
        <exemple>très</exemple>
        <exemple>sans prévenir le registrariat !</exemple>
      </exemplesContenuAttendu>
    </élément>
  </éléments>
</modèleXML3011>

La DTD dérivée

Cet exemple se trouve au memo.dtd :

<?xml version="1.0" encoding="UTF-8"?>
<!-- Modèle XML développé dans le cadre du cours INU3011 Documents structurés -->
<!-- EBSI - Université de Montréal -->

<!-- Équipe: John Bozak (23456), Charles Goldenfarb (12345). -->
<!-- Élément de plus haut niveau: mémo -->

<!--
Les commentaires commençant par "doc:" sont utilisés par oXygen comme documentation d’aide à la
saisie. Ils sont affichés en infobulles pendant l’édition de documents conformes à la DTD lorsque le
curseur survole un nom d’élément ou d’attribut.
-->

<!-- doc: Un mémo de l’EBSI. -->
<!ELEMENT mémo (priorité, auteur, date?, destinataires, sujet, cc?, corps?)>

<!-- doc: Valeur fixe "EBSI" identifie le mémo comme émanant de l’EBSI. -->
<!ATTLIST mémo org NMTOKEN #FIXED "EBSI">

<!-- doc: Nom de fichier d’une éventuelle pièce jointe. Exemples:
  rapport.pdf
  photo-2019.jpeg -->
<!ATTLIST mémo pj CDATA #IMPLIED>

<!-- doc: Statut du mémo: en détermine la visibilité. -->
<!ATTLIST mémo statut (confidentiel | interne | public) "interne">

<!-- doc: Priorité d’envoi du mémo. -->
<!ELEMENT priorité ( normal | urgent | vrac )>

<!-- doc: Priorité normale d’envoi. -->
<!ELEMENT normal EMPTY>

<!-- doc: Priorité maximale, pour messages urgents. -->
<!ELEMENT urgent EMPTY>

<!-- doc: Priorité minimale, pour envois en lot. -->
<!ELEMENT vrac EMPTY>

<!-- doc: Liste des destinataires directs du mémo. -->
<!ELEMENT destinataires (nom+)>

<!-- doc: Liste des récipiendaires d’une copie conforme du mémo. -->
<!ELEMENT cc (nom+)>

<!-- doc: Corps du mémo (peut être omis si la ligne sujet suffit). -->
<!ELEMENT corps (par+)>

<!-- doc: Nom de l’auteur du mémo, sous la forme Prénom Nom, sans ponctuation finale. Exemples:
  Jean K. Vanier
  Marie Hélène Vanier
  Gilles-A. Tremblay -->
<!ELEMENT auteur (#PCDATA)>

<!-- doc: Adresse courriel de l’auteur. Exemples:
  jack.rabbit@ebsi.com
  jean_valjean@victor.hugo.net -->
<!ATTLIST auteur courriel CDATA #REQUIRED>

<!-- doc: Date de rédaction du mémo, forme AAAA-MM-JJ. Exemples:
  2020-09-30
  1970-01-01 -->
<!ELEMENT date (#PCDATA)>

<!-- doc: Sujet du mémo (habituellement sans ponctuation finale). Exemples:
  Convocation à l’assemblée générale
  Nouvelle recrue
  Party de Noël ! -->
<!ELEMENT sujet (#PCDATA)>

<!-- doc: Nom d’un récipiendaire du mémo, sous la forme Prénom Nom, sans ponctuation finale. Exemples:
  Jean K. Vanier
  Marie Hélène Vanier
  Gilles-A. Tremblay -->
<!ELEMENT nom (#PCDATA)>

<!-- doc: Adresse courriel de la personne. Exemples:
  jack.rabbit@ebsi.com
  jean_valjean@victor.hugo.net -->
<!ATTLIST nom courriel CDATA #IMPLIED>

<!-- doc: Un paragraphe de texte; peut contenir des passages en emphase (sous-élément <em>). Exemples:
  L’Université s’est démarquée aux derniers Jeux du commerce.
  La situation est jugée <em>très</em> préoccupante. -->
<!ELEMENT par (#PCDATA | em)*>

<!-- doc: Passage en emphase. Exemples:
  ATTENTION :
  très
  sans prévenir le registrariat ! -->
<!ELEMENT em (#PCDATA)>

Le tableau HTML navigable dérivé

Cet exemple se trouve au memo.html :