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 :

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 :

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 :

Contient :

Doctype Modèle de contenu
ditabase, topic, task, reference, concept ( données textuelles ou keyword ou option ou parmname ou apiname ou cmdname ou msgnum ou varname ou wintitle ou term ou data ou data-about ou foreign ou unknown ou indexterm ou index-base ou index-see ou index-see-also ou index-sort-as) (un nombre quelconque)
map, bookmap ( données textuelles ou keyword ou term ou data ou data-about ou foreign ou unknown ou indexterm ou index-base ou index-see ou index-see-also ou index-sort-as) (un nombre quelconque)

Contenu par :

Doctype Parents
bookmap p, note, lq, sli, li, itemgroup, dd, pre, lines, ph, stentry, indexterm, index-base, entry, keywords, index-see, index-see-also, organizationname
map p, note, lq, sli, li, itemgroup, dd, pre, lines, ph, stentry, indexterm, index-base, entry, keywords, index-see, index-see-also
ditabase p, note, lq, sli, li, itemgroup, dd, pre, lines, ph, stentry, indexterm, index-base, entry, keywords, abstract, section, example, prereq, context, cmd, info, tutorialinfo, stepxmp, choice, choptionhd, chdeschd, choption, chdesc, stepresult, result, postreq, refsyn, proptypehd, propvaluehd, propdeschd, proptype, propvalue, glossdef, screen, codeblock, pd, index-see, index-see-also
topic p, note, lq, sli, li, itemgroup, dd, pre, lines, ph, stentry, indexterm, index-base, entry, keywords, abstract, section, example, screen, codeblock, pd, index-see, index-see-also
task p, note, lq, sli, li, itemgroup, dd, pre, lines, ph, stentry, indexterm, index-base, entry, keywords, abstract, section, example, prereq, context, cmd, info, tutorialinfo, stepxmp, choice, choptionhd, chdeschd, choption, chdesc, stepresult, result, postreq, screen, codeblock, pd, index-see, index-see-also
concept p, note, lq, sli, li, itemgroup, dd, pre, lines, ph, stentry, indexterm, index-base, entry, keywords, abstract, section, example, screen, codeblock, pd, index-see, index-see-also
reference p, note, lq, sli, li, itemgroup, dd, pre, lines, ph, stentry, indexterm, index-base, entry, keywords, abstract, section, example, refsyn, proptypehd, propvaluehd, propdeschd, proptype, propvalue, screen, codeblock, pd, index-see, index-see-also
glossary p, note, lq, sli, li, itemgroup, dd, pre, lines, ph, stentry, indexterm, index-base, entry, keywords, abstract, section, example, glossdef, screen, codeblock, pd, index-see, index-see-also

Héritage :

- topic/indexterm

Attributs :

Nom Description Type de donnée Valeur par défaut Obligatoire ?
start Spécifie qu'une entrée d'index est positionnée au début d'une plage. Cf. la description de <indexterm> pour plus d'informations. CDATA #IMPLIED non
end Spécifie qu'une entrée d'index est positionnée à la fin d'une plage ; sa valeur correspond à celle de l'attribut start sur un autre <indexterm>. Cf. la description de <indexterm> pour plus d'informations. CDATA #IMPLIED non
%univ-atts; (%select-atts;, %id-atts;, %localization-atts;) Un ensemble d'attributs liés, décrit à la section 25.7. %univ-atts; entité paramètre sans objet pour une entité paramètre sans objet
%global-atts; (xtrf, xtrc) Un ensemble d'attributs liés, décrit à la section 25.2. %global-atts; entité paramètre sans objet pour une entité paramètre sans objet
class, keyref Attributs communs, décrit à la section 25.9. Autres attributs DITA communs