10.4. indexterm

Un élément <indexterm> permet à l'auteur d'indiquer qu'un certain mot ou une certaine phrase devraient produire une entrée d'index dans l'index généré.

Le contenu d'un élément <indexterm> est utilisé pour produire une entrée d'index dans l'index généré. On peut imbriquer les éléments <indexterm> pour créer des index à plusieurs niveaux. Le contenu n'est pas affiché comme faisant partie du contenu du thème, seulement comme partie de l'index.

Un élément <indexterm> (sans attributs start ni end) est interprété comme un point de référence fournissant le numéro de la page courante à une entrée d'index dont le contenu est le contenu de l'élément <indexterm>. Tous les éléments <indexterm> avec le même contenu « fusionnent » pour former une seule entrée d'index dans l'index résultant, et tous les numéros de page fournis sont inclus dans cette entrée d'index.

Dans le cas d'éléments <indexterm> imbriqués, ceux sans sous-élément <indexterm> (c'est-à-dire les « terminaux ») fournissent un numéro de page à l'index généré ; les éléments <indexterm> ancêtres de ceux terminaux fournissent les niveaux supérieurs de l'entrée à plusieurs niveaux pour laquelle l'élément <indexterm> représente le niveau le plus bas.

Un élément <indexterm> qui apparaît dans le prologue d'un thème est interprété comme point de référence du début du titre du thème.

Il y a condition d'erreur si un élément <indexterm> sans sous-éléments <indexterm> contient à la fois un élément <index-see> et un élément <index-see-also>. (Note : Les éléments <index-see> et <index-see-also> dans des éléments <indexterm> n'ayant pas de sous-élément <indexterm> sont ignorés.) Pour cette condition d'erreur, une mise en œuvre peut (mais n'est pas obligée) émettre un message d'erreur, et peut (mais n'est pas obligée) récupérer en traitant tous ces éléments <index-see> comme des éléments <index-see-also>.

On peut utiliser les attributs start et end sur <indexterm> dans les cas où l'on souhaite indexer une discussion étendue qui peut se poursuivre sur plusieurs pages. Le début d'une plage (range) est indiqué par un <indexterm> avec un attribut start, la fin d'une plage par un <indexterm> avec un attribut end dont la valeur correspond à celle de l'attribut start de l'élément <indexterm> de début de plage. Un tel balisage apporte à l'index généré une plage de pages couvrant toutes les pages dans le champs de l'index.

L'élément <indexterm> de fin de plage ne devrait avoir aucun contenu en soi ; tout contenu est ignoré. Il n'y a aucune de raison pour l'élément <indexterm> de fin de plage d'avoir des <indexterm> ancêtres ; en revanche, une mise en œuve devrait pouvoir manipuler un élément <indexterm> de fin de plage imbriqué dans un ou plusieurs <indexterm>.

Les attributs start et end sont définis comme étant de type CDATA, quoique l'on recommande pour leurs valeurs qu'elles ne contiennent pas de caractères blancs (tels que des espaces ou les tabulations horizontales) ou des caractères de contrôle. La comparaison des valeurs start et end est faite caractère par caractère, tous les caractères étant significatifs et sans que n'intervienne un pliage de casse (case folding). Les attributs start et end sont ignorés sauf s'ils apparaissent sur un élément <indexterm> qui n'a pas de sous-élément <indexterm> (c'est-à-dire un <indexterm> terminal).

Les indications de plage d'index dans l'élément <topicmeta> d'un élément <topicref> peuvent apparaître au niveau carte, dans le prologue d'un thème, ou dans le corps d'un thème, et s'interprètent comme suit :

• Dans une carte (<map>), le début de plage pointe au début du titre de thème du thème référencé par son <topicref> conteneur. La fin de plage pointe à la fin du sous-élément final contenu par le thème référencé par son <topicref> conteneur, ou à la fin du dernier thème référencé par la carte courante (selon ce qui se présente en premier). Lorsqu'un début et une fin de plage apparaissent dans le même élément <topicmeta>, la plage s'applique à l'élément <topicref> et ses sous-éléments ;
• Dans un prologue (<prolog>), le début de plage pointe au début du titre du thème conteneur. La plage se termine par une fin de plage d'index correspondante dans le même prologue, ou par la fin du prologue, selon ce qui se présente en premier. La plage s'applique au thème conteneur et tous ses sous-éléments y compris les sous-relations définies dans une carte ;
• Dans un corps (<body>), la plage commence là où apparaît l'élément <indexterm> et se termine à l'indication de fin de plage d'index correspondante dans le même élément <body>, ou à la fin de <body>, selon ce qui présente en premier. Une telle plage d'index ne recouvre pas les sous-thèmes du thème.

Si des plages d'index avec le même identificateur se chevauchent, la plage la plus large s'applique, et les fins de plage sont comparées aux débuts de plage selon la règle « premier entré premier sorti ». En d'autres termes, les plages sont interprétées comme imbriquées plutôt que chevauchantes, le conteneur au niveau supérieur étant prioritaire sur les plages plus étroites contenues.

Comme défini ci-dessus, il n'existe pas de début de plage d'index qui n'ait soit une fin correspondante, soit une portée maximum. En revanche, il peut y avoir des indications de fin de plage d'index non appariées ; celles-ci devraient être ignorées.

Exemple

<p>An indexterm element allows the author to indicate that
a certain word or phrase should produce an index entry in the
generated index. You can nest indexterm elements to create
multi-level indexes.<indexterm>indexterm</indexterm>
<indexterm>Valid in Many Places elements<indexterm>indexterm</indexterm>
</indexterm></p>

Un balisage tel que :

<indexterm>cheese
  <indexterm>sheeps milk
    <indexterm>pecorino</indexterm>
  </indexterm>
  <indexterm>goats milk
    <indexterm>chevre</indexterm>
  </indexterm>
</indexterm>

équivaudrait à :

<indexterm>cheese
  <indexterm>sheeps milk
    <indexterm>pecorino</indexterm>
  </indexterm>
</indexterm>
<indexterm>cheese
  <indexterm>goats milk
    <indexterm>chevre</indexterm>
  </indexterm>
</indexterm>

et appartiendrait à l'entrée (input) qui générerait des entrées d'index résultat telles que :

• cheese
  • goats milk
    • chevre 14
  • sheeps milk
    • pecorino 14

Un balisage tel que :

<indexterm>cheese
  <indexterm>sheeps milk
    <indexterm start="level-3-pecorino">pecorino</indexterm>
  </indexterm>
</indexterm>
 . . .
<indexterm end="level-3-pecorino" />

(où les points de suspension représentent plusieurs pages d'entrée) pourrait générer une entrée d'index telle que :

• cheese
  • sheeps milk
    • pecorino 18-24

Contient :

Contenu par :

Héritage :

- topic/indexterm

Attributs :

OASIS DITA Version 1.1 Language Specification — OASIS Standard, 1 August 2007
Copyright © OASIS Open 2005, 2007. All Rights Reserved.