La TEI Lite : encoder pour échanger : une introduction à la TEI
Edition finale révisée pour la TEI P5
traduction française de Sophie David

16. La documentation technique

Bien que l’objet central de ce document soit l’utilisation du schéma TEI pour encoder des documents existants, on peut utiliser ce même schéma pour encoder de nouveaux documents. Dans la préparation de nouveaux documents (tels que celui-ci), XML présente de nombreux avantages : la structure du document peut être représentée clairement, et le même texte électronique peut être réutilisé à des fins très différentes - pour produire par exemple des versions hypertextes ou feuilletables en ligne, mais aussi des versions bien mises en forme, et ce à partir d’une même source.

Pour ce faire, le schéma TEI Lite comprend des éléments permettant de marquer les caractéristiques de documents techniques en général, et de documents XML en particulier.

16.1. Les éléments supplémentaires pour les documents techniques

On peut utiliser les éléments suivants pour marquer les caractéristiques particulières de documents techniques :

  • att (attribut) contient le nom d'un attribut apparaissant dans le courant du texte.
  • code contient un code littéral provenant d'un langage formel, comme un langage de programmation.
  • eg (exemple) contient toutes sortes d'exemples illustratifs.
  • formula (formule) contient une formule mathématique ou tout autre type de formule
  • gi (identifiant générique) contient le nom d'un élément.
  • ident (identifiant) contient un identifiant ou un nom dans un langage formel pour un objet quelconque.
  • val (valeur) contient une seule valeur d'attribut.
L’exemple suivant montre comment ces éléments pourraient être utilisés pour encoder le passage d’un tutoriel, qui constitue une introduction au langage de programmation Fortran :
<p>Par tradition, on introduit
une langue de programmation avec cet exemple
classique: <eg xml:space="preserve">CHAR*12 GRTG GRTG='HELLO WORLD'  PRINT *, GRTG  END</eg>
</p>
<p>Dans ce code, on voit la déclaration d'un variable <ident>GRTG</ident>:
<code>CHAR*12 GRTG</code>, qui indique que l'object <ident>GRTG</ident> contient
12 octets de type <ident>CHAR</ident>. La valeur <val>HELLO WORLD</val> est ensuite
attribuée à cette variable. </p>

On peut paramétrer une application pour qu’un texte, tel que celui présenté ci-dessus, soit correctement formaté (par exemple, en conservant les fins de ligne, en utilisant une police particulière). De même, l’utilisation de balises telles que ident facilite grandement la construction d’un index.

On utilise l’élément formula pour encadrer toute formule mathématique ou chimique, qui se présente dans un texte comme un élément distinct. Comme les formules sont généralement exprimées au moyen d’une grande diversité de signes typographiques spécifiques, ce qui n’est pas le cas des textes ordinaires, le corps de la formule doit faire l’objet d’une notation spécifique. Cette notation doit être spécifiée par l’attribut notation, comme dans l’exemple suivant :
<formula notation="tex"> \begin{math}E =
mc^{2}\end{math} </formula>
Se pose un problème quand l’encodage XML est le propos même du document technique, lui-même encodé en XML. Dans de tels documents, il est essentiel de distinguer clairement l’encodage des exemples de l’encodage du document lui-même ; dans ce type de document, la probabilité de trouver des balises de fin est alors très forte. Une solution simple consiste, pour les exemples, à utiliser la référence d’entité prédéfinie &lt; pour représenter chaque caractère < (qui marque le début d’une balise XML). Une solution plus générale consiste à spécifier que les exemples sont des données, qui ne sont pas destinées à être traitées par un analyseur. Pour ce faire, on se sert d’une construction XML particulière, appelée CDATA marked section, comme dans l’exemple suivant :
<p>Une liste peut
être balisée ainsi: <eg><![ CDATA[ <list> <item>Premier item de
la liste</item> <item>deuxième item</item> </list>]]>
</eg> L'élément <gi>list</gi> contient une série d'éléments
<gi>item</gi>
</p>

L’élément list utilisé dans l’exemple ci-dessus ne doit pas être considéré comme faisant partie du document proprement dit, parce qu’il est inséré dans une section marquée : elle commence par une déclaration spéciale de balisage <![CDATA[, et se termine par ]]>.

Notons également l’utilisation de l’élément gi pour baliser les références aux noms d’éléments (ou identifiants génériques) dans le corps du texte.

16.2. Les sections générées

Les systèmes de production de documents actuelles offrent la possibilité de générer automatiquement des sections telles que la table des matières, l'index etc. Le schéma TEI Lite propose un élément pour marquer l’endroit où une telle section doit se trouver.

L’élément divGen peut être placé à n’importe quel endroit où un élément de division serait autorisé :
<front>
 <titlePage>
<!-- ... -->
 </titlePage>
 <divGen type="toc"/>
 <div>
  <head>Preface</head>
<!-- ... -->
 </div>
</front>
<body>
<!-- ... -->
</body>
<back>
 <div>
  <head>Appendix</head>
<!-- ... -->
 </div>
 <divGen type="indexn="Index"/>
</back>

Cet exemple montre également l’utilisation de l’attribut type pour distinguer les différentes sortes de sections qui auront été générées : dans le premier cas, une table des matières (un toc), et dans le second un index.

Quand un index existant ou une table des matières doivent être encodés (plutôt que générés), on utilise l’élément list (cf. section 11. Les listes).

16.3. La génération d’index

Alors que la production d’une table des matières à partir d’un document correctement balisé ne pose généralement pas de problèmes, la production d’un index de bonne qualité demande souvent un balisage plus minutieux. Bien que l’extraction (par exemple) de toutes les occurrences des éléments term ou name puisse constituer un bon point de départ, cela peut cependant ne pas suffire.

Le schéma TEI propose une balise spécifique index, qu’on utilise pour indiquer à la fois les parties du document qui doivent être indexées, et comment l’index doit être construit.

  • index (entrée d'index) marque un emplacement à indexer dans un but quelconque.
Par exemple, le deuxième paragraphe de cette section pourrait être codé ainsi :
Le schéma TEI propose une balise spécifique
<gi>index</gi>
<index>
 <term>indexation</term>
</index>
<index>
 <term>index (balise)</term>
 <index>
  <term> generation
     d'index</term>
 </index>
</index>, qu’on utilise pour indiquer ...
L’élément index peut également être utilisé pour fournir une information de nature interprétative ou analytique. Par exemple, dans le cadre d’une étude stylistique, on voudrait enregistrer les différentes figures utilisées par Ovide dans les Métamorphoses19. Une telle étude enregistrerait les références à Jupiter (soit deus, se, et le sujet de confiteor [sous une forme fléchie codée 227], les références à Jupiter-sous-l’-apparence-d’-un-taureau (soit imago tauri fallacis et le sujet de teneo), et ainsi de suite.
<l n="3.001">iamque deus posita fallacis
imagine tauri</l>
<l n="3.002">se confessus erat Dictaeaque rura tenebat</l>

Pour ce faire, on peut utiliser l’élément note, discuté dans la section 7. Les notes, ou l’élément interp discuté dans la section 15. L’interprétation et l’analyse. Ici, on montre comment l’élément index peut aussi être utilisé.

On suppose que l’objet doit générer plus d’un index : l’un rassemblera les noms des divinités (appelé dn), un autre les références onomastiques (appelé on), un troisième les références pronominales (appelé pr), et ainsi de suite. On pourrait alors procéder de la manière suivante :
<l n="3.001">iamque deus posita fallacis
imagine tauri <index indexName="dn">
  <term>Iuppiter</term>
  <index>
   <term>deus</term>
  </index>
 </index>
 <index indexName="on">
  <term>Iuppiter (taurus)</term>
  <index>
   <term>imago tauri
       fallacis</term>
  </index>
 </index>
</l>
<l n="3.002">se confessus erat Dictaeaque
rura tenebat <index indexName="pr">
  <term>Iuppiter</term>
  <index>
   <term>se</term>
  </index>
 </index>
 <index indexName="v">
  <term>Iuppiter</term>
  <index>
   <term>confiteor
       (v227)</term>
  </index>
 </index>
</l>

Pour chaque élément index ci-dessus, une entrée sera générée dans l’index approprié. L’entrée est le contenu de l’élément term. Dans chaque cas, les éléments term, rassemblés dans l’élément index secondaire, fournissent un deuxième mot clé. La référence à proprement parler sera extraite du contexte dans lequel l’élément index apparaît, i.e. dans ce cas, l’identifiant de l’élément l qui le contient.

16.4. Les adresses

On utilise l’élément address pour baliser une adresse postale de n’importe quel type. Il contient un ou plusieurs éléments addrLine, pour chaque ligne de l’adresse. Voici un exemple simple :
<address>
 <addrLine>Centre d'Études Supérieures de la Renaissance</addrLine>
 <addrLine>59, rue Néricault-Destouches</addrLine>
 <addrLine> 37013 TOURS</addrLine>
 <addrLine>France</addrLine>
</address>
Les parties de l’adresse peuvent être distinguées en utilisant l’élément name, discuté dans la section 10.1. Les dénominations et les expressions référentielles.
<address>
 <addrLine>Centre d'Études Supérieures de la Renaissance</addrLine>
 <addrLine>59, rue Néricault-Destouches</addrLine>
 <addrLine> 37013 <name type="city">TOURS</name>
 </addrLine>
 <addrLine>
  <name type="country">France</name>
 </addrLine>
</address>
Notes
19
L’analyse, légèrement simplifiée, a été empruntée, avec leur autorisation, à Willard McCarty et Burton Wright, An Analytical Onomasticon to the Metamorphoses of Ovid.

TEI Guidelines . This page generated on 2015-10-15T20:00:39Z.