Tutoriel : contraindre dans DITA

Tutoriel : contraindre le modèle de l'élément `<section>`

la finalité de ce tutoriel est de contraindre le modèle de contenu des sections pour avoir toujours un titre (title) suivi seulement d'éléments "bloc".

Procédure :

Organiser le répertoire doctypes

Dans le répertoire doctype, créez les sous-répertoires contraintes et dtd à l'intérieur.
Dans ce nouveau répertoire DTD, créez à partir d'Oxygen le fichier sectionTopicConstraint.mod en utilisant toujours le type "document type definition".
Ajustez le catalog du plugin pour pointer vers le catalog du module.

Mettre en place le catalog du module

<?xml version="1.0" encoding="UTF-8"?>
<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog" prefer="public">
    <public 
       publicId="urn:pubid:fr:masociete.doctypes:sectionTopicConstraint.modules" 
       uri="./dtd/sectionTopicConstraint.mod"/>
</catalog>

Relancer l'intégrateur du DITA-OT

Mettre en place le domaine de contrainte

Dans le fichier sectionTopicConstraint.mod, préparez la déclaration du nouveau module : <!ENTITY section-constraints "(topic section-sans-bloc-c)">.
C'est cette entité générale qui sera utilisée pour inclure ce nouveau domaine de contrainte.
Vous allez maintenant déclarer le modèle de contenu d'une section. Pour cela, il faudra redéfinir l'entité paramètre %section.content;.
Trouvez dans le répertoire dtd du DITA-OT l'endroit où est défini section.content :
1. Dans le menu fichier sélectionnez rechercher/remplacer dans les fichiers
2. Une fenêtre s'ouvre, sélectionnez les différentes options tel que le surligné dans la figure ci-dessous (attention, mettre un espace entre % et section.content)
3. Cliquez sur "rechercher tout".
4. Dans la fenêtre de résultats de recherche, en bas de l'écran, double-cliquez sur le mot trouvé (dans topic.mod).
Le fichier s'ouvre et la définition est : <!ENTITY % section.content "(%section.cnt;)*" >. Pour comprendre le modèle de contenu standard d'une section, il faut donc chercher la définition de %section.cnt;, obligatoirement en amont de l'utilisation de cette entité paramètre.
Comme l'entité est définie dans le même fichier, on peut se déplacer au début de topic.mod et lancer une recherche de "% section.cnt.
Le résultat est :
```
<!ENTITY % section.cnt "#PCDATA | %basic.block; | %basic.ph; | 
  %data.elements.incl; | %foreign.unknown.incl; | %sectiondiv; | 
  %title; | %txt.incl; " >
```
On aurait donc envie de simplement déclarer :
```
<!ENTITY % section.content "(%title; , (%basic.block;)+)" >
```
Malheureusement, ce n'est pas si simple du fait de la règle inamovible des DTD, qui dit que toute entité appelée doit être déclarée au préalable.
De fait, on se retrouve devant le choix contradictoire suivant :
- On doit définir section.content avant que cela soit défini par les modules de base du standard DITA. L'appel de notre fichier sectionTopicConstraint.mod ne peut donc que se faire avant l'appel des modules de base.
- Cependant pour définir le contenu, on utilise des entités paramètres DITA de base et il faudrait donc en toute logique faire l'appel de notre module sectionTopicConstraint.mod après l'appel des modules de base.
Du coup, il faut se ramener à des spécifications compatibles avec les DTD, tout en essayant de conserver la possibilité de spécialiser.
Créez l'entité section.content en vous ramenant aux éléments atomiques mais en se réservant leur potentielle redéfinition.
```
<!ENTITY % title "title" >
<!ENTITY % dl "dl">
<!ENTITY % fig "fig">
<!ENTITY % imagemap "imagemap">
<!ENTITY % image "image">
<!ENTITY % lines "lines">
<!ENTITY % note "note">
<!ENTITY % object "object">
<!ENTITY % ol "ol">
<!ENTITY % p "p">
<!ENTITY % pre "pre">
<!ENTITY % simpletable "simpletable">
<!ENTITY % sl "sl">
<!ENTITY % table "table">
<!ENTITY % ul "ul" >
<!ENTITY % section.content "(%title; , (%dl;| %fig;| %imagemap;|
%image;| %lines;| %note; | %object;| %ol;| %p;| %pre;|
%simpletable;| %sl;| %table;| %ul;)+)" >
```
La solution manque d'élégance car elle est difficilement maintenable dès lors que l'on fait évoluer de façon directe ou indirecte les contenus de %basic.block;.

Peut-être vaut-il alors mieux spécialiser le nom de l'élément lui-même : le fichier module résultant pourra alors être appelé après la définition de toutes les entités paramètres de base.

Intégrer le module de contrainte

Dans le fichier concept.dtd, ajoutez l'entité générale &section-constraints; à l'entité générale included-domains.
Le fait que l'entité &section-constraints; soit générale permet d'utiliser une entité avant sa déclaration car, de fait, included-domains sera uniquement utilisé au moment du parsing d'un fichier document (.dita).
Incluez le fichier sectionTopicConstraint.mod de contrainte dans la partie "CONTENT CONSTRAINT INTEGRATION" :
1. Créez la déclaration de l'entité paramètre : <!ENTITY % sectionTopicConstraint-c-def PUBLIC "urn:pubid:fr:masociete.doctypes:sectionTopicConstraint.modules" "../../contraintes/dtd/sectionTopicConstraint.mod">
2. Puis inclure cette entité paramètre : %sectionTopicConstraint-c-def ;
Vous pouvez maintenant tester votre intégration.

Tester l'intégration d'une contrainte

Ouvrir le fichier test.dita
Se positionner à la fin de celui-ci, juste avant la clôture de l'élément conbody et insérez un élément section.
Validez le modèle de contenu de celui-ci et validez l'impossibilité de saisir directement du texte dans cette section.

Résultat :

Finalement, la double difficulté, quand on contraint, est de :

respecter le modèle de ce que l'on contraint. Pour ce faire, il faut retrouver la définition originelle de l'élément sur lequel on se base pour contraindre. Par ailleurs, il faut bien s'assurer que le nouveau modèle de contenu est bien une restriction de l'original.
trouver un compromis permettant que l'ensemble reste valide avec le mécanisme des entités paramètres des DTD.

Tutoriel : contraindre dans DITA

Contraindre

Tutoriel : contraindre le modèle de l'élément <section>

Tutoriel : contraindre le modèle de l'élément `<section>`