Adapter l'environnement DITA / Manipuler un document type shell
Sujet parent: Manipuler un document type shell Sujet précédent: Tutoriel : spécialiser un attribut Sujet suivant: Adapter le DITA OT

Tutoriel : spécialiser un topic "document type shell"

Réaliser une spécialisation complète d'un topic.

Durée : 2 h 
Objectifs :
Contenus :

Le tutoriel guide l'apprenant dans les grandes étapes à réaliser. Il suffit alors de reprendre les tutoriels des deux modules précédents pour comprendre comment réaliser une opération particulière.

Règles de spécialisation

Réaliser un topic "recette de cuisine"

Une recette de cuisine est spécialisée à partir d'un topic concept. Elle contient successivement les éléments suivants : nbPers (spécialisé à partir de p), tpsPreparation (p), tpsCuisson (p), ingredients (ul), preparation (sectiondiv), resultats (p).
Les grandes étapes sont les suivantes :
  • Mettre en place la structure des fichiers (on peut aussi, dans la vraie vie, copier un module existant)
  • Créer un document d'exemple
  • Déclarer les éléments
  • Les intégrer dans une DTD
  • Tester avec une recette
Procédure :

    Mise en place de l'environnement

  1. Créez une structure d'accueil recette/dtd dans votre répertoire du plugin doctypes.
  2. Créez le fichier recette.ent à partir d'Oxygen.
  3. Recopiez la DTD concept.dtd (fournie dans le répertoire exercices-dita\squeletteIntegration) et renommez-la en recette.dtd.
  4. De la même façon, recopiez le fichier module concept.mod (fourni dans le répertoire exercices-dita\squeletteIntegration) et renommez-le en recette.mod.
  5. Mettez en place le catalog du module (3 entrées) et liez le au catalog du plugin.
  6. Recopiez la recette du "Tartinable de butternut" dans votre répertoire recette et nommez le fichier recetteTest.dita.
  7. Balisez la recette selon la structure attendue et renseignez le <!DOCTYPE en fonction de ce qui a été écrit dans le catalog.

    Proposition de balisage :

    <?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE recette PUBLIC "urn:pubid:fr:masociete.doctypes:recette" "./dtd/recette.dtd">
<recette id="task_qzv_zlf_1s">
    <title>Tartinable de butternut</title>
    <recettebody>
        <nbPers>6</nbPers>
        <tpsPreparation>10mn</tpsPreparation>
        <tpsCuisson>20mn</tpsCuisson>
        <ingredients>
            <li>1 butternut de 1kg</li>
            <li>100g de graines de tournesol</li>
            <li>Sel/poivre</li>
        </ingredients>
        <preparation>
            <ul>
                <li>Éplucher le butternut et le vider de tous ses pépins </li>
                <li>Le couper en morceaux </li>
                <li>Faire cuire à la vapeur ou dans très peu d’eau </li>
                <li>Torrefier les graines et les mixer grossièrement </li>
                <li>Mélanger graines et butternut sans l’eau de cuisson </li>
                <li>Ecraser avec un presse purée ou une fourchette </li>
                <li>saler, poivrer </li>
            </ul>
        </preparation>
        <resultat>Et hop, c’est prêt ! </resultat>
    </recettebody>
</recette>

    8. Le fichier d'entités : recette.ent

  8. Créez ensuite l'entité paramètre de définition du nouveau domaine, spécialisé par rapport à concept.
    Modèle : <!ENTITY recette-att "(topic concept recette) ">

    9. Le fichier de déclaration des éléments : recette.mod

  9. Dans ce fichier, dans la partie "ELEMENT NAME ENTITIES", supprimez l'existant et créez une entité paramètre pour chaque nom d'élément nouveau qui va être utilisé dans la recette.
  10. Cherchez la définition de concept et remplacez par recette. Prenez soin de remplacer conbody par recettebody. 
    <!--                    LONG NAME: Recette                         -->
<!ENTITY % recette.content
                       "((%title;), 
                         (%titlealts;)?,
                         (%abstract; | 
                          %shortdesc;)?, 
                         (%prolog;)?, 
                         (%recettebody;)?, 
                         (%related-links;)?,
                         (%recette-info-types;)* )"
>
<!ENTITY % recette.attributes
             "id ID #REQUIRED
              %conref-atts;
              %select-atts;
              %localization-atts;
              outputclass  CDATA  #IMPLIED"
>
<!ELEMENT recette    %recette.content;>
<!ATTLIST recette    
              %recette.attributes;
              %arch-atts;
              domains CDATA "&included-domains;">

    11. Les grands changements sont maintenant dans recettebody qui a un contenu structuré.

  11. Trouvez la déclaration de conbody et remplacez le modèle de contenu. 
    <!ENTITY % recettebody.content
                       "(%nbPers; , %tpsPreparation; , %tpsCuisson; , 
                        %ingredients; , %preparation; , %resultat;? )"
>
  12. Finalisez les autres entités paramètres de recettebody, comme précédemment. 
    <!ENTITY % recettebody.content
                       "(%nbPers; , %tpsPreparation; , %tpsCuisson; , %ingredients; , 
                        %preparation; , %resultat;? )"
>
<!ENTITY % recettebody.attributes
             "%id-atts;
              %localization-atts;
              base CDATA #IMPLIED
              %base-attribute-extensions;
              outputclass  CDATA  #IMPLIED"
>
<!ELEMENT recettebody    %recettebody.content;>
<!ATTLIST recettebody    %recettebody.attributes;>
  13. Supprimez la déclaration de conbodydiv et déclarez rapidement la suite. 
    <!-- dérivation de p -->

<!ENTITY % nbPers.content "(%para.cnt;)*">
<!ENTITY % nbPers.attributes
             "%univ-atts;
              outputclass CDATA  #IMPLIED"
>
<!ELEMENT nbPers    %nbPers.content;>
<!ATTLIST nbPers    %nbPers.attributes;>

<!ENTITY % tpsPreparation.content "(%para.cnt;)*">
<!ENTITY % tpsPreparation.attributes
             "%univ-atts;
              outputclass CDATA  #IMPLIED"
>
<!ELEMENT tpsPreparation    %tpsPreparation.content;>
<!ATTLIST tpsPreparation    %tpsPreparation.attributes;>

<!ENTITY % tpsCuisson.content "(%para.cnt;)*">
<!ENTITY % tpsCuisson.attributes
             "%univ-atts;
              outputclass CDATA  #IMPLIED"
>
<!ELEMENT tpsCuisson    %tpsCuisson.content;>
<!ATTLIST tpsCuisson    %tpsCuisson.attributes;>

<!ENTITY % resultat.content "(%para.cnt;)*">
<!ENTITY % resultat.attributes
             "%univ-atts;
              outputclass CDATA  #IMPLIED"
>
<!ELEMENT resultat    %resultat.content;>
<!ATTLIST resultat    %resultat.attributes;>

<!-- dérivation de ul -->
<!ENTITY % ingredients.content
                       "(%li;)+"
>
<!ENTITY % ingredients.attributes
             "spectitle CDATA  #IMPLIED
              %univ-atts;
              outputclass   CDATA  #IMPLIED"
>
<!ELEMENT ingredients    %ingredients.content;>
<!ATTLIST ingredients    %ingredients.attributes;>


<!-- dérivation de sectiondiv -->
<!ENTITY % preparation.content
                       "(%sectiondiv.cnt; |
                         %sectiondiv;)*"
>
<!ENTITY % preparation.attributes
             "%univ-atts;
              outputclass 
                        CDATA 
                                  #IMPLIED"
>
<!ELEMENT preparation    %preparation.content;>
<!ATTLIST preparation    %preparation.attributes;>
  14. Il faut maintenant déclarer les spécialisations individuelles.
    Ces spécialisations sont déclarées de façon indépendante pour plus de lisibilité dans la DTD.

    Par ailleurs, chaque élément définit totalement sa "chaîne de spécialisation" : recette dérive de concept qui dérive lui-même de topic, pendant que tpsCuisson dérive directement de p dans topic.

    <!-- ============================================================= -->
<!--                    SPECIALIZATION ATTRIBUTE DECLARATIONS      -->
<!-- ============================================================= -->
<!ATTLIST recette      %global-atts;  class CDATA "- topic/topic concept/concept recette/recette ">
<!ATTLIST recettebody      %global-atts;  class CDATA "- topic/body concept/conbody recette/recettebody ">
<!ATTLIST nbPers      %global-atts;  class CDATA "- topic/p recette/nbPers ">
<!ATTLIST tpsPreparation      %global-atts;  class CDATA "- topic/p recette/tpsPreparation ">
<!ATTLIST tpsCuisson      %global-atts;  class CDATA "- topic/p recette/tpsCuisson ">
<!ATTLIST ingredients      %global-atts;  class CDATA "- topic/ul recette/ingredients ">
<!ATTLIST preparation      %global-atts;  class CDATA "- topic/sectiondiv recette/preparation ">
<!ATTLIST resultat      %global-atts;  class CDATA "- topic/p concept/p recette/resultat ">

    15. Le fichier shell DTD d'intégration

  15. Ouvrez recette.dtd (issu de concept.dtd).
    C'est à partir de ce fichier recette.dtd que va être mise en place la DTD.
  16. Supprimez tous les domaines utilisés sauf "highlight".

    Pour ce faire, il faut supprimer :

    • l'appel des fichiers .ent de déclaration des entités des domaines,
    • les spécialisations des entités paramètres de base,
    • la spécialisation de included-domains,
    • l'appel des fichiers .mod de déclaration des éléments des domaines.
  17. Modifiez l'entité paramètre recette-info-types pour lui donner l'unique contenu no-topic-nesting.
    Cette entité définit les inclusions de topic, directement à l'intérieur de notre topic recette (en anglais, on parle de "nesting topic". Ici, l'utilisation de l'élément no-topic-nesting permet de définir que l'on ne souhaite pas de topic dans des topics. Toujours pour des raisons de compatibilité avec les DTD et l'utilisation des entités paramètres, on ne peut pas mettre ici un contenu vide, d'où l'utilisation d'un élément fantôme qui n'a aucune utilité réelle.

    Note: Le topic utilisé par ce tutoriel est un learningContnt. La première partie définit l'objectif du tutoriel. Le tutoriel lui-même est dans un "nesting topic" de type task ; la correction du tutoriel est ensuite dans un "nesting topic" de type concept.

  18. Ajoutez l'entité générale recette-att dans included-domains
    Sert à la prise en compte de recette comme nouveau domaine de type topic.
  19. Inclure le module de déclaration des éléments de la recette dans la partie "TOPIC ELEMENT INTEGRATION". 
    <!ENTITY % recette-typemod 
                        PUBLIC 
"urn:pubid:fr:masociete.doctypes:recette.module" 
"recette.mod">
%recette-typemod;
    En toute logique, votre DTD est maintenant valide. Ne passez pas à la suite tant que celle-ci ne fonctionne pas.

    20. Test du topic

  20. Reprendre recetteTest.dita et testez que le topic est maintenant valide.
  21. Intégrez votre nouveau topic au DITA-OT.
  22. Publiez ce topic en XHTML et constatez la prise en compte d'une présentation par défaut grâce à la spécialisation.
Résultat :

Le nouveau type de document fonctionne.

  • Comment choisir entre ajouter des éléments dans le domaine cuisine ou dans ce modèle de recette ?

Solution

Ce topic contient la solution complète du tutoriel précédent.

Contenu de recette.ent

<?xml version="1.0" encoding="UTF-8"?>
<!-- ============================================================= -->
<!--                    HEADER                                     -->
<!-- ============================================================= -->
<!--  MODULE:    DITA Recette                                      -->
<!--  VERSION:   1.0                                               -->
<!--  DATE:      Juin 2015                                         -->
<!--                                                               -->
<!-- ============================================================= -->

<!-- ============================================================= -->
<!--                    PUBLIC DOCUMENT TYPE DEFINITION            -->
<!--                    TYPICAL INVOCATION                         -->
<!--                                                               -->
<!--  Refer to this file by the following public identifier or an 
      appropriate system identifier 
PUBLIC "urn:pubid:fr:masociete.doctypes:recette.entites"
      Delivered as file "recette.ent"                              -->

<!-- ============================================================= -->
<!-- SYSTEM:     Darwin Information Typing Architecture (DITA)     -->
<!--                                                               -->
<!-- PURPOSE:    Define entities for recette                       -->
<!--                                                               -->
<!-- ============================================================= -->



<!-- ============================================================= -->
<!--                    DOMAIN ENTITY DECLARATION                  -->
<!-- ============================================================= -->

  
<!ENTITY recette-att       
  "(topic concept recette)"                               
>

Contenu de recette.mod

<?xml version="1.0" encoding="UTF-8"?>
<!-- ============================================================= -->
<!--                    HEADER                                     -->
<!-- ============================================================= -->
<!--  MODULE:    DITA Recette                                      -->
<!--  VERSION:   1.0                                               -->
<!--  DATE:      Juin 2015                                         -->
<!--                                                               -->
<!-- ============================================================= -->

<!-- ============================================================= -->
<!--                    PUBLIC DOCUMENT TYPE DEFINITION            -->
<!--                    TYPICAL INVOCATION                         -->
<!--                                                               -->
<!--  Refer to this file by the following public identifier or an 
      appropriate system identifier 
PUBLIC "urn:pubid:fr:masociete.doctypes:recette"
      Delivered as file "recette.mod"                              -->

<!-- ============================================================= -->
<!-- SYSTEM:     Darwin Information Typing Architecture (DITA)     -->
<!--                                                               -->
<!-- PURPOSE:    Define elements and specialization atttributes    -->
<!--             for recette                                       -->
<!--                                                               -->
<!-- ============================================================= -->


<!-- ============================================================= -->
<!--                   ARCHITECTURE ENTITIES                       -->
<!-- ============================================================= -->

<!-- default namespace prefix for DITAArchVersion attribute can be
     overridden through predefinition in the document type shell   -->
<!ENTITY % DITAArchNSPrefix
  "ditaarch"
>

<!-- must be instanced on each topic type                          -->
<!ENTITY % arch-atts 
             "xmlns:%DITAArchNSPrefix; 
                        CDATA
                                  #FIXED 'http://dita.oasis-open.org/architecture/2005/'
              %DITAArchNSPrefix;:DITAArchVersion
                        CDATA
                                  '1.2'
"
>


<!-- ============================================================= -->
<!--                   SPECIALIZATION OF DECLARED ELEMENTS         -->
<!-- ============================================================= -->


<!ENTITY % recette-info-types 
  "%info-types;
  "
>


<!-- ============================================================= -->
<!--                   ELEMENT NAME ENTITIES                       -->
<!-- ============================================================= -->
 

<!ENTITY % recette "recette" >
<!ENTITY % recettebody "recettebody" >
<!ENTITY % nbPers "nbPers" >
<!ENTITY % tpsPreparation "tpsPreparation" >
<!ENTITY % tpsCuisson "tpsCuisson" >
<!ENTITY % ingredients "ingredients">
<!ENTITY % ingredient "ingredient" >
<!ENTITY % preparation "preparation">
<!ENTITY % resultat "resultat">

<!-- ============================================================= -->
<!--                    DOMAINS ATTRIBUTE OVERRIDE                 -->
<!-- ============================================================= -->


<!ENTITY included-domains 
  ""
>


<!-- ============================================================= -->
<!--                    ELEMENT DECLARATIONS                       -->
<!-- ============================================================= -->


<!--                    LONG NAME: Recette                         -->
<!ENTITY % recette.content
                       "((%title;), 
                         (%titlealts;)?,
                         (%abstract; | 
                          %shortdesc;)?, 
                         (%prolog;)?, 
                         (%recettebody;)?, 
                         (%related-links;)?,
                         (%concept-info-types;)* )"
>
<!ENTITY % recette.attributes
             "id ID #REQUIRED
              %conref-atts;
              %select-atts;
              %localization-atts;
              outputclass  CDATA  #IMPLIED"
>
<!ELEMENT recette    %recette.content;>
<!ATTLIST recette    
              %recette.attributes;
              %arch-atts;
              domains CDATA "&included-domains;">



<!--                    LONG NAME: Concept Body                    -->
<!ENTITY % recettebody.content
                       "(%nbPers; , %tpsPreparation; , %tpsCuisson; ,
                        %ingredients; , %preparation; , %resultat;? )"
>
<!ENTITY % recettebody.attributes
             "%id-atts;
              %localization-atts;
              base CDATA #IMPLIED
              %base-attribute-extensions;
              outputclass  CDATA  #IMPLIED"
>
<!ELEMENT recettebody    %recettebody.content;>
<!ATTLIST recettebody    %recettebody.attributes;>

<!-- dérivation de p -->

<!ENTITY % nbPers.content "(%para.cnt;)*">
<!ENTITY % nbPers.attributes
             "%univ-atts;
              outputclass CDATA  #IMPLIED"
>
<!ELEMENT nbPers    %nbPers.content;>
<!ATTLIST nbPers    %nbPers.attributes;>

<!ENTITY % tpsPreparation.content "(%para.cnt;)*">
<!ENTITY % tpsPreparation.attributes
             "%univ-atts;
              outputclass CDATA  #IMPLIED"
>
<!ELEMENT tpsPreparation    %tpsPreparation.content;>
<!ATTLIST tpsPreparation    %tpsPreparation.attributes;>

<!ENTITY % tpsCuisson.content "(%para.cnt;)*">
<!ENTITY % tpsCuisson.attributes
             "%univ-atts;
              outputclass CDATA  #IMPLIED"
>
<!ELEMENT tpsCuisson    %tpsCuisson.content;>
<!ATTLIST tpsCuisson    %tpsCuisson.attributes;>

<!ENTITY % resultat.content "(%para.cnt;)*">
<!ENTITY % resultat.attributes
             "%univ-atts;
              outputclass CDATA  #IMPLIED"
>
<!ELEMENT resultat    %resultat.content;>
<!ATTLIST resultat    %resultat.attributes;>

<!-- dérivation de ul -->
<!ENTITY % ingredients.content
                       "(%li;)+"
>
<!ENTITY % ingredients.attributes
             "spectitle CDATA  #IMPLIED
              %univ-atts;
              outputclass   CDATA  #IMPLIED"
>
<!ELEMENT ingredients    %ingredients.content;>
<!ATTLIST ingredients    %ingredients.attributes;>


<!-- dérivation de sectiondiv -->
<!ENTITY % preparation.content
                       "(%sectiondiv.cnt; |
                         %sectiondiv;)*"
>
<!ENTITY % preparation.attributes
             "%univ-atts;
              outputclass 
                        CDATA 
                                  #IMPLIED"
>
<!ELEMENT preparation    %preparation.content;>
<!ATTLIST preparation    %preparation.attributes;>


<!-- ============================================================= -->
<!--                    SPECIALIZATION ATTRIBUTE DECLARATIONS      -->
<!-- ============================================================= -->


<!ATTLIST recette      %global-atts;  class CDATA "- topic/topic concept/concept recette/recette ">
<!ATTLIST recettebody      %global-atts;  class CDATA "- topic/body concept/conbody recette/recettebody ">
<!ATTLIST nbPers      %global-atts;  class CDATA "- topic/p recette/nbPers ">
<!ATTLIST tpsPreparation      %global-atts;  class CDATA "- topic/p recette/tpsPreparation ">
<!ATTLIST tpsCuisson      %global-atts;  class CDATA "- topic/p recette/tpsCuisson ">
<!ATTLIST ingredients      %global-atts;  class CDATA "- topic/ul recette/ingredients ">
<!ATTLIST preparation      %global-atts;  class CDATA "- topic/sectiondiv recette/preparation ">
<!ATTLIST resultat      %global-atts;  class CDATA "- topic/p concept/p recette/resultat ">

<!-- ================== End DITA Recette  ======================== -->

Contenu de recette.ent

<?xml version="1.0" encoding="UTF-8"?>
<!-- ============================================================= -->
<!--                    HEADER                                     -->
<!-- ============================================================= -->
<!--  MODULE:    DITA Recette                                      -->
<!--  VERSION:   1.0                                               -->
<!--  DATE:      Juin 2015                                         -->
<!--                                                               -->
<!-- ============================================================= -->

<!-- ============================================================= -->
<!--                    PUBLIC DOCUMENT TYPE DEFINITION            -->
<!--                    TYPICAL INVOCATION                         -->
<!--                                                               -->
<!--  Refer to this file by the following public identifier or an 
      appropriate system identifier 
PUBLIC "urn:pubid:fr:masociete.doctypes:recette.entites"
      Delivered as file "recette.ent"                              -->

<!-- ============================================================= -->
<!-- SYSTEM:     Darwin Information Typing Architecture (DITA)     -->
<!--                                                               -->
<!-- PURPOSE:    Define specialization for recette topic           -->
<!--                                                               -->
<!-- ============================================================= -->



<!-- ============================================================= -->
<!--                    TOPIC ENTITY DECLARATIONS                  -->
<!-- ============================================================= -->

<!ENTITY % recette-dec     
  PUBLIC "urn:pubid:fr:masociete.doctypes:recette.entites" 
         "recette.ent"
>%recette-dec;

<!-- ============================================================= -->
<!--                    DOMAIN ENTITY DECLARATIONS                 -->
<!-- ============================================================= -->


<!ENTITY % hi-d-dec     
  PUBLIC "-//OASIS//ENTITIES DITA 1.2 Highlight Domain//EN" 
         "../../base/dtd/highlightDomain.ent"
>%hi-d-dec;



<!-- ============================================================= -->
<!--                    DOMAIN ATTRIBUTE DECLARATIONS              -->
<!-- ============================================================= -->


<!-- ============================================================= -->
<!--                    DOMAIN EXTENSIONS                          -->
<!-- ============================================================= -->
<!--                    One for each extended base element, with
                        the name of the domain(s) in which the
                        extension was declared                     -->

<!ENTITY % pre          "pre 
                        ">
<!ENTITY % keyword      "keyword 
                        ">
<!ENTITY % ph           "ph |
                         %hi-d-ph; 
                        ">
<!ENTITY % term         "term 
                        ">
<!ENTITY % fig          "fig 
                        ">
<!ENTITY % dl           "dl 
                        ">
<!ENTITY % index-base   "index-base 
                        ">
<!ENTITY % note         "note 
                        ">

<!-- ============================================================= -->
<!--                    DOMAIN ATTRIBUTE EXTENSIONS                -->
<!-- ============================================================= -->
<!ENTITY % props-attribute-extensions  ""                            >
<!ENTITY % base-attribute-extensions   ""                            >


<!-- ============================================================= -->
<!--                    TOPIC NESTING OVERRIDE                     -->
<!-- ============================================================= -->

<!--                    Redefine the infotype entity to exclude 
                        other topic types and disallow nesting     -->
<!ENTITY % recette-info-types 
                        "no-topic-nesting"                                    >


<!-- ============================================================= -->
<!--                    DOMAINS ATTRIBUTE OVERRIDE                 -->
<!-- ============================================================= -->
<!--                    Must be declared ahead of the DTDs, which
                        puts @domains first in order               -->

<!ENTITY included-domains 
                          "&recette-att;
                           &hi-d-att; 
                           
  "
>

<!-- ============================================================= -->
<!--                    CONTENT CONSTRAINT INTEGRATION             -->
<!-- ============================================================= -->




<!-- ============================================================= -->
<!--                    TOPIC ELEMENT INTEGRATION                  -->
<!-- ============================================================= -->

<!--                    Embed topic to get generic elements        -->
<!ENTITY % topic-type   PUBLIC 
"-//OASIS//ELEMENTS DITA 1.2 Topic//EN" 
"../../base/dtd/topic.mod">
%topic-type;


<!--                    Embed concept to get specific elements     -->
<!ENTITY % recette-typemod 
                        PUBLIC 
"urn:pubid:fr:masociete.doctypes:recette.module" 
"recette.mod">
%recette-typemod;


<!-- ============================================================= -->
<!--                    DOMAIN ELEMENT INTEGRATION                 -->
<!-- ============================================================= -->


<!ENTITY % hi-d-def     
  PUBLIC "-//OASIS//ELEMENTS DITA 1.2 Highlight Domain//EN" 
         "../../base/dtd/highlightDomain.mod"
>%hi-d-def;



<!-- ================== End DITA Recette DTD  ==================== -->
Sujet parent: Manipuler un document type shell Sujet précédent: Tutoriel : spécialiser un attribut Sujet suivant: Adapter le DITA OT
WebHelp généré parXML Author