fontspec (Xe/Lua)

Dieselbe dreizeilige Präambel läuft unter LuaLaTeX durch und bricht unter XeLaTeX mit ! Package fontspec Error: The font "TeX Gyre Termes" cannot be found. ab. Nichts ist kaputt — so ist fontspec gebaut. fontspec ist das Paket, mit dem LaTeX eine Schrift über ihren Namen aufruft; eine einzige \setmainfont-Zeile stellt die Grundschrift um. Wen dieser Name aber befragt, unterscheidet sich je nach Engine, und genau dort gehen Dokumente wirklich kaputt. Diese Seite stellt diesen Unterschied in die Mitte und arbeitet sich von dort durch \setmainfont, \newfontfamily, die Auswahl über Dateien und die OpenType-Funktionsschlüssel — jeweils mit Messwerten.

Auf welchen Engines fontspec läuft – und warum pdfLaTeX nicht dazugehört

fontspec läuft auf genau zwei Engines, XeLaTeX und LuaLaTeX; unter pdfLaTeX scheitert schon die Zeile \usepackage{fontspec}. Der Grund ist historisch. Das TeX der 1980er-Jahre kennt nur seine eigenen TFM-Metriken und Type-1- bzw. METAFONT-Schriften. OpenType und der Gedanke einer systemweiten Schriftdatenbank entstanden erst nach TeX. XeTeX und LuaTeX sind Engines, die von außen für diese Welt neu gebaut wurden und Unicode-Eingabe sowie OpenType-Schriften nativ verarbeiten. fontspec ist die Schicht, die diese neuen Fähigkeiten in LaTeX-Vokabular übersetzt – und pdfTeX besitzt keine solchen Fähigkeiten, die sich übersetzen ließen.

Geladen wird es mit der einen Zeile \usepackage{fontspec}. Klassen und Pakete für XeLaTeX und LuaLaTeX (bxjsarticle, unicode-math, luatexja-fontspec und ähnliche) laden es meist schon vorher; es zusätzlich ausdrücklich zu schreiben, schadet nicht. Beim Portieren eines pdfLaTeX-Dokuments sollten \usepackage[T1]{fontenc} und \usepackage[utf8]{inputenc} entfernt werden: Ersteres ist überflüssig, weil fontspec auf die Kodierung TU umstellt, Letzteres hat auf einer Unicode-Engine keine Bedeutung.

Die Grundschrift mit \setmainfont, \setsansfont, \setmonofont wechseln

Drei Befehle tragen ein Dokument: \setmainfont{…} (die Roman-Schrift, also die voreingestellte Grundschrift), \setsansfont{…} (was \textsf und \sffamily wählen) und \setmonofont{…} (die Monospace-Schrift hinter \texttt und \ttfamily). Das Argument ist ein Schriftname oder ein Dateiname. Daraus sucht fontspec das ganze Quartett zusammen – aufrecht, fett, kursiv, fett kursiv – und verdrahtet es mit \textbf, \textit und \emph, sodass sich am Schreiben des Fließtexts nichts ändert. Dieses automatische Zusammenstellen ist die zentrale Aufgabe von fontspec; zusätzliche Konfiguration schreibt man, wie sich zeigen wird, nur dann, wenn die Automatik versagt.

% compile with lualatex (or xelatex — see the next section)
\documentclass{article}
\usepackage{fontspec}
\setmainfont{TeX Gyre Termes}   % roman / body
\setsansfont{TeX Gyre Heros}    % sans serif
\setmonofont{TeX Gyre Cursor}   % monospaced
\begin{document}
Body text, \textbf{bold}, \textit{italic}, \textsf{sans}, \texttt{mono}.
\end{document}

Grundsätzlich gehören diese Befehle in die Präambel, aus einem einzigen Grund: LaTeX legt seine Mathematikschriften bei \begin{document} fest. Steht \setmainfont in der Präambel, erreicht dieselbe Schrift auch die Roman-Buchstaben in der Mathematik, etwa \mathrm; steht es im Fließtext, ändert sich nur der Text, und das Roman der Mathematik bleibt zurück. Die eigentliche Mathematikschrift liegt außerhalb der Zuständigkeit von fontspec und gehört zu \setmathfont aus unicode-math. Text und Mathematik werden von zwei verschiedenen Befehlen gesteuert.

The font "…" cannot be found. – XeLaTeX und LuaLaTeX suchen an verschiedenen Orten

Erscheint ! Package fontspec Error: The font "…" cannot be found. nur unter XeLaTeX, liegt kein Tippfehler im Namen vor, sondern ein Unterschied darin, wer gefragt wird. XeTeX fragt die Schriftdatenbank des Betriebssystems ab und sieht daher nur Schriften, die das System als installiert führt. LuaTeX baut über luaotfload einen eigenen Index auf, der auch den TeX-Baum umfasst. Von TeX Live mitgelieferte Schriften sind im Betriebssystem nicht registriert, und genau diese Lücke wird zur Lücke im Ergebnis. Auf dem TeX Live 2024 dieses Rechners lief eine identische Datei unter LuaLaTeX durch und blieb unter XeLaTeX stehen.

$ xelatex t1.tex
! Package fontspec Error: The font "TeX Gyre Termes" cannot be found.

$ lualatex t1.tex
Output written on t1.pdf (1 page, 3697 bytes).

$ pdffonts t1.pdf
name                            type          encoding    emb sub uni
NNOCLB+TeXGyreTermes-Regular    CID Type 0C   Identity-H  yes yes yes

Die Grenze verläuft zwischen „mitgelieferter Schrift“ und „Systemschrift“. Gemessen auf diesem Rechner lassen sich systemseitig installierte Schriften – Hiragino Mincho ProN, Hiragino Sans, YuMincho – auch unter XeLaTeX auflösen. Schriften, die TeX Live unter texmf-dist/fonts/opentype/public/ verteilt, sind für XeLaTeX über den Namen dagegen unsichtbar; in TeX Live 2024 liegen dort 125 Pakete (tatsächlich 1.499 .otf-Dateien). Die Entwurfslogik der Engines selbst behandeln /learn/engines/xetex und /learn/engines/luatex. Hier geht es um den Griff, der ein kaputtes Dokument sofort wieder übersetzbar macht.

Es gibt zwei Abhilfen. (1) Mit lualatex übersetzen. Das erfordert keine Änderung an der Quelle und ist meist der kürzeste Weg. (2) Statt des Schriftnamens den Dateinamen schreiben. \setmainfont{texgyretermes-regular.otf} funktioniert auch unter XeLaTeX – aber zu einem Preis: Über die Datei benannt, kann fontspec Fett und Kursiv nicht mehr erraten. Bei \textbf erscheint LaTeX Font Warning: Font shape 'TU/texgyretermes-regular.otf(0)/b/n' undefined, und die als fett gedachte Stelle bleibt mager. Das ist das klassische stille Scheitern: eine Warnung, kein Fehler, also leicht zu übersehen. Dateinamen unterscheiden zudem Groß- und Kleinschreibung – mit TeXGyreTermes-Regular.otf landet dieselbe Schrift wieder bei cannot be found.

Auswahl über Dateien: Path=, Extension=, BoldFont=

Die vollständige dateibasierte Form weist alle vier Schnitte von Hand zu. Das Verzeichnis kommt über Path=, die Endung (.otf oder .ttf) über Extension=, dann werden die Dateien auf UprightFont=, BoldFont=, ItalicFont=, BoldItalicFont= abgebildet. Das Sternchen * in diesen Werten ist ein Platzhalter, der durch den gemeinsamen Basisnamen aus dem ersten Argument ersetzt wird. Fett und Kursiv, die im vorigen Abschnitt verschwunden waren, kehren zurück, sobald diese vier dastehen: In der Messung erzeugte die Variante mit allen vieren null Font shape … undefined-Warnungen, und pdffonts listete Regular, Bold, Italic und BoldItalic nebeneinander.

\usepackage{fontspec}
% XeLaTeX-safe: name the files, and name all four styles
\setmainfont{texgyretermes}[
  Extension      = .otf ,
  UprightFont    = *-regular ,
  BoldFont       = *-bold ,
  ItalicFont     = *-italic ,
  BoldItalicFont = *-bolditalic ,
]

% fonts shipped inside the project directory
\setsansfont{LibreBaskerville}[
  Path        = ./fonts/ ,
  Extension   = .otf ,
  UprightFont = *-Regular ,
  BoldFont    = *-Bold ,
]

Welche Form die richtige ist, entscheidet eine praktische Frage: Wer setzt dieses Dokument? Für einen Entwurf, den nur du liest, ist der Schriftname schneller. Muss dasselbe PDF auch auf fremden Rechnern entstehen – Mitautoren, Einreichung, CI, Docker –, ist es fast die einzige verlässliche Antwort, die Schriften im Projekt mitzuliefern und mit Path= darauf zu zeigen. Mit Path= schaut fontspec direkt auf diesen relativen Pfad statt auf den TeX-Suchpfad, und das gesamte Repository lässt sich mitnehmen.

Mit \newfontfamily eine vierte und fünfte Schrift ergänzen

Eine Schrift, die nicht ins Trio Roman/Sans/Mono passt, ergänzt man, indem man mit \newfontfamily einen eigenen Umschalter erzeugt. Das erste Argument ist der gewünschte Befehlsname, das zweite die Schrift; dieselben Optionen wie bei \setmainfont sind erlaubt. Der erzeugte Befehl ist deklarativ wie \rmfamily und gilt für alles Folgende. Den Geltungsbereich begrenzt man mit Klammern: {\titlefont …}.

\usepackage{fontspec}
\newfontfamily\titlefont{TeX Gyre Bonum}
\newfontfamily\quotefont{TeX Gyre Schola}[Scale = MatchLowercase]
% ...
\titlefont A heading in Bonum

{\quotefont A quoted passage in Schola.}

Für eine nur einmal verwendete Schrift lässt sich die Definition überspringen und \fontspec{Font Name} direkt als Deklaration einsetzen. Allerdings lädt \fontspec die Schrift bei jedem Aufruf neu; für Wiederkehrendes wie Kapitelüberschriften verlängert das still und leise die Übersetzungszeit. Ab zwei Verwendungen gehört es in \newfontfamily. Zudem scheitert \newfontfamily, wenn ein Befehl dieses Namens schon existiert – kurze, von LaTeX bereits belegte Namen wie \sc oder \it also meiden und lieber sprechende Namen wie \titlefont wählen.

OpenType-Funktionen über Schlüssel aufrufen: Ligatures, Numbers, Scale

Eine OpenType-Schrift bringt alternative Glyphen bereits mit – Ligaturen, Ziffernvarianten, Kapitälchen – und fontspec holt sie über key=value-Optionen hervor. Die Wirkung lässt sich schneller messen als betrachten, daher hier Werte aus TeX Gyre Pagella in 10 pt. Mit Numbers=OldStyle wächst die Tiefe von 0123456789 von 0.19998pt auf 2.37999pt: Dass Mediävalziffern 3 und 9 eine Unterlänge geben, steht unmittelbar in der Messung.

• Ligatures= — Ligaturen und Eingabeumwandlung. Ligatures=TeX aktiviert die TeX-Schreibweise: -- wird zum Halbgeviertstrich, --- zum Geviertstrich, ` und '' werden zu typografischen Anführungen. (Gemessen: --- geht von 9,99 pt „drei Bindestriche“ auf exakt 10,0 pt – ein Geviert – als echter Geviertstrich.) Weitere Werte sind Common (Standardligaturen fi, fl …), NoCommon zum Abschalten (gemessen: fi wächst von 6,05 pt auf 6,35 pt), Rare/Discretionary und Historic`.
• Numbers= — Ziffernstil. OldStyle (Mediävalziffern, die im Fließtext liegen) oder Lining (moderne Ziffern gleicher Höhe) mit Proportional oder Monospaced kombinieren. Zahlen in einer Tabelle fluchten senkrecht, sobald Lining,Monospaced gesetzt ist.
• Letters=SmallCaps — echte Kapitälchen. Gemessen an Libertinus Serif sinkt Abc von 6,98 pt auf 6,58 pt Höhe und wächst von 16,26 pt auf 16,94 pt Breite. Achtung: Fehlt der Schrift die smcp-Tabelle, tut fontspec nichts und sagt nichts – bei TeX Gyre Pagella blieb die Breite bei 17,6 pt. Werte wie Letters=Uppercase gibt es ebenfalls.
• SmallCapsFeatures= — ein Bündel Funktionen, das nur in Kapitälchen greift, etwa SmallCapsFeatures={Numbers=OldStyle}. Nach demselben Muster existieren UprightFeatures=, BoldFeatures= und ItalicFeatures=, sodass sich jeder Schnitt einzeln einstellen lässt.
• Scale= — Skalierungsfaktor: eine Zahl oder Scale=MatchLowercase (x-Höhe der Hauptschrift angleichen) bzw. Scale=MatchUppercase (Versalhöhe angleichen). Gemessen sank die x-Höhe von TeX Gyre Heros von 5,24 pt auf 4,68999 pt gegenüber Pagella-Fließtext – genau die 4,69 pt von Pagella.
• StylisticSet= — wählt per Nummer einen von der Schrift bereitgestellten Satz alternativer Glyphen. RawFeature= ist die Hintertür für Funktionen ohne eigenen Schlüssel und reicht ein OpenType-Tag direkt durch; RawFeature={+onum} liefert dasselbe Ergebnis wie Numbers=OldStyle (gemessen dieselbe Tiefe von 2,37999 pt).
• Script= / Language= — wählt Schriftsystem und Sprache (Script=Arabic, Language=Turkish usw.). Renderer= bestimmt die Formungs-Engine; unter XeTeX stehen AAT, OpenType und Graphite zur Wahl. Unter LuaTeX erledigt das luaotfload, weshalb der Schlüssel dort kaum gebraucht wird.

\usepackage{fontspec}
\setmainfont{TeX Gyre Pagella}[
  Ligatures = TeX ,
  Numbers   = OldStyle ,
  SmallCapsFeatures = {Numbers = Lining} ,
]
% match the sans to the body x-height
\setsansfont{TeX Gyre Heros}[Scale = MatchLowercase]

Um eine Funktion nur an einer Stelle statt im ganzen Dokument zu ergänzen, dient \addfontfeature{…} (bzw. \addfontfeatures{…} für mehrere). Der Befehl überschreibt die aktuelle Schrift lokal mit der genannten Funktion und wirkt nur innerhalb der umschließenden Klammern. Der klassische Fall: ein Dokument in Mediävalziffern, in dem die Zahlen einer bestimmten Tabelle fluchten sollen.

Set in old-style figures, but this column
{\addfontfeature{Numbers={Lining,Monospaced}} 01234 56789}
lines up digit by digit.

Wofür fontspec nicht zuständig ist: Mathematik und Japanisch

fontspec betreut nur den lateinischen Text des Körpers; Mathematik und Japanisch laufen auf eigenen Spuren. Für Mathematik lädt man unicode-math und übergibt \setmathfont{…} eine OpenType-Mathematikschrift wie Latin Modern Math, STIX Two Math oder NewCM Math. Ein Wechsel von \setmainfont bewegt die Mathematik überhaupt nicht; ein Dokument, dessen Text und Formeln nicht zusammenpassen, ist also kein reines pdfLaTeX-Problem. Welche Mathematikschrift zu wählen ist, gehört auf die Seite zu Mathematikschriften.

Beim Japanischen ist es dasselbe Bild. \setmainfont ändert nur die lateinische Schrift; Kanji und Kana rühren sich nicht. Unter LuaLaTeX lädt man luatexja-fontspec, praktisch das japanische Gegenstück zu fontspec, und nutzt dessen „j“-Befehle: \setmainjfont{…} (Mincho, die japanische Grundschrift), \setsansjfont{…} (Gothic), \newjfontfamily. Die Optionssyntax ist im Wesentlichen dieselbe, das Wissen um Scale= und Path= lässt sich also direkt übertragen. Japanischer Satz auf einer Unicode-Engine heißt somit, zwei Spuren parallel zu fahren. Welche japanischen Schriften zur Wahl stehen, behandelt die Seite zu japanischen Schriften.