Die Handbücher, die ich für Kunden erstelle, unterliegen NDAs, deshalb zeigt dieser Beitrag denselben Prozess an öffentlichem Material. Ich habe ein dichtes Kapitel echter technischer Dokumentation genommen, Kapitel 3 von DocBook 5.2: The Definitive Guide von Norman Walsh (XML Press, frei verfügbar auf tdg.docbook.org), und es so umstrukturiert, wie ich eine Handbuch-Überarbeitung angehe.
Was die Überarbeitung leistet
- Verdichtet den Konzepttext zu einer erfassbaren Übersicht mit einer Zusammenfassung auf einen Blick
- Hebt den ID/IDREF-Hinweis aus einer Absatz-Nebenbemerkung in einen Callout
- Wandelt die Werkzeugübersicht in eine Vergleichstabelle mit kopierbarem Befehl um
- Baut die drei Fehlerbeispiele als Symptom-Ursache-Lösung-Referenz neu auf
- Kondensiert die Codelistings; der technische Inhalt bleibt unverändert
Das überarbeitete Kapitel
DocBook-Dokumente validieren
Ein DocBook-Dokument ist nur dann DocBook, wenn es validiert. Die Validierung prüft die exakte Reihenfolge und Verschachtelung jedes Elements gegen das Schema. Dieses Kapitel behandelt, was die Validierung erzwingt, welche Werkzeuge sich eignen und wie man die Fehlermeldungen liest, wenn ein Dokument scheitert.
Auf einen Blick
Die Validierung läuft nach dem Parsen: Das Dokument muss bereits wohlgeformtes XML sein.
Modernes DocBook (V5.x) wird durch RELAX NG + Schematron definiert, nicht durch eine DTD.
Frühes Validieren während des Schreibens verhindert fehlerhafte Ausgaben weiter unten im Prozess.
Was die Validierung prüft
Das DocBook-Schema ist eine präzise Beschreibung gültiger Verschachtelung: welche Elemente vorkommen dürfen, in welcher Reihenfolge und mit welchem Inhalt. Ein validierender Parser vergleicht Ihr Dokument mit dieser Beschreibung und meldet jede Stelle, an der es abweicht.
DocBook V5.x wird durch eine RELAX-NG-Grammatik plus Schematron-Regeln definiert. Die ältere DTD existiert noch, erzwingt aber die meisten DocBook-Beschränkungen nicht mehr, validieren Sie deshalb mit einem externen RELAX-NG-/Schematron-Validator.
ID/IDREF-Hinweis
Querverweise nutzen xml:id (ID) und linkend (IDREF). Jede ID muss eindeutig sein, und jede IDREF muss auf eine existierende ID zeigen. Diese Prüfungen gehören nicht zum RELAX-NG-Kern: Die DTD-Kompatibilitätserweiterungen, die sie ergänzen, vertragen sich schlecht mit der DocBook-Grammatik. Deaktivieren Sie entweder diese Prüfungen, ignorieren Sie ihre Warnungen, oder erzwingen Sie die Beschränkungen mit Schematron.
Einen Validator wählen
| Werkzeug | Typ | Hinweise |
|---|---|---|
| <oXygen/> XML Editor | Integriert | RELAX NG + Schematron während des Tippens |
| XMLmind | Integriert | RELAX NG + Schematron |
| Emacs (nxml-mode) | Integriert | RELAX NG während des Tippens |
| Jing | Eigenständig | Kommandozeilen-RELAX-NG + Schematron |
| MSV | Eigenständig | RELAX NG; ausführliche, informative Fehlermeldungen |
| NVDL-fähige Werkzeuge | Dispatch | Vereinfacht Dokumente mit mehreren Namensräumen (SVG, MathML in DocBook) |
MSV von der Kommandozeile ausführen:
java -jar msv.jar docbook.rng document.xmlValidator-Fehler lesen
Jeder Validator formuliert Fehler anders, aber die meisten nennen die Stelle, an der das Parsen brach, und was erwartet wurde. Diese Stelle ist das Symptom, nicht immer die Ursache. Drei wiederkehrende Muster:
| Validator-Meldung | Wahrscheinliche Ursache | Tatsächliche Lösung |
|---|---|---|
unexpected character literal | Zeichendaten stehen dort, wo nur Elemente erlaubt sind, typischerweise weil ein Wrapper-Element oder End-Tag fehlt | Den Text in ein Blockelement wie para einbetten oder das fehlende </para> wiederherstellen |
tag name "paar" is not allowed | Ein falsch geschriebenes Start-Tag oder der falsche Namensraum | Die Schreibweise mit der Liste erlaubter Namen abgleichen. Ergibt der Tippfehler zufällig ein anderes gültiges Element, kann der Fehler andernorts als Kontextfehler auftauchen |
| Validator schlägt ein unerwartetes Element zum Einfügen vor | Ein gültiges Tag im falschen Kontext | Der Validator fügt zur Wiederherstellung nur Elemente hinzu; er benennt nie eines um. Im Beispiel unten schlägt er nie formalpara vor, obwohl das Markup genau das brauchte |
Ein Beispiel: Ein title direkt innerhalb von para erzeugt:
<para><title>Paragraph With Inlines</title>
<emphasis role="bold">This</emphasis> paragraph contains...
</para>
Error at line:9, column:14 of context.xml
tag name "title" is not allowed. Possible tag names are: ...Die Lösung ist hier nicht das Einfügen, das der Validator vorschlägt: Der Autor wollte fast sicher formalpara, den Absatztyp, der einen title erlaubt. Die Meldung war präzise über wo es scheiterte, aber still über warum.
Kernaussage
Validator-Fehler beschreiben das Symptom, nicht die Diagnose. Lesen Sie zuerst das Element vor der gemeldeten Zeile, und behandeln Sie den vorgeschlagenen Fix als Hinweis, nicht als Anweisung.
Quelle
Umstrukturiert und verdichtet aus Kapitel 3, „Validating DocBook Documents”, DocBook 5.2: The Definitive Guide von Norman Walsh (XML Press). Das Originalkapitel lesen. Umstrukturierung, Tabellenaufbau und redaktionelle Entscheidungen stammen von mir; der technische Inhalt von Walsh.
