Glossare und Nomenklatur

In jedem Autorenleitfaden steht derselbe Satz: Eine Abkürzung wird beim ersten Auftreten ausgeschrieben und danach nur noch kurz verwendet. Von Hand ist das kaum einzuhalten. Ein verschobener Abschnitt verschiebt auch das „erste Auftreten“, und wer die entscheidende Stelle übersieht, wird von einem Gutachter darauf hingewiesen. Das LaTeX-Paket glossaries und sein Nachfolger glossaries-extra übergeben diese Regel der Maschine. Jeder Begriff, jede Abkürzung wird einmal in der Präambel definiert, im Text steht nur \gls{key}: Die erste Verwendung schreibt sich selbst aus, und nebenbei erscheinen nur die tatsächlich verwendeten Einträge sortiert im Glossar am Ende. Diese Seite verfolgt den gesamten Weg – Einträge definieren, \newacronym, makeglossaries ausführen, \printglossary – und räumt vorab die vier Gründe aus, aus denen ein Glossar leer bleibt; drei davon erzeugen nicht einmal eine Warnung.

Einmal definieren, überall aufrufen: newglossaryentry und gls

In die Präambel kommt \newglossaryentry{key}{name=..., description=...}, im Text steht \gls{key}. Das erste Argument key ist ein selbst gewähltes Etikett; name wird gedruckt, description ist die Erläuterung, die später im Glossar steht. Festzuhalten ist, dass \gls zwei Aufgaben zugleich erledigt: Es fügt den name an Ort und Stelle ein und schreibt zugleich einen Vermerk in eine Hilfsdatei, dass dieser Begriff ins Glossar gehört. Ein Begriff, der zwar definiert, aber nie mit \gls aufgerufen wurde, erscheint deshalb gar nicht. Dass nur verwendete Begriffe aufgeführt werden, ist Absicht und kein Mangel.

Die Varianten unterscheiden sich nur in den ersten Buchstaben des Befehls. Am Satzanfang steht \Gls{key}, für den Plural \glspl{key}, für beides \Glspl{key}. Der automatisch gebildete Plural ist bloß name plus „s“, eine unregelmäßige Form wie matrices muss also über den Schlüssel plural angegeben werden. Soll die Form im Fließtext vom Anzeigenamen abweichen, setzt man text; ein zugehöriges Zeichen kommt in den Schlüssel symbol und wird mit \glssymbol{key} abgerufen; die Erläuterung allein fügt \glsdesc{key} ein. Reicht eine Beschreibung über mehrere Absätze, dient \longnewglossaryentry. Und der Aufruf eines nicht vorhandenen key bricht den Lauf ab mit ! Package glossaries Error: Glossary entry ... has not been defined. – dass ein Tippfehler nicht stillschweigend durchgeht, ist hier ein Vorzug.

\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}

Abkürzungen der Maschine überlassen: newacronym und die erste Verwendung

Definiert wird mit \newacronym{key}{short}{long}, danach genügt \gls{key}. short ist die Abkürzung, etwa SVM, long die Langform, support vector machine. Zweimal dasselbe \gls{svm} geschrieben, liest sich die Ausgabe beim ersten Mal „support vector machine (SVM)“ und danach stets „SVM“. Hier übernimmt die Maschine die Regel, die von Hand niemand einhält: Das Erstverwendungs-Flag wird pro Eintrag und in der Reihenfolge der Verarbeitung geführt, sodass beim Verschieben eines Abschnitts die Ausschreibung mitwandert. Wird das Manuskript umgestellt, widerspricht sich nichts.

Soll ein Begriff ab einer bestimmten Stelle wieder ausgeschrieben werden – etwa in einem Kapitel, das für sich stehen soll –, hilft \glsreset{key}, für alle Einträge auf einmal \glsresetall. Für eine eigene Abkürzungsliste lädt man das Paket als \usepackage[acronym]{glossaries}: Dann existieren zwei unabhängige Listen, Glossar und Abkürzungsverzeichnis, jede mit eigenem Satz Hilfsdateien. Ist zusätzlich glossaries-extra geladen, wird \newacronym zu einem Alias von \newabbreviation mit category=acronym – wer neu beginnt, schreibt also besser gleich \newabbreviation und hat damit die volle Auswahl an Abkürzungsstilen.

\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}

Der Build: makeglossaries macht aus .glo eine .gls

LaTeX erfasst die Begriffe nur; es sortiert und formatiert sie nicht. Im ersten Lauf erzeugt \makeglossaries eine .ist-Datei – die Stildatei mit den Sortierregeln –, und jeder von \gls erreichte Begriff sammelt sich in der .glo. Schiebt man an dieser Stelle das externe Programm makeglossaries ein, legt es seine Karten offen: Es gibt makeindex -s mydoc.ist -t mydoc.glg -o mydoc.gls mydoc.glo aus. Es ist genau dasselbe makeindex, das auch einen Index baut. Sobald die sortierte .gls vorliegt, liest ein weiterer LaTeX-Lauf sie ein.

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

Zwei Glossare bedeuten zwei Dateisätze. Das voreingestellte Glossar läuft von .glo nach .gls mit einem .glg-Protokoll; mit der Option acronym benutzt das Abkürzungsverzeichnis .acn nach .acr mit .alg, und makeglossaries ruft makeindex zweimal auf. Genau diese Aufgabe – zu wissen, wie viele Listen es gibt, und das Werkzeug entsprechend oft zu starten – ist der Grund, makeglossaries dazwischenzuschalten, statt makeindex selbst einzutippen. Das Skript ist in Perl geschrieben; fehlt Perl, was unter Windows häufig vorkommt, tritt makeglossaries-lite an seine Stelle: dieselbe Arbeit, umgesetzt als makeglossaries-lite.lua und von texlua ausgeführt.

Wenn das Glossar leer bleibt: vier Ursachen, drei davon stumm

Die häufigste Ursache ist das vergessene makeglossaries, und dieser Fehlschlag hinterlässt kaum Spuren. Ohne .gls erscheint das Glossar überhaupt nicht, samt Überschrift – es bleibt kein leerer Rahmen, es wird schlicht nichts gesetzt. Kein Fehler, keine Warnung, nur eine Zeile tief im Protokoll: No file mydoc.gls. Es ist genau die Falle des vergessenen makeindex beim Index, und sie ist gut getarnt: \gls selbst expandiert schon im ersten Lauf korrekt, sodass beim Blick auf den PDF-Text alles zu funktionieren scheint.

• makeglossaries wurde nie ausgeführt. Keine .gls, also fehlen Glossar und Überschrift. Keine Warnung; im Protokoll steht nur No file mydoc.gls.
• \makeglossaries fehlt in der Präambel. Die Ausgabedatei wird gar nicht geöffnet, es entsteht nicht einmal eine .glo, und wieder wird nichts gedruckt. Keine Warnung.
• Ein Begriff wurde definiert, aber nie mit \gls aufgerufen. Unbenutzte Einträge werden nicht erfasst und daher nicht aufgeführt. Das ist Absicht – ein Begriff, der ins Glossar soll, muss im Text mindestens einmal vorkommen.
• Gemeldet wird ausgerechnet der umgekehrte Fehler. Steht \makeglossaries da, fehlt aber \printglossary, erscheint Package glossaries Warning: No \printglossary or \printglossaries found. (Remove \makeglossaries if you dont want any glossaries.) This document will not have a glossary.

Noch eine Kombination scheitert wortlos. Wer hyperref verwendet, lädt glossaries nach hyperref – eine der wenigen Ausnahmen von der Faustregel, hyperref zuletzt zu laden. Der Einsteigerleitfaden des Pakets sagt das ausdrücklich, und eine falsche Reihenfolge erzeugt keinerlei Warnung: Links und Seitenzahlen im Glossar gehen einfach still kaputt. Die Reihenfolge sieht so aus.

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

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

Ausgeben: Titel, Typ und Aufnahme ins Inhaltsverzeichnis mit printglossary

\printglossaries gibt alle eingerichteten Listen aus, \printglossary genau eine. Welche Form passt, hängt davon ab, ob Optionen nötig sind: Soll jede Liste eigenen Titel oder Stil bekommen, übergibt man sie, etwa \printglossary[type=main, title={Glossar}]; sonst genügt die eine Zeile \printglossaries. Das Überschriftenwort selbst steckt in \glossaryname und lässt sich mit \renewcommand austauschen.

Diese Überschriften sind unnummeriert und gelangen daher standardmäßig nicht ins Inhaltsverzeichnis. Wird das Paket als \usepackage[toc]{glossaries} geladen, geschieht das automatisch – zuverlässiger, als für jedes Glossar ein \addcontentsline zu setzen. Das Erscheinungsbild selbst schaltet \setglossarystyle{...} um: list (die Vorgabe) baut auf einer description-Umgebung auf, altlist stellt den Begriff in eine eigene Zeile und rückt die Erläuterung darunter ein, und die long-Familie setzt das Ganze als Tabelle. Je länger die Beschreibungen, desto stärker zahlen sich altlist und die long-Stile in Lesbarkeit aus.

Der moderne Aufbau: glossaries-extra und bib2gls

Die erste Fassung von glossaries trägt das Datum 16. Mai 2007; Nicola Talbot veröffentlichte sie als Nachfolgerin des älteren Pakets glossary. Dieselbe Autorin brachte 2015 glossaries-extra und 2017 bib2gls heraus. Die Kombination übernimmt ihre Idee unverändert aus der Literaturverwaltung: Die Begriffe stehen in einer .bib-Datei, und bib2gls wählt allein die im Text tatsächlich verwendeten aus, sortiert sie und liest sie ein – dieselbe Rolle, die biber für zitierte Werke spielt. Auswahl und Sortierung, früher Sache von makeindex oder xindy, übernimmt damit ein einziges Programm.

Der Schlüssel ist die Option record. \usepackage[record]{glossaries-extra} schaltet die Indexierung über makeindex oder xindy ab und schreibt stattdessen Zeilen wie \glsxtr@record{set}{}{page}{glsnumberformat}{1} in die .aux. bib2gls liest diese und schreibt genau die benötigten Einträge in eine .glstex zurück. Wegen dieses Entwurfs ist es normal, dass im ersten Lauf noch nichts definiert ist – deshalb stuft glossaries-extra einen unbekannten Eintrag vom Fehler zur Warnung herab. Eine Reihe von Package glossaries-extra Warning: Glossary entry ... has not been defined im ersten Durchgang ist zu erwarten. Das schlichte glossaries bricht in derselben Lage ab; beide Entscheidungen passen zu ihrem jeweiligen Entwurf.

@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}

Im Dokument ändert sich kaum etwas. Die .bib wird mit \GlsXtrLoadResources[src={terms}] geladen – src ist der Dateiname ohne Endung –, und Begriffe ruft weiterhin \gls{set} auf. Anders ist der Druckbefehl: Da bib2gls bereits sortiert hat, verwendet man \printunsrtglossary (unsrt für unsorted, also „unverändert ausgeben“). Im Build tritt bib2gls an die Stelle von makeglossaries; --group erzeugt Zwischenüberschriften nach Anfangsbuchstaben, und pdflatex lässt sich durch xelatex oder lualatex ersetzen. Eine Einschränkung bei der Einrichtung: bib2gls ist in Java geschrieben und benötigt eine Java-Laufzeitumgebung, mindestens Java 8. Der TeX-Live-Befehl ist ein Shell-Skript, das eine .jar startet; ohne Java merkt man das beim ersten Aufruf.

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

Nur eine Symbolliste: nomencl

Für eine Symboltabelle am Anfang einer Arbeit ließe sich glossaries verwenden, doch das leichtgewichtige nomencl kommt mit weniger beweglichen Teilen aus. \usepackage{nomencl} und \makenomenclature in die Präambel, jedes Symbol beim ersten Auftreten mit \nomenclature{$g$}{gravitational acceleration} markieren und \printnomenclature dorthin schreiben, wo die Liste stehen soll. Symbole sind Mathematik und gehören daher in $...$. Der Build leiht sich wieder makeindex: \makenomenclature erzeugt eine .nlo, der mitgelieferte Stil nomencl.ist sortiert sie zu einer .nls, und ein weiterer LaTeX-Lauf liest sie ein.

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

Sortiert wird nach der Eingabe des Symbols, Zeichen für Zeichen. Schreibt man $\sigma$, ist der Sortierschlüssel die Zeichenkette $\sigma$, in der Dollarzeichen und Backslash vor jedem Buchstaben des Alphabets stehen. Im Versuch landet σ tatsächlich vor g und m. Daher das optionale Argument, das einen eigenen Sortierschlüssel liefert: In \nomenclature[g-sigma]{$\sigma$}{...} wird g-sigma sortiert, gedruckt wird das Symbol. Und gleich noch ein Hinweis: Die Zeile unmittelbar vor einem \nomenclature endet mit %, denn ein verirrtes Leerzeichen um das Symbol bringt die Sortierung durcheinander.

\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}

Die Überschrift lautet standardmäßig „Nomenclature“ und wird über \renewcommand{\nomname}{...} ersetzt. Für einen Eintrag im Inhaltsverzeichnis lädt man \usepackage[intoc]{nomencl}. Optionen ergänzen jeden Eintrag zudem automatisch: refpage hängt „, page n“ an, refeq „, see equation (n)“. Und sollen physikalische Konstanten von Variablen getrennt stehen, teilt eine Neudefinition von \nomgroup anhand des ersten Zeichens des eben erwähnten Sortierschlüssels die Liste in Untergruppen mit eigenen Überschriften.

• Für ein Glossar aus Begriffen und Abkürzungen dient glossaries. Erstverwendung, Plural und Großschreibung werden mit erledigt.
• Neu anfangen? glossaries-extra zusammen mit bib2gls. Die Begriffe stehen in einer .bib, und \printunsrtglossary gibt die verwendeten aus – nur muss Java vorhanden sein.
• Für eine reine Liste mathematischer Symbole genügt nomencl. Mit \nomenclature markieren, einmal makeindex laufen lassen, fertig.
• Alle brauchen einen zusätzlichen Durchgang. Das externe Programm (makeglossaries / bib2gls / makeindex) dazwischenschalten und LaTeX erneut starten. Wird es vergessen, schimpft niemand.