Acronymes et listes de symboles

Une esquisse avec glossaries-extra, ou une liste faite à la main quand cela suffit.

Acronymes et listes de symboles

Les documents longs accumulent des abréviations, et les conventions qui les entourent sont strictes. Un acronyme est écrit en toutes lettres à sa première occurrence, puis abrégé ensuite, et une thèse a généralement besoin d’une liste des abréviations dans les pages liminaires. Tenir cette liste à la main échoue de façon prévisible. Vous inversez deux chapitres, la première occurrence se déplace, et soudain « ML » apparaît trois pages avant « machine learning (ML) ». Le paquet glossaries-extra suit les premières occurrences à votre place.

La méthode automatisée

\usepackage[acronym]{glossaries-extra}
\makeglossaries
\newacronym{ml}{ML}{machine learning}

L’option acronym active la prise en charge des acronymes, et \makeglossaries met en route le mécanisme qui collecte les entrées pendant la compilation. Chaque \newacronym prend trois arguments : une clé que vous taperez dans le texte, la forme courte et la forme longue. Définissez-les toutes dans le préambule, ou dans un fichier séparé que vous chargez avec \input, afin qu’elles restent au même endroit.

Dans le corps du texte, vous ne tapez jamais l’acronyme lui-même :

\gls{ml} on first use expands; later uses stay short.
\printglossaries

Le premier \gls{ml} du document affiche « machine learning (ML) », et tous les suivants affichent simplement « ML ». Comme le paquet suit l’utilisation plutôt que la position dans la source, le développement suit la première occurrence où que votre réorganisation la déplace. \printglossaries affiche la liste des abréviations collectées à l’endroit où vous le placez, généralement après la table des matières. Des commandes voisines gèrent la grammaire : \glspl pour les pluriels, \Gls pour une majuscule en début de phrase.

Le piège se trouve dans la compilation. Entre deux passes de LaTeX, l’utilitaire makeglossaries doit s’exécuter pour trier et mettre en forme les entrées, faute de quoi \printglossaries ne produit rien, sans aucun message. Les configurations complètes avec latexmk s’en chargent automatiquement. Les chaînes de compilation plus simples ne le font pas toujours, et glossaries-extra propose une solution de repli pour elles. Si votre liste refuse obstinément d’apparaître, l’exécution manquante de l’utilitaire est le premier suspect, bien avant un bogue dans votre document.

La méthode à la main

Pour une simple liste de symboles, un environnement description tenu à la main suffit souvent :

\section*{Notation}
\begin{description}
\item[$\eta$] learning rate
\item[$\theta$] model parameters
\end{description}

Chaque \item[...] affiche son argument entre crochets comme une étiquette en gras, suivie de l’explication, ce qui correspond exactement à la forme d’une liste de notations. Il n’y a pas de suivi de la première occurrence, mais une liste de symboles en a rarement besoin : les symboles sont de toute façon définis là où ils apparaissent pour la première fois dans les formules.

Le conseil honnête est d’adapter l’outil à l’échelle. Un article de cinq acronymes se gère plus facilement à la main. Une thèse de 200 pages avec quarante acronymes, non : là, le paquet rentabilise plusieurs fois son coût de mise en place. La leçon sur les listes détaille l’environnement description.

Retour à Forme longue