Créer un index avec LaTeX

Au cours des articles précédents sur LaTeX (regroupés ici en un seul document PDF), Fabien Conus et moi avons abordé la création de tables des matières, des figures, de liste des tableaux. Dernièrement, nous avons également parlé de la création de bibliographies dans cet article. Pour être complet sur les facultés de LaTeX en matière d'édition d'ouvrages destinés à la publication, il reste maintenant à évoquer la création d'index.

Créer un index sous LaTeX oblige à passer par un outil externe dédié (comme pour la bibliographie avec BibTeX) . Deux sont sur le « marché » actuel : MakeIndex et Xindy. Je vais détailler la procédure et les commandes à utiliser avec l'outil le plus répandu et le plus fiable, MakeIndex, et dire un mot sur une alternative séduisante, Xindy, malheureusement pas encore au point sur notre plate-forme.

Je tiens à préciser d'emblée que je ne me considère pas du tout comme un spécialiste de l'indexation. Je n'ai moi-même produit qu'un seul document avec index, et il s'agissait justement de l'introduction à LaTeX en PDF citée ci-dessus. Cela a suffi, je pense, à ce que j'acquière une maîtrise raisonnable de la technique de création d'un index avec LaTeX et MakeIndex, et c'est cette technique que je vais exposer ici. Mais quant au choix proprement dit des mots à indexer, je n'en parlerai pas ici : cela relève de la compétence de l'auteur du document lui-même.

Créer un index avec MakeIndex : marche à suivre

On commence par charger le paquet makeidx (à ne pas confondre avec l'outil externe MakeIndex) dans son document LaTeX. On place donc en préambule la commande

\usepackage{makeidx}

makeidx n'est pas à proprement parler indispensable à la création de l'index mais il simplifie son incorporation et apporte quelques fonctionnalités supplémentaires, ainsi qu'on va le voir.

Puis on place, toujours en préambule, la commande \makeindex (qui n'a rien à voir non plus avec l'outil MakeIndex). Ce paquet indique à LaTeX de relever les différentes commandes d'indexation \index{…} dont nous détaillerons la syntaxe un peu plus loin et qui seront placés dans le corps de document. Si on n'inclut pas cette commande \makeindex, les commandes \index deviennent inactives (cela peut éventuellement faire gagner du temps à la compilation, dans le cas où on ne souhaite pas avoir l'index formé tout de suite).

Passons maintenant à l'indexation proprement dite. Par exemple, si je souhaite indexer les mots « plage », « vent » et « charognards » qui sont contenues dans l'exemple suivant (extrait du livre Mes ours et moi de Robert Franklin Leslie — qui connait ce magnifique livre ?), je procède ainsi :

En moins d'une semaine, la plage\index{plage} était redevenue propre, parfumée et presque vivante. Les charognards\index{charognards} avaient dévoré ou emporté les cadavres. Les oursons en avaient eu leur part. Le vent\index{vent} et la pluie avaient dissipé les odeurs de mort et de brûlé.

Il ne faut laisser absolument aucun espace entre le mot à indexer et la commande \index correspondante, afin de ne pas laisser une éventuelle coupure de page venir s'insérer entre les deux. On peut également procéder de la façon suivante, plus lisible :

En moins d'une semaine, la plage%
\index{plage}
était redevenue propre, parfumée et presque vivante. Les charognards%
\index{charognards}
avaient dévoré ou emporté les cadavres. Les oursons en avaient eu leur part. Le vent%
\index{vent}
et la pluie avaient dissipé les odeurs de mort et de brûlé.

Notez l'insertion judicieuse des symboles de commentaires % : ils suppriment l'espace qui serait créée dans le fichier PDF par le retour à la ligne dans le fichier LaTeX.

Enfin, on insère la commande \printindex (définie par le paquet makeidx) à l'endroit où l'on souhaite voir l'index apparaître. Dans la plupart des cas, on le souhaite en toute fin d'ouvrage, donc on placera cette commande juste avant le \end{document}.

Pour récapituler, voici à quoi ressemble un fichier LaTeX minimaliste, en français, contenant tout ce qu'il faut pour une indexation :

\documentclass{article} %Pour la francisation %(le texte est ici encodé en Mac OS Roman) \usepackage[applemac]{inputenc} \usepackage[T1]{fontenc} \usepackage{lmodern,textcomp} \usepackage[frenchb]{babel} %Pour l'index \usepackage{makeidx} \makeindex % \begin{document} En moins d'une semaine, la plage% \index{plage} était redevenue propre, parfumée et presque vivante. Les charognards% \index{charognards} avaient dévoré ou emporté les cadavres. Les oursons en avaient eu leur part. Le vent% \index{vent} et la pluie avaient dissipé les odeurs de mort et de brûlé. \printindex \end{document}

Appelons ce fichier, disons, exemple.tex. Maintenant, procédons à la formation de l'index proprement dit. Cela se fait en trois étapes :

1. Création du document complet, hors index. Dans les cas les plus simples, comme notre exemple, une seule compilation LaTeX suffit. Mais si vous devez générer une table des matières, une bibliographie, etc., alors faites-le impérativement à cette étape, avec toutes les compilations qui sont nécessaires, sous peine de fausser complètement la numérotation des pages pour l'index.

   Si la commande \makeindex est présente dans le préambule, un fichier exemple.idx aura été créé à cette étape. Il contient les différentes entrées de l'index relevées séquentiellement dans le fichier LaTeX (sous une forme conçue pour être compréhensible par MakeIndex) ainsi que le numéro de page correspondant dans le PDF.

2. Compilation avec Makeindex. Il suffit pour cela d'ouvrir le menu « Composition » de TeXShop et d'y choisir l'option « MakeIndex » (raccourci « commande-majuscule-i »).

   

   MakeIndex crée alors un fichier exemple.ind contenant les différentes entrées de l'index, dûment triées par ordre alphabétique et avec toutes les instructions nécessaires pour la mise en forme par LaTeX qui sera effectuée à l'étape suivante. Un fichier exemple.ilg a été créé, c'est le fichier « log » de la compilation avec MakeIndex. Il est très utile à consulter en cas de problème avec ce dernier.

3. Compilation avec LaTeX. LaTeX incorpore (à l'endroit défini par \printindex) le contenu du fichier exemple.ind et interprète son contenu.

Ça y est, notre index est prêt !

Certes, il n'est pas vraiment imposant, mais il ne tient désormais qu'à vous de l'étoffer :-) Ce que nous allons voir maintenant va certainement vous y aider.

Possibilités offertes par la commande \index

Gestion du tri et personnalisation du style de l'entrée

Supposons que vous voulez classer dans votre index un symbole ou un mot particulier qui ne fasse pas partie des mots à caractères latins. Par exemple, dans un texte en français, on voudrait logiquement que la lettre grecque ß (obtenue par la commande $\beta$ en LaTeX) soit classée à la lettre « b », comme s'il s'agissait du mot « beta » en toutes lettres. Ainsi ß apparaîtra entre les mots « bar » et « botte » par exemple. Pour obtenir cela, il faut utiliser la syntaxe suivante :

\index{forme servant au tri@forme réelle}

Dans notre cas, la forme servant au tri est « beta », la forme réelle est $\beta$. On entrera donc en argument de la commande \index le mot « beta » et la commande $\beta$ séparés par une arobase :

\index{beta@$\beta$}

Dans l'index final, cela donnera quelque chose comme ceci :

La mot placé devant l'arobase, qui sert au tri de l'entrée, est appelée clé de tri de l'entrée.

Cette distinction entre l'entrée proprement dite et sa clé de tri est essentielle dans un autre cas de figure : les mots contenant des caractères accentués (ou un c cédille, ou un « e dans l'o », etc.). En effet, MakeIndex ne sait pas trier les caractères non ASCII. Pour lui, le mot « été » entré tel quel en argument d'une commande \index serait à classer avec les symboles du genre « % » ou « & », avant même les mots commençant par « a ». Plutôt gênant, n'est-ce pas ?

Heureusement, on peut contourner le problème en lui demandant de le trier comme le mot « ete », sans les accents :

\index{ete@été}

Il apparaîtra alors classé comme il le faut dans l'index, comme dans l'exemple ci-dessous :

Gestion de différents niveaux d'entrées

On peut donner plusieurs niveaux à son entrée d'index. Par exemple, si vous préparez un cours de mathématiques traitant des fonctions, vous souhaiterez certainement indexer le mot « fonction » dans votre ouvrage. Mais outre la notion de fonction en elle-même, il y a la fonction trigonométrique, exponentielle, logarithme… ou même logarithme népérien, décimal, etc. On peut gérer cela avec la commande \index, en séparant les niveaux d'entrée par le symbole !, le point d'exclamation. Par exemple :

\index{fonction!logarithme}

On peut avoir jusqu'à trois niveaux d'entrées, comme ici :

\index{fonction!logarithme!neperien@népérien}

(noter l'insertion d'une clé de tri pour le mot « népérien », en raison de ses accents).

Bien évidemment, la hiérarchie sera parfaitement restituée dans votre index, comme ci-dessous :

Entrées regroupées

Imaginez que vous vouliez indexer un mot, et que ce mot apparaisse particulièrement fréquemment sur plusieurs pages consécutives. Par exemple, si vous écrivez un traité d'apiculture, le mot « abeille » est censé y apparaître souvent :-) Alors, plutôt que de placer une commande \index{abeille} à chaque fois que ce mot est employé, ce qui serait vite fastidieux, on peut « regrouper » toutes ces entrées d'index. De telle sorte que l'index mentionnerait en face du mot « abeille », non plus toute une série de numéros de pages séparés par des virgules, mais un intervalle de pages, comme ici :

Pour cela, il suffit de placer la commande

\index{abeille|(}

au début du passage où le mot est traité, et la commande

\index{abeille|)}

à la fin de ce passage.

Références croisées

On peut souhaiter qu'une entrée renvoie à une autre dans l'index. Ainsi dans l'exemple précédent, le logarithme est référencé dans l'entrée « fonction ». Il peut donc être intéressant de créer une entrée « logarithme » qui ne place pas de numéro de page mais qui renvoie le lecteur à l'entrée « fonction », comme ici :

Pour obtenir cette référence à une autre entrée, on utilise la commande see (qui s'écrit sans contre-oblique), fournie par le paquet makeidx. Cette commande doit être séparée de l'entrée par une barre verticale | comme pour le regroupement d'entrées. Ainsi, l'exemple précédent a été permis par la commande

\index{logarithme|see{fonction}}

N'oubliez pas de charger en préambule le paquet babel avec l'option frenchb, car sinon vous verriez le mot see à la place de « voir » dans l'index.

Personnalisation du style du numéro de page.

Si vous souhaitez mettre en valeur la pagination de votre entrée dans l'index, cela se fait en utilisant la commande LaTeX à argument correspondante (sans la contre-oblique), selon la syntaxe employé dans l'exemple suivant :

\index{abeille|textbf}

Cela donnera le résultat attendu :

Gestion des caractères spéciaux

Comment indexer des mots contenant les symboles « ! », « @ » ou « | », voire ces symboles eux-même, dont on a vu qu'ils ont une signification spéciale pour MakeIndex ? En les faisant précéder d'un double-quote droit, « " ». Par exemple :

\index{out"!}

« Et comment indexer le double-quote droit lui-même, alors ? » vous demanderiez-vous. Et bien, il suffit de le faire précéder lui aussi d'un double-quote droit :-)

Une difficulté avec Makeindex est d'indexer les accolades : en effet, si un mot indexé contient une accolade ouvrante, il faut qu'il y ait une accolade fermante plus loin. Et c'est valable pour les commandes \{ et \} : si la première apparaît, l'autre doit impérativement suivre plus loin ! En guise d'illustration, voici comment on pourrait indexer les accolades elles-mêmes :

\index{{}1@$\lbrace$}

pour l'accolade ouvrante, et

\index{{}2@$\rbrace$}

pour l'accolade fermante. Les chiffres 1 et 2 ont été ajoutés pour obliger MakeIndex à classer l'accolade ouvrante devant l'accolade fermante.

Personnaliser l'index

De la même façon qu'on personnalise les styles de la bibliographie avec des fichiers de style, d'extension .bst (cf. l'article sur la bibliographie avec LaTeX)), on peut personnaliser son style d'index via des fichiers de style d'extension .ist. Mais la gestion de ces styles est rendue moins évidente par trois choses :

• on est alors obligé d'utiliser MakeIndex via le Terminal, car TeXShop ne permet d'accéder qu'au style standard de MakeIndex;
• La syntaxe de ces fichiers .ist est propre à MakeIndex et n'a pas grand'chose à voir avec celle de LaTeX (c'est la même chose avec les fichiers .bst de BibTeX, il est vrai) ;
• il semble y avoir relativement peu de styles prédéfinis pour MakeIndex dans le monde LaTeXien (je n'en connais pas pour ma part), contrairement à ceux de BibTeX.

Heureusement, élaborer soi-même le style qui convient le mieux semble relativement simple (n'ayant jamais dû le faire moi-même, je reste prudent ici).

Je vais illustrer (sans la détailler) la façon de procéder sur un exemple simple, que j'ai pompé sans vergogne sur l'excellent site de l'ENS consacré à LaTeX, dans sa section « Index ».

Nous reprenons notre exemple du début de cet article (fichier exemple.tex). Supposons qu'on souhaite maintenant séparer nettement les groupes de mots de notre index, en plaçant en début de chaque groupe l'initiale de leurs mots, en capitales et en caractères gras. Il faut d'abord créer un fichier .ist qui permette d'obtenir ceci. Appelons-le monstyle.ist. Il devra contenir les lignes suivantes :

heading_prefix "{\\bfseries\\hfil "
heading_suffix "\\hfil}\\nopagebreak\n"
headings_flag 1

Ce fichier doit être placé dans votre répertoire de travail, ou bien dans le répertoire /Users//Library/texmf/makeindex/ist que vous aurez éventuellement vous-même créé.

Lors de la génération du fichier PDF avec index, la compilation par MakeIndex via TeXShop (l'étape 2) doit être remplacée par cette procédure : ouvrez le Terminal, chargez-y votre répertoire de travail et entrez la commande

makeindex -s monstyle.ist exemple.idx

Votre fichier exemple.ind est alors créé, et à l'étape 3 l'index obtenu apparaîtra ainsi :

Ce qui est exactement ce qu'on désirait.

Le livre de Bernard Desgraupes, LaTeX : apprentissage, guide et référence (éditions Vuibert) détaille de façon claire et en français tout ce qu'il faut savoir pour créer un fichier de style d'indexation, dans son chapitre 12, thème XII, pages 540-542. Vous trouverez également toutes les instructions pour cela dans votre installation LaTeX (en supposant que vous utilisez MacTeX 2008 et maîtrisez l'anglais), au chemin suivant :

/usr/local/texlive/2008/texmf-dist/doc/makeindex/base/ind.dvi

Lacunes de MakeIndex

Pas de gestion directe des caractères accentués.

Pour ses clés de tri, MakeIndex, on l'a vu, n'accepte que des caractères ASCII. Cela peut s'avérer assez contraignant si l'on est amené à trier des groupes de mots du genre « côte », « cote », « coté », « côté » (exemples tirés du LaTeX Companion, deuxième édition, section 11.3.2, p. 682). MakeIndex est alors incapable de faire le tri entre ces mots puisqu'ils correspondent tous les quatre à la même clé de tri (« cote »). En conséquence, ils figureront donc dans l'index dans l'ordre de leur apparition dans le texte.

On peut contourner ce problème en trichant légèrement avec cette clé de tri. Le juste ordre de ces quatre mots, selon les critères usuels de tri des dictionnaires français, est « cote », « coté », « côte », « côté ». On leur associera donc respectivement les clés de tri « cote1 », « cote2 », « cote3 » et « cote4 » :

\index{cote1@cote} \index{cote2@coté} \index{cote3@côte} \index{cote4@côté}

Mais l'idéal, évidemment, serait que les mots accentués soient triés directement sans qu'il y ait besoin de spécifier des clés de tri particulières !

C'est ce que permet l'outil d'indexation Xindy, plus récent. Malheureusement, s'il est paraît-il tout-à-fait opérationnel sur Linux, il ne semble pas fonctionner correctement sur Mac OS X (voir ce fil de discussion récent sur le newsgroup fr.comp.text.tex, initié par moi-même).

Précautions à prendre avec le paquet hyperref

Si vous avez chargé le paquet hyperref (abordé dans cet article), chaque numéro de page de l'index devient un hyperlien qui renvoie, dès qu'on clique dessus, à la page du texte concernée. Mais cela ne marche plus si on a mis le numéro de la page en gras, en italique ou en oblique, etc., et plus généralement si on a personnalisé le style du numéro de la façon exposée plus haut :

\index{abeille|textbf}

On contourne le problème en utilisant la commande \hyperpage du paquet hyperref. Par exemple, pour mettre respectivement en gras et en italique des numéros de page dans l'index, on pourra définir des commandes \pagebf et \pageit en introduisant dans le préambule du document LaTeX les lignes suivantes :

\newcommand{\pagebf}[1]{\textbf{\hyperpage{#1}}} \newcommand{\pageit}[1]{\textit{\hyperpage{#1}}}

et on les utilisera dans le corps du document à la place des commandes de changement de style habituelles :

\index{abeille|pagebf}

(toujours sans mettre de contre-oblique !). Ainsi les numéros de page resteront « cliquables ». J'ai retiré cette astuce du livre de David Carella, Règles typographiques et normes, éditions Vuibert, qui aborde les règles typographiques et leurs applications dans le cadre de LaTeX, en particulier pour l'index (section « Indexation », pages 22 à 24).

Pour aller plus loin

Le paquet index étend les fonctionnalités de LaTeX concernant l'index. Il permet notamment la création d'index multiples et la visualisation des entrées d'index au cours de l'élaboration du document. Voyez sa documentation pour plus de détails.

Certaines extensions de LaTeX utilisent MakeIndex (voire Xindy) pour créer non plus un index mais un glossaire. Les paquets nomencl et glossaries, notamment, ont été créés dans ce but. Tristan Lorino, dans son livre de présentation de LaTeX, dont une version PDF est librement téléchargeable sur le Web, détaille sa propre façon de faire pour la création d'un glossaire. N'ayant jamais eu à en créer moi-même, je ne peux pas en dire plus. Guillôme, si tu passes par là ? ;-)