DocBook ist eine semantische Auszeichnungssprache für technische Dokumentation . Ursprünglich für die Erstellung technischer Dokumente im Zusammenhang mit Computerhardware und -software gedacht, kann sie aber auch für jede andere Art von Dokumentation verwendet werden. [ 1 ]

Als semantische Sprache ermöglicht DocBook die Erstellung von Dokumentinhalten in einer präsentationsneutralen Form , die die logische Struktur des Inhalts erfasst. Diese Inhalte lassen sich anschließend in verschiedenen Formaten veröffentlichen, darunter HTML , XHTML , EPUB , PDF , Manpages , WebHelp [ 2 ] und HTML-Hilfe , ohne dass Änderungen am Quellcode erforderlich sind. Mit anderen Worten: Ein im DocBook-Format verfasstes Dokument lässt sich problemlos in andere Formate übertragen, ohne dass es neu geschrieben werden muss.

Design

DocBook ist eine XML- Sprache. In der aktuellen Version (5.x) ist die DocBook-Sprache formal durch ein RELAX NG- Schema mit integrierten Schematron- Regeln definiert. (Es sind auch W3C XML Schema + Schematron- und DTD-Versionen ( Document Type Definition ) des Schemas verfügbar, diese gelten jedoch als nicht standardkonform.)

DocBook-Dokumente sind eine semantische Sprache, die nicht das Aussehen ihrer Inhalte beschreibt, sondern deren Bedeutung. Anstatt beispielsweise die visuelle Formatierung eines Abstracts zu erläutern, kennzeichnet DocBook einen bestimmten Abschnitt lediglich als Abstract. Die Entscheidung, wo genau das Abstract platziert wird, wie es aussieht oder ob es überhaupt in die endgültige Ausgabe aufgenommen wird, obliegt einem externen Verarbeitungstool oder einer Anwendung.

DocBook bietet eine Vielzahl semantischer Element-Tags. Diese sind in drei Hauptkategorien unterteilt: strukturelle, Block- und Inline-Tags.

Struktur- Tags legen allgemeine Merkmale ihrer Inhalte fest. Das bookElement `<book>` beispielsweise gibt an, dass seine untergeordneten Elemente die Teile eines Buches darstellen. Dazu gehören Titel, Kapitel, Glossar, Anhänge usw. Die Struktur-Tags von DocBook umfassen unter anderem:

  • set: Benannte Sammlung eines oder mehrerer books oder articles, kann mit anderen Mengen verschachtelt werden
  • book: Titelsammlung von chapters, articles und/oder parts, mit optionalen Glossaren, Anhängen usw.
  • part: Eine betitelte Sammlung aus einem oder mehreren chapterTeilen – kann mit anderen Teilen verschachtelt sein und einen speziellen Einleitungstext enthalten.
  • article: Benannte, unnummerierte Sammlung von Blockelementen
  • chapter: Eine betitelte, nummerierte Sammlung von Blockelementen – Kapitel benötigen keine expliziten Nummern; die Kapitelnummer entspricht der Anzahl der vorherigen Kapitelelemente im XML-Dokument plus 1.
  • appendixEnthält Text, der einen Anhang darstellt
  • dedicationDer Text stellt die Widmung des enthaltenen Bauelements dar .

Strukturelemente können andere Strukturelemente enthalten. Strukturelemente sind die einzigen zulässigen Elemente der obersten Ebene in einem DocBook-Dokument.

Blockelemente sind Elemente wie Absätze, Listen usw. Nicht alle diese Elemente können direkt Text enthalten. Sequenzielle Blockelemente werden nacheinander dargestellt. Was „nach“ bedeutet, kann je nach Sprache variieren. In den meisten westlichen Sprachen bedeutet „nach“ „darunter“: Textabsätze werden von oben nach unten gedruckt. Andere Schriftsysteme können eine andere Richtung haben ; im Japanischen beispielsweise werden Absätze oft in Spalten von rechts nach links gedruckt, sodass „nach“ in diesem Fall links davon liegt. Die DocBook-Semantik ist gegenüber solchen sprachbasierten Konzepten völlig neutral.

Inline- Tags sind Elemente wie Hervorhebungen, Hyperlinks usw. Sie umschließen Text innerhalb eines Blockelements. Diese Elemente verursachen beim Rendern im Absatzformat keinen Textumbruch, veranlassen den Textprozessor aber in der Regel, den eingeschlossenen Text typografisch anzupassen, indem er Schriftart, Größe oder ähnliche Attribute ändert. (Die DocBook-Spezifikation sieht zwar eine unterschiedliche typografische Behandlung vor, macht aber keine konkreten Vorgaben dazu.) Das heißt, ein DocBook-Prozessor muss ein emphasisTag nicht zwangsläufig kursiv formatieren . Ein Reader-basierter DocBook-Prozessor könnte die Schriftgröße vergrößern, oder ein textbasierter Prozessor könnte Fettdruck anstelle von Kursivschrift verwenden.

Beispieldokument

<?xml version="1.0" encoding="UTF-8"?> <book xml:id= "simple_book" xmlns= "http://docbook.org/ns/docbook" version= "5.0" > <title> Ein sehr einfaches Buch </title> <chapter xml:id= "chapter_1" > <title> Kapitel 1 </title> <para> Hallo Welt! </para> <para> Ich hoffe , dein Tag verläuft <emphasis> wunderbar </emphasis> ! </para> </chapter> <chapter xml:id= "chapter_2 " > <title> Kapitel 2 </title> <para> Hallo Welt ! </para> </chapter> </book>

Semantisch gesehen ist dieses Dokument ein „Buch“ mit einem „Titel“, das zwei „Kapitel“ mit jeweils einem eigenen „Titel“ enthält. Diese „Kapitel“ enthalten „Absätze“ mit Text. Die Auszeichnung ist in Englisch gut lesbar.

Genauer gesagt ist das Wurzelelement des Dokuments `<docBook>` book. Alle DocBook-Elemente befinden sich im XML-Namensraum ` <docBook> `, daher verfügt das Wurzelelement über ein `xmlns`- Attribut, um den aktuellen Namensraum festzulegen. Außerdem muss das Wurzelelement eines DocBook-Dokuments eine Versionsangabe enthalten , die die Version des Formats angibt, auf dem das Dokument basiert.

(XML-Dokumente können Elemente aus mehreren Namensräumen gleichzeitig enthalten, wie die idAttribute im Beispiel.)

Ein bookElement muss ein `<title>` -Element titleoder ein infoElement mit einem `<head>`-Element enthalten title. Dies muss vor allen untergeordneten Strukturelementen stehen. Nach dem Titel folgen die untergeordneten Strukturelemente, in diesem Fall zwei chapterElemente. Jedes dieser Elemente muss ein `<head>`-Element enthalten title. Sie enthalten paraBlockelemente, die Freitext und andere Inline-Elemente wie das `<head>` emphasisim zweiten Absatz des ersten Kapitels enthalten können.

Schemas und Validierung

Die Regeln sind formal im DocBook -XML-Schema definiert . Geeignete Programmierwerkzeuge können ein XML-Dokument (DocBook oder ein anderes) anhand des zugehörigen Schemas validieren, um festzustellen, ob und wo das Dokument gegen das Schema verstößt. XML-Bearbeitungswerkzeuge können Schemainformationen auch nutzen, um die Erstellung nicht konformer Dokumente von vornherein zu vermeiden.

Erstellung und Verarbeitung

Da DocBook auf XML basiert, können Dokumente mit jedem beliebigen Texteditor erstellt und bearbeitet werden. Ein dedizierter XML-Editor ist somit auch ein funktionaler DocBook-Editor. DocBook stellt Schemadateien für gängige XML-Schema-Sprachen bereit, sodass jeder XML-Editor, der schemabasierte Inhaltsvervollständigung unterstützt, diese auch für DocBook bietet. Viele grafische oder WYSIWYG -XML-Editoren ermöglichen die Bearbeitung von DocBook wie mit einem Textverarbeitungsprogramm . [ 3 ]

Tabellen, Listenelemente und andere formatierte Inhalte können in den DocBook-Editor kopiert und eingefügt werden und bleiben in der DocBook-XML-Ausgabe erhalten. [ 3 ] Da DocBook einem klar definierten XML-Schema entspricht, können Dokumente mit jedem Tool oder jeder Programmiersprache, die XML unterstützt, validiert und verarbeitet werden.

Geschichte

DocBook entstand 1991 in Diskussionsgruppen im Usenet und entwickelte sich schließlich zu einem Gemeinschaftsprojekt von HAL Computer Systems und O'Reilly & Associates. Daraus ging eine eigene Wartungsorganisation hervor (die Davenport Group), bevor 1998 DocBook dem SGML Open Consortium beitrat, aus dem später OASIS hervorging . Aktuell wird DocBook vom DocBook Technical Committee bei OASIS betreut. [ 4 ]

DocBook ist sowohl im SGML- als auch im XML- Format als DTD verfügbar . Die XML-Version ist auch in den Formaten RELAX NG und W3C XML Schema erhältlich. Ab DocBook 5 dient die RELAX-NG-Version als „normatives“ Format, aus dem die anderen Formate generiert werden.

DocBook begann ursprünglich als SGML-Anwendung, doch eine entsprechende XML-Anwendung wurde entwickelt und hat die SGML- Anwendung mittlerweile in den meisten Anwendungsfällen ersetzt. (Ab Version 4 der SGML-DTD wurde dieses Versionsnummerierungsschema auch für die XML-DTD beibehalten.) Anfänglich nutzte eine Gruppe von Softwareunternehmen DocBook, da deren Vertreter an der Entwicklung beteiligt waren. Schließlich wurde DocBook jedoch von der Open-Source-Community übernommen und hat sich dort zu einem Standard für die Dokumentation zahlreicher Projekte entwickelt, darunter FreeBSD , KDE , die GNOME -Desktop-Dokumentation, die GTK+ -API- Referenzen, die Linux-Kernel -Dokumentation (die seit Juli 2016 auf Sphinx / reStructuredText [ 5 ] [ 6 ] umgestellt wird ) und die Arbeit des Linux Documentation Project .

Vor DocBook v5.0

Bis DocBook 5 wurde DocBook normativ durch eine Dokumenttypdefinition (DTD) definiert. Da DocBook ursprünglich als Anwendung von SGML entwickelt wurde , war die DTD die einzige verfügbare Schemasprache. DocBook 4.x-Formate können SGML oder XML sein, die XML-Version besitzt jedoch keinen eigenen Namensraum.

DocBook 4.x-Formate mussten sich an die Vorgaben einer DTD halten. Die wichtigste Einschränkung war, dass ein Elementname seinen möglichen Inhalt eindeutig definiert. Das heißt, ein Element mit dem Namen „info“ infomuss unabhängig von seiner Position in der DocBook-Datei immer dieselben Informationen enthalten. Daher gibt es in DocBook 4.x viele verschiedene Arten von Informationselementen: „info“, „info“ bookinfo, chapterinfo„info“ usw. Jedes dieser Elemente hat ein etwas anderes Inhaltsmodell, aber sie teilen auch einige Gemeinsamkeiten. Außerdem wiederholen sie Kontextinformationen. Das „book“ info-Element ist ein direktes Kindelement des Buches und benötigt daher keine spezielle Benennung für den menschlichen Leser. Da das Format jedoch durch eine DTD definiert wurde, musste es entsprechend benannt werden. Das Wurzelelement hat keine Versionsangabe und benötigt auch keine, da die Version in der DTD-Deklaration am Anfang eines Dokuments vor DocBook 5 bereits festgelegt ist.

DocBook 4.x-Dokumente sind nicht mit DocBook 5 kompatibel, können aber mithilfe eines XSLT-Stylesheets in DocBook 5-Dokumente konvertiert werden. Ein solches db4-upgrade.xslStylesheet ist Bestandteil der DocBook 5-Schema- und Spezifikationspakete. [ 7 ]

Ausgabeformate

DocBook-Dateien dienen der Erstellung von Ausgabedateien in verschiedensten Formaten. Dies geschieht fast immer mithilfe von DocBook-XSL -Stylesheets. Dabei handelt es sich um XSLT -Stylesheets, die DocBook-Dokumente in verschiedene Formate ( HTML , XSL-FO für die spätere Konvertierung in PDF usw.) umwandeln. Diese Stylesheets können so komplex sein, dass sie Inhaltsverzeichnisse, Glossare und Indizes generieren. Sie können die Auswahl bestimmter Abschnitte eines Masterdokuments steuern, um verschiedene Versionen desselben Dokuments zu erstellen (z. B. ein „Tutorial“ oder eine „Kurzanleitung“, die jeweils einen Teil des Materials enthalten). Benutzer können eigene, benutzerdefinierte Stylesheets oder sogar ein vollständiges Programm schreiben, um das DocBook je nach Bedarf in das gewünschte Ausgabeformat zu konvertieren.

Norman Walsh und das Entwicklungsteam des DocBook-Projekts pflegen die zentrale Anwendung zur Ausgabe von DocBook-Quelldokumenten: Ein Satz von XSLT- Stylesheets (sowie ein älterer Satz von DSSSL- Stylesheets), der qualitativ hochwertige HTML- und Druckausgaben ( FO / PDF ) sowie Ausgaben in anderen Formaten, einschließlich RTF , Manpages und HTML-Hilfe, generieren kann.

Webhilfe [ 2 ] ist ein in Chunked HTML-Ausgabeformat in den DocBook XSL- Stylesheets, das in Version 1.76.1 eingeführt wurde. Die Dokumentation für Webhilfe [ 8 ] enthält auch ein Beispiel für Webhilfe und ist Teil der DocBook XSL-Distribution.

Zu den wichtigsten Funktionen gehören das vollständig CSS-basierte Seitenlayout, die Suche im Hilfetext und ein Inhaltsverzeichnis in Baumstruktur. Die Suche bietet Stemming , Hervorhebung von Treffern, explizite Seitenbewertung und den standardmäßigen mehrsprachigen Tokenizer . Suche und Inhaltsverzeichnis befinden sich in einem Bereich, der zwar wie ein Frameset aussieht , aber tatsächlich mit div-Tags und Cookies implementiert ist (um ein progressives Laden zu gewährleisten).

Vereinfachtes DocBook

DocBook bietet eine Vielzahl von Funktionen, die für neue Benutzer möglicherweise überfordernd wirken. Für alle, die die Vorteile von DocBook ohne lange Einarbeitungszeit nutzen möchten, wurde Simplified DocBook entwickelt. Es handelt sich dabei um eine reduzierte Version von DocBook, die speziell für einzelne Dokumente wie Artikel oder Whitepaper konzipiert ist (Bücher werden nicht unterstützt). Die Simplified DocBook DTD liegt aktuell in Version 1.1 vor. [ 9 ]

Kritik

Ingo Schwarze, der Autor von OpenBSDs mandoc , hält DocBook für dem semantischen mdoc- Makro für Manpages unterlegen . Bei dem Versuch , einen DocBook-zu-mdoc-Konverter zu schreiben (frühere Konverter wie docbook-to-man berücksichtigen keine semantischen Elemente), empfand er die semantischen Teile im Vergleich zu den in mdoc abgedeckten Elementen als „aufgebläht, redundant und unvollständig zugleich“. Darüber hinaus bemängelt Schwarze die unpräzise DocBook-Spezifikation hinsichtlich der Verwendung von Tags, die mangelnde Versionskompatibilität der Sprache, die Ungenauigkeiten und die insgesamt inkonsistente Ausgestaltung. [ 10 ]

Siehe auch

Referenzen

Weiterführende Literatur

Norman Walsh ist der Hauptautor des Buches „DocBook: The Definitive Guide“ , der offiziellen Dokumentation von DocBook. Dieses Buch ist online unter der GFDL und auch als gedruckte Ausgabe verfügbar.