Tutoriel : ajouter un nouveau domaine

Comprendre comment ajouter un nouveau domaine à un document-type existant.

Durée : 75 mn 
Objectifs :
Contenus :
Dans ce tutoriel, on va créer un domaine "cuisine" dans lequel on spécialisera un élément ph (phrase) en un élément ustensil, pour coder des phrases de type
<p>Prendre une <ustensil>louche</ustensil> et prélever une partie du bouillon pour le faire réduire.</p>

Ajouter un domaine

Mode opératoire

Création d’un nouvel élément

Syntaxe de la spécialisation

Création d'un domaine "cuisine"

Le module se dénomme cuisine. Les noms de fichier utiliseront la racine cuisineDomain et toute abréviation commencera par cuis.

Dans ce tutoriel, il faudra créer deux fichiers cuisineDomain.ent et cuisineDomain.mod puis les faire prendre en compte par le DITA-OT et ensuite les intégrer à notre type de document concept.

Procédure :

    Organisation des répertoires et du catalogue

  1. Dans le répertoire doctypes créez un répertoire cuisineDomain puis un répertoire dtd.
  2. Dans cuisineDomain/dtd, créez les fichiers cuisineDomain.mod et cuisineDomain.ent :
    1. Dans Oxygen, créez un nouveau document
    2. Dans la fenêtre, choisir le type "document type definition"
    3. Enregistrez le premier fichier et répétez l'opération pour le second.
  3. Comme dans le précédent tutoriel, dans cuisineDomain, créez un catalogue (catalog.xml).
  4. Ajoutez une entrée dans le catalogue de la racine du plugin.
  5. Dans le catalogue du domaine, ajoutez deux entrées pour identifier les fichiers du domaine :
    1. <public publicId="urn:pubid:fr:masociete.doctypes:cuisineDomain.entites" uri="./dtd/cuisineDomain.ent"/>
    2. <public publicId="urn:pubid:fr:masociete.doctypes:cuisineDomain.modules" uri="./dtd/cuisineDomain.mod"/>
  6. Lancez l'intégrateur.
  7. Paramétrage des entités

  8. Ouvrir cuisineDomain.ent. Dans ce fichier, il va falloir créer les entités du domaine, qui seront ensuite utilisées pour l'intégration du domaine.
  9. Déclarez l'entité de spécialisation de ph : <!ENTITY % cuis-d-ph "ustensil " > .
  10. Déclarez l'entité de définition du nouveau domaine (vocabulaire) : <!ENTITY cuis-d-att "(topic cuis-d)" >.
    On notera que cette entité est générale et sera utilisée au moment du parsing des documents, pas des modèles. Une erreur fréquente consiste à taper juste après la déclaration <!ENTITY un signe %, alors que l'on cherche une entité générale.
  11. Déclaration de ustensil

  12. Ouvrir cuisineDomain.mod
  13. Déclarez une entité de définition de l'élément que vous ajoutez : <!ENTITY % ustensil "ustensil" >. Cette entité sert à des redéfinitions ultérieures (voir les explications d'E. Kimber sur le sujet).
  14. Déclarez l'élément
    1. Déclaration d'une entité paramètre pour le contenu : <!ENTITY % ustensil.content "(#PCDATA | %text;)*">
      Avec cette déclaratrion, on pourra saisir du texte mixé à tous les éléments accessibles via l'entité paramètre text.
    2. Déclaration d'une entité paramètre pour les attributs : <!ENTITY % ustensil.attributes "keyref CDATA #IMPLIED %univ-atts; outputclass CDATA #IMPLIED" >
    3. Déclaration de l'élément : <!ELEMENT ustensils %ustensil.content;>
    4. Déclaration des attributs : <!ATTLIST ustensils %ustensil.attributes;>
    Cette structure imposée par le standard permet, par la suite, de spécialiser les attributs ou le contenu de ustensil.
  15. Déclarez l'héritage de l'élément : <!ATTLIST ustensil %global-atts; class CDATA "+ topic/ph cuis-d/ustensil " >
    • @class : le caractère + indique que l'on est dans une spécialisation de domaine (- pour les structures de contenus)
    • les espaces avant et après cuis-d/ustensil sont utiles pour les chemins XPATH définis par comparaison de chaîne de caractères.
    • %global-atts; ajoute des attributs de "debug" : xtrf (xml-trace-filename) et xtrc (xml-trace-counter).

    La structure fnale est donc :

    <!ENTITY % ustensil.content "(#PCDATA | %text;)*">
    <!ENTITY % ustensil.attributes
                 "keyref  CDATA  #IMPLIED
                  %univ-atts; 
                  outputclass  CDATA #IMPLIED"
    >
    
    <!ELEMENT ustensil    %ustensil.content;>
    <!ATTLIST ustensil    %ustensil.attributes;>
    
    <!ATTLIST ustensil %global-atts;  class CDATA "+ topic/ph cuis-d/ustensil "  >
  16. Intégration du domaine de cuisine dans le topic concept

  17. Rouvrir concept.dtd, puis, dans l'ordre :
  18. Intégrez le jeu d'entités cuisineDomain.ent en utilisant son nom public.
    <!ENTITY % cuis-d-dec     
      PUBLIC "urn:pubid:fr:masociete.doctypes:cuisineDomain.entites" 
             "../../cuisineDomain/dtd/Domain.ent"                                              
    >%cuis-d-dec;
  19. Redéfinissez l'entité paramètre %ph;
    <!ENTITY % ph "ph | %hi-d-ph; | %cuis-d-ph; | %sw-d-ph; | %ui-d-ph; ">
  20. Ajoutez la déclaration du domaine
    <!ENTITY included-domains "
    &concept-att; &hi-d-att; &ut-d-att; &indexing-d-att; 
    &hazard-d-att; &abbrev-d-att; &sw-d-att; &ui-d-att; 
    &cuis-d-att; " 
    >
    Note : comme précédemment, on intègre ici via une entité générale.
  21. Intégrez la définition des éléments (cuisineDomain.mod) en utilisant son nom public.
    <!ENTITY % cuis-d-def     
      PUBLIC "urn:pubid:fr:masociete.doctypes:cuisineDomain.modules" 
             "cuisineDomain.mod"
    >%cuis-d-def;
    La DTD doit maintenant être valide.
  22. Testez l'intégration en ajoutant un élément ustensil dans un paragraphe p.
    Ceci doit être possible et le document résultant doit être valide.
Résultat :
  • Tout prochain ajout d'un élément au domaine sera automatiquement pris en compte dans concept.dtd, si tant est que, dans la DTD, l'entité paramètre de prise en compte est bien redéfinie (%ph; ou %pre; ou %keyword; ...).
  • Dans l'état actuel de la technologie (utilisation de DTD), ceci est à refaire pour tous les document type shell utilisant le domaine cuisine.