À quoi ça sert ?

Ce court guide est destiné à expliquer le mécanisme du ODD chaining. Un fichier ODD spécifie une utilisation de la TEI en sélectionnant des éléments ou des attributs particuliers, etc. dans l’ensemble de la TEI. Mais il est également possible de rafiner encore plus cette spécification en faisant dériver votre ODD les uns des autres. En principe, vous pouvez chaîner des ODDs ensemble de cette manière autant que vous le souhaitez. Vous pouvez employer cette fonctionnalité de différentes manières : vous pouvez ajouter des restrictions additionnelles à un ODD existant, par exemple pour modifier la liste des valeurs possibles d’un attribut vous pouvez réduire le sous-ensemble d’éléments produits par un ODD existant vous pouvez ajouter de nouveaux éléments ou des modules à un ODD existant

Comment ça marche ?

Un ODD ne peut contenir rien d’autre que des déclarations indépendantes, en employant seulement des éléments elementSpec, classSpec. Mais la plupart des ODDs se composent de plusieurs références à l’énorme quantité de déclarations déjà fournies par les de la TEI. Des ODDs comme TEI Lite ou TEI Bare se composent de référérences aux objets qu’ils utilisent, exprimés au moyens d’éléments tels que moduleRef, elementRef, ou classRef. Ces références (ainsi que toutes les déclarations indépendantes) sont réunies au sein d’un élément schemaSpec qui spécifie le schéma que l’ODD est destiné à générer. Cet élément dispose d’un attribut source utile mais peu connu dont l’objectif est de déclarer où les objets référencés par la spécification du schéma (les déclarations indépendantes) peuvent être trouvées. Par défaut, quand un ODD ne spécifie aucune source, on assume que celles-ci doivent être collectées dans la livraison la plus récente des Guidelines TEI. Vous pouvez modifier ce comportement en renseignant une URI différente. Par exemple, un schemaSpec avec l’attribut source disposant de la valeur tei:2.4.0 irait chercher ses déclarations dans la livraison 2.4.0 des Guidelines. Un autre avec la valeur mySuperODD.subset.xml irait rechercher les déclarations dans un fichier de ce nom dans le répertoire courant. Et un autre encore avec la valeur http://example.com/superODDs/anotherSubset.xml irait le chercher à la valeur d’URL renseignée.

Il est important de comprendre que la ressource indiquée par l’attribut source doit contenir une spécificiation explicite et complète des éléments : c’est-à-dire des elementSpec plutôt que des elementRef, des classSpec plutôt que des classRef, et ainsi de suite. Elle peut bien sûr contenir d’autres élements TEI, mais ceux-ci seront ignorés entièrement au cours de la construction d’un schéma. Un fichier dénommé p5subset.xml, faisant partie de chaque livraison de la TEI, est un exemple d’une ressource de ce genre : il contient une spécification de chaque élément TEI, de toutes les classes, macro et type de données, et rien d’autre. Lorsque le paramètre de l’attribut source n’est pas fourni, c’est la version la plus récente de ce fichier qui est employée lors du traitement d’un ODD.

Traitement d’un ODD

Regardons d’un peu plus près la manière dont la TEI définit un schéma très léger appelé TEI Bare. Son élément de spécification de schéma commence comme suit :

Aucune attribut source n’est spécifié, ainsi la les déclarations des éléments demandés seront prises dans le fichier courant p5subset.xml.

Notez que cet ODD contient à la fois des références et des spécifications : il contient des références à des modèles (qui peuvent être conçues comme des raccourcis pour des références à des éléments ou des classes, dès lors qu’un module n’est rien d’autre qu’une collection de spécifications d’éléments et de classes) et des spécifications pour deux classes (classSpec), plutôt que des références (classRef). La référence au module tei contenue dans cette spécification icnlue la plupart des classes de la TEI, y compris ces deux classes-là. Un processeur ODD devra alors résoudre les spécifications de classe dupliquées pour les classes att.global et att.fragmentable. La solution requise est indiquée par la valeur de l’attribut mode : si celle-ci est delete alors les deux déclarations seront ignorées, et la classe est supprimée ; si sa valeur est change alors les deux déclarations seront mélangées de sorte que les parties spécification présentes dans la seconde spécification écrasent les premières. Dans ce cas, l’effet sera de supprimer les trois attributs mentionnés.

Vous pouvez vérifier que cet ODD fait bien ce que vous attendez, si vous disposez d'une version récente du oXygen TEI Framework: téléchargez simplement le fichier tei_bare.odd (disponible au depot github de la TEI), et demandez à oXygen de lui appliquer la transformation prédéfinie TEI ODD to HTML. Cela va produire un mini-manuel pour la personnalisation TEI Bare au format HTML au début de laquelle vous pourrez consulter la liste des éléments que le schéma contient.

Vous pouvez alors vérifier que les modifications de la classe d’attribut att.global indiquées ci-dessus ont bien été exécutées en consultant cette documentation.

Maintenir votre propre sous-ensemble

Nous venons de traiter un ODD utilisant une référence au sous-ensemble par défaut p5subset, c’est-à-dire d’après l’ensmeble de la TEI. Supposez cependant que vous voudriez utiliser TEI Bare comme point de départ d’une autre personnalisation. Nous pourrions simplement éditer la source de TEI Bare, et ajouter nos propres modifications dans ce fichier, mais cela deviendrait bientôt ingérable si nous devions faire avec des personnalisations plus importantes comme point de départ. Au lieu de cela, nous allons utiliser TEI Bare lui-même comme source. Pour cela, comme noté ci-dessus, nous allons devoir générer une version compilée de TEI Bare qui contient seulement des éléments de spécification dans laquelle toutes les références ont été résolues. Cela peut être effectué facilement en employant la feuille de style odd2odd.xsl qui fait partie du paquet TEI Stylesheet, mais n’est pas actuellement incluse dans le framework d’oXygen. Il existe toutefois un utilitaire en ligne de commande teitoodd qui fait ce travail, et qu’il est aussi facile d’installer dans votre propre transformation oXygen. Nous laissons cela comme un exercice pour le lecteur.

Chaînage : sous-ensemble

Supposez maintenant que nous avons une version compilée de TEI_bare dans un fichier nommé TEI_bare.compiled.xml. Le traitement de la spécification de schéma suivante produirait alors exactement le même résultat que nous aurions obtenu d’une version non compilée.

Cela fonctionne car chaqu’une des éléments moduleRef ici réfèrent au module (i.e. ensemble d’éléments, etc.) disponible dans l’ODD compilé plutôt qu’aux modules définis dans l’ensemble de la TEI. Notez aussi que seulement fournir l’ODD compilé comme source d’un schema n’est pas suffisant : nous devons aussi spécifier laquelle des déclarations elle contient nous voulons utiliser : nihil ex nihilo fit...!

Cependant, la raison pour laquelle nous nous sommes engagés sur cette voie n’était pas de pouvoir faire d’une autre manière ce que nous pouvions déjà faire autrement. Produisons maintenant une version réduite de TEI Bare dans laquelle l’élément head serait manquant.

Et juste pour la complétude, voici une autre manière d’arriver au même effet :

Notez qu’on ne peut supprimer ou modifier que les choses qui sont déjà présentes dans l’ODD compilé spécifié par l’attribut source. Cette approche du chaînage est bien adaptée dans une situation où nous définissons d’abord un ODD qui combine tous les éléments (etc.) que nous envisageons d’utiliser et que nous dérivons ensuite un sous-ensemble particulier à partir d’eux. Par exemple, un pour les manuscrits, un pour les imprimés de la Renaissance, un pour les imprimés contemporains, etc. (Cette approche a, par exemple, été adoptée par la Deutsches Text Archive.)

Chaînage : super-ensemble

Mais le chaînage ODD n’est pas restreint à la définition de sous-ensembles. Supposez que nous voulions prendre le schéma existant TEI Bare et ajouter des déclarations d’autres modules. Nous pourrions bien sûr laborieusement copier toutes les déclarations dont nous avons besoin dans notre schemaSpec, mais cela serait bien plus élégant d’avoir de ne pas avoir à faire ça. Supposez, par exemple, que nous voulions ajouter tout ce qui est fourni par le module gaiji. Ce module n’était pas inclus lorsque nous avons défini notre version compilée de TEI Bare, bien qu'il est évidemment disponible dans l’ensemble de la TEI. Voici une manière de faire :

Le moduleRef qui va rechercher le module gaiji utilise son propre attribut source pour spécifier où trouver les déclarations de ce module. Cela ne ferait pas sens d’aller les chercher dans tei_bare.compiled.odd : elle n’y sont pas. Au lieu de cela, on va les retrouvées depuis une copie en ligne d’un ODD compilé qui fournit l’ensemble des Guidelines TEI. Bien sûr, nous aurions aussi pu en meme temps réaliser la définition d’un sous-ensemble. Par exemple :

Cet ODD nous donnera tout ce qui est disponible dans tei_bare avec les g, char, et glyph tirés par défaut du module gaiji. Nous pourrions parvenir au même effet en nommant explicitement les élements dont nous avions besoin, de nouveau en spécifiant où ceux-ci devraient être trouvés :

On peut employer cette technique pour ramener un élément qui a été effacé du schéma compilé. Par exemple, l’élément q n’est pas disponible avec TEI Bare, mais il peut facilement être rétabli. Nous pouvons même spécifier quelle version de l’élément q est souhaitée : dans ce cas, nous irons chercher la version définie dans la distribution 3.0.0 de la TEI P5 :

Il existe un tableau utile répertoriant les dates et les numéros de version de toutes les versions de TEI P5 au TEI website.

Un cas d'usage

Supposons que vous mettiez en place une application de crowdsourcing pour la transcription de documents d'archives de quelque nature que ce soit. Une fois les documents capturés et légèrement étiquetés, vous envisagez d'enrichir les archives avec des métadonnées détaillées décrivant les personnes et les lieux qui y sont mentionnés. Vous prévoyez donc d'avoir besoin de deux schémas : un (très simple et contraint) pour valider les fichiers de transcription, et un autre (également très contraint, mais différemment) pour valider les métadonnées. Mais bien sûr, vous devrez également valider les documents complétés, combinant les deux types de données. Et il y a certaines fonctionnalités (paragraphes, titres, etc.) communes aux deux, ce qui suggère que vous aurez également besoin d'un troisième schéma... Le chaînage ODD est la réponse !

(Avant de poursuivre votre lecture, je vous suggère de télécharger notre petit ensemble de fichiers d'exemple et de lancer votre processeur XML préféré. Veuillez noter que ces fichiers d'exemple sont simplement destinés à démontrer l'effet du chaînage : dans une application réelle, on personnalise son schéma beaucoup plus précisément, par exemple en supprimant les attributs inutiles, en simplifiant les modèles de contenu, en ajoutant différents exemples, etc.)

Il nous faudra définir le troisième schéma, qui contient tout ce qui est susceptible d'être utile à l'un ou l'autre des deux autres, plus tout ce qui est commun aux deux. Appelons celui-ci notre mère ODD. Ouvrez le fichier motherODD.xml et vous verrez un ODD typique, avec l'élément racine TEI, défini en référence aux directives TEI complètes. En plus du module d'infrastructure tei, il contient des éléments tels que pb, p, hi, div, et name du module core, ainsi que l'ensemble de métadonnées que nous prévoyons d'utiliser pour chaque document TEI valide, qui prend ses composants des modules header, namesdates, et corpus.

Nous définirons nos deux schémas plus spécialisés en référence à celui-ci. Nous devons donc compiler le motherODD, le transformant effectivement en une collection ou une bibliothèque de spécifications TEI complètes. Nous faisons cela en exécutant la transformation odd2odd mentionnée ci-dessus : les résultats de notre fichier exemple se trouvent dans le fichier motherODD.compiled. Jetez maintenant un œil aux deux sous-ensembles ODD différents dans notre exemple : un (justTranscripts.xml) pour les transcriptions et un (justMetadata.xml) pour les métadonnées. Notez que chacun de ces fichiers ODD fait référence à motherODD.compiled au moyen de son attribut source. Notez également que chacun d'eux spécifie un élément racine différent : ceci afin que l'on puisse utiliser les schémas résultants pour valider une transcription sans en-tête, ou un en-tête sans transcription.

Essayez de traiter chacun de ces fichiers ODD pour générer de la documentation et un schéma, de la manière habituelle. Comparez ensuite les résultats. Nous avons inclus quelques exemples de fichiers de données pour vous permettre de vérifier que la validation fonctionne comme elle le devrait : le fichier transcription.xml doit être valide par rapport au schéma généré à partir de l'ODD justTranscription.xml et le fichier metadata.xml doit être valide par rapport au schéma généré à partir de l'ODD justMetadata.xml. Notre exemple suppose un flux de travail particulier dans lequel, par exemple, l'attribut ref est utilisé pour associer des éléments name a un élément person ou place dans l'en-tête ; votre kilométrage peut bien sûr varier.

Enfin, jetez un œil au fichier driver.tei : il utilise xInclude pour combiner les deux fichiers en un document TEI complet, qui devrait être valide par rapport au schéma généré à partir du motherODD. Encore une fois, n'hésitez pas à modifier si nécessaire en fonction de vos propres pratiques de travail !