FAQ

Manche LaTeX-Probleme melden sich mit einer Zeile, die mit ! beginnt. Die teuren tun das nicht. Eine Referenz, die trotz wiederholter Läufe ?? bleibt; eine Abbildung, die zwei Seiten zu spät erscheint; ein PDF im A4-Format, obwohl in der Quelle letterpaper steht; ein Manuskript, das hier baut und auf dem Rechner der Koautorin scheitert. Diese FAQ-Seite sammelt ausschließlich solche übergreifenden Fragen – jene, die mehrere Mechanismen zugleich betreffen – und beantwortet sie damit, was während des Laufs tatsächlich geschieht. Probleme, die eine einzelne Fehlermeldung klärt, haben eigene Seiten; das Verzeichnis am Ende führt dorthin.

Warum zweimal kompiliert werden muss

Weil LaTeX die Quelle genau einmal von vorn nach hinten liest und nicht vorausschauen kann. Beim Satz von \ref{sec:first} auf Seite 1 steht die Nummer, die \label später trägt, noch nicht fest. Also schreibt \label die Nummer in die .aux-Datei, und \ref liest die .aux, die der vorherige Lauf hinterlassen hat. Gemessen auf TeX Live 2024 gibt der erste Lauf LaTeX Warning: Reference 'sec:first' on page 1 undefined on input line 4. und LaTeX Warning: There were undefined references. aus, und im PDF steht tatsächlich „See Section ?? on page ??.“ Die .aux enthält zu diesem Zeitpunkt \newlabel{sec:first}{{1}{1}{}{}{}}; der zweite Lauf liest das und setzt „See Section 1 on page 1.“ Ein ?? ist demnach kein Schaden, sondern die Anzeige, dass man noch in der ersten Runde ist.

$ pdflatex ref.tex        # run 1
LaTeX Warning: Reference 'sec:first' on page 1 undefined on input line 4.
LaTeX Warning: There were undefined references.
LaTeX Warning: Label(s) may have changed. Rerun to get cross-references right.

$ pdftotext ref.pdf -
See Section ?? on page ??.

$ pdflatex ref.tex        # run 2 — no warnings
$ pdftotext ref.pdf -
See Section 1 on page 1.

Die abschließende Meldung LaTeX Warning: Label(s) may have changed. Rerun to get cross-references right. ist LaTeXs eigener Hinweis, dass sich die soeben geschriebene .aux von der gelesenen unterscheidet. Entscheidend ist: zwei Durchläufe sind eine Untergrenze, keine Regel. Eine zusätzliche Ziffer kann eine Zeile umbrechen, das ändert eine Seitenzahl, und schon ändert sich die .aux erneut; mit Inhaltsverzeichnis, Abbildungsverzeichnis oder hyperref-Lesezeichen sind drei oder vier Durchläufe völlig normal. Genau dafür gibt es latexmk: Es wiederholt, bis sich die .aux nicht mehr ändert. Man sollte die Durchläufe also nicht von Hand zählen. Umgekehrt gilt: einem ?? niemals nachjagen, bevor zweimal kompiliert wurde. Übersteht es zwei Durchläufe, ist das \label falsch geschrieben, gar nicht vorhanden, oder eine veraltete .aux steht im Weg – wird sie gelöscht, beginnt alles wieder beim ersten Lauf.

Warum das Literaturverzeichnis nicht erscheint

Weil Literaturverzeichnisse von einem eigenen Programm außerhalb von LaTeX erzeugt werden und ein voller Zyklus vier Befehle braucht. bibtex liest die .tex-Datei überhaupt nicht. Es liest die Zeilen \citation und \bibdata, die LaTeX in die .aux geschrieben hat, holt die passenden Einträge aus der .bib und erzeugt eine .bbl. Auf TeX Live 2024 gemessen sind die Stufen unübersehbar. Das erste pdflatex meldet LaTeX Warning: Citation 'knuth1984' on page 1 undefined, und im PDF steht „As shown by [?].“ – ohne jedes Verzeichnis. bibtex nennt darauf seine Eingaben: The top-level auxiliary file: doc.aux, The style file: plain.bst, Database file #1: refs.bib. Das zweite pdflatex setzt das References-Verzeichnis tatsächlich, doch der Zitatverweis im Text bleibt [?]. Erst der dritte Lauf macht daraus [1].

pdflatex doc     # writes \citation and \bibdata into doc.aux; text shows [?]
bibtex   doc     # reads doc.aux + refs.bib, writes doc.bbl
pdflatex doc     # pulls in doc.bbl: the list appears, the mark is still [?]
pdflatex doc     # now the \bibitem labels are in doc.aux: the mark becomes [1]

latexmk -pdf doc # does all four, and repeats until nothing changes

Auch der dritte Durchlauf erklärt sich aus demselben .aux-Hin-und-Her. Die \bibitem-Einträge der .bbl, die Lauf zwei einliest, schreiben die Zuordnung „dieser Schlüssel ist [1]“ in die .aux – jedoch mitten in eben diesem Lauf, nachdem das \cite im Text längst gesetzt wurde. Nutzbar ist die Zuordnung daher erst ab dem nächsten Lauf, weshalb ein drittes pdflatex, insgesamt der vierte Befehl, nötig ist. biblatex mit biber hat dieselbe Gestalt; biber tritt an die Stelle von bibtex und liest eine .bcf. In der Praxis überlässt man alles latexmk und hört auf zu zählen. Bleibt das Verzeichnis leer, liegt es fast immer an dreierlei: \bibliography{refs} mit der Endung .bib geschrieben, kein einziges \cite im Text (mit \nocite{*} erscheint alles) oder ein vertippter Schlüssel. Letzteres zeigt das .blg-Protokoll als Warning--I didn't find a database entry for "...".

Warum die Abbildung auf der falschen Seite landet

Weil eine figure ein Gleitobjekt ist: LaTeX hält sie zurück, bis eine Seite Platz bietet. Der übliche Stolperstein ist der Unterschied zwischen \newpage und \clearpage. \newpage beendet lediglich die aktuelle Seite – es gibt die wartenden Gleitobjekte nicht aus. \clearpage setzt zunächst alle anstehenden Gleitobjekte und beendet erst danach die Seite. Werden zwei Fassungen derselben Quelle auf TeX Live 2024 übersetzt, die sich nur in diesem einen Befehl unterscheiden, und wird das Ergebnis mit pdftotext Seite für Seite gelesen, ist die Folge unübersehbar.

\section{Alpha}
... a page of text ...
\begin{figure}[t]
  \centering \rule{10cm}{16cm}
  \caption{First figure}
\end{figure}

\newpage      % <- only this line differs between the two builds
%\clearpage

\section{Beta}
\begin{figure}[t]
  \centering \rule{6cm}{5cm}
  \caption{Second figure}
\end{figure}
Text of Beta.

Die \newpage-Fassung wurde vier Seiten lang: S. 1 der Text von Alpha, S. 2 die Überschrift „Beta“ samt Text, S. 3 Abbildung 1, S. 4 Abbildung 2. Abbildung 1, die zu Alpha gehört, sprang über die nächste Abschnittsüberschrift und erschien dahinter. Die \clearpage-Fassung hat drei Seiten: S. 1 der Text von Alpha, S. 2 allein Abbildung 1, S. 3 Abbildung 2 zusammen mit der Überschrift „Beta“ und ihrem Text. Die Abbildung überschreitet keine Abschnittsgrenze mehr, und das Dokument ist obendrein eine Seite kürzer. Die meisten Fälle von „die Abbildung ist im falschen Kapitel gelandet“ gehen also auf ein \newpage an einer Gliederungsgrenze zurück. An Kapitel- und Abschnittsgrenzen gehört \clearpage (bei doppelseitigem Druck \cleardoublepage). Außerdem gilt: [htbp] statt eines bloßen [h] – [h] bedeutet „hier, falls es passt, sonst später“, und ein Gleitobjekt, das höher als \textheight ist, teilt sich nie eine Seite mit Text. Die feine Steuerung der Gleitobjekte gehört auf die Seite zu Gleitobjekten und Platzierung.

Warum das Bild fehlt oder nur als leerer Rahmen erscheint

Erscheint überhaupt nichts, liegt der Verdacht auf einer Diskrepanz zwischen Bildformat und Ausgabeweg; erscheint ein leerer Rahmen, auf draft. pdflatex liest PDF, PNG und JPEG direkt und EPS gar nicht – dieses muss mit epstopdf umgewandelt oder dem Paket epstopdf überlassen werden. Der DVI-Weg, platex und danach dvipdfmx, verarbeitet EPS sehr wohl. Wird die Datei nicht gefunden, lautet die Meldung ! LaTeX Error: File 'fig.eps' not found., und die Ursache ist fast immer eine vergessene Endung, ein falscher Pfad oder ein \graphicspath{{figures/}} ohne abschließenden Schrägstrich. Der andere Klassiker, ! LaTeX Error: Cannot determine size of graphic in xxx.png (no BoundingBox)., erscheint, wenn graphicx nie mitgeteilt wurde, unter welchem Treiber es läuft – die FAQ von Cloud LaTeX führt genau diese Meldung als eigenen Eintrag.

Der Fall des leeren Rahmens ist, einmal durchschaut, beinahe enttäuschend simpel. Ein Dokument mit \documentclass[draft]{article} auf TeX Live 2024 übersetzt und mit pdftotext ausgelesen, liefert dort, wo das Bild stehen sollte, den Dateinamen als Text. Genau das leistet draft: Es überspringt die Bildausgabe und hinterlässt einen maßgleichen Rahmen mit dem Namen darin. Ein vergessenes draft in den Klassenoptionen und der anschließende Schluss, die Bilder seien beschädigt, gehört zu den häufigsten Missgeschicken. Für die Einreichfassung draft unbedingt entfernen; geht es nur um Geschwindigkeit, beschränkt \usepackage[draft]{graphicx} den Effekt auf die Grafiken. Fehlt die Abbildung auch dann noch, wenn alle Ursachen dieses Abschnitts ausgeschlossen sind, fehlt sie womöglich gar nicht, sondern ist auf eine andere Seite gerutscht – dann hilft der vorige Abschnitt.

Warum es bei mir baut und beim Koautor nicht

Die Unterschiede zwischen zwei Rechnern lassen sich in der Praxis auf drei Dinge zurückführen: das TeX-Live-Jahr, die Versionen der installierten Pakete und eigene Dateien im persönlichen Baum. Die ersten beiden macht eine einzige Zeile sichtbar. Steht \listfiles vor \documentclass, endet die .log mit einem Block *File List*, der je Datei eine Zeile mit Datum und Version enthält – auf TeX Live 2024 etwa amsmath.sty 2023/05/13 v2.17o AMS math features und graphicx.sty 2021/09/16 v1.2d Enhanced LaTeX Graphics. Lässt man sich denselben Block vom Koautor schicken und vergleicht beide, findet sich der Übeltäter meist in einer einzigen Zeile. Den Jahrgang der Engine selbst nennt pdflatex --version mit pdfTeX 3.141592653-2.6-1.40.26 (TeX Live 2024).

% put this on the very first line of the source
\listfiles

$ pdflatex doc.tex && sed -n '/File List/,/^ \*\*\*/p' doc.log
 *File List*
 article.cls    2023/05/17 v1.4n Standard LaTeX document class
 amsmath.sty    2023/05/13 v2.17o AMS math features
graphicx.sty    2021/09/16 v1.2d Enhanced LaTeX Graphics (DPC,SPQR)

$ kpsewhich -var-value=TEXMFHOME   # macOS, TeX Live 2024
/Users/you/Library/texmf

$ pdflatex --version | head -1
pdfTeX 3.141592653-2.6-1.40.26 (TeX Live 2024)

Die dritte Ursache, der persönliche Baum, ist am schwersten zu erkennen. kpsewhich -var-value=TEXMFHOME liefert unter TeX Live 2024 auf macOS /Users/you/Library/texmf – die mit TeX Live 2024 ausgelieferte texmf.cnf setzt TEXMFHOME = ~/Library/texmf, während unter Windows und Linux ~/texmf voreingestellt ist. Jede dort abgelegte .sty, .bst oder private Schrift ist nur auf dem eigenen Rechner sichtbar; wer das Manuskript erhält, bekommt ! LaTeX Error: File 'mystyle.sty' not found. Die Abhilfe ist schlicht: selbstgemachte Dateien in den Manuskriptordner legen und mitliefern. Soll auch der Jahresunterschied von TeX Live verschwinden, hilft nur, die Umgebung selbst festzunageln, etwa über ein Docker-Image. Die Gepflogenheiten der Zusammenarbeit gehören auf die Seite zur Koautorschaft, das Festnageln der Umgebung auf die Seite zu Docker und CI.

Warum das PDF A4 ist, obwohl letterpaper verlangt wurde

Weil eine Klassenoption den Satzspiegel ändert – Textblock und Ränder –, nicht das Papier des PDF selbst. Wird \documentclass[letterpaper]{article} auf TeX Live 2024 unverändert übersetzt und mit pdfinfo geprüft, lautet die Antwort Page size: 595.276 x 841.89 pts (A4). Der Grund liegt in der Startkonfiguration von pdfTeX. Die in das Format eingebrannte pdftexconfig.tex setzt \pdfpageheight = 297 true mm und \pdfpagewidth = 210 true mm, und das sind Primitive, die die Medienbox des PDF festlegen. Eine Klassenoption reicht in diese Schicht nicht hinein. Ergänzt man dasselbe Dokument um \usepackage[letterpaper]{geometry}, ändert sich die Antwort zu 612 x 792 pts (letter), denn geometry kümmert sich um Satzspiegel und Blattmaß zugleich.

$ pdflatex letter.tex && pdfinfo letter.pdf | grep "Page size"
Page size:       595.276 x 841.89 pts (A4)      # \documentclass[letterpaper]{article}

# fix 1 — geometry sets the type area AND the sheet
%   \usepackage[letterpaper]{geometry}
Page size:       612 x 792 pts (letter)

# fix 2 — set the pdfTeX primitives before \documentclass
%   \pdfpagewidth=8.5truein \pdfpageheight=11truein
Page size:       612 x 792 pts (letter)

Es gibt drei Abhilfen, und die Lage entscheidet. Am geradlinigsten ist geometry, das zugleich erlaubt, die Ränder an derselben Stelle festzulegen. Wer die Präambel nicht wachsen lassen will, schreibt vor \documentclass die Zeile \pdfpagewidth=8.5truein \pdfpageheight=11truein und erhält ebenfalls 612 x 792 pts (letter) – gemessen. Auf dem DVI-Weg erzeugt dvipdfmx das PDF, also wird die Größe beim Umwandeln angegeben, etwa mit dvipdfmx -p letter. Nützlich ist auch zu wissen, warum an diesen Längen true steht: Wird das Dokument mit \mag insgesamt skaliert, bleiben nur die mit true markierten Maße von der Skalierung unberührt. Die Einzelheiten zum Papier gehören auf die Seite über die PDF-Erzeugung.

Warum Japanisch fehlt oder verstümmelt erscheint

Fast immer sind es die falsche Engine oder die falsche Dateikodierung. pdflatex kann Japanisch überhaupt nicht setzen. Es gibt zwei gangbare Wege: uplatex (mit einer Klasse wie jsarticle oder jlreq), das an dvipdfmx übergibt, oder lualatex mit luatexja. Die Quelle wird als UTF-8 gespeichert. Übersehen wird meist, dass „unterstützt Japanisch“ nicht eindeutig ist: platex und uplatex decken unterschiedliche Zeichenbereiche ab. Auf TeX Live 2024 bricht platex bei einer Zeile mit 髙 (U+9AD9) mit ! LaTeX Error: Unicode character ^^e9^^ab^^99 (U+9AD9) not set up for use with LaTeX. ab, während uplatex dieselbe Zeile ohne Warnung übersetzt. Scheitert ein Dokument also nur an Personennamen oder Zeichenvarianten, ist die Engine verdächtig, nicht die Schrift.

Erscheinen die Zeichen zwar, aber als Ersatzkästchen oder in falscher Schrift, liegt es an der Konfiguration der japanischen Schriften. Auf dem dvipdfmx-Weg wählt kanji-config-updmap, welche japanische Schrift eingebettet wird; unter LuaTeX-ja benennt man sie mit \setmainjfont und Verwandten. Und wird der Text nur auf dem Rechner der Empfängerin verstümmelt, sind Kodierung und Zeilenenden verdächtig: Wurde eine Datei nicht als UTF-8 gespeichert, sondern etwa als Shift_JIS oder EUC-JP, deutet platex sie je nach -kanji=-Einstellung anders. Die Satzverfahren selbst gehören auf die Seite zum japanischen Satz, Kodierung und Zeilenenden auf die Seite zur Kodierung.

Warum die Schriften angeblich nicht eingebettet sind

Geprüft wird mit pdffonts, nicht geraten. Auf eine schlichte pdfLaTeX-Ausgabe von TeX Live 2024 angewandt, erscheinen die Spalten emb, sub, uni und eine Zeile wie KJJYRX+CMR10 Type 1 Builtin yes yes yes – yes unter emb und ein sechsbuchstabiges Subset-Präfix vor dem Schriftnamen. Beides zusammen bedeutet: eingebettet. Eine Zeile mit no unter emb bringt dagegen jedes Einreichsystem einer Zeitschrift und jede PDF/A-Prüfung zum Stehen. Drei Ursachen decken fast alle Fälle ab: Type-3-Bitmapschriften (keine Type1 vorhanden, also METAFONT-Bitmaps), die vierzehn PDF-Standardschriften (Helvetica und Verwandte, referenziert ohne mitgeliefert zu werden) und eine dvipdfmx-Map, die auf eine nicht einbettbare Schrift zeigt.

$ pdffonts document.pdf
name                       type       encoding  emb sub uni object ID
-------------------------- ---------- --------- --- --- --- ---------
KJJYRX+CMR10               Type 1     Builtin   yes yes yes      4  0

# "yes" under emb, plus the six-letter subset prefix, means embedded.
# Any line with "no" under emb will fail a PDF/A or journal check.

Welche Seite beantwortet welche Fehlermeldung

Keine der bisherigen Fragen hängt an einer einzelnen Fehlermeldung. Beginnt eine Zeile jedoch mit !, sieht es anders aus: die Meldung selbst weist den Weg. Der Fehlerbereich dieser Website führt je Meldung eine eigene Seite, und ! Missing $ inserted., ! Undefined control sequence., ! LaTeX Error: Missing \begin{document}., Runaway argument?, ! LaTeX Error: Option clash for package ... sowie Overfull \hbox haben jeweils ihre eigene. Die folgende Tabelle gibt den Wortlaut so wieder, wie er auf TeX Live 2024 reproduziert wurde, samt der Bedeutung dieser einen Zeile. Beim Lesen gilt nur ein Kniff: immer den obersten Fehler zuerst beheben. TeX-Fehler pflanzen sich fort, und was darunter steht, ist meist ein Nachbeben des ersten.