Quellcode-Listings

Wenn Programmquellcode schön erscheinen soll, mit Zeilennummern und Syntaxhervorhebung für Schlüsselwörter, Kommentare und Zeichenketten, sind listings und minted die beiden Standardpakete. Ersteres braucht keine externen Werkzeuge und läuft überall; letzteres ruft die externe Pygments-Engine auf und liefert deutlich genauere Hervorhebung. Wenn Code nur exakt wie eingegeben wiedergegeben werden soll, reicht die einfachere verbatim-Familie.

Zwei Ansätze

Für Quellcode gibt es zwei Wege mit unterschiedlichen Grundideen. listings ist rein mit LaTeX-Makros implementiert und braucht keinerlei zusätzliche Software; \usepackage{listings} genügt auf Overleaf ebenso wie in einer gesperrten Laborumgebung, die du nicht konfigurieren kannst. minted dagegen übergibt die Arbeit an Pygments, einen vollwertigen Python-Lexer, und holt das Ergebnis zurück nach LaTeX. Weil Pygments Hunderte Sprachen wirklich parst, ist die Hervorhebung erheblich genauer als bei listings.

Genau dieser Unterschied bestimmt die Wahl: listings für Einfachheit und Portabilität, minted für die Qualität der Hervorhebung. Da minted ein externes Programm startet, braucht es die besondere Erlaubnis shell escape (unten erklärt) und läuft in eingeschränkten Umgebungen möglicherweise nicht. Wenn Code nur verbatim erscheinen soll, ohne Farben und Zeilennummern, sind verbatim oder fancyvrb leichter; siehe dazu „Verbatim“.

Grundlagen von listings

Lade zuerst \usepackage{listings}. Einen Codeblock umschließt du mit der Umgebung lstlisting; eine ganze externe Datei bindest du mit \lstinputlisting ein; ein kurzes Stück im Fließtext setzt du mit \lstinline. Statt Optionen an jeder Stelle zu wiederholen, sammelt man Sprach- und Darstellungseinstellungen üblicherweise einmal in der Präambel mit \lstset{...}.

\usepackage{listings}
\usepackage{xcolor}

\lstset{
  language=Python,                 % 言語 / language
  basicstyle=\ttfamily\small,       % 本文の書体 / base font
  keywordstyle=\color{blue}\bfseries,
  commentstyle=\color{teal}\itshape,
  stringstyle=\color{red!60!black},
  numbers=left,                    % 行番号を左に / line numbers on the left
  numberstyle=\tiny\color{gray},
  frame=single,                    % 枠線 / a single-line frame
  breaklines=true,                 % 長い行を折り返す / wrap long lines
  showstringspaces=false,          % 文字列中の空白を記号化しない
  tabsize=2,
}

\begin{lstlisting}[caption={階乗を計算する}, label=lst:fact]
def factorial(n):
    # 再帰で階乗を求める
    if n <= 1:
        return 1
    return n * factorial(n - 1)
\end{lstlisting}

Die wichtigsten \lstset-Schlüssel sind diese: basicstyle setzt die Grundschrift (\ttfamily\small ist üblich); keywordstyle, commentstyle und stringstyle gestalten Schlüsselwörter, Kommentare und Zeichenketten. numbers=left setzt Zeilennummern an den linken Rand, numberstyle formatiert sie. frame=single zeichnet einen Rahmen, breaklines=true bricht lange Zeilen um, und mit caption= und label= wird der Block zu einem nummerierten „Listing“ wie Abbildung oder Tabelle, auf das du mit \ref verweisen kannst.

Einzelne Blöcke können Optionen in [ ] überschreiben, etwa \begin{lstlisting}[language=C, numbers=none]. Bei einer externen Datei kannst du sogar einen Zeilenbereich ausschneiden: \lstinputlisting[language=Python, firstline=37, lastline=45]{sample.py}. Für Code im Text wählst du wie bei \verb ein Trennzeichen, z. B. \lstinline|while (i < n)|.

Grenzen von listings (UTF-8 und Japanisch)

Die Hervorhebung in listings ist eine Annäherung auf Basis einer sprachspezifischen Schlüsselwortliste und einfacher Regeln; sie ist nicht so klug wie ein echter Lexer. Kontextabhängige Färbung, etwa wenn dasselbe Wort einmal Typname und einmal Variable ist, fällt ihm schwer, und bei komplexeren Sprachen treten die Kanten deutlicher hervor. Das ist eine Grenze des Ansatzes selbst.

Ein zweiter praktischer Fallstrick sind Mehrbytezeichen. listings setzt standardmäßig kein UTF-8 voraus, daher können japanische Kommentare im Code verstümmelt oder spaltenverschoben erscheinen. Es gibt zwei Gegenmittel. Wenn du Code direkt in den Text schreibst, bringst du die Zeichen einzeln mit literate= bei, etwa \lstset{... literate={あ}{{あ}}1 ...}; bei vielen Zeichen ist das unpraktisch. Bindest du dagegen eine externe Datei ein, ist die einfache Lösung, statt listings das Paket listingsutf8 zu laden (es wirkt nur mit \lstinputlisting).

Grundlagen von minted (Pygments)

Mit \usepackage{minted} schreibst du Codeblöcke in der Umgebung minted. Der große Unterschied zu listings ist, dass der Sprachname das erste Argument ist: \begin{minted}{python}. Daneben gibt es den Einzeilen-Kurzbefehl \mint, den Inline-Befehl \mintinline und \inputminted für externe Dateien.

\usepackage{minted}

% ドキュメント全体の配色テーマ / a color theme for the whole document
\usemintedstyle{monokai}

\begin{minted}[linenos, bgcolor=black!90, fontsize=\small]{python}
def factorial(n):
    if n <= 1:
        return 1
    return n * factorial(n - 1)
\end{minted}

% 単一行 / a single line
\mint{python}|print("Hello!")|

% 本文中に埋め込む / inline in running text
\mintinline{python}{print("Hello!")}

% 外部ファイルを取り込む / include an external file
\inputminted[linenos]{python}{sample.py}

Optionen stehen direkt nach dem Umgebungsnamen in [ ] als key=value. Häufig sind linenos für Zeilennummern, style= für ein Pygments-Farbthema (monokai usw.; Galerie unter pygments.org/styles), bgcolor= für eine Hintergrundfarbe und fontsize=. Ein dokumentweites Thema setzt du mit \usemintedstyle{monokai}; breitere Voreinstellungen mit \setminted{style=monokai, linenos}. Für eine von Pygments nicht unterstützte Sprache oder bewusst ohne Hervorhebung wählst du die Sprache text.

Der Code für \mint und \mintinline wird wie bei \verb abgegrenzt: mit passenden Trennzeichen (beliebige Satzzeichen, etwa |...|) oder mit geschweiften Klammern {...}. Beachte: \mint ist nicht für Inline-Satz gedacht; es erspart nur die Umgebung, wenn der Code aus einer einzigen Zeile besteht. Für Code im Fließtext nimm immer \mintinline.

Shell escape (der Haken bei minted)

Da minted ein externes Python-Programm startet, musst du mit aktiviertem shell escape kompilieren, also mit der Erlaubnis, dass LaTeX externe Befehle ausführen darf. Bei pdfLaTeX gibst du die Option -shell-escape an.

pdflatex -shell-escape document.tex

Darunter werden außerdem Python 3.8+ und Pygments benötigt. Mit minted Version 3, einer vollständigen Neufassung ab 2025, hat sich die Lage verbessert. Bei Installation über eine TeX-Paketverwaltung (tlmgr install minted usw.) wird die gesamte Python-Seite einschließlich Pygments im TeX-Baum als eigene ausführbare Datei latexminted mitgeliefert; eine separate Pygments-Installation entfällt. Außerdem ist latexminted für eingeschränktes shell escape ausgelegt: Ab TeX Live 2024 ist es als vertrauenswürdiges Programm registriert, sodass du ganz ohne -shell-escape kompilieren kannst.

Trotzdem brauchst du unter TeX Live vor 2024 und unter MiKTeX weiterhin -shell-escape (bei MiKTeX -enable-write18). Weil shell escape beliebige externe Befehle ausführen kann, verwende es nicht für Dokumente aus nicht vertrauenswürdigen Quellen. In einer vorkonfigurierten Umgebung wie Overleaf oder lokal mit eigenem Code ist es dagegen in Ordnung (Overleaf unterstützt minted standardmäßig). Diese „externe Abhängigkeit plus shell escape“ ist der wichtigste Kompromiss gegenüber dem portableren listings.

Was wählen?

• Du willst keine Einrichtung und die Sicherheit, dass es überall läuft → listings. Auf Overleaf oder einem gesperrten Rechner genügt \usepackage.
• Genauigkeit der Hervorhebung und Sprachabdeckung sind wichtiger → minted. Pygments spielt in einer anderen Liga.
• Du kannst keine externen Werkzeuge installieren / kein shell escape nutzen → listings, eindeutig.
• Du brauchst nur unveränderte Codeausgabe ohne Farben → verbatim oder fancyvrb reichen (siehe „Verbatim“).
• Du willst einen Algorithmus als Pseudocode schreiben → die spezialisierten Pakete algorithm2e / algpseudocode (siehe „Algorithms“).