Qu’est-ce que l’index d’une thèse ?

Un index est un outil de navigation interne au document. Il joue un rôle similaire à celui de la table des matières, mais à un niveau de granularité beaucoup plus fin. C’est une liste alphabétique qui peut contenir des termes et des noms propres, avec des renvois vers les pages dans lesquelles on peut trouver les occurrences de ces termes ou bien du contenu qui s’y rapporte.

L’art de créer un index est né en France. Pourtant, notre pays semble l’avoir totalement oublié. La plupart des livres et des thèses francophones ne contiennent pas d’index, ou alors une version rudimentaire comme dans l’exemple ci-dessous, qui n’est en fait pas un index mais une concordance – une liste de termes qui apparaissent tels quels dans le texte, et dont toutes les occurrences sont comptées.

Ce type d’index n’est pas un très bon outil savant. On peut le comprendre de manière simple : si vous voulez lire les passages qui se rapportent à un concept, mais que l’entrée correspondante dans l’index indique pas moins d’une cinquantaine de renvois, comment savoir quel passage consulter ?

Un bon index est le résultat d’un travail d’analyse du texte, qui conduit à en reformuler le contenu pour donner des points d’accès au lecteur. La longueur de l’index dépend alors de la complexité et de la densité du texte à indexer. Dans le cas d’une thèse, un index peut ainsi facilement occuper plus d’une dizaine de pages. Les indexeurs professionnels parlent d’un « index n% », où le pourcentage correspond au volume de l’index rapporté au volume du texte indexé ; à titre d’exemple, j’ai fait pour ma thèse un index 5% (14 pages d’index pour environ 280 pages de texte).

Exemple de sous-entrées et de renvois : Par ailleurs, un index c’est aussi une liste structurée de manière très spécifique, dans le but d’optimiser la recherche d’information. Les entrées les plus volumineuses sont divisées en différentes sous-entrées. Quant aux renvois internes (voir, voir aussi), ils permettent de multiplier les points d’accès vers une même information, de réduire l’ambiguïté entre termes homographes et d’orienter le lecteur vers certaines expressions plutôt que d’autres.

Par conséquent, créer un index c’est du travail. On comprend alors pourquoi il existe des indexeurs professionnels, et pourquoi beaucoup de doctorantes et de doctorants baissent les bras devant l’ampleur de la tâche, se contentant de faire une petite concordance rapide via Word ou LibreOffice.

Pourtant, il y a de bonnes raisons de relever ce défi. Lorsqu’on écrit une thèse, j’en vois au moins deux. D’abord, c’est un exercice d’analyse et de synthèse très puissant, qui renforce la maîtrise qu’on a de notre sujet, et qui développe la capacité à en faire la médiation. En effet, faire un index implique de se relire et de résumer progressivement les thèmes abordés, d’une manière qui doit être utile aux futurs lecteurs. Cela aide notamment à restituer la thèse sous une forme condensée, que ce soit lors la soutenance ou après.

Et ensuite, le résultat est un outil précieux pour les lecteurs, à commencer par le jury. Un index de qualité facilitera le travail des rapporteurs, qui ne manqueront pas de le signaler. Mais n’oublions pas que nous sommes aussi notre propre lecteur : je ne compte plus les fois où j’ai ouvert mon mémoire de thèse depuis la soutenance pour vérifier ce que j’avais écrit à propos de telle personne ou telle thématique ; à chaque fois, je pars de l’index, qui s’avère beaucoup plus utile que la recherche plein texte.

C’est donc un gros boulot – j’ai mis une semaine entière à faire l’index de ma thèse, en travaillant du matin au soir – mais pour moi le jeu en vaut la chandelle.

Et maintenant, passons aux choses concrètes !

Indexer via Pandoc : deux options

J’ai rédigé ma thèse en Pandoc Markdown. On a parfois besoin de faire des choses pour lesquelles il n’y a pas de notation prévue ni dans la syntaxe Markdown de base, ni dans la variante de Pandoc ; par exemple, créer un index. On a alors deux possibilités.

Première possibilité : on se concentre sur l’un des formats d’export que l’on vise, et qui est capable de faire ce qu’on essaye de faire. Par exemple, il est possible de créer un index dans un PDF généré via LaTeX : cela passe par l’ajout de commandes \index{…} dans le texte, qui sont interprétées par le programme pour générer automatiquement l’index en fin de document. La solution consiste alors tout simplement à ajouter dans notre fichier rédigé en Markdown les instructions exprimées dans la syntaxe du format d’export visé. Concrètement ici, on parsème notre texte de commandes LaTeX. Exemple :

… cette expression fait référence au travail de Michel Foucault\index{Foucault, Michel} sur l'implication réciproque du savoir et du pouvoir.

Ces commandes ne seront interprétées par Pandoc que lorsqu’on convertit le fichier en LaTeX ou en PDF via LaTeXLaTeX est l’un des moteurs que peut utiliser Pandoc pour convertir un fichier Markdown en PDF. Je parle de « PDF via LaTeX » pour désigner ces exports. On peut aussi utiliser Pandoc pour convertir son fichier Markdown en LaTeX, puis utiliser un autre programme pour passer du fichier LaTeX au fichier PDF ; c’est d’ailleurs la solution que je détaille dans la section d’après.
. Dans les autres formats d’export, elles seront tout simplement ignorées.

Deuxième possibilité : plusieurs formats d’exports que l’on vise sont capables de faire ce qu’on veut faire, et on veut donc en profiter. Par exemple, on sait qu’on va générer un index via LaTeX pour le PDF mais aussi qu’on a un programme tiers (autre que Pandoc) capable de faire de même pour la version HTML. Dans ce cas, on peut s’appuyer sur deux capacités apportées par Pandoc : le balisage sémantique et la programmation éditoriale. Je m’explique : « balisage sémantique » signifie qu’on va d’abord marquer le texte avec une syntaxe générique, propre à Pandoc, pour rajouter une métadonnée relative à la signification du passage concerné. Exemple :

… cette expression fait référence au travail de [Michel Foucault]{index="Foucault, Michel"} sur l'implication réciproque du savoir et du pouvoir.

Cette syntaxe étant native à Pandoc, ce dernier est capable de passer l’information correspondante à tous les formats d’export. Pour en tirer parti, c’est là qu’intervient la programmation éditoriale : on ajoute à la conversion un script rédigé exprès pour gérer cette information. Pandoc implémente ceci sous la forme de « filtres » en Lua. Ici, le filtre contiendrait des instructions pour remplacer la syntaxe générique par la bonne syntaxe pour chaque format d’export. Il ne resterait alors plus qu’à exécuter le fameux programme capable de générer l’index.

Dans le cas de ma thèse, j’ai choisi la première option, que je détaille dans la section suivante. En effet, je n’avais pas connaissance de programmes permettant de générer un index pour la version HTML. Or via Antoine Fauchié je sais désormais qu’il existe de tels programmes, notamment celui créé par David Larlet pour les Ateliers de Sens Public et qui est en cours de documentation. Personnellement, je suis convaincu que tout l’intérêt de Pandoc c’est de faire du multiformats à partir d’une source unique, en recherchant une forme d’homogénéité éditoriale. Je suis donc plutôt un partisan de la deuxième méthode, et je mettrai peut-être à jour ce billet lorsque j’aurai pu la tester moi-même.

Ajout du 26/02 : En attendant, les développeurs de Pandoc ont gentiment réagi à la publication de ce billet en proposant un exemple bien pratique de filtre Lua que voici :

function Span (span)
  if span.attributes.index then
    local index_command = string.format('\\index{%s}', span.attributes.index)
    return span.content .. {pandoc.RawInline('latex', index_command)}
  end
end

Si on ajoute ce filtre lors d’une conversion, il transformera la syntaxe générique de Pandoc […]{index="…"} en la commande LaTeX …\index{…}. Si on ne veut pas mélanger LaTeX et Markdown, on peut donc utiliser ce filtre dès maintenant avec la solution ci-dessous. Il suffit de sauvegarder ce filtre sous un nom comme index.lua et ajouter --lua-filter=index.lua lors de la conversion.

Quant à moi, ça me fournit un point de départ sympa si j’ai besoin un jour d’écrire un filtre qui gère simultanément le cas LaTeX et le cas HTML.

Générer l’index du PDF à partir de Markdown

Voici en résumé le processus que j’ai appliqué pour générer l’index de ma thèse au format PDF :

1. baliser le texte avec les commandes \index{…} ;
2. passer de Markdown à LaTeX via Pandoc, en utilisant un modèle LaTeX qui inclut les bons packages dans le préambule ;
3. passer de LaTeX à PDF via XeLaTeX et Xindy.

Je détaille ça en dessous, avec en bonus un tutoriel express sur la manière d’automatiser tout ça sous une forme pratique à utiliser (spoiler : il s’agit de Make).

pandoc these.md -o these.tex --template=template.tex

\usepackage[xindy]{imakeidx}
\makeindex[columns=2, title=Index]

xelatex these.tex

texindy -C utf8 -L french these.idx

xelatex these.tex

pandoc these.md -o these.tex --template=template.tex
xelatex these.tex
texindy -C utf8 -L french these.idx
xelatex these.tex

cible visée : fichiers requis
  commandes à exécuter pour fabriquer la cible visée
  si les fichiers requis existent

cible finale : fichier intermédiaire requis
  commande qui fabrique la cible finale

fichier intermédiaire : fichiers de base requis
  commande qui fabrique le fichier intermédiaire

.PHONY : cible1 cible2

cible1 : fichier cible 1

fichier cible 1 : fichiers requis
  instructions

cible2 : fichier cible 2

fichier cible 2 : fichiers requis
  instructions

.PHONY : all pdf html

all : pdf html

pdf : these.pdf

these.pdf : these.tex
  xelatex these.tex
  texindy -C utf8 -L french these.idx
  xelatex these.tex

these.tex : these.md
  pandoc these.md -o these.tex --template=template.tex

html : these.html

these.html : these.md
  pandoc these.md -o these.html --template=template.html

Le mot de la fin (pour l’instant)

Ce billet constitue un peu la profession de foi d’un néo-converti : après avoir créé l’index de ma thèse, je suis désormais convaincu qu’il s’agit d’un outil essentiel, trop peu utilisé en France. Mais les ressources pour se lancer sont trop rares, surtout quand on rédige en Markdown. Alors je partage mon expérience en espérant qu’elle serve à d’autres, et j’espère pouvoir prolonger ce premier travail bientôt avec l’indexation en HTML.