PDA

Archiv verlassen und diese Seite im Standarddesign anzeigen : Tip: Fehlersuche



Xenara
10-12-2009, 09:55
Lieber Hilfe-Suchender,

hier findest Du eine kleine Anleitung, wie man Problemen auf die Spur kommt, die plötzlich und scheinbar ohne ersichtlichen Grund auftauchen.


"Fehlersuche in LaTeX" oder "Wie erstelle ich ein Minimalbeispiel?"

Wenn Du Dein Problem im Forum schilderst, sind Fehlerbeschreibungen im Stile von "Hilfe! Mein Dokument kompiliert einfach nicht mehr." nicht aussagekräftig genug, um Dir helfen zu können. Daher ist ein Codeausschnitt in Form eines Minimalbeispiels (http://www.minimalbeispiel.de) (MB) immer extrem hilfreich.

Hier deshalb eine kleine Anleitung, wie Du ein Minimalbeispiel selbst erstellen kannst, anhand dessen Dir dann im Forum geholfen werden kann:


Oft genug und richtig kompiliert?

Als erstes überprüfst Du: Hast Du das Dokument wirklich mehrmals kompiliert?
Denn beim 1. LaTeX-Lauf wird nur das Dokument einmal grob zusammengeschustert, im 2. erst werden Verzeichnisse (u.a. TOC), Verweise etc. erstellt. Und ab dem 3. gehts noch um schönere Zusammenstellung/Formatierung/Bildplatzierung und die absolut richtigen Seitenzahlen in den Verzeichnissen.
Wenn Du hier also sicher gehen willst, kompiliere 4x, dann ist von LaTeX aus alles fertig formatiere.
Solltest du ein Literaturverzeichnis mit BibTeX erstellen wollen, musst du auch mit bibtex kompilieren, und zwar in der Reihenfolge latex -> bibtex -> latex (ggf. dann mehrmals LaTeX).
Ähnliches gilt für die Erstellung von Stichwortverzeichnissen, Glossaren und Abkürzungsverzeichnissen: Hier muss meistens auch mit makeindex kompiliert werden - wie oft, in welcher Reihenfolge und womit genau (wenn überhaupt), entnimmst du den Dokumentationen zum jeweiligen Paket, mit dem du das entsprechende Verzeichnis erstellen willst.

Überprüfe, _wie_ du komplierst: Mit pdflatex (also direkt von .tex nach .pdf) oder mit dvips (von .tex nach .dvi nach .ps nach .pdf)? Je nachdem kann es Probleme mit Bildern geben, da pdflatex zwar .png und .jpg akzeptiert, dvips jedoch nicht.


Von LaTeX erzeugte Dateien gelöscht?

Manchmal verhindern die von LaTeX selbst erzeugten Dateien wie .aux, .bbl, .toc das korrekte Kompilieren, wenn man eigentlich einen Fehler im .tex behoben hat, er aber in diesen Dateien noch drin gespeichert ist.
Die Dateien werden im gleichen Ordner wie das Hauptdokument erstellt und können einfach gelöscht werden.
Wenn Du unsicher bist, lege einen neuen Ordner (z.B. "MyTrash") an und verschiebe die Dateien dorthin, dann kannst Du sie einfach zurückholen, falls Du versehentlich etwa eine .tex, .bib-Datei oder - je nach Editor - die Projektverwaltungsdatei "gelöscht" bzw. dorthin verschoben hast.

Wenn die von LaTeX erzeugten Dateien gelöscht wurden, sind je nach Dokument wieder mehrere Kompilierungsvorgänge nötig, um sie wieder zu erzeugen.
Wenn die Fehlerquelle im Hauptcode bisher nicht behoben wurde, so ist es gut möglich, dass der Fehler erst nach dem zweiten LaTeX-Lauf wieder da ist. Dann musst Du weiter auf Fehlersuche gehen, am Besten über ein Minimalbeispiel wie unten beschrieben.


Reihenfolge der Pakete überprüft?

Manchmal liegen Fehler an der Reihenfolge, in der die Pakete im Header stehen.
Genaue Informationen, ob eine bestimmte Reihenfolge relevant ist, finden sich in den Dokumentationen der Pakete.

So muss etwa das häufig verwendete Paket "hyperref" in 95% der Fälle als allerletztes Paket geladen werden. Ausnahmen davon, also Pakete, welche nach "hyperref" zu laden sind, sind das Paket "glossaries", sowie die in der README von "hyperref" beschriebenen Pakete.



Wenn Du diese Punkte getestet hast und das Problem noch besteht, machst Du folgendermassen weiter:


Vom Dokument zum Minimalbeispiel - Variante 1

0. Backup: Arbeite nie auf Deinem Originaldokument, sondern immer nur auf einer Kopie!
Z.B. nimm den ganzen Projektordner wie er ist und packe eine Kopie davon in einen zip-Ordner oder, wenn es nur eine einzelne Datei ist, kopiere diese und arbeite im Folgenden nur noch mit der Kopie weiter. So hast Du das Original auf jeden Fall noch sicher und Du ersparst Dir einige Wutanfälle und Nervenzusammenbrüche.

1. Erstelle eine neue, leere .tex-Datei.

2. Kopiere folgendes dorthin:



\documentclass{article}

\begin{document}
Test
\end{document}


3. Kompiliere dieses Mini-Minimalbeispiel mit pdflatex. Läuft das?

4. Wenn ja, dann kopiere nach und nach den Code aus der alten Datei ins neue Dokument.
Eine mögliche Vorgehensweise: Fange zunächst mit Documentclass, Paketen, Inputs etc., was vor \begin{document} (der "Präambel") ist, es steht also immernoch nur "Test" im Body (das ist der Inhalt, also alles zwischen \begin{document} und \end{document}). Nach _jedem_ Paket, input oder sonstiger Änderung der Präambel kompilierst Du und überprüfst, ob es noch ohne Fehler läuft (Warnungen erstmal weitestgehend ignorieren).

5. Wenn die gesamte Präambel drin ist und das Dokument dann noch läuft, machst Du mit dem Body weiter. Dabei gehst Du genauso vor wie bei der Präambel. Nach _jedem_ input, Bild oder Textabschnitt kompilierst Du und überprüfst wieder, ob es läuft.
Dazu musst Du natürlich sicherstellen, dass LaTeX eventuelle Inputs/Bilder etc. auch findet.
Und wenn es um Probleme mit dem Inhaltsverzeichnis oder anderen Verzeichnissen geht, kompilierst Du nach jedem Einfügen eines Teils jeweils 2x, da die Verzeichnisse ja erst beim 2. Lauf aktualisiert werden (s.o.).

6. Falls Du input- oder include-Dateien verwendest: Tritt der Fehler auch auf, wenn Du die ausgelagerten Textteile direkt ins Hauptdokument einbindest?
Wenn ja, steckt irgendwo in diesem Code ein Fehler. Kommentiere nach und nach aus, um der problematischen Stelle auf die Spur zu kommen.
Wenn nein, ist möglicherweise die Einbindung über input/include schuld. Verwende dann für das problematische input/include die filecontents-Umgebung (s.u.).


Vom Dokument zum Minimalbeispiel - Variante 2

Hier gehtst Du quasi andersherum vor wie in Variante 1:

Du arbeitest wieder nur auf einer Kopie deines Dokuments (Backup!).
Kommentiere nach und nach alles aus dem Dokument aus. Dabei fängst Du mit Input-Dateien und Bildern an und kontrollierst, ob und wann ein Fehler _nicht_ mehr auftaucht. Hier musst Du natürlich ebenfalls nach jedem Schritt kompilieren.


Mit so einer Vorgehensweise solltest Du das Problem schon sehr gut eingrenzen können.
Wenn dann klar ist, wo in etwa der Haken ist, kannst Du das Problem im Idealfall bereits selbst lösen.

Wenn nicht:
Dann kopierst Du den Code nochmal in ein neues Dokument. Dort fängst Du nochmal an mit auskommentieren von Zeilen im Body, bis nur noch der Fehler übrig ist. Danach gehst du in den Header und kommentierst nach und nach die Pakete aus, bis nur noch die übrig sind, die wirklich zum Reproduzieren des Fehlers nötig sind.
Dann löschst Du alles, was auskommentiert ist. Der Rest ist dann dein Minimalcode oder Minimalbeispiel.


Hinweise und Tipps

a) Bilder:
Wenn Du Bilder eingefügt hast, ist es nicht nötig, das eigene Bild mit anzuhängen (Ausnahme s.u.).
Um trotzdem den normalen \includegraphics{Bild}-Aufruf im Minimalbeispiel lassen zu können, verwendest Du die Option "demo" des Pakets "graphicx":


...
\usepackage[demo]{graphicx}
...
\begin{document}
\includegraphics[Optionen]{Bild}
\end{document}

Wenn Du zwar \includegraphics verwenden kannst, aber \usepackage{graphicx} gar nicht in der Prämbel stehen hast, wird bereits anderweitig geladen (z.B. der Dokumentenklasse "beamer"). Dann kannst Du die Option mit "\PassOptionsToPackage{demo}{graphicx}" übergeben:


\PassOptionsToPackage{demo}{graphicx}
\documentclass{...}
...
\begin{document}
\includegraphics[Optionen]{Bild}
\end{document}

Mit der "demo"-Optionen werden nur absolute Skalierungen berücksichtigt.
Beispiel:


a) \includegraphics[width=2cm]{Dein-Bild}
b) \includegraphics[scale=.5]{Dein-Bild}

a) Hier wäre das Bild mit [width=2cm] dann 2cm breit, aber die Höhe hat keinen Bezug zur Höhe Deines Originalbildes.
b) Bei [scale=.5] wird ein interner Bezug gewählt, der nichts mit Deinem Originalbild zu tun hat.

Wenn es Dir auf genauen Maße ankommt, kannst du statt \includegraphics[Optionen]{Dein-Bild} mit \rule{x}{y} einen schwarzen Kasten einfügen:


\begin{figure}[htbp]
%\includegraphics[Optionen]{Bild}
\rule{3cm}{2cm}
\caption{Caption}
\label{label}
\end{figure}


_Nur_ wenn der Fehler definitiv mit dem Bild zu tun hat, lädst Du es als Extra-Datei mit hoch und beschreibst kurz, wie das Bild erstellt wurde.


b) Andere Dateien, auf die im Dokument zugegriffen wird:
Wenn Du in Deinem Beispiel auf weitere Dateien zugreifen musst (häufig ist das eine .bib-Datei, die als Literaturverzeichnis dient), kannst Du den relevanten Teil dieser Dateien mittels einer filecontents-Umgebung zum Teil deines Beispiels machen und so potentiellen Helfern einige Arbeit ersparen. Das, was im filecontents steht, wird als separate Datei automatisch aus dem LaTeX-Lauf heraus erzeugt, also etwa eine Datei "dateiname.bib", aber auch „dateiname.tex“ o.ä., die dann im Dokument verwendet werden können. Es sind auch mehrere filecontents-Umgebungen nacheinander möglich. Der Code dafür sieht so aus (einzufügen irgendwo in der Präambel zwischen \documentclass{...} und \begin{document}):



\usepackage{filecontents} % Ein- oder Auskommentieren, siehe Hinweis unten
\begin{filecontents}{dateiname.bib}
(Inhalt der Datei)
\end{filecontents}


Zu \usepackage{filecontents}:

- Beim Weglassen/Auskommentieren von \usepackage{filecontents} wird die Datei nur erstellt - so sie noch nicht vorhanden ist - aber nie geändert (auch nicht in den weiteren Läufen von LaTeX). Änderungen kommen nur zum Tragen, wenn die Datei neu erstellt wird. Dazu musst Du also Du die Datei, z.B. "dateiname.bib", erst aus dem Verzeichnis löschen (etwa manuell im Explorer).

- Laden/Einkommentieren von \usepackage{filecontents} sorgt dafür, dass eine Datei "dateiname.bib" entweder erstellt, oder - wenn sie bereits vorhanden ist - überschrieben wird.
Warnung: Es wird also durchaus auch Deine einzige, originale, alles umfassende Literatursammlung überschrieben, wenn sie den gleichen Dateinamen hat wie die filecontents-Datei. Da hilft dann nur noch das Backup.


c) Manche Probleme können verschiedenen Paketversionen oder veralteten Installationen liegen. Um herauszufinden, welche Versionen und Pakete gerade verwendet werden, stellt man den Befehl "\listfiles" ganz an den Anfang des Headers noch _vor_ \documentclass{...}. Dies ergibt im .log-File dann eine Liste der Pakete, die mit "*File List*" beginnt.



Wichtig: Wie kommts ins Forum?

Das soweit fertige MB kompilierst Du und überprüfst, ob das Ergebnis (z.B. die Fehlermeldung) tatsächlich noch das gleiche ist wie beim Ausgangsdokument.
Dann stellst Du exakt diesen Code als Minimalbeispiel mit einer kurzen, aussagekräftigen Erklärung hier ins Forum.

Wenn das .log-File wichtig ist, dann stellst Du es mit ein, und zwar genau das .log-File, das sich bei Dir ergibt, wenn Du das Minimalbeispiel kompilierst, welches Du im Posting verwendest.

Beim Posten bitte die korrekte Code-Umgebung verwenden, entweder über das #-Symbol in der Formatierungsleiste für die Forenbeiträge oder über [ CODE ]...[ /CODE ] (ohne Leerzeichen!), dann kommt der Code auch richtig im Forum an.



Fortsetzung in Post #2!

Xenara
11-10-2010, 14:46
Fortsetzung von Post #1!

Wieso der ganze Aufwand?

Keiner ausser Dir als Fragesteller kennt das Dokument. Viele Einstellungen, Pakete, Formatierungen etc. beeinflussen sich gegenseitig und es ist ebenso wichtig zu wissen, wie Du eine bestimmte Stelle eingegeben hast (z.B. eine table-Umgebung). Daher muss man unbedingt wissen, wie der genaue Aufbau bei Deinem konkreten Fall ist, der das Problem verursacht.

Und, was ganz wichtig ist: Mit einem MB machst Du es den Helfern einfach: Sie müssen nur kurz den Code kopieren und können das Problem nachvollziehen und im besten Fall gleich beheben. So ist die Hemmschwelle zum Helfen sehr gering, und oft sind es nur Kleinigkeiten, wie etwa ein vergessenes "&" in einer Tabelle.
Aber wenn ein Hilfs-Williger erstmal anfangen muss, selbst das Problem herstellen müssen, dann ist das sehr mühsam und macht absolut keinen Spass.
Ausserdem entsteht dann ganz schnell der Eindruck, dass der Fragesteller einfach zu faul war, sein Problem selbst anzugehen.

Also: Mit einem schicken kleinen MB lässt sich ein Problem (nahezu) immer beheben. :)

Viel Spass beim Basteln,
Xenara
mit Hilfe von bischi, lockstep, Hobbes, rais, voss und sommerfee

Diskussion zu diesem Post (http://www.mrunix.de/forums/showthread.php?t=67140)


22.12.2009: Beitrag aus einem Thread heraus hier hin kopiert. Ich hoffe, das ist für dich so ok :D (siehe PM).
22.12.2009, 12:15: Beitrag darf gerne stehenbleiben. Habe die Formulierungen im Beitrag überarbeitet, so dass er allgemeiner gilt.
22.12.2009, 14:11: Überschriften formatiert und Kleinigkeiten umformuliert .
25.12.2009: Anmerkungen von lockstep und Hobbes eingebaut, gesamten Artikel auf "Du"-Anrede umgestellt und einige Formulierungen überarbeitet.
16.01.2010: Separater Diskussionsthread.
[Edit: Xenara] 18.01.2010: Problematik der verschiedenen Kompilierungsmöglichkeiten (dvips, bibtex) eingefügt.
[Edit: Xenara] 19.01.2010: Hinweis c, filelist eingefügt.
[Edit: Xenara] 03.03.2010: Absatz "Von LaTeX erzeugte Dateien gelöscht?" eingefügt.
[Edit: Xenara] 14.03.2010: "Vom Dokument zum Minimalbeispiel - Variante 1" -> Absatz 6. zu input/include eingefügt.
[Edit: Xenara] 16.03.2010: "Wichtig: Wie kommts ins Forum?" -> Neue Überschrift, explizit .log-File mit aufgenommen.
[Edit: Xenara] 30.03.2010: Empfehlung, ein Backup zu machen, umformuliert und verstärkt. Ausserdem Hinweis zu Filecontents-Umgebung eingefügt, dass wenn \usepackage{filecontents} geladen wird, die Datei überschrieben wird.
[Edit: Xenara] 01.04.2010: Hinweis zum Kompilieren bei der Erstellung von Verzeichnissen mit makeindex nach locksteps' Vorschlag eingefügt.
[Edit: Xenara] 04.04.2010: Hinweis zum Kompilieren bei der Erstellung von Verzeichnissen mit makeindex nach rais' Vorschlag abgeändert.
[Edit: Xenara] 23.06.2010 "Hinweise" -> "Reihenfolge der Pakete überprüft?" neu eingefügt.
[Edit: Xenara] 10.09.2010 "Hinweise und Tipps a) Bilder" -> Hinweis auf Option "demo" des graphicx-Pakets eingefügt.
[Edit: Xenara] 11.10.2010 Rechtschreibfehlerchen korrigiert, Hinweis auf die Code-Umgebung im Forum eingefügt und etwas deutlicher auf das Löschen von Paketen eingegangen.