Auf dieser Seite

Guidedog / Dokumentation 0.2.0

Fehlermeldungen

Eine Diagnose soll das Problem benennen, seinen Ort zeigen und einen hilfreichen nächsten Schritt nennen. Guidedog speichert diese Angaben als strukturierte Daten. Das Terminal ergänzt Farben und Quellmarkierungen. JSON enthält die Daten ohne Terminalgestaltung.

Diagnosen lesen

UNDEFINED SUBSTITUTION                              rst.substitution.undefined

  guide/page.rst:4: See |logo| here.
                        ^^^^^^

The substitution "|logo|" is not defined.
No output was written.

Add a definition, e.g. ".. |name| replace:: text".

Eine Diagnose hat vier Teile, stets in dieser Reihenfolge:

1. Die Titelzeile. Der Titel nennt die Problemart in Großbuchstaben; Warnungen und Hinweise beginnen mit WARNING: und NOTE:. Rechts steht der Diagnosecode, etwa rst.substitution.undefined: ein stabiler Name für die Suche.
2. Der Ort. Datei und Zeile, die Quellzeile selbst und eine Markierung unter der betroffenen Stelle. Probleme ohne bestimmte Zeile, etwa ein fehlender Ordner oder eine Option, zeigen nur den Pfad oder keine Ortsangabe.
3. Was passiert ist. Die Erklärung und bei Bedarf die Folge für die Ausgabe: hier, dass nichts geschrieben wurde.
4. Was zu tun ist. Der Hinweis erscheint im Farbterminal grün und nennt eine konkrete Handlung. Bei mehreren Lösungen wird die wahrscheinlichste zuerst genannt.

Farben unterstreichen nur, was der Text bereits sagt. --color=never schaltet sie ab, --color=always behält sie auch außerhalb eines Terminals bei.

Jeder Hinweis zeigt einen nächsten Schritt

Guidedog verlangt dies auch von eigenen Meldungen: Ein Hinweis beginnt mit einer Handlung („Add“, „Pass“, „Set“, „Rename“, „Run“) und nennt deren Ziel, etwa --budget=MIB, root_doc in conf.toml oder eine Direktivenoption. tests/hints_test.odin prüft alle möglichen Meldungen und verwirft leere Hinweise, Wiederholungen sowie „report this“ ohne benötigte Angaben. Zulässig sind auch Vorschläge, die die Korrektur benennen („Did you mean numfig?“), und handlungsfreie Anmerkungen mit „Nothing to do:“ samt Begründung.

Liegt der Fehler bei Guidedog, sagt der Hinweis dies ausdrücklich und bittet um eine Meldung mit Befehl, auslösendem Input und Ausgabe von guidedog --version.

Diagnosen für Programme

--diagnostics=json schreibt jeden Bericht als ein JSON-Objekt je Zeile auf die Standardfehlerausgabe, für Editoren und kontinuierliche Integration:

{"schema":1,"code":"rst.substitution.undefined","severity":"error",
 "title":"UNDEFINED SUBSTITUTION","message":"The substitution \"|logo|\" is not defined.",
 "hint":"Add a definition, e.g. \".. |name| replace:: text\".","path":"guide/page.rst",
 "line":4,"column":5,"end_line":4,"end_column":11,"source":"See |logo| here.",
 "category":""}

Hier ist die Ausgabe umbrochen; jedes Objekt steht tatsächlich in einer Zeile. schema bezeichnet die Formatversion und ändert sich nur mit den Feldern. Prüfen Sie sie zuerst. Spalten zählen Unicode-Skalare ab 1, keine Bytes oder Terminalzellen. source enthält die ganze ursprüngliche Zeile. Das Terminal zeigt einen begrenzten Ausschnitt und richtet den Marker nach dem Escapen von Steuerzeichen und Messen breiter Zeichen aus. category ist die Kategorie aus suppress_warnings oder leer.

Wenn der Speicher nicht reicht

Speichermangel führt ebenfalls zu einer Diagnose, nie zu einem Absturz. Es gibt zwei Fälle:

host.budget (SPEICHERBUDGET ERREICHT)

Der Build erreicht sein Speicherbudget (--budget=MIB, Standard 1 GiB). Der Bericht nennt den Schritt und bei Vorlagen die anfordernde Zeile. Im Terminal fragt er einmal: Budget erhöhen, Arbeitsspeicher auf Platte verwenden oder stoppen. Andernfalls stoppt er. --budget oder --memory=disk legt die Wahl vorab fest. Der Hinweis nennt dasselbe Budget als Zahl, etwa:

Build again with --budget=256, or with --memory=disk to keep working memory on
disk (slower); or split the work into smaller files.

Der Vorschlag umfasst den belegten Speicher plus das Vierfache der abgelehnten Anforderung (der Schritt hält auch Ausgabe und Schreibkopie) oder das doppelte alte Budget, je nachdem, was größer ist. Er wird auf 64 MiB aufgerundet. Passt der Schritt in den freien Speicher, überschreitet er diesen nicht. Andernfalls nennt der Hinweis das und empfiehlt zuerst --memory=disk:

Build again with --memory=disk to keep working memory on disk (slower): the step
needs a budget of about 1408 MiB, more than the 900 MiB this machine has free. Or
free that memory and build with --budget=1408, or split the document.

host.memory (SPEICHER ERSCHÖPFT)

Das System verweigert eine vom Budget erlaubte Anforderung. Der Befehl stoppt ohne diesen Speicher: Ein Build veröffentlicht nichts, eine GDS-Änderung erfolgt ganz oder gar nicht, convert schreibt eine ganze Seite oder keine. Geben Sie Speicher frei oder verringern Sie die Threads (-j 1) und wiederholen Sie den Befehl. Nach dem Veröffentlichungsbeschluss braucht der Ausgabewechsel keinen Speicher; eine Ablehnung kann ihn nicht halbwegs stoppen. Fehlt Speicher zur Planung einer früheren offenen Veröffentlichung, bleibt sie für den nächsten Build bestehen.

Beide enden mit Status 3.

Exit-Status

Jeder Befehl endet mit einem dieser Statuswerte, damit Skripte Fehlerarten unterscheiden können:

Status	Bedeutung
0	Erfolg. Die Ausgabe wurde geschrieben und bei einem Build veröffentlicht.
1	Problem im Input: Dokumentfehler, Ablehnung durch Richtlinien (Raw-Inhalt ohne --raw), unlesbares Dokument oder eine durch -W bzw. --strict als Fehler behandelte Warnung.
2	Falscher Befehlsaufruf: unbekannte Option oder unbekannter Befehl, fehlender oder ungültiger Wert oder ungültige Einstellung in conf.toml bzw. -D.
3	Eine Grenze wurde erreicht: Speicherbudget (--budget), Verschachtelungstiefe (--max-depth), Knotenzahl (--max-nodes), Stack (--stack-kib), zu große Quelle oder fehlender Systemspeicher.
4	Eine Datei oder ein externes Programm ist fehlgeschlagen: nicht lesbarer oder beschreibbarer Pfad, während des Lesens geänderte Datei oder Typst, das nicht startet oder beendet wird.
5	Guidedog ist intern fehlgeschlagen; die Diagnose bittet um eine Fehlermeldung.
70	Bei einem Absturz zeigt Guidedog GUIDEDOG CRASHED (internal error), den Befehl, den Fehler und die Ausgabe von guidedog --version. Als Meldestelle nennt es den Issue-Tracker des Builds oder dessen Anbieter. Da erst am Ende veröffentlicht wird, bleibt die vorherige Ausgabe erhalten.
130	Der Befehl wurde mit Strg+C unterbrochen; veröffentlichte Dateien blieben unverändert.

Ein aus beliebigem Grund fehlgeschlagener Build belässt die vorige Ausgabe und die Build-Aufzeichnungen unverändert. Beheben Sie das Problem und bauen Sie erneut.