Ihr erstes Dokument

Das erste LaTeX-Dokument darf eine einzige Zeile lang sein und lässt sich trotzdem übersetzen: \documentclass{article}\begin{document}Hi\end{document}. Durch pdflatex geschickt, entsteht daraus tatsächlich ein einseitiges PDF von 11.529 Byte. Wer beim ersten Dokument stecken bleibt, hat meist übersprungen, was diese Zeile tut, und stattdessen eine lange Vorlage abgeschrieben. Diese Seite beginnt bei diesem Minimum und arbeitet sich nach außen: wo die Präambel endet und der Textkörper beginnt, wie der Compiler aufgerufen wird, was die plötzlich auftauchenden Dateien .aux und .log wirklich sind, warum manchmal zwei Durchgänge nötig sind, und welche %- und $-Fallen am ersten Tag jeden erwischen – jeweils mit der echten Ausgabe im Terminal.

Das kleinste LaTeX-Dokument, das sich übersetzen lässt (hello world)

Drei Befehle, mehr nicht. \documentclass{article} erklärt, um welche Art Dokument es sich handelt, \begin{document} öffnet den Textkörper, \end{document} schließt ihn. Fehlt einer der drei, entsteht kein PDF; sind alle drei da, läuft es selbst dann, wenn dazwischen nichts steht. Die lesbare Fassung unten als hello.tex speichern. Die Datei sollte UTF-8 sein, die Endung muss .tex lauten.

\documentclass{article}
\begin{document}
This is my first document.
\end{document}

Das article in \documentclass{article} ist die Klasse. Eine Klasse ist der Bauplan des gesamten Dokuments: wie breit die Ränder sind, wie groß Überschriften ausfallen und wie viel Raum sie umgibt, ob es überhaupt Kapitel gibt. Standardmäßig dabei sind article (Aufsätze, Kurzberichte, technische Notizen – ohne \chapter), report (längere Berichte mit Kapiteln), book (Bücher, auf beidseitigen Druck ausgelegt) und letter (Briefe). Für Japanisch bietet sich jlreq oder jsarticle an. Liegt eine Klassendatei einer Zeitschrift oder eines Verlags bei, sollte sie ohne Zögern verwendet werden: die gesamte Diskussion über die Hausregeln entfällt damit.

Präambel und Textkörper: die zwei Welten, die \begin{document} trennt

Alles vor \begin{document} ist die Präambel, alles danach der Textkörper. In der Präambel wird festgelegt, wie gesetzt werden soll; nichts davon erscheint auf dem Papier. Im Textkörper dagegen erscheint im Wesentlichen, was dort steht. Diese Grenze ist keine Marotte von LaTeX, sondern zwingend: Bevor auch nur ein Zeichen gesetzt wird, müssen Papierformat, Satzbreite, Schriften und sämtliche zu ladenden Pakete feststehen. Deshalb darf \usepackage nur in der Präambel stehen. Im Textkörper bricht der Lauf mit ! LaTeX Error: Can be used only in preamble. ab.

Der spiegelbildliche Fehler kommt genauso oft vor: Steht normaler Fließtext in der Präambel, erscheint ! LaTeX Error: Missing \begin{document}. Beim ersten Mal irritiert das – \begin{document} wurde ja geschrieben –, aber LaTeX meint „Text kam an, bevor der Textkörper begonnen hatte“, also es steht Text vor dem Beginn des Textkörpers. Notizen in der Präambel gehören mit % auskommentiert.

Zum PDF übersetzen mit pdflatex und latexmk

Im Terminal genügt pdflatex hello.tex. In einem Editor oder auf Overleaf tut die Schaltfläche „Kompilieren“ genau dasselbe. Das Zeichen für Erfolg sind die letzten beiden Zeilen: Output written on hello.pdf und Transcript written on hello.log. Stehen sie da, existiert das PDF. Die Flut an Pfaden, die zuvor durchläuft, ist die Liste der geladenen Klassendateien und Schriften – normale Ausgabe, die niemand lesen muss.

$ pdflatex hello.tex
This is pdfTeX, Version 3.141592653-2.6-1.40.26 (TeX Live 2024)
(./hello.tex
LaTeX2e <2023-11-01> patch level 1
(/usr/local/texlive/2024/texmf-dist/tex/latex/base/article.cls
Document Class: article 2023/05/17 v1.4n Standard LaTeX document class
...
Output written on hello.pdf (1 page, 31014 bytes).
Transcript written on hello.log.

Geht etwas schief, gibt pdflatex unter Umständen ein ? aus und wartet auf Eingabe. Nicht die Eingabetaste hämmern – x tippen und mit Enter bestätigen bricht ab. Wer dieses Gespräch gar nicht führen möchte, nimmt pdflatex -interaction=nonstopmode hello.tex: Der Lauf geht trotz Fehlern bis zum Ende und schreibt alles ins Log. Und es lohnt sich, früh latexmk -pdf hello.tex zu lernen: Es wiederholt den Übersetzungslauf so oft, wie das Dokument es braucht, womit das „zweimal“-Problem des nächsten Abschnitts erledigt ist.

Was sind all die neuen Dateien? .aux, .log, .toc, .out

Ein einziger Durchgang, und im Ordner liegen vier Dateien mehr. Nichts ist schiefgegangen: LaTeX hinterlässt Notizen für sich selbst. Läuft ein Dokument mit Inhaltsverzeichnis und einem Abschnitt durch pdflatex, entstehen neben hello.tex die Dateien hello.aux (132 Byte), hello.log (3.250 Byte), hello.pdf (31.014 Byte) und hello.toc (59 Byte). Das Herzstück ist dabei .aux. Geöffnet enthält sie genau drei Zeilen.

% hello.aux, written by the first run
\relax
\@writefile{toc}{\contentsline {section}{\numberline {1}Introduction}{1}{}\protected@file@percent }
\gdef \@abspage@last{1}

Vorgelesen heißt das: „Abschnitt Nummer 1, Introduction, steht auf Seite 1“ und „die letzte Seite ist Seite 1“. .aux ist also ein Notizbuch mit Nummern und Seitenpositionen, das im nächsten Durchgang wieder gelesen wird. .toc ist das daraus gebaute Inhaltsverzeichnis, .log die vollständige Aufzeichnung des Laufs, und .out erscheint erst mit hyperref – darin stehen die Lesezeichen des PDF.

Die praktische Regel ist kurz. Nur .tex und die Bilder gehören in die Versionsverwaltung, die Hilfsdateien auf die Ignorierliste. latexmk -c räumt sie mit einem Befehl weg. Gewohnheitsmäßig löschen sollte man sie aber nicht: Sie existieren, um Arbeit zu sparen, und sie jedes Mal wegzuwerfen heißt, jedes Mal absichtlich den Umweg zu nehmen. Zum Besen greift man erst, wenn ein Problem ohne Erklärung bestehen bleibt.

Warum zweimal übersetzt werden muss: ?? und die Rerun-Warnung

Weil LaTeX im ersten Durchgang die Antwort noch nicht kennt. Steht dort „siehe Abschnitt 1“, erfährt LaTeX Nummer und Seite dieses Abschnitts erst, nachdem er tatsächlich gesetzt wurde – und Verweise stehen fast immer vor dem, worauf sie zeigen. Also setzt der erste Durchgang, was möglich ist, und schreibt die Antworten in .aux; der zweite liest sie zurück und füllt die Lücken. Beim Inhaltsverzeichnis ist es dasselbe: \tableofcontents steht vorn, sein Inhalt steht erst am Ende fest. Hier die echte Aufzeichnung beider Durchgänge.

$ pdflatex ref.tex          # first run, from a clean directory
No file ref.aux.
No file ref.toc.
LaTeX Warning: Reference `sec:intro' on page 1 undefined on input line 5.
LaTeX Warning: There were undefined references.
LaTeX Warning: Label(s) may have changed. Rerun to get cross-references right.
Output written on ref.pdf (1 page, 33009 bytes).

# the PDF now reads:  "See Section ?? on page ??."

$ pdflatex ref.tex          # second run
Output written on ref.pdf (1 page, 34613 bytes).

# the PDF now reads:  "See Section 1 on page 1."

Drei Dinge sind bemerkenswert. Der erste Lauf meldet No file ref.aux. – das Notizbuch existiert noch nicht. Verweise erscheinen als ??, dazu die Meldung LaTeX Warning: Label(s) may have changed. Rerun to get cross-references right. Das Wort „Rerun“ ist die Anweisung: noch einmal laufen lassen. Im zweiten Lauf ist die Warnung verschwunden und aus ?? ist 1 geworden. Beim Inhaltsverzeichnis dasselbe: Im ersten Lauf erscheint nur die Überschrift, erst im zweiten die Einträge. Steht ?? im PDF, ist nichts kaputt – es ist die Bitte um einen weiteren Durchgang.

Wer keine Durchgänge zählen mag, überlässt das latexmk. Ein latexmk -pdf ref.tex im leeren Verzeichnis gibt Run number 1 of rule 'pdflatex', Run number 2 of rule 'pdflatex' und schließlich Latexmk: All targets (ref.pdf) are up-to-date aus – es führt genau die zwei nötigen Durchgänge aus und hört auf. Literaturverzeichnisse (BibTeX/biber) und Register (makeindex) erhöhen die Zahl weiter, auch darum kümmert sich latexmk. LaTeX Workshop in VS Code, TeXShop und Overleaf rufen im Hintergrund ohnehin meist latexmk auf.

Zeichen, die nicht so erscheinen, wie sie getippt wurden: %, &, _, #, $

LaTeX kennt zehn Zeichen, die roh getippt etwas anderes bedeuten: # $ % & ~ _ ^ \ { }. Am ersten Tag erwischt % die meisten – und zwar deshalb, weil es keinen Fehler auslöst. Steht Only 50% of the sample survived. und in der nächsten Zeile The rest did not., druckt das PDF „Only 50The rest did not.“ Alles von % bis zum Zeilenende wird als Kommentar verworfen, und das verschwundene Zeilenende hängt die nächste Zeile einfach an denselben Absatz an. Es wird kein Fehler gemeldet, also warnt nichts – und Prozentangaben kommen in wissenschaftlichen Texten ständig vor. Richtig ist 50\%.

Zwei weitere Eigenheiten sind gerade deshalb lästig, weil sie keinen Fehler auslösen. Erstens verschluckt ein Befehl das Leerzeichen dahinter. Aus \LaTeX is a macro package. wird „LATEXis a macro package.“, denn LaTeX frisst das folgende Leerzeichen, während es das Ende des Befehlsnamens sucht. Abhilfe schaffen leere Klammern, \LaTeX{} is, oder \LaTeX\ is. Zweitens die Anführungszeichen: "hello" liefert an beiden Enden ein schließendes Zeichen (”hello”). Das öffnende besteht aus zwei Gravis-Zeichen, das schließende aus zwei Apostrophen; richtig ist also ``hello''.

Die ersten Fehlermeldungen lesen: ! Missing $ inserted. und Verwandte

Zu lesen sind nur die erste Zeile mit ! und die unmittelbar folgende l.-Zeile. l. steht für „line“; die Zahl dahinter ist die Zeilennummer, der Zeileninhalt wird mitgedruckt und genau dort in zwei Teile gebrochen, wo TeX gestolpert ist. Die Bruchstelle ist der Tatort. So sieht es aus, wenn x_1 im Fließtext steht. Da TeX sich nach dem ersten Fehler weiterquält, sind die folgenden Meldungen meist eine Kettenreaktion. Nur die oberste beheben und erneut laufen lassen.

$ pdflatex e2.tex      # line 3 of the source reads: The value of x_1 is small.
! Missing $ inserted.
<inserted text>
                $
l.3 The value of x_
                   1 is small.

$ pdflatex e3.tex      # line 3 reads: Smith & Jones wrote it.
! Misplaced alignment tab character &.
l.3 Smith &
            Jones wrote it.

$ pdflatex sc.tex      # line 3 reads: Issue #42 and more.
! You can't use `macro parameter character #' in horizontal mode.
l.3 Issue #
           42 and more.

$ pdflatex e5.tex      # \begin{itemize} was never closed
! LaTeX Error: \begin{itemize} on input line 3 ended by \end{document}.

$ pdflatex e4.tex      # \end{document} is missing entirely
*** (job aborted, no legal \end found)
!  ==> Fatal error occurred, no output PDF file produced!

! Missing $ inserted. heißt: „Etwas, das nur in Formeln funktioniert, tauchte im Text auf, also hat TeX ein $ ergänzt.“ Die Ursache ist fast immer _ oder ^: entweder eine echte Formel daraus machen, $x_1$, oder maskieren, x\_1. ! LaTeX Error: \begin{itemize} on input line 3 ended by \end{document}. ist eine nicht geschlossene Umgebung – eine der freundlicheren Meldungen, denn sie nennt die Zeile, in der die Umgebung geöffnet wurde. Die bedrohlichste, ! ==> Fatal error occurred, no output PDF file produced!, bedeutet meist nur, dass \end{document} fehlt. Und ! Undefined control sequence. ist ein Tippfehler (\sectoin) oder ein vergessenes Paket.

Mit Titel und Überschriften wird ein Bericht daraus

Ab hier wird nur noch ergänzt. \title, \author und \date in die Präambel, \maketitle an den Anfang des Textkörpers – schon steht der Titel. Überschriften mit \section und \subsection werden automatisch nummeriert, und \tableofcontents baut das Inhaltsverzeichnis (das, wie gesehen, erst ab dem zweiten Durchgang erscheint). \date{\today} wird zum Datum des Übersetzungslaufs, und eine Überschrift ohne Nummer bekommt ein Sternchen: \section*{...}.

\documentclass{article}
\title{My First Report}
\author{Taro Yamada}
\date{\today}
\begin{document}
\maketitle
\tableofcontents

\section{Introduction}
Blank lines start new paragraphs. Line breaks in the source do not.

\section{Method}
\subsection{Setup}\label{sec:setup}
Only 50\% of the sample survived. See Section~\ref{sec:setup}.
\end{document}

Das Beispiel enthält auch die wichtigste Regel für den Textkörper überhaupt: Zeilenumbrüche in der Quelle werden ignoriert, eine Leerzeile beginnt einen neuen Absatz. Ob nach jedem Satz umgebrochen oder drei Leerzeilen gelassen wird – die Ausgabe bleibt gleich. Die endgültigen Umbrüche bestimmt LaTeX mit Blick auf den gesamten Absatz. Eine Leerzeile gehört nur dorthin, wo wirklich ein neuer Absatz beginnen soll.

Funktionen über Pakete ergänzen: \usepackage

Fehlende Funktionen liefern Pakete, und eingebunden wird eines mit einer einzigen \usepackage{...}-Zeile in der Präambel. Bilder brauchen graphicx, ernsthafte Mathematik amsmath, andere Ränder geometry, Verweise und PDF-Lesezeichen hyperref. Tausende Pakete liegen einer Distribution wie TeX Live bei; ihr Archiv heißt CTAN, Comprehensive TeX Archive Network. Aber nicht gleich einen ganzen Stapel laden. Nur behalten, was sich begründen lässt: Kollidieren zwei Pakete und erscheint etwa Option clash for package ..., wächst der Aufwand für die Eingrenzung mit der Zahl der geladenen Pakete.

\documentclass[a4paper,11pt]{article}
\usepackage{graphicx}                  % include images
\usepackage{amsmath}                   % proper math environments
\usepackage[margin=25mm]{geometry}     % page margins
\usepackage{hyperref}                  % links and PDF bookmarks; load it last
\begin{document}
\section{Results}
Text, images and equations go here.
\end{document}

Konventionell wird hyperref zuletzt geladen. Es arbeitet, indem es Befehle anderer Pakete umschreibt; zu früh geladen, überschreibt ein später folgendes Paket seine Änderungen. Und damit ist der erste Tag abgedeckt: das Minimaldokument, die Trennung von Präambel und Textkörper, das Übersetzen, die Hilfsdateien, der zweite Durchgang, die Sonderzeichen und die ersten Fehlermeldungen. Von hier an schreibt man, was man wirklich schreiben will, und ergänzt Funktionen eine nach der anderen, sobald sie gebraucht werden.