Tutoriel : ajouter un nouveau domaine

Ajouter un domaine

Trois interventions
- Déclaration des entités du domaine
  - Par exemple les nouvelles « phrases » du domaine « software » :
  - <!ENTITY % sw-d-ph "filepath | msgph | systemoutput | userinput">
  - Dans un fichier externe (softwareDomain.ent)
- Assemblage des entités du domaine par surcharge d’entités
  - <!ENTITY % ph "ph | %hi-d-ph; | %pr-d-ph; | %sw-d-ph; | %ui-d-ph;">
  - Dans la DTD
- Gérer les modules du topic
  - <!ENTITY included-domains &concept-att; &hi-d-att; &ut-d-att; &indexing-d-att; &hazard-d-att; &abbrev-d-att; &pr-d-att; (topic sw-d) &ui-d-att; ">
  - Attention ! Ici on utilise des entités générales
  - Dans la DTD
- Création du module déclarant les éléments du domaine
  - Déclarer les éléments du domaine
  - Dans un fichier externe (softwareDomain.mod)
Rappel DTD
- Toute entité utilisée doit être déclarée au préalable
- Si une entité est déclarée plusieurs fois, c’est sa première déclaration rencontrée qui prime

Mode opératoire

Pour ajouter un domaine, il faut créer deux nouveaux fichiers
- cuisineDomain.ent
  - Déclaration des entités
    - Utile pour surcharger
    - Exemple de surcharge de ph : <!ENTITY % ph "ph | %hi-d-ph; | %cuis-d-ph; | %sw-d-ph; | ui-d-ph; ">
  - Déclaration du domaine lui-même
- cuisineDomain.mod
  - Déclaration des modèles de contenus des éléments
Puis faire prendre en compte ce domaine par tous les types de document concernés
- Intervention au niveau du (des) doctype(s) concerné(s).

Création d’un nouvel élément

Dans un fichier xxx.mod

Une structure toujours identique

<!ENTITY % montruc.content "(%words.cnt;)*">
<!ENTITY % montruc.attributes "%univ-atts; outputclass CDATA #IMPLIED">

<!ELEMENT montruc %montruc.content;>
<!ATTLIST montruc %montruc.attributes;>

Basée sur l’utilisation d’entités pour surcharger
- Contraindre l’élément montruc = redéfinir %montruc.content;

Syntaxe de la spécialisation

La spécialisation est formellement définie par l’attribut @class
Tout élément DITA doit avoir un attribut @class
Contenu de l’attribut
- “+” (spécialisation de domaine) ou “-” (spécialisation de structure)
- Suivi d’une succession de couples qui décrivent la structure d’héritage
  - Du moins spécialisé au plus spécialisé
  - Couple =
    - Nom de l’élément racine
    - Nom de l’élément spécialisé
Exemple :
- class="- topic/title concept/title glossentry/glossterm "
Dans la pratique
- Ne pas oublier l’espace à la fin de l’attribut
- Un seul espace entre chaque couple

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

Dans le répertoire doctypes créez un répertoire cuisineDomain puis un répertoire dtd.
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.
Comme dans le précédent tutoriel, dans cuisineDomain, créez un catalogue (catalog.xml).
Ajoutez une entrée dans le catalogue de la racine du plugin.
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"/>
Lancez l'intégrateur.

Paramétrage des entités

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.
Déclarez l'entité de spécialisation de ph : <!ENTITY % cuis-d-ph "ustensil " > .
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.

Déclaration de ustensil

Ouvrir cuisineDomain.mod
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).
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.
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 "  >
```

Intégration du domaine de cuisine dans le topic concept

Rouvrir concept.dtd, puis, dans l'ordre :

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;

Redéfinissez l'entité paramètre %ph;

<!ENTITY % ph "ph | %hi-d-ph; | %cuis-d-ph; | %sw-d-ph; | %ui-d-ph; ">

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.

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