L'inclusion comme ce document la définit est un type particulier de transformation [XML Information Set].
4.1 La localisation d'inclusion
La valeur de l'attribut href, après échappement selon
4.1.1 L'échappement des valeurs des attributs href, est interprétée
soit comme une référence URI, soit comme une référence IRI.
L'adresse URI de base pour les adresses URI ou IRI relatives est celle de
l'élément xi:include, comme indiqué dans [XML Base].
[Définition :
L'adresse URI, ou IRI, issue de la résolution de la valeur normalisée de l'attribut href
(ou de la chaîne vide si l'attribut est absent) vers une forme d'adresse URI, ou IRI, absolue s'appelle
la localisation d'inclusion.]
L'absence d'une valeur pour l'attribut href, soit que href="", soit que
l'attribut href est absent, est source d'incompatibilité pour certaines stratégies d'implémentation. Par exemple, un
processeur XInclude pourrait ne pas disposer d'une représentation textuelle de
l'ensemble d'information source à inclure (parse="text"), ou
il peut être dans l'impossibilité d'accéder à une autre partie du document en utilisant parse="xml" et un pointeur XPointer
à cause d'un problème de transmission. Une implémentation peut choisir de traiter
une ou toutes les absences de valeur de l'attribut href comme des
erreurs de ressource. Les implémentations
devraient documenter les conditions dans lesquelles ces
erreurs de ressource se produisent.
4.1.1 L'échappement des valeurs des attributs href
La valeur de l'attribut href est convertie soit en une référence URI, soit en une
référence IRI, selon ce qui convient à l'implémentation.
Des travaux sont actuellement en cours afin de produire un document RFC
qui définisse les identificateurs de ressources internationnalisés (IRI).
Comme ces travaux n'ont pas encore abouti, cette spécification définira les références IRI de manière syntaxique.
Nous prévoyons de publier un erratum en remplacement des parties de ce chapitre avec une référence au document RFC quand
celui-ci sera paru. Pour une définition et une discussion plus générales à propos des adresse IRI,
cf. [IRI draft] (travaux en cours).
[Définition : Une référence IRI est une chaîne
qui peut être convertie en une référence URI par échappement des caractères supplémentaires suivants :]
-
Les caractères du plan 0 de Unicode [#xA0-#xD7FF], [#xF900-#xFDCF], [#xFDF0-#xFFEF] ;
-
Les caractères des plans 1-14 de Unicode [#x10000-#x1FFFD] ... [#xE0000-#xEFFFD] ;
Pour convertir la valeur de l'attribut href en une référence IRI,
on doit échapper les caractères suivants :
-
le caractère espace
(#x20) ;
Remarque :
On conseille aux auteurs d'éviter les caractères espace
non échappés, dans la mesure où la spécification XML Schema les a
identifiés comme un facteur de risque
pour l'interopérabilité.
-
les délimiteurs signe inférieur à <
(#x3C), signe supérieur à >
(#x3E) et
guillemet double "
(#x22) ;
-
les caractères à risques accolade gauche {
(#x7B),
accolade droite }
(#x7D), barre verticale |
(#x7C),
barre oblique inversée \
(#x5C), accent circonflexe ^
(#x5E)
et accent grave `
(#x60) ;
On échappe ces caractères de la façon suivante :
-
Chaque caractère supplémentaire est converti dans le codage UTF-8 [Unicode] en un ou plusieurs octets ;
-
Les octets résultants sont échappés selon le mécanisme d'échappement des adresses URI (c'est-à-dire, convertis dans une
forme %HH, où HH représente la notation hexadécimale de la valeur d'octet) ;
-
Le caractère original est remplacé par la séquence de caractères résultante.
Pour convertir une référence IRI en une référence URI,
on doit échapper les caractères supplémentaires admis pour les adresses IRI
en utilisant la même méthode.
4.1.2 L'utilisation de XInclude avec une négociation de contenu
L'utilisation d'un mécanisme comme la négociation de contenu HTTP [IETF RFC 2616]
introduit un niveau de complexité potentiel supplémentaire dans l'emploi de XInclude. Les développeurs qui utilisent XInclude dans des
situations où une négociation de contenu est probable ou possible devraient avoir conscience du fait qu'ils sont susceptibles d'inclure
un contenu pouvant différer structurellement de celui attendu, même si c'est un contenu XML. Par exemple, une seule
adresse URI, ou IRI, peut désigner, selon les cas, une représentation XML brute de la ressource,
une représentation XSL-FO [XSL-FO]
ou une représentation XHTML [XHTML],
tout comme des versions dans des codages de caractères ou des langues différents.
Les auteurs dont le traitement XInclude dépend de la réception d'un vocabulaire XML particulier devraient utiliser
les attributs accept et accept-language pour augmenter la probabilité que la ressource soit livrée dans le
format voulu.
4.2 Les éléments inclus si parse="xml"
Dans le cas où parse="xml", la localisation d'inclusion est
résolue, la ressource est récupérée et un ensemble d'information est créé par analyse de la ressource comme si le type de média était
"application/xml" (y compris la détermination du codage de caractères).
Remarque :
On a volontairement omis de donner les caractéristiques de la création d'un ensemble d'information afin de laisser une
certaine flexibilité aux implémentations et pour éviter de définir un modèle de traitement particulier pour les composants de
l'architecture XML. Par exemple, les détails sur la question de savoir si on doit effectuer une validation
par DTD ou bien par schéma XML ne sont pas définis par cette spécification.
Remarque :
Les codages de caractères des ressources incluantes et incluses peuvent être différents. Ils n'affectent pas
l'ensemble d'information final mais ils peuvent être pris en compte au cours d'une sérialisation consécutive.
L'indisponibilité d'une ressource pour une raison quelconque (par exemple, la ressource n'existe pas, des problèmes de connexion ou
des mesures de sécurité en empêchent la récupération, le système d'adresse URI ne permet pas
la récupération, la ressource a un codage non reconnu ou la ressource est déterminée par les mécanismes propres d'une implémentation
comme n'étant pas du XML) entraîne une erreur de ressource.
Une ressource dont le contenu n'est pas du XML bien formé provoque une erreur fatale.
Remarque :
La distinction entre une erreur de ressource et une erreur fatale dépend quelque peu de l'implémentation. Supposons une
localisation d'inclusion renvoyant un document HTML, comme peut-être une page d'erreur. Un processeur pourrait
déterminer qu'aucun ensemble d'information ne saurait être créé à partir de la ressource (par exemple, en examinant le type de média)
et donc invoquer une erreur de ressource, en validant un comportement de reprise. Un autre processeur, obéissant à une autre heuristique,
pourrait tenter d'analyser la ressource non-XML comme étant du XML et rencontrer une erreur (fatale) de format erronné.
[Définition :
Les éléments xi:include dans cet ensemble d'information sont traités récursivement pour créer
l'ensemble d'information acquis. Pour un appel interne au document (via un attribut xpointer),
on utilise l'ensemble d'information source comme
ensemble d'information acquis.]
[Définition :
La partie de l'ensemble d'information acquis à inclure est appelée
la cible d'inclusion.] L'item d'information de document de
l'ensemble d'information acquis sert de
cible d'inclusion sauf si l'attribut xpointer
est présent et identifie une sous-ressource. Les formes de pointeur XPointer décrites dans [XPointer Framework]
et [XPointer element() scheme] doivent être gérées.
Les processeurs XInclude gèrent en option d'autres formes de pointeur XPointer comme celles décrites dans
[XPointer xpointer() Scheme]. Une erreur de pointeur XPointer est une
erreur de ressource.
Le système [XPointer xpointer() Scheme] n'est pas défini selon la spécification [XML Information Set]
mais il se base sur le modèle de données [XPath 1.0], car l'ensemble d'information XML n'a pas encore été développé.
La correspondance entre les localisations de nœud XPath et les items d'information est directe. Toutefois, le
système xpointer()
suppose que toutes les entités ont été développées. Donc, tenter de résoudre un système xpointer()
sur un document contenant des items d'information d'appel d'entité non développé entraînera une
erreur fatale.
L'ensemble des éléments inclus de niveau supérieur
est dérivé de l'ensemble d'information acquis comme suit.
4.2.1 Les items d'information de document
La cible d'inclusion peut être un item d'information de document
(par exemple, un attribut xpointer non spécifié ou un pointeur XPointer visant spécifiquement
la racine du document). Auquel cas, l'ensemble des
éléments inclus de niveau supérieur correspond à la
propriété enfants de l'item d'information de document de
l'ensemble d'information acquis, à l'exception de l'enfant
item d'information de déclaration de type de document, le cas échéant.
Remarque :
La spécification de l'ensemble d'information XML ne prévoit pas la conservation des blancs en dehors de l'élément document.
Le langage XInclude ne prévoit rien non plus en ce sens.
4.2.4 Les localisations des points
La cible d'inclusion peut être un ensemble de localisations qui
représente un point. Auquel cas, l'ensemble des éléments inclus est vide.
4.2.5 Les items d'information des éléments, des commentaires et des instructions de traitement
La cible d'inclusion peut être un nœud d'élément, un nœud de
commentaire ou un nœud d'instruction de traitement, représentant respectivement un item d'information d'élément,
un item d'information de commentaire ou un item d'information d'instruction de traitement. Auquel cas,
l'ensemble des éléments inclus de niveau supérieur consiste
en l'item d'information correspondant au nœud d'élément, de commentaire ou d'instruction de traitement dans
l'ensemble d'information acquis.
4.2.6 Les items d'information des attributs et des déclarations d'espace de nommage
Une cible d'inclusion consistant en un nœud d'attribut ou un
nœud de déclaration d'espace de nommage entraîne une erreur fatale.
4.2.7 Les boucles d'inclusion
Si, au cours du traitement récursif d'un élément xi:include, un autre élément xi:include
est rencontré, dont la localisation d'inclusion et la valeur de
l'attribut xpointer ont déjà été traitées dans la chaîne d'inclusion, alors c'est une
erreur fatale.
En d'autres termes, les propositions suivantes sont toutes illégales :
-
Un élément xi:include peut appeler le document
contenant l'élément d'inclusion lorsque parse="text".
-
Un élément xi:include peut identifier une autre partie
de la même ressource locale (mêmes attributs href, attributs xpointer différents).
-
Deux éléments xi:include non imbriqués peuvent
identifier une ressource contenant elle-même un élément xi:include.
Les propositions suivantes sont légales :
-
Un élément xi:include pointant sur lui-même, ou sur un quelconque ancêtre, si parse="xml".
-
Un élément xi:include pointant sur un quelconque élément d'inclusion, ou un ancêtre de celui-ci, qui
a déjà été traité à un niveau supérieur.
4.3 Les éléments inclus si parse="text"
Lorsque parse="text", la localisation d'inclusion
est résolue puis la ressource est récupérée et transformée en un ensemble d'items d'information de caractère. Cette caractéristique
facilite l'inclusion d'exemples XML fonctionnels ainsi que d'autres formats basés sur du texte.
L'indisponibilité d'une ressource pour une raison quelconque (par exemple, la ressource n'existe pas, des problèmes de connexion ou
des mesures de sécurité en empêchent la récupération, le système d'adresse URI ne permet pas
la récupération ou la ressource a un codage non reconnu) entraîne une
erreur de ressource.
Le codage d'une telle ressource est déterminé par :
-
une information de codage externe, le cas échéant, sinon ;
-
si le type de média de la ressource est "text/xml", "application/xml" ou
correspond aux conventions "text/*+xml" ou "application/*+xml", comme décrit
dans les types de média XML [IETF RFC 3023], alors le codage est reconnu comme défini
dans XML, sinon ;
-
la valeur de l'attribut encoding, le cas échéant, sinon ;
-
UTF-8.
Les séquences d'octets en dehors de l'intervalle permis par le codage entraînent une
erreur fatale. Les caractères non admis dans les documents XML provoquent aussi
une erreur fatale.
Chaque caractère issu de la transformation de la ressource est représenté dans les
éléments inclus de niveau supérieur comme un
item d'information de caractère dont la propriété code de caractère prend la valeur du
codage ISO 10646 et la propriété blancs dans le contenu de l'élément est définie à "false".
La normalisation du texte inclus se traite selon le modèle de caractère [Character Model].
4.5 La création de l'ensemble d'information final
L'ensemble d'information final est une copie de l'ensemble d'information source, chacun des éléments xi:include
se traitant comme suit :
L'item d'information de l'élément xi:include est trouvé.
[Définition :
La propriété parent de cet élément se rapporte à un item d'information appelé le parent d'inclusion.]
La propriété enfants du parent d'inclusion est modifiée
en remplaçant l'item d'information de l'élément xi:include par les
éléments inclus de niveau supérieur.
La propriété parent de chaque élément inclus est fixée sur le
parent d'inclusion.
Tenter de remplacer un élément xi:include apparaissant comme l'élément document (au niveau supérieur)
dans l'ensemble d'information source par autre chose qu'une liste de zéro ou plus commentaires, zéro ou plus instructions de traitement
et un seul élément entraîne une erreur fatale.
Certains processeurs peuvent se trouver incapables de représenter la propriété espaces de nommage dans la portée d'un élément
si celui-ci n'inclut pas d'associations pour tous les préfixes associés dans la propriété espaces de nommage dans la portée de son parent.
Ces processeurs peuvent donc inclure d'autres associations d'espace de nommage héritées
du parent d'inclusion dans la propriété espaces de nommage dans la portée
des éléments inclus.
L'historique d'inclusion de chaque élément inclus de niveau supérieur
est enregistré dans la propriété d'extension inclure l'historique. La propriété inclure l'historique
se compose d'une liste d'items d'information d'élément, représentant les éléments xi:include des
niveaux d'inclusion récursifs. Si une propriété inclure l'historique apparaît déjà sur un
élément inclus de niveau supérieur, alors
l'item d'information de l'élément xi:include est rajouté en fin de liste.
S'il n'y a pas de propriété inclure l'historique, alors cette propriété est ajoutée avec pour seule valeur
l'item d'information de l'élément xi:include.
Les éléments inclus apparaîtront tous dans
l'ensemble d'information final. Y compris les items d'information d'appel d'entité non développé, le cas échéant.
Les appels dans un même document au sein des éléments xi:include se résolvent par rapport à
l'ensemble d'information source. Par conséquent, l'ordre dans lequel les éléments xi:include sont traités
n'affecte pas le résultat.
Dans l'exemple suivant, la seconde inclusion pointe toujours sur le premier élément xi:include et non
sur lui-même, indépendamment de l'ordre dans lequel les inclusions sont traitées. Ainsi cette inclusion aboutit à deux copies de
quelquechose.xml
et ne produit pas d'erreur de boucle d'inclusion.
<x xmlns:xi="http://www.w3.org/2001/XInclude">
<xi:include href="quelquechose.xml"/>
<xi:include xpointer="xmlns(xi=http://www.w3.org/2001/XInclude)xpointer(x/xi:include[1])"
parse="xml"/>
</x>
4.5.1 Les entités non analysables
Tout item d'information d'entité non analysable apparaissant dans la propriété références
d'un attribut sur les éléments inclus, ou tout descendant de ceux-ci,
s'ajoute aux entités non analysables de l'item d'information de document de
l'ensemble d'information final, tant que ce n'est pas un doublon
d'un membre existant. Les doublons n'apparaissent pas dans l'ensemble d'information final.
Les entités non analysables ayant les mêmes nom, identifiant système,
identifiant publique, URI de base de déclaration,
nom de notation et notation sont censées être des doublons. Une application
peut également détecter que des entités non analysables constituent des doublons
par d'autres moyens. Par exemple, déterminer que l'adresse URI résultant de la combinaison des
propriétés identifiant système et URI de base de déclaration est la même.
Inclure des éléments d'entité non analysable ayant le même nom, sans que l'on ait déterminé s'il s'agit de doublons ou non, constitue
une erreur fatale.
4.5.2 Les notations
Tout item d'information de notation apparaissant dans la propriété références d'un attribut
dans les éléments inclus, ou tout descendant de ceux-ci, s'ajoute à la
propriété notations de l'item d'information de document de
l'ensemble d'information final, tant que ce n'est pas un doublon
d'un membre existant. De la même façon, toute notation appelée par une entité non analysable s'ajoute, comme décrit dans le chapitre
4.5.1 Les entités non analysables, à moins qu'il ne s'agisse d'un
doublon. Les doublons n'apparaissent pas dans l'ensemble d'information final.
Les éléments de notation ayant les mêmes nom, identifiant système,
identifiant public et URI de base de déclaration sont censés
être des doublons. Une application peut également détecter que des notations constituent
des doublons par d'autres moyens. Par exemple, déterminer que l'adresse URI résultant de la combinaison des
propriétés identifiant système et URI de base de déclaration est la même.
Inclure des éléments de notation ayant le même nom, sans que l'on ait déterminé s'il s'agit de doublons ou non, constitue
une erreur fatale.
4.5.3 L'ajustement de la propriété références
Pendant l'inclusion, un item d'information d'attribut dont la propriété type d'attribut est
IDREF
ou IDREFS
aura une propriété références avec zéro ou plus valeurs d'élément issues de
l'ensemble d'information source ou des ensembles d'informations inclus. Ces valeurs doivent
être ajustées pour correspondre aux valeurs d'élément qui apparaissent dans l'ensemble d'information final. Au cours de ce processus,
XInclude corrige également les contradictions entre la propriété références et la
propriété type d'attribut, susceptibles de se produire dans les circonstances suivantes :
-
Un fragment de document contient un attribut de type IDREF
pointant vers un élément dans le document inclus, mais hors
de la partie incluse. Auquel cas, aucun élément dans l'ensemble d'information final ne correspond à la valeur d'élément dans la
propriété références originale.
-
Un document, ou fragment de document, n'est pas auto-contenu. C'est-à-dire qu'il contient un attribut de type IDREF
qui ne
se rapporte pas à un élément au sein de ce document, ou fragment de document, avec l'intention de réaliser ces références après
l'inclusion. Auquel cas, la valeur de la propriété références est inconnue ou elle n'a pas de valeur.
-
L'ensemble d'information final comporte des conflits d'identificateur, c'est-à-dire, plusieurs attributs ont un identificateur de
type d'attribut avec la même propriété valeur normalisée. Auquel cas, les attributs
dont la propriété type d'attribut est IDREF
ou IDREFS
avec la même
propriété valeur normalisée peuvent avoir des propriétés références avec des valeurs différentes.
Pour résoudre ces contradictions, XInclude considère la propriété type d'attribut comme définitive.
Dans l'ensemble d'information final, la valeur de la propriété références d'un item d'information d'attribut
dont la propriété type d'attribut est IDREF
ou IDREFS
s'ajuste comme suit :
Pour chaque atome dans la propriété valeur normalisée, la propriété références
contient un item d'information d'élément avec les mêmes propriétés que l'item d'information d'élément
dans l'ensemble d'information final avec un attribut dont la propriété type d'attribut est ID
et la
propriété valeur normalisée est égale à l'atome en question. L'ordre des éléments dans la
propriété références est le même que celui des atomes apparaissant dans la
propriété valeur normalisée. Si on ne trouve aucun élément ou plusieurs éléments pour l'une des valeurs atomiques,
alors la propriété références n'a pas de valeur.
4.5.4 L'ajustement des espaces de nommage
La propriété espaces de nommage dans la portée assure que la visibilité d'un espace de nommage sera conservée
au travers de l'inclusion. Toutefois, après l'inclusion, la propriété attributs d'espace de nommage
peut ne pas fournir la liste complète des déclarations d'espace de nommage nécessaires pour interpréter les noms qualifiés dans le
contenu des attributs ou des éléments dans l'ensemble d'information final. On ne recommande donc pas que les processeurs XInclude
exposent les attributs d'espace de nommage dans l'ensemble d'information final. Si on ne peut pas l'éviter,
alors l'implémentation peut ajouter des items d'information d'attribut
à la propriété attributs d'espace de nommage pour une approximation des informations transmises par
la propriété espaces de nommage dans la portée.
4.5.5 L'ajustement de l'adresse URI de base
La propriété addresse URI de base de l'ensemble d'information acquis ne change pas pendant la fusion
de l'ensemble d'information et elles reste inchangée après la fusion. Les références URI relatives dans
l'ensemble d'information inclus se résolvent donc par rapport à la même adresse URI, bien qu'elles soient incluses dans un
document dont l'adresse URI de base en vigueur est potentiellement différente. On ajoute des
attributs xml:base à l'ensemble d'information final pour refléter ce fait.
Chaque item d'information d'élément dans les
éléments inclus de niveau supérieur qui a une propriété
URI de base différente de celle de
son parent d'inclusion voit s'ajouter un item d'information d'attribut
à sa propriété attributs. Cet attribut a les propriétés suivantes :
-
Un nom d'espace de nommage de http://www.w3.org/XML/1998/namespace ;
-
Un nom local de base ;
-
Un préfixe de xml ;
-
Une valeur normalisée égale soit à l'URI de base
de l'élément, soit une référence URI équivalente, relative à la propriété URI de base
du parent d'inclusion. Les circonstances dans lesquelles une adresse URI relative est souhaitable et comment calculer
une telle adresse URI relative dépendent de l'implémentation ;
-
Un drapeau spécifié indiquant que cet attribut était effectivement défini dans la balise ouvrante de son élément ;
-
Un type d'attribut de CDATA
;
-
Une propriété références sans valeur ;
-
Un élément possesseur de l'item d'information de l'élément.
Si un item d'information d'attribut xml:base est déjà présent, alors il est remplacé par le nouvel attribut.
4.5.6 L'ajustement de la langue
Alors que l'attribut xml:lang est décrit comme hérité de XML,
l'ensemble d'information XML ne prévoit rien pour préserver l'héritage de cette propriété dans la composition du document
au contraire de XInclude. Ce chapitre introduit une propriété langue qui enregistre la visibilité de
l'information fournie par xml:lang afin de la préserver pendant l'inclusion.
Un processeur XInclude devrait augmenter
l'ensemble d'information source et
l'ensemble d'information acquis en ajoutant la
propriété langue à chaque item d'information d'élément. La valeur de cette propriété correspond à
la valeur normalisée de l'attribut xml:lang apparaissant, le cas échéant,
sur l'élément en question, une déclaration xml:lang="" n'amenant aucune valeur ; sinon c'est la valeur de la
propriété langue de l'élément parent de cet élément, le cas échéant ; sinon la propriété n'a pas de valeur.
Chaque item d'information d'élément dans les
éléments inclus de niveau supérieur qui a une valeur
de propriété langue différente de celle de son parent d'inclusion
(en prenant en compte l'insensibilité à la casse d'après [IETF RFC 3066]), ou qui a une valeur
si son parent d'inclusion est un item d'information de document,
voit s'ajouter un item d'information d'attribut dans sa propriété attributs. Cet attribut
a les propriétés suivantes :
-
Un espace de nommage de http://www.w3.org/XML/1998/namespace ;
-
Un nom local de lang ;
-
Un préfixe de xml ;
-
Une valeur normalisée égale à la propriété langue de l'élément. Si la
propriété langue n'a pas de valeur, alors la valeur normalisée correspond à la chaîne vide
-
Un drapeau spécifié indiquant que cet attribut était effectivement défini dans la balise ouvrante de son élément ;
-
Un type d'attribut de CDATA
;
-
Une propriété références sans valeur ;
-
Un élément possesseur de l'item d'information de l'élément.
Si un item d'information d'attribut xml:lang est déjà présent, alors il est remplacé par le nouvel attribut.
Remarque :
L'attribut xml:space ne reçoit pas de traitement spécial XInclude.
4.5.7 Les propriétés conservées par l'ensemble d'information
En tant que transformation d'un ensemble d'information, le langage XInclude opère sur la structure logique des
documents XML, et non sur la sérialisation de leur texte. Toutes les propriétés d'un item d'information décrites dans
la spécification [XML Information Set] autres que celles modifiées spécifiquement par cette spécification
sont conservées au cours de l'inclusion. Les propriétés inclure l'historique et langue
introduites par la présente spécification le sont aussi. Les propriétés d'extension telles que les propriétés
[XML Schemas] d'ensemble d'information de validation après schéma
(PSVI) sont supprimées par défaut. Toutefois, un processeur XInclude
peut, au choix de l'utilisateur, conserver ces propriétés dans
l'ensemble d'information final si celles-ci sont exactes selon la spécification définissant la sémantique des propriétés d'extension.
Par exemple, la propriété PSVI validité décrit les conditions des ancêtres et des descendants.
Une modification des ancêtres et des descendants pendant le processus XInclude peut en rendre la valeur inexacte.
Par défaut, XInclude retire cette propriété mais, au choix de l'utilisateur, elle pourrait être recalculée pour obtenir une
valeur sémantiquement exacte. La manière précise d'accomplir cette opération n'est pas abordée par cette spécification.
