Dieses Dokument entstand aus dem Bedürfnis heraus, für Neuankömmlinge in der Newsgroup de.comp.text.tex eine Beispielsammlung zu schaffen, die das Prinzip des Minimalbeispiels erläutert. Der Text ist Public Domain, die Version für die Newsgroup wird momentan von Christian Faulhammer gepflegt und in der regelmässig veröffentlichten Einführung erwähnt. Korrekturen, Änderungswünsche und Kommentare bitte an christian(at)faulhammer.org senden.
Wer ausführliche Informationen zur Interpretation von Fehlermeldungen haben möchte, sollte einen Blick in den „LATE X Companion“ werfen, der aber für Anfänger nicht direkt geeignet ist.
Danken möchte ich allen Teilnehmern der Newsgroup, die immer wieder darauf hinweisen, wie wichtig ein Minimalbeispiel ist und wertvolle Hinweise zum Erstellen desselben liefern. Speziell möchte ich Ulrich Schwarz für die Übersetzung ins Englische, Hilmar Preuße für die erste LATE X-Version und Kurt Lidwin für das Überarbeiten derselbigen erwähnen.
Das Erstellen eines Minimalbeispiels ist eine Methode zur Fehlererkennung und -behebung, sowie zum Bestimmen der Ursache eines bestimmten Verhaltens. Minimalbeispiele müssen möglichst klein und lauffähig sein, d.h. sie besitzen den Grundaufbau eines LATE X-Dokuments und sind ohne Ergänzen von Elementen ausführbar.
Das Minimalbeispiel muss vollständig und lauffähig sein, damit
der Fragende nicht aus Unkenntnis, Informationen, die für die Diagnose wichtig sind, weglassen kann,
der Antwortende das Beispiel einfach per Kopieren und Einfügen übertragen und ausprobieren kann.
Das Minimalbeispiel muss klein sein,
damit der Antwortende sich nicht durch viele, irrelevante Codezeilen arbeiten muss,
weil dadurch die möglichen Fehlerquellen eingegrenzt werden,
weil man kurze Beispiele gut per E-Mail verschicken oder in Newsgroups veröffentlichen kann,
weil sich viele Probleme, wie fehlende Klammern, falsche Syntax, vergessene Schriftumschaltbefehle usw., während der Minimierung von selbst erledigen,
weil man bei kleinen Dokumenten nicht so schnell den Überblick verliert.
Selbst Anfänger sollten mit dem Erstellen keine Probleme haben, da hierfür nur ein wenig Geduld und schematisches Vorgehen mit gesundem Menschenverstand nötig sind. Meistens findet man das Problem selbst und spart sich die Frage in de.comp.text.tex schlichtweg. Nach dieser kurzen Erläuterung kommt dann eine Auflistung der Werkzeuge, gefolgt von einigen Beispielen. Dabei werden verschiedene Problemquellen (fehlerhafte Paketoptionen, Paketkombinationen, Syntaxfehler etc.) separat behandelt. Bei komplexeren Fällen sind natürlich alle Schritte gleichzeitig auf das Dokument anzuwenden.
Um ein Minimalbeispiel zu erstellen, gilt vor allem ein Prinzip: Teilen und (besser be-)herrschen. Teilen kann man auf verschiedene Arten, auch abhängig von der Struktur des Dokuments. Zuerst sollte auch der Befehl \listfiles in das Dokument aufgenommen werden, damit alle verwendeten Dateien (Pakete, Klassen etc.) inklusive Versionsnummer in der Log-Datei auftauchen. Diese Informationen können für die Antwortenden wichtig sein und sollten nicht fehlen.
Für das „richtige Leben“ gilt immer: Backup anfertigen und dann an einer Kopie arbeiten, um nicht eventuell wichtiges Material zu vernichten!
Da LATE X grundsätzlich beim ersten vorkommenden Befehl \end{document} aufhört, die eventuell danach folgenden Zeilen zu interpretieren, eignet sich das Vorziehen dieses Befehls sehr gut zur Fehlersuche.
Ist der gesamte Quelltext auf eine Datei konzentriert, ist folgendes sinnvoll. Geschicktes Verschieben des Befehls \end{document} in Richtung Beginn des Textes hilft, das Problem grob einzukreisen. Dabei bewegen wir uns blockweise nach oben. Damit sind logische Blöcke gemeint, also Absätze, Umgebungen (gekennzeichnet durch \begin und \end) usw. Durch das Verschieben bleibt der Originaltext erhalten, wir müssen nur immer eine einzige Zeile einfügen (und jedesmal übersetzen lassen). So bekommt man einen Anhaltspunkt, in welchem Block der Fehler liegt. Nun noch alles von \begin{document} bis zum Beginn des gefundenen Blocks löschen; tritt der Fehler dann immer noch auf, liegt das Problem genau dort.
Im Grunde ist das Vorgehen analog, nur dass man in einer Quelldatei, die mit Hilfe von \input eingebunden wird, das Ende durch \endinput gekennzeichnet wird. Zuerst sollte man aber die Teile identifizieren, die verantwortlich sind, durch das schrittweise Auskommentieren der \input- und/oder \include-Befehle oder durch den Einsatz von \includeonly.
Wenn man den zuständigen Block gefunden hat, muss man es soweit vereinfachen, dass man sein Problem auf eine Zeile festnageln kann (darum drehen sich auch die Beispiele).
Es gibt Paketkombinationen, die sich nicht miteinander vertragen. Jetzt werden die Pakete wieder einzeln nach und nach herausgenommen. Damit dieser Test schnell durchgeführt werden kann, empfiehlt es sich, \usepackage so zu verwenden:
Einzelne Pakete werden durch ein einziges % (in der ersten Spalte) auskommentiert und deaktiviert. Sobald es keinen Fehler mehr gibt, nimmt man das zuletzt ausgeklammerte Paket wieder rein und fährt mit dem Nächsten fort.
Selbstdefinierte Befehle und Umgebungen sollten
einfach gelöscht werden, wenn sie im Restdokument nicht mehr verwendet werden
andernfalls „geleert“ werden, also einfach nur ein #1 (usw.) als zweites Argument haben oder nichts tun.
Auch dies sollte schrittweise erfolgen, falls der Fehler durch einen dieser Befehle verursacht wird.
Jetzt wenden wir im Grunde wieder „Verschieben des Endes“ an, nur nicht blockweise, sondern zeilenweise. Der Rest muss wohl nicht näher erläutert werden. Im Idealfall bleibt nur eine Zeile des Dokuments selber übrig, die man dann genauer untersuchen kann oder, wenn alle Stricke reißen, in de.comp.text.tex veröffentlichen kann (oder jeder anderen Hilfequelle). Das Lesen der Einführung ist dabei sowohl für Anfänger als auch Neulinge empfehlenswert.
Es gibt noch viele weitere Möglichkeiten, Bereiche auszuklammern, sei es mit dem comment-Paket, bedingten Anweisungen (if) u.ä.
Eingefügte Bilder sind fast immer problematisch. Eigentlich müsste man sie weitergeben; meist sind sie aber sehr groß und enthalten womöglich vertrauliche Informationen. Ein Ablegen auf dem eigenen Webspace ist damit auch nicht möglich. Was also tun? Ganz einfach, wir ersetzen das Bild schlichtweg durch ein Rechteck, das mit \rule erzeugt wird.
Manchmal ist es unumgänglich, dass zusätzliche Dateien angefügt werden müssen, z.B. eine kleine Literaturdatenbank. LATE X bietet eine einfache Möglichkeit, alles in eine Datei zu stecken und bei Bedarf die zusätzlichen Dateien mit einem bestimmten Inhalt zu erzeugen: Die filecontents-Umgebung.
Achtung! Die Zeilennummern sind nur zur Verdeutlichung da! Wie dargestellt sind die Beispiele nicht übersetzbar und lauffähig, deswegen bitte bei eigenen Versuchen weglassen.
Folgendes Beispiel ist eine einfache ausgerichtete Formel, die man auch mit Hilfe der eqnarray-Umgebung erstellen kann, aber das amsmath-Paket ist wesentlich leistungsfähiger.
Die Fehlermeldung lautet:
Obiges lässt vermuten, dass der Fehler in den Zeilen 6 bis 9 zu suchen ist. Also kommentiert man diese alle in der align-Umgebung aus.
Jetzt tritt der Fehler nicht mehr auf, man hat also zuviel entfernt, ein einzelnes Einfügen der Zeilen mit dauernden Testläufen zeigt, dass ab der Zeile 8 wieder eine fehlerrelevante Stelle dabei ist. Daraufhin nimmt man alles darüber bis \begin{align*} heraus (als Kommentar) und der Fehler tritt immer noch auf. Also löscht man jetzt die Zeilen und erhält ein minimales Beispiel, da das einzige Paket, das man lädt, überhaupt erst die Umgebung align zur Verfügung stellt.
Jetzt sucht man ein bisschen und sieht, dass man nach \mathrm{e^{} die schließende geschweifte Klammer vergessen hat (gute Editoren helfen dabei hervorragend). Es muss richtig heißen: \mathrm{e}^{}.
Nehmen wir mal an, der folgende Quelltext läge vor:
Nur stört der subjektiv zu kleine Abstand zwischen dem Bruch und dem Gleichheitszeichen, erzeugt durch Zeile 7. Dieses Problem möchte man den Leuten in de.comp.text.tex schildern, ist sich aber bewusst, dass das Beispiel alles andere als übersichtlich ist. Also beschränkt man das Beispiel auf das Wesentliche, dazu gehören in diesem Fall wohl die selbstdefinierten Befehle aus den Zeilen 3 und 4, das finden wir mit einem einfachen Testlauf heraus. Weg damit!
Auf die Richtigkeit der Mathematik kommt es ja nicht an. Trotz dieser Entschlackung ist das Dokument immer noch recht komplex (zumindest behaupten wir das mal, sonst hätte dieser Text keinen Sinn). Nötig ist wirklich nur Zeile 7 und von dieser auch nur der Anfang, also entfernen wir den Rest und vereinfachen die Schreibweise noch weiter.
Und wir haben ein minimales Beispiel, das genau das Problem zeigt ohne Ballast mit sich herum zu schleppen. Als Antwort könnte man dann einen Vorschlag wie den folgenden bekommen.
Dieses Beispiel dient vor allem dazu, wie man Dinge ersetzt, die man nicht auf einfache Weise in die Newsgroup als Text einbringen kann. Was das bedeuten soll? Ganz einfach: Wenn man Bilder einfügt, sind diese meist recht groß und können schlecht als Text in eine News gesetzt werden, da einige Server Binärnachrichten in Textgruppen (wie de.comp.text.tex eine ist) verbieten und filtern.
Man hat sich ein schönes kleines Dokument gebastelt, das ein Bild und ein wenig Text enthält, wir wollen noch ein bisschen Mathematik schreiben und haben deswegen einige Pakete eingebunden.
Zuerst einmal testen wir, ob es was mit den anderen Paketen zu tun haben könnte, die eingebunden werden. Ein Auskommentieren von Zeile 3 ändert aber nichts am Aussehen des Textes. Da keine Standardklasse zum Einsatz kommt, sondern ein Ersatz aus dem KOMA-Script-Paket, machen wir diese sehr empfehlenswerte Klasse verantwortlich. Ein Ersetzen von scrreprt durch report bringt aber keinerlei Verbesserung, wir lassen es aber in diesem Zustand, weil wir die Klasse „report“ auf jedem System erwarten können. Nun reduzieren wir noch das restliche Drumherum und kommen zu einem deutlich minimalerem Stand.
Aber im Grunde ist es nicht wirklich minimal. Flugs noch die Grafik entfernt und fertig ist unser endgültiges Minimalbeispiel.
Der Grund für einen Fehler kann auch außerhalb des LATE X-Quelltextes liegen. Sehen wir uns das ein wenig näher an.
Viele Leute werden eine der gebräuchlichen IDEs oder Editoren mit TE X-Unterstützung (Emacs, Kile, TE XnicCenter, WinEdt, um nur einige zu nennen) einsetzen. Damit können zum einen die Dateien bearbeitet werden, zum anderen hat man einfachen Zugriff auf LATE X und Konsorten (Tastenkürzel, Symbolleisten etc.). Aber manchmal verfahren sie sich in ihrem Versuch, dem Benutzer zu helfen: Entweder liegt Fehlkonfiguration vor, sie finden die Programme nicht, ihnen entgehen Fehlermeldungen oder sie sind einfach zu eingeschränkt in ihren Fähigkeiten. Es kann vorkommen, dass sie glauben, das Dokument liege im DIN A5-Papierformat vor, nur weil man \input{a5} für das Einfügen des fünften Anhangs benutzt. Wenn irgendwas schief geht und der TE X-Code ist mit Sicherheit korrekt, sollte man folgendes bedenken:
Rotationen, Grafiken oder Farben sind häufig ein Problem für Programme, die DVI-Dateien darstellen. Oft gibt es dabei Darstellungsprobleme. Wichtig ist die korrekte Ausgabe im PostScript- oder PDF-Format.
latex, pdflatex, bibtex und makeindex usw. sollten einmal von Hand auf der Kommandozeile aufgerufen werden. Manchmal versteckt der Editor einfach die Fehlermeldungen vor dem Benutzer. makeindex zeichnet sich durch das Erzeugen von schwer zu erkennenden Fehlern aus.
Und erkannt? Zwischen zwei LATE X-Läufen, die jeweils 120 Zeilen Ausgabe erzeugen wäre es sicherlich untergegangen. Jeden Schritt einzeln vorzunehmen, hilft die Ausgabe zu überprüfen, ohne dass man die Log-Dateien durchsehen muss, die meist sehr unübersichtlich sind.
Manchmal wird LATE X oder ein Paket durch den Inhalt der Hilfsdateien verwirrt. Als Beispiel das folgende:
Ohne tiefer einsteigen zu müssen, reicht es zu wissen, dass das Wort „foo“; in die aux-Datei geschrieben wird. Der erste Lauf wird klappen, der zweite nicht, da es nicht erlaubt ist, in die aux-Datei zu schreiben, wenn sie gerade gelesen wird. Das Abbrechen von latex (mit x) bewirkt kein Neuerstellen der aux-Datei und jeder weitere Lauf wird ebenso missglücken. Das ist komplett unabhängig davon wie die tex-Datei abgeändert wird!
Um nachzuvollziehen was passiert, kann man Klammern zählen: Wenn TE X eine Datei öffnet, wird (dateiname auf dem Bildschirm ausgegeben, und ) wenn diese Datei wieder geschlossen wird. In unserem Fall erhalten wir etwas wie
Man sieht, dass test.aux die letzte Datei ist, die geöffnet, aber nicht mehr geschlossen wird, also wird sich der Fehler dort finden (Ok, das wurde vorher schon verraten).
Natürlich kann man das auch einfacher lösen: Löschen der entsprechenden Datei. Endungen der häufigsten Hilfs-Dateien mit ihrem Zweck und Inhalt folgen (so dass man weiß, wie man sie nach dem Löschen neu erstellen kann).
aux: Label, Verweise, Literaturstellen, babel-Einstellungen, diverse andere Dinge. Herkunft: tex- oder ltx-Datei
toc, lof, lot: Inhalts-, Abbildungs- und Tabellenverzeichniss. Quelle: tex- or ltx-Datei
bbl: Literaturverzeichnis. Quelle: bib- und aux-Dateien mittels bibtex
ind, idx: Index. Quelle: ind aus idx mittels makeindex oder xindy, idx aus tex- oder ltx-Datei
gls, glo: Glossar. Analog zu ind und idx