Glossaires et nomenclature

Toutes les consignes aux auteurs comportent la même phrase : développer une abréviation à sa première occurrence, puis n’employer que la forme courte. À la main, la règle est presque intenable. Déplacez une section et « la première occurrence » se déplace avec elle ; manquez l’endroit qui comptait et un relecteur le verra. Le package glossaries de LaTeX, et son successeur glossaries-extra, confient cette règle à la machine. Chaque terme ou abréviation se définit une fois dans le préambule ; dans le corps, on écrit \gls{key} : la première occurrence se développe d’elle-même et, accessoirement, seuls les termes réellement employés apparaissent, triés, dans le glossaire de fin. Cette page parcourt tout le chemin — définir les entrées, \newacronym, lancer makeglossaries, \printglossary — et écarte d’emblée les quatre façons dont un glossaire sort vide, dont trois ne produisent même pas d’avertissement.

Définir une fois, appeler partout : newglossaryentry et gls

Dans le préambule, écrivez \newglossaryentry{key}{name=..., description=...} ; dans le corps, appelez \gls{key}. Le premier argument, key, est une étiquette que vous choisissez ; name est ce qui s’imprime et description l’explication qui figurera dans le glossaire. Ce qu’il faut retenir, c’est que \gls accomplit deux tâches à la fois : il insère le name à l’endroit voulu et écrit en même temps, dans un fichier auxiliaire, une note indiquant que ce terme appartient au glossaire. Un terme défini mais jamais appelé par \gls n’apparaît donc pas. Ne lister que les termes employés relève du principe, non du défaut.

Les variantes ne diffèrent que par les premières lettres de la commande. En début de phrase, \Gls{key} ; au pluriel, \glspl{key} ; pour les deux, \Glspl{key}. Le pluriel engendré automatiquement n’est que name suivi d’un « s » : une forme irrégulière comme matrices doit donc être donnée par la clé plural. Si la forme employée dans le texte courant doit différer du nom affiché, réglez text ; placez un symbole associé dans la clé symbol et appelez-le par \glssymbol{key} ; insérez la seule explication avec \glsdesc{key}. Si une description couvre plusieurs paragraphes, recourez à \longnewglossaryentry. Enfin, appeler une key inexistante interrompt la compilation avec ! Package glossaries Error: Glossary entry ... has not been defined. — qu’une faute de frappe ne passe pas inaperçue est ici une qualité.

\usepackage{glossaries}
\makeglossaries              % opens the glossary files -- required

\newglossaryentry{set}{%
  name={set},
  description={a collection of distinct objects}%
}
\newglossaryentry{matrix}{%
  name={matrix},
  plural={matrices},      % irregular plural, spelled out
  description={a rectangular array of numbers}%
}

\begin{document}
\Gls{set} theory studies a \gls{set}; linear algebra studies \glspl{matrix}.
\printglossaries
\end{document}

Confier les abréviations à la machine : newacronym et le développement initial

On définit avec \newacronym{key}{short}{long}, puis on écrit simplement \gls{key}. short est l’abréviation, par exemple SVM, et long la forme complète, support vector machine. Écrivez deux fois le même \gls{svm} : la sortie donne « support vector machine (SVM) » la première fois, puis « SVM » ensuite. C’est ici que la machine reprend la règle qu’aucun auteur ne tient à la main : le drapeau de première occurrence est suivi entrée par entrée et selon l’ordre du traitement, si bien que déplacer une section déplace aussi le développement. Réorganisez le manuscrit, rien ne se contredit.

Pour qu’un terme soit redéveloppé à partir d’un certain point — un chapitre censé se lire seul, par exemple —, employez \glsreset{key}, ou \glsresetall pour toutes les entrées d’un coup. Pour réunir les abréviations dans une liste propre, chargez le package par \usepackage[acronym]{glossaries} : vous obtenez deux listes indépendantes, un glossaire et une liste d’acronymes, chacune avec son jeu de fichiers auxiliaires. Et lorsque glossaries-extra est également chargé, \newacronym devient un alias de \newabbreviation avec category=acronym : si vous démarrez un nouveau projet, écrire directement \newabbreviation donne accès d’emblée à toute la gamme des styles d’abréviation.

\usepackage[acronym]{glossaries}   % a second, separate list
\makeglossaries

\newacronym{svm}{SVM}{support vector machine}

\begin{document}
\gls{svm} is a classifier.   % -> support vector machine (SVM)
Another \gls{svm} follows.   % -> SVM

\glsreset{svm}               % start a chapter that must stand alone
\gls{svm} again in full.     % -> support vector machine (SVM)

\printglossary[type=main,title={Glossary}]
\printglossary[type=\acronymtype,title={Acronyms}]
\end{document}

La compilation : makeglossaries transforme le .glo en .gls

LaTeX se contente d’enregistrer les termes ; il ne les trie ni ne les met en forme. À la première compilation, \makeglossaries produit un fichier .ist — le fichier de style contenant les règles de tri — et chaque terme atteint par \gls s’accumule dans le .glo. Insérez ici le programme externe makeglossaries et il abat son jeu : il affiche makeindex -s mydoc.ist -t mydoc.glg -o mydoc.gls mydoc.glo. C’est exactement le makeindex qui construit un index. Une fois le .gls trié en place, une compilation LaTeX supplémentaire le relit.

pdflatex mydoc       # writes mydoc.glo (and mydoc.ist)
makeglossaries mydoc # sorts it: no file extension here
pdflatex mydoc       # reads mydoc.gls, prints the glossary

# what makeglossaries actually runs, once per glossary type:
#   makeindex -s mydoc.ist -t mydoc.glg -o mydoc.gls mydoc.glo
#   makeindex -s mydoc.ist -t mydoc.alg -o mydoc.acr mydoc.acn

Deux glossaires, deux jeux de fichiers. Le glossaire par défaut va de .glo à .gls, avec un journal .glg ; avec l’option acronym, la liste d’acronymes emprunte .acn vers .acr (journal .alg), et makeglossaries appelle makeindex deux fois. C’est exactement ce rôle — savoir combien de listes existent et lancer l’outil autant de fois — qui justifie d’intercaler makeglossaries plutôt que de taper makeindex soi-même. Le script est écrit en Perl ; là où Perl manque, situation fréquente sous Windows, on appelle makeglossaries-lite : même travail, réalisé par makeglossaries-lite.lua et exécuté par texlua.

Quand le glossaire sort vide : quatre causes, trois muettes

La cause la plus fréquente est l’oubli de makeglossaries, et cet échec ne laisse presque aucun indice. Sans .gls, le glossaire n’apparaît pas du tout, titre compris : il ne reste pas un cadre vide, rien n’est composé à cet endroit. Ni erreur ni avertissement, juste une ligne enfouie dans le journal : No file mydoc.gls. C’est exactement le piège du makeindex oublié pour un index, et il est bien déguisé : \gls se développe correctement dès la première compilation, si bien qu’en regardant le corps du PDF tout semble fonctionner.

• makeglossaries n’a jamais été lancé. Pas de .gls, donc ni glossaire ni titre. Aucun avertissement ; le journal ne contient que No file mydoc.gls.
• \makeglossaries manque dans le préambule. Le fichier de sortie n’est même pas ouvert, aucun .glo n’est créé et, de nouveau, rien n’est imprimé. Aucun avertissement.
• Un terme a été défini mais jamais appelé par \gls. Les entrées inutilisées ne sont pas enregistrées, donc pas listées. C’est voulu : un terme destiné au glossaire doit apparaître au moins une fois dans le corps.
• La seule faute réellement signalée est l’inverse. Avec \makeglossaries présent mais \printglossary oublié, on obtient Package glossaries Warning: No \printglossary or \printglossaries found. (Remove \makeglossaries if you dont want any glossaries.) This document will not have a glossary.

Une autre combinaison échoue sans un mot. Si vous employez hyperref, chargez glossaries après hyperref — l’une des rares exceptions au conseil habituel qui veut que hyperref vienne en dernier. Le guide du débutant du package le dit explicitement, et se tromper d’ordre ne déclenche aucun avertissement : les liens et les numéros de page du glossaire se cassent en silence. Disposez-les ainsi.

\usepackage[colorlinks]{hyperref}
\usepackage{glossaries}   % after hyperref, not before
\makeglossaries

% put the glossary into the table of contents as well:
% \usepackage[toc]{glossaries}

L’imprimer : titre, type et entrée dans la table avec printglossary

\printglossaries émet toutes les listes que vous avez mises en place ; \printglossary en émet une. Le choix dépend du besoin d’options : pour donner à chaque liste son titre ou son style, passez-les, comme dans \printglossary[type=main, title={Glossaire}] ; sinon, la seule ligne \printglossaries suffit. Le mot du titre lui-même réside dans \glossaryname et se remplace avec \renewcommand.

Ces titres ne sont pas numérotés et n’atteignent donc pas la table par défaut. Charger le package sous la forme \usepackage[toc]{glossaries} les y place automatiquement, ce qui est plus fiable que d’aligner un \addcontentsline par glossaire. L’apparence elle-même se change avec \setglossarystyle{...} : list (la valeur par défaut) repose sur un environnement description, altlist met le terme sur une ligne à part et renfonce l’explication en dessous, et la famille long compose l’ensemble en tableau. Plus les descriptions sont longues, plus altlist et les styles long gagnent en lisibilité.

La configuration moderne : glossaries-extra et bib2gls

La première version de glossaries porte la date du 16 mai 2007 ; Nicola Talbot l’a publiée comme successeur de l’ancien package glossary. La même autrice a ensuite sorti glossaries-extra en 2015 et bib2gls en 2017. La combinaison emprunte son idée telle quelle à la gestion bibliographique : les termes vivent dans un fichier .bib, et bib2gls ne retient que ceux réellement employés dans le corps, les trie et les importe — exactement le rôle que biber joue pour les ouvrages cités. La sélection et le tri, autrefois du ressort de makeindex ou de xindy, reviennent à un seul programme.

La clé est l’option record. Charger \usepackage[record]{glossaries-extra} désactive l’indexation par makeindex ou xindy et écrit à la place, dans le .aux, des lignes du type \glsxtr@record{set}{}{page}{glsnumberformat}{1}. bib2gls les lit et réécrit dans un .glstex uniquement les entrées nécessaires. À cause de cette conception, il est normal que rien ne soit encore défini à la première compilation — d’où le fait que glossaries-extra rétrograde une entrée inconnue de l’erreur vers l’avertissement. Une colonne de Package glossaries-extra Warning: Glossary entry ... has not been defined au premier passage est attendue. Le glossaries nu, lui, interrompt la compilation dans la même situation ; les deux choix sont cohérents avec leur conception.

@entry{set,
  name = {set},
  description = {a collection of distinct objects}
}

@abbreviation{svm,
  short = {SVM},
  long  = {support vector machine}
}

@symbol{sigma,
  name = {\ensuremath{\sigma}},
  description = {standard deviation}
}

\usepackage[record]{glossaries-extra}
\GlsXtrLoadResources[src={terms}]   % terms.bib, without the extension

\begin{document}
\gls{set} and \gls{svm} are used here.
\printunsrtglossary                 % already sorted by bib2gls
\end{document}

Ce que l’on écrit dans le document change à peine. Le .bib se charge par \GlsXtrLoadResources[src={terms}] — src est le nom de fichier sans extension — et les termes s’appellent toujours par \gls{set}. Ce qui diffère, c’est la commande d’impression : bib2gls ayant déjà trié, on emploie \printunsrtglossary (unsrt pour unsorted, c’est-à-dire « émettre tel quel »). Dans la chaîne de compilation, bib2gls remplace makeglossaries ; --group ajoute des intertitres par initiale, et pdflatex peut céder la place à xelatex ou lualatex. Une réserve à l’installation : bib2gls est écrit en Java et exige un environnement d’exécution Java, au moins Java 8. La commande de TeX Live est un script shell qui lance un .jar ; sur une machine sans Java, on s’en aperçoit dès le premier appel.

pdflatex mydoc
bib2gls --group mydoc   # reads mydoc.aux, writes mydoc.glstex
pdflatex mydoc

Une simple liste de symboles : nomencl

Pour une table de symboles en tête d’article, glossaries conviendrait, mais le léger nomencl y parvient avec moins de rouages. Placez \usepackage{nomencl} et \makenomenclature dans le préambule, marquez chaque symbole à sa première apparition par \nomenclature{$g$}{gravitational acceleration}, puis écrivez \printnomenclature là où la liste doit figurer. Les symboles relèvent des mathématiques : entourez-les de $...$. La compilation emprunte de nouveau makeindex : \makenomenclature produit un .nlo, le style fourni nomencl.ist le trie en un .nls, et une compilation LaTeX supplémentaire le relit.

pdflatex mydoc
makeindex mydoc.nlo -s nomencl.ist -o mydoc.nls
pdflatex mydoc

Le tri porte sur la saisie du symbole, caractère par caractère. Écrivez $\sigma$ et la clé de tri est la chaîne $\sigma$, où le dollar et la barre oblique inverse précèdent toutes les lettres de l’alphabet. À l’essai, σ se place avant g et m. D’où l’argument optionnel, qui fournit votre propre clé de tri : dans \nomenclature[g-sigma]{$\sigma$}{...}, c’est g-sigma qui est trié tandis que le symbole s’imprime. Tant qu’on y est : terminez par % la ligne qui précède un \nomenclature, car une espace parasite autour du symbole fausse le tri.

\usepackage{nomencl}
\makenomenclature
\renewcommand{\nomname}{List of Symbols}
% \usepackage[intoc]{nomencl}  % also list it in the contents

\begin{document}
Let $g$ be gravity.%
\nomenclature{$g$}{gravitational acceleration}%
A mass $m$ feels $F = mg$.%
\nomenclature{$m$}{mass of the object}%
\nomenclature[g-sigma]{$\sigma$}{stress}% sort key, not the symbol

\printnomenclature
\end{document}

Le titre est par défaut l’anglais « Nomenclature » ; on le remplace par \renewcommand{\nomname}{...}. Pour le faire figurer dans la table des matières, chargez \usepackage[intoc]{nomencl}. Des options annotent également chaque entrée : refpage ajoute « , page n » et refeq « , see equation (n) ». Et si l’on veut séparer les constantes physiques des variables, redéfinir \nomgroup d’après le premier caractère de la clé de tri que l’on vient de voir répartit la liste en sous-groupes dotés de leurs propres titres.

• Pour un glossaire de termes et d’abréviations, glossaries. Développement initial, pluriels et capitales sont pris en charge.
• Nouveau projet ? glossaries-extra avec bib2gls. Les termes vivent dans un .bib et \printunsrtglossary émet ceux que vous avez employés — vérifiez seulement que Java est disponible.
• Pour une simple liste de symboles mathématiques, nomencl. Marquez avec \nomenclature, lancez makeindex une fois, c’est terminé.
• Tous exigent un passage supplémentaire. Intercalez le programme externe (makeglossaries / bib2gls / makeindex) et relancez LaTeX. Si vous l’oubliez, personne ne vous grondera.