Community

Wenn LaTeX einen zur Verzweiflung bringt, sitzt die Person mit der Antwort meist auf tex.stackexchange.com. Diese Community verlangt allerdings Eintritt, und der Eintritt heißt nicht Höflichkeit, sondern minimal working example, kurz MWE. Wie ernst das gemeint ist? So ernst, dass TeX Live ein Paket namens mwe mitliefert, dessen einzige Aufgabe darin besteht, minimale Beispiele leichter teilbar zu machen, und dass texdoc minexample ein 21-seitiges Heftchen öffnet, das ausschließlich davon handelt, wie man ein solches Beispiel baut. Diese Seite zeigt, wohin eine LaTeX-Frage gehört – TeX Stack Exchange, das Erbe der Usenet-Gruppe comp.text.tex, TUG und die nationalen Anwendergruppen, die Fehlerverfolgung der Pakete – und wie man so fragt, dass eine Antwort zurückkommt: die Kunst, ein 300-Seiten-Dokument auf zwanzig Zeilen einzudampfen.

Vor dem Fragen: tex.stackexchange.com durchsuchen

Die meisten LaTeX-Fragen sind bereits gestellt worden, und zwar mit denselben Worten. TeX Stack Exchange (tex.stackexchange.com) entstand im August 2010 – dieses Datum ist kein Hörensagen, es steht im Mitteilungsblatt des LaTeX-Teams selbst. LaTeX3 News Nummer 5 (Januar 2011), die TeX Live mitliefert, hält fest, dass die Frage-und-Antwort-Site TeX Stack Exchange entstanden und rasch gewachsen sei: Zum Redaktionsschluss hatten rund 2.800 Personen 2.600 Fragen gestellt, bei insgesamt 5.600 Antworten, und 2.200 Nutzer schauten täglich vorbei. Ein texdoc l3news öffnet dieselbe Seite auf der eigenen Maschine. Gut ein Jahrzehnt später sind zwei Stellen dazugekommen, gewachsen ist aber vor allem der Bestand an alten Fragen. Für die Suche gibt es einen Kniff: das Problem nicht mit eigenen Worten beschreiben, sondern die Fehlermeldung wörtlich einfügen. Eine Zeile wie ! Undefined control sequence oder ! Missing $ inserted ist der beste Suchschlüssel überhaupt.

In den drei Jahrzehnten davor lag der Schwerpunkt der TeX-Diskussion bei der Usenet-Gruppe comp.text.tex (im deutschsprachigen Raum bei de.comp.text.tex). Wie zentral sie war, zeigen die Danksagungen der Bücher jener Zeit. In TeX by Topic (Addison-Wesley, 1991) dankt Victor Eijkhout den Teilnehmern der Diskussionslisten TeXhax, der niederländischen TeX-nl und comp.text.tex und schreibt, ihre Fragen und Antworten hätten ihm viel Stoff zum Nachdenken gegeben. Das Buch liegt TeX Live bei – texdoc texbytopic öffnet es samt Danksagung, sodass sich die Verschiebung des Schwerpunkts direkt nachlesen lässt. Die Newsgroup existiert weiterhin, doch für eine LaTeX-Frage ist heute TeX Stack Exchange die erste Adresse. Alte Beiträge tauchen in Suchergebnissen nach wie vor auf; wenn das geschieht, gehört die Jahreszahl geprüft.

Was ein minimal working example wirklich ist

Ein MWE ist das kürzeste vollständige Dokument, das den Fehler noch reproduziert – und „vollständig“ ist streng gemeint. Nicola L C Talbots Creating a LaTeX Minimal Example (2014, in TeX Live enthalten, texdoc minexample) beginnt mit dem Hinweis, ein minimales Beispiel dürfe kein Paket und keinen Code enthalten, der nichts zum Problem beiträgt, müsse aber eine Dokumentklasse und die document-Umgebung enthalten. Es ist also kein Fragment. Es ist etwas, das die Gegenseite unverändert speichern und durch pdflatex schicken kann – genau das bedeutet das „working“ im Namen. Wer stattdessen drei Zeilen ohne \begin{document} einfügt, erhält als erste Antwort die Bitte um ein vollständiges Beispiel und verliert eine Runde.

% A minimal working example: complete, compilable, and as short as it can be.
% Nothing here that does not bear on the problem being reported.
\documentclass{article}
\usepackage{booktabs}
\begin{document}
\begin{tabular}{ll}
  \toprule
  left & right \\
  \bottomrule
\end{tabular}
\end{document}

Schwierig wird es bei Beispielen, die eine Abbildung brauchen: Das eigene Foto lässt sich nicht mitschicken, und selbst dann läge es der Gegenseite nicht vor. Dafür gibt es das Paket mwe. Ein \usepackage{mwe} lädt graphicx und stellt aus dem TeX-Baum eine Reihe von Standardbildern bereit – example-image, example-image-a, example-image-16x9, example-grid-100x100bp und weitere. Wer TeX Live installiert hat, besitzt sie bereits, sodass ein Beispiel mit \includegraphics{example-image} auf jeder Maschine übersetzt. Aus demselben Grund gilt für Fließtext in Menge: \lipsum[1-3] aus lipsum oder \blindtext aus blindtext (mwe lädt lipsum, sofern vorhanden, von selbst). Ein Beispiel ohne Anhänge wird allein deswegen schneller beantwortet.

Von 300 Seiten auf zwanzig Zeilen: building up und hacking down

Es gibt nur zwei Wege, und Talbot nennt sie building up und hacking down. Beim Aufbauen beginnt man mit \documentclass{article} und einer leeren document-Umgebung und fügt eines nach dem anderen hinzu, bis das Problem auftritt. Beim Abtragen beginnt man mit einer Kopie des echten Dokuments und entfernt so lange, bis das Problem verschwindet. Aufbauen passt zu kurzen Texten, Abtragen ist bei 300 Seiten schneller – aber nicht zeilenweise abtragen. Immer die Hälfte löschen. Die erste Hälfte der Präambel auskommentieren: Bleibt das Problem, ist diese Hälfte unschuldig, und das weiß man nach einem einzigen Lauf. Den Rest wieder halbieren, und noch einmal: Nach etwa einem Dutzend Runden werden aus Hunderten Zeilen eine Handvoll. Das ist binäre Suche, und derselbe Griff funktioniert auch bei \include-ten Kapiteln.

• Auf einer Kopie arbeiten. Niemals in die originale .tex schneiden; jede Löschung geschieht am Duplikat.
• Zuerst den Fließtext wegwerfen. Die per \include eingebundenen Kapitel, Abbildungen, Tabellen und das Literaturverzeichnis entfernen und nach \begin{document} nur die eine auffällige Zeile stehen lassen.
• Die Präambel halbieren. Bleibt das Problem, ist die entfernte Hälfte unschuldig; verschwindet es, gerät das eben Entfernte in Verdacht und wird seinerseits halbiert.
• Eigene Makros auflösen. Ein \newcommand durch seinen Rumpf zu ersetzen trennt „der Fehler steckt in meinem Makro“ von „der Fehler steckt im Paket“.
• Die Klasse versuchsweise durch article ersetzen. Verschwindet das Problem dadurch, ist die Klasse die Ursache – auch das ist ein Befund. Beim Melden gehört er dazu.
• Nach jedem Schnitt neu übersetzen. Der häufigste Fehlschlag besteht darin, weiterzumachen, ohne zu merken, dass sich das Problem schon einige Löschungen zuvor nicht mehr zeigte.

Ist der Text eingedampft, kommen zum Schluss die Versionsangaben dazu. Von Hand aufschreiben muss man sie nicht: Eine einzige Zeile \listfiles vor \documentclass, dann übersetzen – am Ende der .log entsteht ein Abschnitt *File List*, der jede geladene Datei mit Datum und Version aufführt. Ergänzt um die Engine (pdflatex, xelatex oder lualatex) und die Distribution (TeX Live 2024, MiKTeX, Overleaf) lässt sich die Umgebung damit praktisch nachbauen. Die Fehlermeldung nicht zusammenfassen, sondern die Zeile mit ! und die folgenden Zeilen wörtlich einfügen. Eine Beschreibung wie „da kommt irgendein Fehler“ trägt immer weniger Information als die Originalzeile.

% \listfiles before \documentclass, then look at the end of the .log:
 *File List*
 article.cls    2023/05/17 v1.4n Standard LaTeX document class
  size10.clo    2023/05/17 v1.4n Standard LaTeX file (size option)
booktabs.sty    2020/01/12 v1.61803398 Publication quality tables
 ***********

Jenseits von Stack Exchange: TUG, nationale Anwendergruppen, Fehlerverfolgung

Die TUG, die TeX Users Group, ist eine 1980 gegründete internationale gemeinnützige Mitgliederorganisation. Sie trägt die Entwicklung mit, TeX Live eingeschlossen, gibt die Zeitschrift TUGboat heraus und veranstaltet eine Jahreskonferenz. Dass TUGboat nicht bloß Lesestoff ist, lässt sich auf der eigenen Platte nachprüfen: Die Einreichungsklasse ltugboat.cls liegt TeX Live bei – ihre Copyright-Zeile lautet „Copyright 1994-2023 TeX Users Group“, und die TUG selbst ist die betreuende Instanz –, und ein texdoc tugboat öffnet ltubguid.pdf, die Hinweise für Autorinnen und Autoren. Wer also etwas über TeX aufschreiben und veröffentlichen möchte, hat das Satzwerkzeug dafür bereits installiert.

Die TeX-Welt wird auch von länderweise organisierten Anwendergruppen getragen. Die offizielle TeX-Live-Anleitung dankt in ihren Acknowledgements der TUG, dem deutschsprachigen DANTE e.V., dem niederländischen NTG und dem polnischen GUST für die notwendige technische und administrative Infrastruktur, fügt „bitte treten Sie der TeX-Anwendergruppe in Ihrer Nähe bei“ hinzu und verweist auf tug.org/usergroups.html. Auch die spanischsprachige Gruppe CervanTeX steuert TeX Live eine FAQ bei; tlmgr info es-tex-faq bestätigt es. Im japanischen Sprachraum pflegt die Japanese TeX Development Community (texjporg) pLaTeX und upLaTeX, jsclasses (ursprünglich von Haruhiko Okumura), die japanische Unterstützung in dvipdfmx sowie gentombow und ptex2pdf und betreibt das TeX Wiki (texwiki.texjp.org); Okumuras TeX-Forum (okumuralab.org/tex/) ist die faktische Anlaufstelle für Fragen auf Japanisch. Daneben stehen das latex.org-Forum, die Mailingliste [email protected] und r/LaTeX auf Reddit.

Steht fest, dass es sich nicht um eine Frage handelt, sondern um einen Fehler, ändert sich das Ziel. Ein paketspezifischer Fehler gehört in die Fehlerverfolgung der Autorin oder des Autors – und die Adresse muss man nicht suchen, sie liegt bereits auf der eigenen Maschine. Enthält die Ausgabe von tlmgr info <Paket> eine Zeile cat-contact-bugs oder cat-contact-repository, ist das die offizielle Meldestelle (tlmgr info mwe etwa liefert eine GitHub-Issues-Seite). Ein Fehler in LaTeX selbst, also im Kern, geht an das LaTeX Project (latex-project.org), und dafür gibt es das Paket latexbug. Es dient der Einordnung von Fehlern, und das LaTeX-Team bittet darum, es in jeder Testdatei zu laden, die einem Fehlerbericht beiliegt: Das Laden entscheidet, ob der Fehler wirklich zum Kern gehört oder zu einem fremden Paket. Ein an die falsche Stelle geschickter Bericht kommt nirgends an.

Wie eine Frage aussieht, die beantwortet wird

Vier Dinge genügen: eine kurze Beschreibung des Symptoms, das MWE, die wörtliche Fehlermeldung und das bereits Versuchte. In dem genannten Heftchen rät Talbot, die Beschreibung knapp zu halten, die zur Eingrenzung unternommenen Versuche aufzuzählen und sich nicht in eine lange Schilderung des eigenen Projekts zu verlieren – zu viel Information schreckt vom Lesen ab. Sie spricht außerdem eine leicht vergessene Voraussetzung aus: niemand wird bezahlt und niemand ist verpflichtet zu antworten, weshalb eine Anfrage nicht wie eine Forderung oder ein Vorwurf klingen sollte. Dass dieser Rat 2014 geschrieben wurde und unverändert in TeX Live mitreist, sagt einiges über das Klima dieser Community. Eine Ergänzung: Auch das eigentliche Ziel gehört hingeschrieben. Wer nur den gescheiterten Weg zu sehen bekommt, kann den einfacheren nicht vorschlagen.