4.2. Inclusion de contenu (conref)

L'attribut conref DITA fournit un mécanisme pour réutiliser des fragments de contenu. L'attribut conref stocke une référence à un autre élément et son traitement remplace l'élément appelant par l'élément référencé.

L'élément contenant la référence de contenu agit comme conteneur (placeholder) pour l'élément appelé. L'identificateur de l'élément appelé doit être soit absolu, soit résolvable dans le contexte de l'élément appelant. Cf. la section 4.1. Identificateurs et références pour des détails sur les identificateurs.

Plus formellement, l'attribut conref DITA peut être considéré comme un mécanisme de transclusion. À cet égard, l'attribut conref est similaire à XInclude tout comme aux références de valeur HyTime. Toutefois, DITA diffère de ces mécanismes en comparant les contraintes de chaque contexte pour s'assurer de la continuité de la validité du contenu de remplacement dans son nouveau contexte. En d'autres termes, la validité de conref ne s'applique pas simplement au contenu courant au moment du remplacement mais aux gammes de contenu possible vu les contraintes des deux types de document. Un processeur conref valide ne permet pas la résolution d'une relation de réutilisation qui deviendrait invalide sous les règles du contenu réutilisé ou bien du contenu réutilisant.

Si l'élément appelé est du même type que celui de l'élément appelant, et la liste des domaines dans l'instance de thème appelée (déclarée dans l'attribut domains) est la même ou est un sous-ensemble de la liste des domaines dans le document appelant, l'ensemble d'éléments permis dans l'élément appelé est garanti le même, ou un sous-ensemble, de l'ensemble d'éléments permis dans l'élément conteneur (placeholder). L'approche préférée est celle où le processeur résolvant un attribut conref tolérerait les spécialisations des éléments valides et généraliserait au besoin les éléments dans le fragment de contenu pour le contexte appelant.

Le remplacement du conteneur intervient après l'analyse du document mais avant le stylage ou autres opérations de transformation ou de présentation sur le thème complet.

La cible de l'attribut conref peut être substituée selon les conditions en élaboration (build-time) ou à l'exécution (runtime). Par exemple, un contenu tel que des noms de produits ou des chemins d'installation peuvent être séparé du contenu du thème puisque ceux-ci changent lorsque le thème est réutilisé par d'autres produits ; les produits réutilisants peuventt substituer leurs propres cibles pour l'attribut conref afin de permettre une résolution vers leurs propres noms de produits et chemins d'installtion, et ainsi de suite.

La cible d'un attribut conref doit être un thème DITA ou une carte DITA (ou pointer vers le thème ou la carte en entier). Les fragments de contenu DITA (tels qu'un document n'ayant qu'un seul paragraphe) ne contiennent pas assez d'information en eux-mêmes pour permettre au processeur conref de déterminer la validité des références vers ces fragments.

Les spécifications d'attribut de l'élément résolu peuvent se déduire à la fois des éléments sources et cibles, dans l'ordre de priorité suivant :

  1. 1. Tous les attributs tels que spécifiés sur l'élément source sauf ceux qui spécifient la valeur "-dita-use-conref-target" ;
  2. 2. Tous les attributs tels que spécifiés sur l'élément cible sauf :
    1. a. L'attribut id ;
    2. b. Tout attribut spécifié aussi sur l'élément source tel que sa valeur spécifiée (sur l'élément source) ne soit pas "-dita-use-conref-target".
  3. 3. L'attribut xml:lang a un traitement spécial, comme décrit à la section 4.6.1. L'attribut xml:lang.

Le seul cas où l'élément résolu incluera un attribut dont la valeur spécifiée est "-dita-use-conref-target" est lorsque l'élément cible aura cet atribut avec la valeur "-dita-use-conref-target" et l'élément source n'aura pas cet attribut ainsi spécifié ou bien l'aura avec la valeur "-dita-use-conref-target". Si l'élément résolu final (après résolution complète de la chaîne conref éventuelle) a un attribut avec la valeur "-dita-use-conref-target", on devrait le traiter comme s'il avait cet attribut non spécifié.

Une valeur d'attribut donnée sur l'élément résolu provient en totalité soit de la source, soit de la cible : les valeurs d'attribut de la cible et de la source d'un attribut donné ne sont jamais additifs, même si la propriété (telle que le type de public) prend une liste de valeurs.

Si l'élément cible a un attribut conref spécifié, on devrait appliquer les règles précédentes récursivement, avec l'élément résolu d'une combinaison source/cible devenant l'un des deux éléments participant à la combinaison source/cible suivante. Le résultat devrait préserver, sans généralisation, tous les éléments qui sont valides dans le contexte de départ, même s'ils ne sont pas valides dans un contexte intermédiaire. Par exemple, si topicA et topicC permettent une mise en évidence (highlighting), et pas topicB, alors la chaîne de références de contenu topicA->topicB->topicC devrait préserver tous les éléments de mise en évidence dans le contenu référencé. Le résultat est le même que si les couples conref sont résolus récursivement en commençant par l'élément source.