Index

Un index, c’est-à-dire la liste alphabétique des termes et des numéros de page en fin d’ouvrage, est construit par LaTeX dès lors que vous marquez les termes dans le texte. Trois éléments suffisent : déclarer \makeindex dans le préambule, placer \index{…} à chaque point à indexer, puis appeler \printindex là où la liste doit paraître. La subtilité est que le tri n’est pas effectué par LaTeX lui-même, mais par un programme séparé, makeindex (mendex / upmendex pour le japonais) ; comme avec bibtex, il faut donc une passe supplémentaire. Cette page va des déclarations initiales à la syntaxe des entrées (! sous-entrées, @ clés de tri, | encapsulation des pages), au processus de compilation, au tri japonais, aux réglages de style et au paquet moderne imakeidx.

Les quatre éléments d’un index

Les commandes d’index standard viennent du paquet makeidx. Chargez-le dans le préambule puis déclarez \makeindex ; à partir de là, LaTeX écrit les entrées d’index dans un fichier séparé (.idx). Il ne reste qu’à marquer les termes et à indiquer où la liste doit être imprimée.

• \usepackage{makeidx} — charge les commandes d’indexation (préambule).
• \makeindex — la déclaration qui active la collecte des entrées d’index (préambule). Sans elle, \index est ignoré silencieusement.
• \index{entry} — la marque placée dans le corps là où un terme apparaît. Rien n’est imprimé à cet endroit ; seul le numéro de page courant est enregistré.
• \printindex — la commande qui compose réellement l’index terminé, généralement à la fin du document.

L’idée essentielle est que \index est une marque invisible. Vous écrivez toujours le mot vous-même dans le corps du texte, puis ajoutez \index{…} juste après (random numbers\index{random numbers} are used). Le numéro de page de l’endroit marqué est celui qui sera enregistré pour cette entrée.

Écrire des entrées d’index

L’argument de \index possède sa petite syntaxe pour les sous-entrées, les clés de tri, les plages de pages, la mise en forme des numéros de page et les renvois. Elle repose sur quatre caractères spéciaux interprétés par makeindex (et non par LaTeX) : !, @, | et ".

Sous-entrées (!). Un point d’exclamation sépare les niveaux. \index{animals!cats} crée une entrée principale « animals » avec une sous-entrée « cats ». Répéter ! permet d’imbriquer jusqu’à trois niveaux (davantage avec la famille mendex / upmendex).

Clé de tri (@). Écrite sortkey@display, elle sépare la chaîne utilisée pour le tri de celle réellement imprimée. C’est indispensable pour les symboles et les formules, qui ne se trient pas selon leur glyphe. \index{alpha@$\alpha$} imprime α dans l’index mais le classe à « alpha ». En japonais, elle fournit la lecture des kanji (\index{さくいん@索引}).

Plages de pages (|( … |)). Lorsqu’un sujet couvre plusieurs pages, marquez le début avec |( et la fin avec |) pour obtenir une plage comme 12–15. Ouvrez avec \index{recursion|(} et fermez plus loin avec \index{recursion|)}.

Encapsulation des numéros de page (|). Placez une barre verticale suivie du nom d’une commande à un argument, et ce numéro de page seul sera formaté avec elle. \index{cat|textbf} met en gras la page où le terme est défini ; \index{group|textit} la met en italique. Vos propres noms de commandes fonctionnent aussi.

Renvois (|see / |seealso). Toujours après une barre, vous pouvez émettre un pointeur vers une autre entrée au lieu d’un numéro de page. \index{dog|see{pets}} produit « dog, *see* pets » ; |seealso{…} donne « *see also* ».

Imprimer les caractères spéciaux littéralement ("). Pour mettre !, @, | ou " dans une entrée comme caractères ordinaires, faites précéder chacun d’un guillemet double. Par exemple, \index{C"!} crée l’entrée « C! ».

Le processus de compilation (lancer makeindex)

Un index n’est pas terminé en une seule compilation. Comme bibtex, c’est un processus en trois étapes avec un programme séparé au milieu. D’abord, LaTeX collecte les appels \index dans un fichier brut, file.idx. Ensuite, le programme makeindex trie et formate ce fichier en file.ind, un index prêt à être composé. Enfin, une nouvelle exécution de LaTeX permet à \printindex de lire file.ind pour faire apparaître l’index dans le document. Un journal de traitement reste dans file.ilg.

\documentclass{article}
\usepackage{makeidx}
\makeindex
\begin{document}

METAFONT\index{METAFONT} は字形を、TeX\index{TeX} は組版を担う。
ここでは乱数\index{乱数|textbf} の生成を扱い、
群\index{group@群} と環\index{ring@環} にも触れる。
アルゴリズム\index{algorithm|(} の説明はここから始まり…

% （数ページ後）
…アルゴリズム\index{algorithm|)} の説明はここで終わる。

\printindex
\end{document}

Depuis la ligne de commande, lancez-le ainsi. -s choisit un fichier de style, -o nomme la sortie et -t nomme le journal ; si vous les omettez, seule l’extension change.

pdflatex mydoc        # writes mydoc.idx
makeindex mydoc       # mydoc.idx -> mydoc.ind (log in mydoc.ilg)
pdflatex mydoc        # \printindex reads mydoc.ind

Toute la séquence est prise en charge automatiquement par latexmk : il appelle makeindex quand le .idx change et relance LaTeX le nombre de fois nécessaire, si bien que vous n’avez pas à exécuter les trois étapes à la main.

Index japonais (mendex / upmendex)

Comme makeindex suppose un ordre alphabétique occidental, les index japonais utilisent mendex (avec pLaTeX) ou upmendex (avec upLaTeX / LuaLaTeX, compatible Unicode). Les deux sont compatibles avec makeindex : il suffit de les appeler à l’endroit où vous auriez appelé makeindex.

uplatex mydoc                 # writes mydoc.idx
upmendex -s style.ist mydoc   # sorts kana correctly -> mydoc.ind
uplatex mydoc                 # \printindex reads mydoc.ind

Le grand avantage est le tri des kana. Avec makeindex, classer les entrées dans l’ordre syllabique japonais imposait de fournir pour chacune une lecture hiragana/katakana sous la forme reading@display, puis de normaliser à la main les marques sonores. upmendex trie correctement et automatiquement les kana avec ICU (International Components for Unicode), ce qui supprime une grande partie de ce travail. En fournissant un fichier dictionnaire avec -d, vous enregistrez en bloc les lectures des mots en kanji, et pouvez souvent vous passer entièrement des lectures avec @.

Règle pratique : mendex pour pLaTeX, upmendex pour upLaTeX / LuaLaTeX. Fournir les lectures avec @ fonctionne dans les deux cas (\index{さくいん@索引}).

Modifier le style de l’index (.ist)

L’apparence de l’index est contrôlée par un fichier de style (.ist), passé avec -s, comme dans makeindex -s style.ist file. Il s’agit simplement d’une liste de paires <parameter> <value> : les chaînes sont entre guillemets doubles, % commence un commentaire (les styles mendex / upmendex sont compatibles vers le haut avec makeindex).

• headings_flag — une valeur non nulle insère un titre de groupe (la lettre initiale, par ex. A, B… ou des groupes de kana) avant chaque nouveau groupe.
• lethead_prefix / lethead_suffix — chaînes placées avant et après ce titre.
• delim_0 / delim_1 / delim_2 — le séparateur entre une entrée (à chaque niveau) et son numéro de page (par ex. ", " ou un filet pointillé).
• item_0 / item_1 — chaînes insérées entre les entrées et entre les niveaux (retours à la ligne, indentation).
• preamble / postamble — code émis avant et après l’ensemble de l’index.

Pour de simples titres de groupe, un petit .ist comme celui-ci suffit.

% style.ist
headings_flag    1
heading_prefix   "{\\bfseries "
heading_suffix   "}\\nopagebreak\n"
delim_0          "\\dotfill "

La méthode moderne : imakeidx

imakeidx étend makeidx et apporte deux grands avantages. D’abord, il lance makeindex automatiquement pendant la compilation : lancez LaTeX avec -shell-escape (autorisation d’exécuter des programmes externes) et l’index est construit presque comme la table des matières, sans passe manuelle. Ensuite, il prend en charge plusieurs index dans un même document, par exemple un index des noms et un index thématique.

La configuration se fait en passant des options à \makeindex. name= distingue un index, title= fixe son titre, intoc l’inscrit dans la table des matières, program= choisit le programme de tri (makeindex / xindy / texindy, ou mendex / upmendex pour le japonais), et options= transmet des arguments comme -s style.ist. Écrivez plusieurs appels à \makeindex pour obtenir plusieurs index, puis dirigez les entrées avec \index[name]{…} et imprimez-les avec \printindex[name].

\documentclass{article}
\usepackage{imakeidx}

% two indexes; built automatically with -shell-escape
\makeindex[name=subject, title=事項索引, intoc, program=upmendex]
\makeindex[name=people,  title=人名索引, intoc, program=upmendex,
          options={-s style.ist}]

\begin{document}
群\index[subject]{group@群} は重要だ。
クヌース\index[people]{Knuth@クヌース} が TeX を作った。

\printindex[subject]
\printindex[people]
\end{document}

# auto-build: makeindex/upmendex is invoked for you
lualatex -shell-escape mydoc
lualatex -shell-escape mydoc   # second pass resolves page numbers

Seul xindy exige le shell-escape *complet*, mais toute construction automatique nécessite -shell-escape. Si vous préférez, vous pouvez encore appeler makeindex / mendex de l’extérieur avec imakeidx. Là où -shell-escape ne peut pas être activé (certains services web, CI stricte), la construction automatique est indisponible ; revenez à une passe manuelle ou laissez latexmk s’en charger.