Dokumentklasse und Präambel

Am 1. Juni 1994 teilte LaTeX einen Befehl in zwei, und seither beginnt jedes LaTeX-Dokument gleich: eine Zeile \documentclass, danach eine Präambel aus \usepackage-Deklarationen. Vorher hieß es \documentstyle[12pt,twoside]{article}, wobei Optionen und Zusatzstile in dieselben eckigen Klammern gestopft wurden. Die Trennung von Dokumentklasse und Paketen war kein Aufräumen. Die Klasse bestimmt, was ein Dokument ist – Aufsatz, Bericht, Buch, Foliensatz –, die Präambel bestimmt, was es kann. Ist diese Grenze richtig gezogen, setzt eine Zeitschrift das ganze Manuskript neu, indem sie eine einzige Zeile ändert; ist sie falsch gezogen, geht der Abend, der dem Schreiben gehören sollte, für Option clash for package geometry drauf.

Was \documentclass tatsächlich festlegt

\documentclass[options]{class} ist der einzige Befehl, der in einem Dokument zuerst stehen muss; davor ist nur ein mit % beginnender Kommentar erlaubt. In den geschweiften Klammern steht der Klassenname, in den eckigen die Optionen – und der Name in den geschweiften Klammern verweist auf eine reale Datei. article lädt article.cls, einige hundert Zeilen Definitionen, die nichts als Regeln enthalten. Eine \section-Überschrift etwa wird in \Large\bfseries gesetzt, mit 3.5ex Abstand darüber und 2.3ex darunter; diese drei Werte stehen wörtlich in article.cls. Vom eigenen Text steht dort kein einziges Zeichen.

Diese Arbeitsteilung ist kein Zufall. Anfang der 1980er Jahre begann Leslie Lamport ein Buch zu schreiben, fand das damals verbreitete Makropaket unzureichend und überlegte, dass sich die ohnehin nötigen eigenen Makros mit etwas Mehraufwand auch für andere brauchbar machen ließen. In einem Interview für die DMV-Mitteilungen vom Januar 2000 bezeichnet er genau das als den Ursprung von LaTeX. Eine Klasse ist also die Trennung von Struktur und Erscheinungsbild, gegossen in eine Datei. Im Textkörper steht \section{Introduction} – nur die Bedeutung –, und es ist Sache der Klasse, daraus eine große, fette, nummerierte Überschrift mit Abstand darüber zu machen. Genau deshalb liefern Fachgesellschaften und Verlage eigene Klassen aus: amsart, IEEEtran, elsarticle, revtex4-2 und acmart existieren wirklich und werden in Einreichungsrichtlinien vorgeschrieben. Lamport selbst schlug Ende der 1980er Jahre der ACM vor, Standard-Dokumentstile für TeX/LaTeX, troff und Scribe zu schaffen, damit elektronische Einreichungen schneller laufen – ein ACM-Redakteur lehnte ab.

% Only the first line changes; the body stays as it is.
\documentclass[11pt,a4paper]{article}  % top level heading is \section
% \documentclass[11pt,a4paper]{book}   % \chapter becomes available

\begin{document}
\section{Introduction}
The source carries the structure; the class supplies the appearance.
\end{document}

article, report und book: Worin sie sich unterscheiden

Praktisch läuft der Unterschied auf zwei Punkte hinaus: ob es Kapitel gibt und ob zweiseitiger Druck angenommen wird. article.cls definiert überhaupt kein \chapter, die oberste Ebene ist dort \section; report.cls und book.cls definieren eines. Die Voreinstellungen stehen jeweils in der Zeile \ExecuteOptions der Klassendatei: article verwendet letterpaper,10pt,oneside,onecolumn,final, report ergänzt openany, und nur book wechselt zu twoside und openright. Die Stolperfalle ist das Papierformat – alle drei setzen letterpaper voraus, wer A4 will, muss a4paper selbst angeben. Auch der Titel unterscheidet sich: In article steht er oben auf der ersten Textseite, in report und book bekommt er eine eigene Seite.

book bringt einen weiteren Mechanismus mit: \frontmatter / \mainmatter / \backmatter, die die Konventionen eines gedruckten Buchs in jeweils etwa einer Zeile umsetzen. \frontmatter ruft \pagenumbering{roman} auf, sodass Vorwort und Inhaltsverzeichnis kleine römische Zahlen (i, ii, iii …) erhalten und Kapitel unnummeriert bleiben. \mainmatter ruft \pagenumbering{arabic} auf, beginnt die Zählung wieder bei 1 und schaltet die Kapitelnummern ein. \backmatter behält arabische Seitenzahlen, lässt die Kapitelnummern aber erneut weg, damit das Register nicht als „Kapitel 12 Register“ erscheint. Jedes Buch, dessen Vorwort i, ii, iii trägt und dessen Text wieder bei 1 beginnt, ist das Ergebnis dieser drei Zeilen.

Reichen die vier Standardklassen nicht, hält CTAN für fast jeden Zweck eine bereit. Für Vorträge ist beamer die Standardwahl: Eine frame-Umgebung ergibt eine Folie, schrittweise Einblendungen (Overlays) und Themes inklusive. Wirkt die Standardtypografie angestaubt, entsprechen KOMA-Scripts scrartcl / scrreprt / scrbook den Klassen article / report / book und bieten eine weitaus reichere Schnittstelle für Feinjustierungen. Für japanischen Satz stehen zur Wahl: jsarticle / jsbook (die jsclasses, betreut von Haruhiko Okumura und dem texjporg-Team) unter pLaTeX / upLaTeX, ihre LuaTeX-ja-Gegenstücke ltjsarticle / ltjsbook unter LuaLaTeX sowie jlreq, das auf den Requirements for Japanese Text Layout (JLReq) beruht, die Engine automatisch erkennt und über die Optionen report und book das Verhalten der jeweiligen Klasse annimmt. In jedem Fall lautet die erste Frage gleich: Passt die Klasse zur verwendeten Engine?

Was die Optionen von \documentclass bedeuten

Optionen sind kommagetrennte Schalter in den eckigen Klammern, die für das ganze Dokument gelten, etwa \documentclass[11pt,a4paper,twoside]{article}. Die Reihenfolge spielt keine Rolle; werden zwei Optionen derselben Familie angegeben (etwa oneside und twoside), gewinnt die spätere. Die folgende Tabelle listet die praktisch relevanten auf, doch merken sollte man sich vor allem die Voreinstellungen: Textgröße 10pt, Papier letterpaper, Satzspiegel onecolumn. Wer auf A4 drucken will, muss a4paper jedes Mal selbst angeben.

Ein Mechanismus erwischt hier jeden mindestens einmal. Die in \documentclass angegebenen Optionen gehören nicht allein der Klasse: Sie werden an jedes später geladene Paket als globale Optionen weitergereicht. In der Terminologie von clsguide ist alles, was direkt an \usepackage[...] geht, eine lokale Option, alles an \documentclass[...] eine globale, und ein Paket greift sich aus beiden Quellen die Namen heraus, die es kennt. \documentclass[twocolumn]{article} versetzt daher jedes zweispaltenfähige Paket stillschweigend in den Zweispaltenmodus. Derselbe Mechanismus ist auch das Heilmittel gegen ! LaTeX Error: Option clash for package geometry. – dieser Fehler erscheint, wenn ein Paket zweimal mit unterschiedlichen Optionen geladen wird, meist weil eine Klasse oder Vorlage es bereits geladen hat. LaTeX rät im Protokoll selbst dazu, die Option in die \documentclass-Deklaration hochzuziehen, denn eine globale Option kollidiert nicht mit einem zweiten Laden.

Was in die Präambel gehört und was in den Textkörper

Die Präambel reicht von der Zeile nach \documentclass bis unmittelbar vor \begin{document} und darf nur Deklarationen enthalten – kein einziges Zeichen Fließtext. Steht dort ein gewöhnlicher Satz, bricht der Lauf mit ! LaTeX Error: Missing \begin{document}. ab. Der Name führt in die Irre; gemeint ist: „etwas Druckbares kam an, bevor der Textkörper begonnen hat“. Dieselbe Zeile erscheint, wenn ein %-Kommentar in der Präambel unvollständig bleibt oder sich ein geschütztes bzw. dickes Leerzeichen einschleicht. Das Spiegelbild ist ein \usepackage im Textkörper, das ! LaTeX Error: Can be used only in preamble. liefert – alle Pakete müssen vorliegen, bevor die erste Seite gesetzt wird.

• Pakete laden — \usepackage[options]{package}. Mehrere lassen sich als \usepackage{amsmath,amssymb} bündeln, doch diese Form kann keine Optionen tragen.
• Titelangaben — \title{...}, \author{...}, \date{...}. Gesetzt wird der Titel erst durch \maketitle im Textkörper; die drei Deklarationen stehen üblicherweise in der Präambel.
• Eigene Befehle und Umgebungen — \newcommand, \renewcommand, \newenvironment für Konstrukte, die im ganzen Dokument vorkommen.
• Längen und Zähler — \setlength{\parindent}{0pt}, \setcounter{tocdepth}{2} und andere dokumentweite Werte.
• Seitenstil und Paketkonfiguration — \pagestyle{headings}, \hypersetup{...}, \graphicspath{{figures/}}: Anpassungen nach dem Laden.
• Was dort nichts zu suchen hat — Überschriften, Absätze, Abbildungen, Tabellen; alles, was in der Ausgabe erscheint, gehört hinter \begin{document}.

In welcher Reihenfolge werden Pakete geladen?

Den meisten Paketen ist die Reihenfolge gleichgültig, doch die Ausnahmen lohnen das Merken. Die bekannteste ist hyperref; das Handbuch sagt unmissverständlich, es solle zuletzt unter den geladenen Paketen stehen. Der Grund ist schlicht: hyperref definiert eine ganze Reihe von LaTeX-Befehlen neu. Wird es zu früh geladen, überschreibt ein später geladenes Paket diese Neudefinitionen, und Links wie PDF-Lesezeichen brechen stillschweigend. Das Handbuch versieht den Rat mit einer Fußnote: Es sei begonnen worden, die Zahl der Neudefinitionen und damit die Abhängigkeit von der Ladereihenfolge zu verringern. Es handelt sich also um eine derzeitige Behelfslösung, nicht um ein dauerhaftes Gesetz.

Und dieses „zuletzt“ hat eine berühmte Ausnahme: cleveref muss nach hyperref geladen werden. cleveref baut seine Verweisbefehle auf, indem es erkennt, was hyperref definiert hat; die umgekehrte Reihenfolge funktioniert schlicht nicht. Kommt zusätzlich varioref ins Spiel, schreibt dessen Handbuch die Folge varioref → hyperref → cleveref vor. Tückisch ist diese Falle, weil sie lautlos zuschlägt: Das cleveref-Handbuch warnt, dass Querverweise bei falscher Reihenfolge auf völlig falsche Ziele zeigen – ohne jede Warnung in Ausgabe oder Protokoll. Wer je Verweisnummern hatte, die rätselhaft um eins verschoben waren, prüft zuerst die Reihenfolge dieser drei Zeilen in der Präambel.

\documentclass[11pt,a4paper]{article}

% 1. encoding and fonts
\usepackage[T1]{fontenc}
% 2. language
\usepackage[english]{babel}
% 3. page geometry
\usepackage[margin=25mm]{geometry}
% 4. mathematics
\usepackage{amsmath,amssymb}
% 5. graphics and colour
\usepackage{graphicx}
\usepackage{xcolor}
% 6. hyperref near the end: it redefines many commands
\usepackage{hyperref}
% 7. cleveref is the exception, it must come after hyperref
\usepackage{cleveref}

% document-wide settings and definitions
\newcommand{\R}{\mathbb{R}}
\setlength{\parindent}{0pt}
\title{A Short Note}
\author{Ada Lovelace}
\date{\today}

\begin{document}
\maketitle

\section{Setup}\label{sec:setup}
For all $x \in \R$ we have $x^2 \ge 0$.

\section{Result}
The argument of \cref{sec:setup} applies unchanged.
\end{document}

Die Präambel kleiner halten als das Dokument

In eben jenem Interview wurde Lamport gebeten, drei LaTeX-Fehler zu nennen, die man sich abgewöhnen sollte. Alle drei Antworten lauteten gleich: zu viel über die Formatierung und zu wenig über den Inhalt nachzudenken. Die Wiederholung war die Pointe. Genau in der Präambel steht diese Falle – einmalige optische Korrekturen, einmal ausprobierte und nie entfernte Pakete, zweimal benutzte Abkürzungen, alles sammelt sich an. Der Preis ist nicht Hässlichkeit, sondern dass sich der Schuldige, wenn irgendwann ein Fehler auftritt, irgendwo in diesen Dutzenden Zeilen versteckt. Es bleibt nur, was für das ganze Dokument gilt: Klasse, Sprache und Schriften, Mathematik, Abbildungen und Tabellen, Links. \newcommand gebührt allein Konstruktionen, die sich beim Schreiben tatsächlich wiederholt haben. Und wo eine Einreichungsvorlage im Spiel ist, hat deren Präambel Vorrang – ein Paket zu ersetzen, das die Klasse voraussetzt, kommt meist als Option clash zurück oder in erheblich schwerer lesbarer Form.

• Ein neuer Bericht — mit article anfangen. Am Seitendesign lässt sich arbeiten, wenn der Text grob steht.
• Eine Abschlussarbeit — die von der Hochschule verteilte Klasse unverändert nehmen und Rand- oder Überschriftenanpassungen ans Ende schieben; die Vorlagenpräambel nicht anzufassen ist der kürzeste Weg.
• Eine Zeitschrifteneinreichung — zuerst die Klasse des Verlags (elsarticle, IEEEtran, revtex4-2 …) setzen und darüber nur das Nötigste an eigener Präambel ergänzen.
• Druck auf A4 — die Standardklassen setzen letterpaper voraus, also \documentclass[a4paper]{...} ausdrücklich angeben; mit geladenem geometry geht es auch dort.
• Wenn ein Fehler auftritt — zuerst das zuletzt hinzugefügte \usepackage oder \newcommand verdächtigen; hilft das nicht, die Präambel halbieren und binär suchen.