4.5. Composition

Le contenu peut être composé (chunked) — décomposé ou composé en nouveaux documents de sortie — de différentes façons pour la création, la livraison du contenu et la navigation. Par exemple, on devra peut-être livrer en une seule page quelque chose créée plus facilement comme un ensemble de thèmes séparés. Un créateur de cartes peut utiliser l'attribut chunk pour découper des documents entiers en thèmes composants ou combiner plusieurs thèmes en un seul document pour le traitement de sortie.

Exemples d'utilisation

Voici quelques exemples d'utilisation potentielle de l'attribut chunk :

Réutilisation d'un thème imbriqué
Un fournisseur de contenu crée un ensemble de thèmes dans un document unique. Un réutilisateur veut n'incorporer qu'un seul des thèmes imbriqués du document. La réutilisation peut référencer le thème imbriqué depuis une carte DITA en utilisant l'attribut chunk pour spécifier que le thème devrait être produit dans son propre document.
Identification d'un ensemble de thèmes comme unité
Un développeur de curriculums veut composer une leçon pour un système de gestion d'apprentissage SCORM (SCORM Learning Management System) à partir d'un ensemble de thèmes sans contraindre la réutilisation de ces thèmes. Le système de gestion peut sauvegarder et restaurer la progression de l'apprenti à travers la leçon si celle-ci est identifiée comme une unité référençable. Le développeur du curriculum définit la collection des thèmes avec une carte DITA, en utilisant l'attribut chunk pour identifier le module d'apprentissage comme une unité avant de générer le manifeste SCORM.

Utilisation de l'attribut chunk

Lorsqu'un ensemble de thèmes est transformé pour une sortie avec une carte, l'auteur de la carte peut utiliser l'attribut chunk pour remplacer un comportement de composition par défaut (default chunking behavior) qui s'applique. L'attribut chunk permet à l'auteur de la carte de demander la décomposition des documents multithèmes en plusieurs documents, et la composition de plusieurs thèmes individuels en un seul document.

La composition (chunking) est nécessairement une transformation de sortie spécifique, avec une sortie composée, demandée pour certains types de sortie et non gérée pour d'autres. La composition est également spécifique de la mise en œuvre, avec certaines mises en œuvres gérant certaines méthodes de composition mais pas toutes, ou ajoutant de nouvelles méthodes de combinaison spécifiques d'une mise en œuvre aux méthodes standards décrites dans cette spécification.

La valeur de l'attribut chunk se compose d'un ou plusieurs atomes délimités par des espaces :

by–topic
Si la valeur de l'attribut chunk inclut l'atome "by-topic", une politique de composition (chunking policy) est établie pour l'élément <topicref> courant qui produit une composition de sortie séparée pour l'élément <topic> cible et chacun de ses descendants. La politique n'est applicable qu'à une action de composition (chunk action) de l'élément courant (par exemple, "to-content"), sauf si l'attribut est affecté sur l'élément <map>, lorsque la politique "by-topic" est établie pour la carte entière.
by–document
Si la valeur de l'attribut chunk inclut l'atome "by–document", une politique de composition est établie pour l'élément <topicref> courant, qui produit une seule composition de sortie pour le document référencé (par exemple, "to-content"), sauf si l'attribut est affecté sur l'élément <map>, lorsque la politique "by-document" est établie pour la carte entière.
select–topic
Si la valeur de l'attribut chunk inclut l'atome "select-topic", un thème individuel est sélectionné, sans les autres thèmes (ancêtres, descendants ou frères) du même document. La valeur est ignorée si l'élément sur lequel il apparaît ne pointe pas vers un thème.
select–document
Si la valeur de l'attribut chunk inclut l'atome "select–document", le contenu du thème référencé ainsi que tous les autres thèmes (ancêtres, descendants ou frères) contenus dans le même document sont sélectionnés. La valeur est ignorée si l'élément sur lequel il apparaît ne pointe pas vers un thème.
select–branch
Si la valeur de l'attribut chunk inclut l'atome "select-branch", un thème individuel ainsi que tous les thèmes imbriqués qui y sont contenus sont sélectionnés. La valeur est ignorée si l'élément sur lequel il est spécifié ne pointe pas vers un thème.
to–content
Si la valeur de l'attribut chunk inclut l'atome "to-content", le traitement génère une nouvelle composition de contenu (content chunk). Spécifié sur l'élément <map>, il crée un seul document qui contient tous les thèmes référencés par la carte.
to–navigation
Si la valeur de l'attribut chunk inclut l'atome "to-navigation", le traitement génère une nouvelle composition de navigation (<toc>, <related-links>). Spécifié sur l'élément <map>, il crée une seule composition de navigation avec le contenu entier de la carte.

Notez que le jeu des valeurs d'atome de type select-xxx n'est utile que pour l'adressage d'un thème dans un document contenant plusieurs thèmes.

Quelques atomes ou combinaisons d'atomes ne conviendront peut-être pas à tous les types de sortie. Si des atomes non gérés ou incompatibles sont rencontrés au cours du traitement de sortie, des avertissements ou des messages d'erreurs devraient être produits. La récupération (recovery) sur de tels conflits ou d'autres erreurs dépend de la mise en œuvre.

L'attribut chunk n'a pas de valeur par défaut et n'hérite pas des valeurs des éléments conteneurs. On peut établir une politique "by-xxx" par défaut en spécifiant l'attribut chunk sur l'élément <map>.

Si aucune valeur d'attribut chunk n'est donnée, le comportement de composition dépend de la mise en œuvre et peut varier pour des mises en œuvre différentes. Si des variations de cet ordre ne sont pas souhaitées, on peut établir une valeur par défaut pour la carte entière en incluant une valeur d'attribut chunk sur l'élément <map>.

Pour la création de nouveaux documents via un traitement chunk, le nom de l'objet de stockage ou l'identificateur (si pertinent) provient de l'attribut copyto s'il est présent, sinon le nom racine provient de l'attribut id si la politique by-topic est en vigueur et du nom du document référencé si c'est la politique by-document.

Exemples

Soit plusieurs documents de thème simples, parent1.dita, parent2.dita, etc., child1.dita, child2.dita, etc., grandchild1.dita, grandchild2.dita contenant des thèmes avec les identificateurs P1, P2, etc., C1, C2, etc., GC1, GC2, etc., plusieurs documents de thème imbriqués avec les identificateurs N1, N2, etc. et des sous-thèmes avec les identificateurs N1a, N2a, etc. imbriqués au sein du parent, et le document ditabase.dita avec le contenu suivant :

<dita> 
   <topic id="X"/> 
   <topic id="Y"> 
      <topic id="Y1"> 
         <topic id="Y1a"/> 
      </topic> 
      <topic id="Y2"/> 
   </topic> 
   <topic id="Z"> 
      <topic id="Z1"/> 
   </topic> 
</dita>

La carte map1.ditamap :

<map chunk="by-document"> 
   <topicref href="parent1.dita" chunk="to-content"> 
      <topicref href="ditabase.dita#Y1" 
         chunk="select-topic"/> 
   </topicref> 
</map>

Produit un seul document de sortie, parent1.xxxx, contenant le thème P1 avec le thème Y1, mais pas le thème Y1a qui y est imbriqué.

La carte map2.ditamap :

<map chunk="by-document"> 
   <topicref href="parent1.dita" chunk="to-content"> 
      <topicref href="ditabase.dita" 
         chunk="select-branch"/> 
   </topicref> 
</map>

Produit un seul document de sortie, parent1.xxxx, contenant le thème P1, le thème Y1 imbriqué dans P2 et le thème Y1a imbriqué dans Y1.

La carte map3.ditamap :

<map chunk="by-topic"> 
   <topicref href="parent1.dita" chunk="to-content"> 
      <topicref href="ditabase.dita#Y1" 
         chunk="select-document"/> 
   </topicref> 
</map>

Produit un seul document de sortie, P1.xxxx, contenant le thème P1 et les thèmes X, Y et Z avec leurs sous-éléments imbriqués dans le thème P1.

La carte map4.ditamap :

<map chunk="by-document"> 
   <topicref href="parent1.dita" copyto="parentchunk"> 
      <topicref href="nested1.dita" chunk="select-branch"/> 
   </topicref> 
</map>

Produit un seul document de sortie nommé parentchunk.xxxx contenant le thème P1 avec le thème N1 imbriqué dans P1 et le thème N1a imbriqué dans N1.

La carte map5.ditamap :

<map chunk="by-document"> 
   <topicref href="parent1.dita" 
      chunk="to-content" copyto="parentchunk"> 
      <topicref href="child1.dita" chunk="select-branch"/> 
      <topicref href="child2.dita" 
         chunk="to-content select-branch" 
         copyto="child2chunk"> 
         <topicref href="grandchild2.dita"/> 
      </topicref> 
      <topicref href="child3.dita"> 
         <topicref href="grandchild3.dita" 
            chunk="select-branch"/> 
      </topicref> 
   </topicref> 
</map>

Produit deux documents de sortie : les thèmes P1, C1, C3 et GC3 dans parentchunk.xxxx, et les thèmes C2 et GC2 topics dans child2chunk.xxx.

La carte map6.ditamap :

<map> 
   <topicref href="nested1.dita#N1" copyto="nestedchunk" 
     chunk="to-content select-topic"/> 
</map>

Produit un seul document de sortie, nestedchunk.xxxx, contenant le thème N1 sans thèmes imbriqués.

La carte map7.ditamap :

<map> 
   <topichead navtitle="How to do lots of things" 
      chunk="to-navigation"> 
       <topicref href="parent1.dita" 
             navtitle="How to set up a web server"> 
          <topicref href="child1.dita" 
             chunk="select-branch"/> 
          ... 
          </topicref> 
       <topicref href="parent2.dita" 
             navtitle="How to ensure database security"> 
          <topicref href="child2.dita" 
             chunk="select-branch"/> 
              ... 
          </topicref> 
         ... 
   </topicref> 
</map> 

Produit deux compositions de navigation, l'une pour P1, C1, etc., et l'autre pour P2, C2, etc.

L'exemple précédent identifie un « mode d'emploi » pour établir un produit comme une seule unité. Le « mode d'emploi » pourrait être fourni à la fois comme des pages HTML navigables et comme un document PDF imprimabe associé à la page HTML racine.

Atomes spécifiques des mises en œuvre et considérations futures

Des atomes de composition supplémentaires pourront s'ajouter au standard DITA dans le futur. On peut aussi définir d'autres atomes spécifiques des mises en œuvre. Afin d'éviter les conflits de noms entre les mises en œuvre ou avec les ajouts futurs au standard, les atomes spécifiques des mises en œuvre devraient se composer d'un préfixe qui donne le nom ou une abréviation de la mise en œuvre suivi d'un caractères DEUX-POINTS « : » suivi du nom de la méthode de composition. Par exemple, "acme:level2" pourait être un atome de la boîte à outils DITA d'Acme qui nécessite la méthode de composition "level2".