DocBook - DocBook

DocBook
Dateinamenerweiterung
.dbk, .xml
Internet-Medientyp
Anwendung/docbook+xml
Entwickelt von OASE
Formattyp Auszeichnungssprache
Verlängert von SGML , XML
Standard 5.1 (November 2016) ,
4.5 (Oktober 2006)
Offenes Format ? Jawohl

DocBook ist eine semantische Auszeichnungssprache für die technische Dokumentation . Es war ursprünglich zum Schreiben technischer Dokumente im Zusammenhang mit Computerhardware und -software gedacht, kann aber für jede andere Art von Dokumentation verwendet werden.

Als semantische Sprache ermöglicht DocBook seinen Benutzern, Dokumentinhalte in einer präsentationsneutralen Form zu erstellen , die die logische Struktur des Inhalts erfasst; dieser Inhalt kann dann in einer Vielzahl von Formaten veröffentlicht werden, einschließlich HTML , XHTML , EPUB , PDF , Manpages , Web-Hilfe und HTML-Hilfe , ohne dass Benutzer Änderungen an der Quelle vornehmen müssen. Mit anderen Worten, wenn ein Dokument im DocBook-Format geschrieben ist, kann es leicht in andere Formate portiert werden, anstatt neu geschrieben werden zu müssen.

Entwurf

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

Als semantische Sprache beschreiben DocBook-Dokumente nicht, wie ihre Inhalte "aussehen", sondern die Bedeutung dieser Inhalte. Zum Beispiel, anstatt zu erklären , wie die abstrakten für einen Artikel könnte visuell formatiert werden, sagt DocBook einfach , dass ein bestimmte Abschnitt ist eine Zusammenfassung. Es liegt an einem externen Verarbeitungstool oder einer Anwendung, zu entscheiden, wo auf einer Seite das Abstract hingehört und wie es aussehen soll oder ob es überhaupt in die endgültige Ausgabe aufgenommen werden soll oder nicht.

DocBook bietet eine Vielzahl von semantischen Element-Tags. Sie sind in drei große Kategorien unterteilt, nämlich strukturell, auf Blockebene und inline.

Strukturelle Tags spezifizieren allgemeine Merkmale ihres Inhalts. Das bookElement gibt beispielsweise an, dass seine untergeordneten Elemente die Teile eines Buches darstellen. Dazu gehören Titel, Kapitel, Glossare, Anhänge usw. Die strukturellen Tags von DocBook umfassen, sind aber nicht beschränkt auf:

  • set: Betitelte Sammlung von einem oder mehreren books oder articless, kann mit anderen Sets verschachtelt werden
  • book: Betitelte Sammlung von chapters, articles und/oder parts, mit optionalen Glossaren, Anhängen usw.
  • part: Betitelte Sammlung von einem oder mehreren chapters – kann mit anderen Teilen verschachtelt werden und kann einen speziellen Einführungstext haben
  • article: Betitelte, nicht nummerierte Sammlung von Elementen auf Blockebene
  • chapter: Betitelte, nummerierte Sammlung von Elementen auf Blockebene – Kapitel erfordern keine expliziten Nummern, eine Kapitelnummer ist die Anzahl der vorherigen Kapitelelemente im XML-Dokument plus 1
  • appendix: Enthält Text, der einen Anhang darstellt
  • dedication: Text stellt die Widmung des enthaltenen Strukturelements dar

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

Tags auf Blockebene sind Elemente wie Absätze, Listen usw. Nicht alle diese Elemente können direkt Text enthalten. Sequentielle Elemente auf Blockebene rendern eines nach dem anderen. Nach kann in diesem Fall je nach Sprache unterschiedlich sein. In den meisten westlichen Sprachen bedeutet "nach" unten: Textabsätze werden auf der Seite gedruckt. Die Schriftsysteme anderer Sprachen können eine andere Richtung haben ; Im Japanischen werden Absätze beispielsweise oft in abwärts gerichteten Spalten gedruckt, wobei die Spalten von rechts nach links verlaufen, so dass "danach" in diesem Fall links wäre. Die DocBook-Semantik ist gegenüber solchen sprachbasierten Konzepten völlig neutral.

Tags auf Inline-Ebene sind Elemente wie Hervorhebungen, Hyperlinks usw. Sie umschließen Text innerhalb eines Elements auf Blockebene. Diese Elemente führen nicht dazu, dass der Text beim Rendern in einem Absatzformat unterbrochen wird, aber sie bewirken normalerweise, dass der Dokumentprozessor eine bestimmte typografische Behandlung auf den eingeschlossenen Text anwendet, indem er die Schriftart, Größe oder ähnliche Attribute ändert. (Die DocBook-Spezifikation sagt zwar , dass sie eine andere typografische Behandlung erwartet, stellt jedoch keine spezifischen Anforderungen an diese Behandlung.) Das heißt, ein DocBook-Prozessor muss ein emphasisTag nicht in Kursivschrift umwandeln . Ein leserbasierter DocBook-Prozessor könnte die Größe der Wörter erhöhen oder ein textbasierter Prozessor könnte fett statt kursiv verwenden.

Beispieldokument

 <?xml version="1.0" encoding="UTF-8"?>
 <book xml:id="simple_book" xmlns="http://docbook.org/ns/docbook" version="5.0">
   <title>Very simple book</title>
   <chapter xml:id="chapter_1">
     <title>Chapter 1</title>
     <para>Hello world!</para>
     <para>I hope that your day is proceeding <emphasis>splendidly</emphasis>!</para>
   </chapter>
   <chapter xml:id="chapter_2">
     <title>Chapter 2</title>
     <para>Hello again, world!</para>
   </chapter>
 </book>

Semantisch ist dieses Dokument ein "Buch", mit einem "Titel", das zwei "Kapitel" mit jeweils eigenen "Titeln" enthält. Diese "Kapitel" enthalten "Absätze", die Text enthalten. Das Markup ist auf Englisch gut lesbar.

Genauer gesagt ist das Wurzelelement des Dokuments book. Alle DocBook-Elemente befinden sich in einem XML-Namespace , daher hat das Root-Element ein xmlns- Attribut, um den aktuellen Namespace festzulegen. Außerdem muss das Stammelement eines DocBook-Dokuments eine Version haben , die die Version des Formats angibt, auf dem das Dokument aufbaut.

(XML-Dokumente können Elemente aus mehreren Namespaces gleichzeitig enthalten. Der Einfachheit halber wird dies im Beispiel nicht veranschaulicht.)

Ein bookElement muss a enthalten title, oder ein infoElement, das a enthält title. Dies muss vor allen untergeordneten Strukturelementen sein. Nach dem Titel folgen die strukturellen Kinder, in diesem Fall zwei chapterElemente. Jeder von ihnen muss eine title. Sie enthalten paraBlockelemente, die freien Text und andere Inline-Elemente wie emphasisim zweiten Absatz des ersten Kapitels enthalten können.

Schemata und Validierung

Regeln sind formal im DocBook XML-Schema definiert . Geeignete Programmiertools können ein XML-Dokument (DocBook oder anders) anhand seines entsprechenden Schemas validieren, um festzustellen, ob (und wo) das Dokument diesem Schema nicht entspricht. XML-Bearbeitungstools können auch Schemainformationen verwenden, um die Erstellung nicht konformer Dokumente von vornherein zu vermeiden.

Erstellung und Verarbeitung

Da DocBook XML ist, können Dokumente mit jedem Texteditor erstellt und bearbeitet werden. Ein dedizierter XML-Editor ist ebenfalls ein funktionaler DocBook-Editor. DocBook bietet Schemadateien für gängige XML-Schemasprachen, sodass jeder XML-Editor, der Inhaltsvervollständigung basierend auf einem Schema bereitstellen kann, dies für DocBook tun kann. Viele grafische oder WYSIWYG- XML-Editoren bieten die Möglichkeit, DocBook wie ein Textverarbeitungsprogramm zu bearbeiten .

Da DocBook einem wohldefinierten XML-Schema entspricht, können Dokumente mit jedem Tool oder jeder Programmiersprache mit XML-Unterstützung validiert und verarbeitet werden.

Geschichte

DocBook begann 1991 in Diskussionsgruppen im Usenet und wurde schließlich ein gemeinsames Projekt von HAL Computer Systems und O'Reilly & Associates und brachte schließlich seine eigene Wartungsorganisation (die Davenport Group) hervor, bevor es 1998 zum SGML Open Konsortium wechselte, das später zu . wurde OASE . DocBook wird derzeit vom DocBook Technical Committee bei OASIS gepflegt .

DocBook ist sowohl in SGML- als auch in XML- Form als DTD verfügbar . RELAX NG und W3C XML Schema- Formulare der XML-Version sind verfügbar. Ab DocBook 5 ist die RELAX NG-Version die „normative“ Form, aus der die anderen Formate generiert werden.

DocBook begann ursprünglich als SGML-Anwendung, aber eine äquivalente XML-Anwendung wurde entwickelt und hat jetzt die SGML- Anwendung für die meisten Anwendungen ersetzt. (Angefangen mit Version 4 der SGML DTD wurde die XML DTD mit diesem Versionsnummerierungsschema weitergeführt.) Anfangs verwendete eine wichtige Gruppe von Softwareunternehmen DocBook, da ihre Vertreter an seinem ursprünglichen Design beteiligt waren. Schließlich wurde DocBook jedoch von der Open-Source-Community übernommen, wo es zu einem Standard für die Erstellung von Dokumentationen für viele Projekte geworden ist, darunter FreeBSD , KDE , GNOME- Desktop-Dokumentation, die GTK+ -API- Referenzen, die Linux-Kernel- Dokumentation und die Arbeit der Linux Dokumentationsprojekt .

Pre DocBook v5.0

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

DocBook 4.x-Formate mussten innerhalb der Einschränkungen einer DTD-Definition leben. Die wichtigste Einschränkung war, dass ein Elementname seinen möglichen Inhalt eindeutig definiert. Das heißt, ein benanntes Element infomuss die gleichen Informationen enthalten, egal wo es sich in der DocBook-Datei befindet. Daher gibt es in DocBook 4.x viele Arten von Info-Elementen: bookinfo, chapterinfo, usw. Jedes hat ein etwas anderes Inhaltsmodell, aber sie teilen einen Teil ihres Inhaltsmodells. Darüber hinaus wiederholen sie Kontextinformationen. Das ist das infoElement des Buches, weil es ein direktes Kind des Buches ist; es muss nicht speziell für einen menschlichen Leser benannt werden. Da das Format jedoch durch eine DTD definiert wurde, musste es als solches benannt werden. Das Root-Element hat oder benötigt keine Version , da die Version in die DTD-Deklaration am Anfang eines Dokuments vor DocBook 5 integriert ist.

DocBook 4.x-Dokumente sind nicht mit DocBook 5 kompatibel, können aber über ein XSLT-Stylesheet in DocBook 5-Dokumente umgewandelt werden. Eine ( db4-upgrade.xsl) wird als Teil der Verteilung des DocBook 5-Schema- und Spezifikationspakets bereitgestellt.

Ausgabeformate

DocBook-Dateien werden verwendet, um Ausgabedateien in einer Vielzahl von Formaten vorzubereiten. Fast immer wird dies mithilfe von DocBook XSL- Stylesheets erreicht. Dies sind XSLT- Stylesheets, die DocBook-Dokumente in eine Reihe von Formaten umwandeln ( HTML , XSL-FO für die spätere Konvertierung in PDF , etc.). Diese Stylesheets können ausgereift genug sein, um Inhaltsverzeichnisse, Glossare und Indizes zu erstellen. Sie können die Auswahl bestimmter Teile eines Masterdokuments beaufsichtigen, um verschiedene Versionen desselben Dokuments zu erstellen (z. B. ein "Tutorial" oder eine "Kurzanleitung", die jeweils aus einer Teilmenge des Materials bestehen). Benutzer können ihre eigenen benutzerdefinierten Stylesheets oder sogar ein vollwertiges Programm schreiben, um das DocBook je nach Bedarf in ein geeignetes Ausgabeformat zu verarbeiten.

Norman Walsh und das DocBook Project-Entwicklungsteam pflegen die Schlüsselanwendung für die Ausgabe von DocBook-Quelldokumenten: Eine Reihe von XSLT- Stylesheets (sowie eine Legacy-Reihe von DSSSL- Stylesheets), die hochwertiges HTML generieren und drucken können ( FO / PDF ). Ausgabe sowie Ausgabe in anderen Formaten, einschließlich RTF , man-Seiten und HTML-Hilfe.

Die Webhilfe ist ein stückweises HTML-Ausgabeformat in den DocBook XSL- Stylesheets, das in Version 1.76.1 eingeführt wurde. Die Dokumentation zur Web-Hilfe enthält auch ein Beispiel für die Web-Hilfe und ist Teil der DocBook XSL-Distribution.

Die Hauptmerkmale sind das vollständig CSS-basierte Seitenlayout, die Suche nach Hilfeinhalten und ein Inhaltsverzeichnis in zusammenklappbarer Baumform. Die Suche verfügt über Stemming , Match-Highlighting, explizite Seitenbewertung und den standardmäßigen mehrsprachigen Tokenizer . Die Suche und das Inhaltsverzeichnis befinden sich in einem Bereich, der als Frameset angezeigt wird , aber tatsächlich mit div-Tags und Cookies implementiert wird (so dass es progressiv ist).

Vereinfachtes DocBook

DocBook bietet eine große Anzahl von Funktionen, die für einen neuen Benutzer überwältigend sein können. Für diejenigen, die den Komfort von DocBook ohne steile Lernkurve wünschen, wurde Simplified DocBook entwickelt. Es ist eine kleine Teilmenge von DocBook, die für einzelne Dokumente wie Artikel oder Whitepaper entwickelt wurde (dh "Bücher" werden nicht unterstützt). Die vereinfachte DocBook-DTD hat derzeit die Version 1.1.

Kritik

Ingo Schwarze, der Autor von OpenBSD ‚s mandoc hält DocBook schlechter als die semantische mdoc Makro für Manpages . Bei dem Versuch, einen DocBook-to-mdoc-Konverter zu schreiben (frühere Konverter wie docbook-to-man decken semantische Elemente nicht ab), findet er die semantischen Teile "aufgebläht, redundant und gleichzeitig unvollständig" im Vergleich zu den in behandelten Elementen mdoc. Außerdem findet Schwarze die DocBook-Spezifikation nicht genau genug bezüglich der Verwendung von Tags, die Sprache ist nicht über mehrere Versionen portierbar, grob im Detail und insgesamt inkonsistent.

Siehe auch

Verweise

Weiterlesen

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 Print-Publikation erhältlich.

Externe Links