Unveränderte Ausgabe

Einen einzelnen Backslash in LaTeX zu drucken ist schwieriger als ein Integralzeichen zu drucken – das ist kein Scherz. Verbatim, also \verb für ein Fragment und die verbatim-Umgebung für einen Block, ist die einzige Ecke des Systems, die nur funktioniert, indem LaTeX seine eigene Grammatik kurzzeitig abschaltet. Alle scheinbar willkürlichen Regeln folgen daraus: warum \verb keinen Zeilenumbruch überschreiten darf, warum \end {verbatim} mit einem Leerzeichen darin den Lauf zum Stillstand bringt und warum \verb in \section{...} oder \footnote{...} mit einer Fehlermeldung scheitert, in der Verbatim gar nicht vorkommt. Diese Seite behandelt die verbatim-Umgebung und \verb, die Sternformen, die Leerzeichen sichtbar machen, das Einlesen ganzer Dateien mit \verbatiminput und \VerbatimInput, die Variante alltt, die einige Befehle aktiv lässt, gerahmte und nummerierte Blöcke mit fancyvrb sowie das Setzen eines einzelnen Backslash oder Unterstrichs im laufenden Text.

Was die verbatim-Umgebung tatsächlich abschaltet

Alles zwischen \begin{verbatim} und \end{verbatim} erscheint exakt wie eingegeben – samt Zeilenumbrüchen und Leerzeichen – in Schreibmaschinenschrift, ganz ohne Zusatzpaket. Der Mechanismus ist kein Maskieren, sondern eine Herabstufung. Beim Eintritt in die Umgebung schreibt LaTeX die Category Codes von \, {, }, $, &, #, ^, _, % und ~ auf einen Schlag in „gewöhnliches Zeichen“ um. Ein Category Code ist die Rollenmarke, die TeX jedem Zeichen beim Einlesen anheftet; sie entscheidet, ob das Zeichen einen Befehl beginnt, eine Gruppe öffnet oder bloß Druckerschwärze ist. Ein Backslash in Verbatim beginnt also keinen Befehl – nicht weil Befehle ignoriert würden, sondern weil der Backslash in diesem Moment nur ein Zeichen ist, das zufällig wie ein Backslash aussieht.

\begin{verbatim}
for i in range(3):
    print("100% & $5 \n")   # none of this is interpreted
\end{verbatim}

Das umzusetzen ist auch für den Autor unbequem, und diese Unbequemlichkeit ist im Quelltext von LaTeX selbst konserviert. In latex.ltx, der Datei, die LaTeX definiert, wird das Makro, das nach dem Ende eines Verbatim-Blocks sucht, mit | als Escape-Zeichen und [ sowie ] als Klammern definiert. Innerhalb dieser Definition müssen die drei Zeichen \, { und } gewöhnliche druckbare Zeichen sein, weshalb sich die Sprache dort nicht in ihrer üblichen Notation ausdrücken kann. Für die Dauer dieser Definition hört der Quelltext von LaTeX auf, in LaTeX geschrieben zu sein. Die beiden Zeilen lassen sich in der mit TeX Live 2024 gelieferten latex.ltx direkt nachlesen.

Aus dieser Art der Enderkennung folgen zwei praktische Regeln. Erstens: Die Zeichenkette \end{verbatim} darf innerhalb der Umgebung nicht vorkommen – LaTeX betrachtet sie sofort als Ende. Zweitens: Zwischen \end und {verbatim} darf kein Leerzeichen stehen. Der Abschluss wird Zeichen für Zeichen als Trennmarke eines Makroarguments verglichen; \end {verbatim} wird deshalb überhaupt nicht erkannt, TeX liest bis zum Dateiende weiter und bricht mit Runaway argument? und anschließend ! File ended while scanning use of \@xverbatim. ab. Ein Formatierungswerkzeug, das Leerzeichen glättet, erzeugt genau diesen Fehler. Wenn die Zahl der Leerzeichen zählt, druckt die Sternform verbatim* jedes einzelne als ␣.

Das Begrenzungszeichen von \verb wählen – und warum es keine Zeile überspringt

Für ein kurzes wörtliches Stück mitten in einer Zeile dient \verb. Unmittelbar nach \verb steht ein Begrenzungszeichen, dann der wörtlich zu druckende Text, dann dasselbe Zeichen erneut – etwa \verb|\textbf{x}|. Als Begrenzung taugt fast jedes Zeichen, das im Inhalt nicht vorkommt; enthält der Inhalt ein |, dann eben \verb!...!, \verb+...+ oder \verb/.../. Zwei Zeichen scheiden aus. Ein Buchstabe funktioniert nicht, denn \verbx liest TeX als einen völlig anderen Befehlsnamen. Und * steht nicht zur Verfügung, weil \verb* für die Sternform reserviert ist, die Leerzeichen als ␣ druckt.

The macro \verb|\textbf{...}| sets bold text;
a pipe in the content needs another delimiter, as in \verb!a|b!.

Count the gaps: \verb*|a  b| prints the spaces as visible marks.

Für \verb gilt eine weitere harte Grenze: Das schließende Begrenzungszeichen muss auf derselben Zeile stehen. Kommt zuerst das Zeilenende, endet der Lauf mit ! LaTeX Error: \verb ended by end of line. Meist fehlt schlicht das schließende Zeichen; erstaunlich häufig hat aber auch ein Editor eine lange Zeile automatisch umbrochen oder neu formatiert und das Argument dabei zerteilt. Für längere Inhalte gehört der Text ohnehin aus \verb heraus in eine Blockumgebung. Und wenn es nur um eine Zeichenkette geht, die oft ~, #, % oder _ enthält – typischerweise eine URL –, passt \url{...} aus dem Paket url oder hyperref besser: wörtlich, und zugleich an sinnvollen Stellen umbrechbar.

Backslash und Unterstrich im laufenden Text setzen

Für ein oder zwei Zeichen braucht es kein Verbatim. Ein Backslash ist \textbackslash, ein Unterstrich ist \_. Der häufigste Unfall dabei: \\ ist kein Backslash, sondern der Befehl für den Zeilenumbruch – \\ druckt nichts und bricht stattdessen die Zeile um. $\backslash$ im Mathematikmodus liefert zwar die Form, aber in der Mathematikschrift; im laufenden Text ist \textbackslash die richtige Antwort. Ein nackter Unterstrich führt zu ! Missing $ inserted. – für TeX bedeutet _ „es folgt ein Index“ –, und file\_name behebt das.

Warum \verb in \section, \footnote und \caption scheitert

Weder \verb noch die verbatim-Umgebung dürfen im Argument eines anderen Befehls stehen. Der Grund ist kein Verbot, sondern schlichte Chronologie. \verb schaltet die Category Codes erst unmittelbar vor dem Lesen seines eigenen Texts um. Der Inhalt von \section{...} wurde jedoch bereits im Moment des Aufrufs von \section unter den normalen Category Codes in eine Tokenliste verwandelt. Wenn \verb an die Reihe kommt, ist \foo längst keine Folge von vier zu druckenden Zeichen mehr, sondern der Befehl \foo. Verbatim kann nichts erneut lesen, was schon gelesen wurde – mehr steckt nicht dahinter.

Unangenehm daran ist, dass sich dieser Fehlschlag in Meldungen zeigt, in denen das Wort Verbatim nie vorkommt. \section{The \verb|\foo| command} bricht mit ! Undefined control sequence. ab – \foo wurde tatsächlich als Befehl gelesen, und den gibt es nicht. Enthält der Inhalt überhaupt kein Sonderzeichen, etwa bei \mbox{\verb|abc|}, erscheint die ungewöhnlich hilfreiche Meldung ! LaTeX Error: \verb illegal in argument. Blockumgebungen sind noch schwerer zu lesen: \footnote{\begin{verbatim} ... \end{verbatim}} liefert Runaway argument? und danach ! Paragraph ended before \@xverbatim was complete., in \parbox{5cm}{...} wird daraus ! Argument of \@xverbatim has an extra }. und in \caption{...} ! Argument of \@caption has an extra }. Alle sind dieselbe Ursache mit anderem Gesicht.

Eine Tabellenzelle ist dagegen kein Argument. Die Zellen von tabular werden gelesen, während TeX auf die Spalten- und Zeilentrenner achtet; \verb funktioniert dort unverändert, auch in einer p{4cm}-Spalte. Innerhalb derselben Tabelle ist das dritte Argument von \multicolumn{2}{c}{...} jedoch tatsächlich ein Argument – und dort scheitert es. Die Merkregel lautet also nicht „nicht in Tabellen“, sondern „nicht in einem von geschweiften Klammern begrenzten Argument“.

Drei Auswege stehen bereit. Der erste ist das Paket cprotect (Bruno Le Floch, v1.0e), dessen einziger Zweck Verbatim in Makroargumenten ist: Ein \cprotect vor den betroffenen Befehl genügt, und \cprotect\section{The \verb|\foo| command} übersetzt sauber. Mitgeliefert wird \cprotEnv zum Schützen des \begin einer Umgebung. Der zweite ist \SaveVerb / \UseVerb aus fancyvrb: den wörtlichen Text zuerst unter einem Namen speichern und im Argument nur noch diesen Namen aufrufen. Der dritte betrifft nur Fußnoten – wird fancyvrbs \VerbatimFootnotes in der Präambel deklariert, funktioniert Verbatim innerhalb von \footnote. Der Wechsel von \verb zu fancyvrbs \Verb hilft dagegen nicht: Das Zeitproblem ist dasselbe. Und als letzter Ausweg ist \texttt{\textbackslash foo} von Hand geschrieben der kürzeste Weg, wenn es nur um eine einzige Überschrift geht.

% Fails: \foo was already a command token before \verb could act
% \section{The \verb|\foo| command}   -> Undefined control sequence

% Workaround 1 -- cprotect
\usepackage{cprotect}
\cprotect\section{The \verb|\foo| command}

% Workaround 2 -- save it first, use it later
\usepackage{fancyvrb}
\SaveVerb{cmd}|\foo|
\section{The \UseVerb{cmd} command}

% Workaround 3 -- verbatim inside footnotes
\VerbatimFootnotes

Ganze Dateien einlesen: \verbatiminput und \VerbatimInput

Mit \usepackage{verbatim} in der Präambel und \verbatiminput{hello.py} im Text wird jede Zeile dieser externen Datei wörtlich gesetzt. Anders als beim Kopieren in das Manuskript aktualisiert sich das PDF automatisch, sobald die Quelldatei geändert wird; Code und Dokument driften nicht auseinander. Wenn der gezeigte Code tatsächlich lauffähig sein soll, ist das der sicherste Weg.

Es lohnt zu fragen, warum es neben der Standard-Umgebung verbatim überhaupt ein Paket namens verbatim gibt – und die Antwort ist nicht \verbatiminput. Die Dokumentation dieses Pakets von Rainer Schöpf, Teil des Tools-Bundles von LaTeX, nennt den Grund unmissverständlich: Die eingebaute Umgebung kann keine einzige Zeile ausgeben, bevor sie alles bis \end{verbatim} als ein einziges Makroargument gelesen hat; lange Listings können daher den Speicher von TeX sprengen. Das Paket ersetzt die Implementierung durch eine, die Verbatim zeilenweise liest und setzt – ein Kunstgriff, den die Dokumentation dem Makro \comment aus AMS-TeX zuschreibt. Sobald Verbatim Zeile für Zeile gelesen werden kann, fällt \verbatiminput praktisch nebenbei ab. Ein sichtbarer Nebeneffekt bleibt: Text, der in derselben Zeile hinter \end{verbatim} steht, wird von der eingebauten Umgebung gedruckt, von der Paketfassung dagegen stillschweigend verworfen. Der Unterschied ist gewollt und dokumentiert.

\usepackage{verbatim}
% ...
\verbatiminput{hello.py}

\begin{comment}
This paragraph is skipped entirely -- not printed, not typeset.
\end{comment}

Dasselbe Paket ergänzt eine comment-Umgebung, die alles zwischen \begin{comment} und \end{comment} überspringt – nicht wörtliche Ausgabe, sondern gar keine, praktisch zum vorübergehenden Beiseitelegen eines Entwurfs. Für feinere Kontrolle beim Einbinden von Dateien dient \VerbatimInput[options]{filename} aus fancyvrb, dem nächsten Abschnitt. Anders als \verbatiminput nimmt es Rahmen und Zeilennummern entgegen und holt mit firstline=10, lastline=25 nur einen Ausschnitt der Datei – genau richtig, wenn eine lange Quelle nur eine relevante Stelle enthält.

alltt: Verbatim, in dem einige Befehle weiterlaufen

Wer nur einen Teil eines Codebeispiels fett oder farbig setzen möchte, kommt mit gewöhnlichem Verbatim nicht weiter: Sämtliche Befehle sind abgeschaltet. Die Umgebung alltt aus dem Paket alltt, das dem Standard-LaTeX beiliegt, löst das. alltt setzt Text ähnlich wie verbatim monospaced und wie eingegeben, nur drei Zeichen behalten ihre übliche Bedeutung: der Backslash \ und die Klammern { und }. Das Ergebnis sieht wörtlich aus und führt innen dennoch LaTeX-Befehle aus.

\usepackage{alltt}
% ...
\begin{alltt}
def \textbf{greet}(name):
    return "Hi, " + name   \textit{# a comment}
\end{alltt}

Im Beispiel erscheint der Funktionsname greet fett und der Kommentar kursiv, alles Übrige bleibt exakt wie eingegeben. Der Preis liegt offen: Um die drei Zeichen \, {, } als Zeichen zu drucken, müssen sie nun als \textbackslash, \{, \} geschrieben werden – verbatim druckt sie direkt. alltt ist also ein Tauschgeschäft: drei Zeichen an Wörtlichkeit gegen das Recht, den Rest zu formatieren. Für leichte, von Hand gesetzte Hervorhebungen eignet sich alltt, für Text, an dem sich kein einziges Zeichen bewegen darf, verbatim.

Zeilennummern und Rahmen: die Verbatim-Umgebung von fancyvrb

Weder Zeilennummern noch Rahmen bietet das eingebaute Verbatim. Diese Aufgabe übernimmt das Paket fancyvrb, dessen Kern die Verbatim-Umgebung mit großem V ist – etwas anderes als das kleingeschriebene verbatim. Optionen werden je Umgebung als \begin{Verbatim}[numbers=left, frame=single] übergeben oder per \fvset{numbers=left, ...} in der Präambel dokumentweit voreingestellt. Begonnen hat fancyvrb 1992 Timothy Van Zandt, der auch PSTricks schrieb; seit 2000 betreut es Herbert Voß (die Fassung in TeX Live 2024 trägt die Nummer 4.5c). Drei Jahrzehnte angesammelter Praxisoptionen erklären, warum es für fast jeden Fall eine Antwort hat.

\usepackage{fancyvrb}
\fvset{fontsize=\small}          % document-wide default
% ...
\begin{Verbatim}[numbers=left, frame=single]
def greet(name):
    return "Hello, " + name
\end{Verbatim}

% only lines 10-25 of an external file, framed
\VerbatimInput[firstline=10, lastline=25, frame=lines]{server.py}

Mit commandchars=\\\{\} wirken \, { und } innerhalb des wörtlichen Texts wieder als Escape- und Gruppierungszeichen, sodass sich Befehle wie in alltt einbetten lassen. Statt denselben Optionssatz jedes Mal zu wiederholen, empfiehlt es sich, eine eigene Umgebung zu definieren: \DefineVerbatimEnvironment{Code}{Verbatim}{numbers=left, frame=single}; danach genügt \begin{Code}. Alles auf dieser Seite dient allerdings dem unveränderten Ausgeben von Text; nichts davon färbt Schlüsselwörter, also betreibt nichts davon Syntax-Highlighting. Für farbig aufbereiteten Quellcode sind listings, das allein mit TeX-Makros einfärbt, und minted, das die Arbeit an Pygments aus Python abgibt, zuständig – die verwandte Seite „Code-Listings“ vergleicht beide.