FreeBSD Documentation Project: SGML

Das Documentation Project verwendet SGML zur Erstellung der Dokumentation.

SGML steht für Standard Generalized Markup Language.

Kurz gesagt (SGML-Puristen mögen dies verzeihen) handelt es sich bei SGML um eine Sprache zum Schreiben anderer Sprachen.

Wahrscheinlich haben Sie SGML bereits verwendet, ohne dass Sie sich dessen bewusst sind. So verfügt beispielsweise HTML (die Sprache, in der zahlreiche Internetseiten geschrieben sind) über eine formale Beschreibung, die in SGML verfasst wurde. Wenn Sie HTML verwenden, verwenden Sie aber trotzdem kein SGML, sondern eine Sprache, die in SGML definiert wurde.

Es gibt zahlreiche, in SGML definierte Sprachen. HTML ist dabei lediglich eine unter vielen Sprachen. Eine weitere bekannte Sprache ist "DocBook". Diese Sprache wurde speziell dafür entwickelt, technische Dokumentationen zu schreiben. Dazu verfügt sie über zahlreiche Tags (also Markierungen der Form <Tag Inhalt>), um diese Dokumentationen für deren anschließende Formatierung zu beschreiben. Das FreeBSD Documentation Project hat DocBook an seine Bedürfnisse angepasst und unter anderem einige neue Elemente definiert, um die Sprache präziser zu machen.

Sehen Sie sich dazu den folgenden (in HTML geschriebenen) Absatz an. Der Inhalt ist Nebensache, konzentrieren Sie sich auf die verwendeten Tags:

    <p>The system's passwords are stored in <tt>/etc/passwd</tt>. To edit
      this file you should use <b><tt>vipw</tt></b>. However, if you just
      want to add a new user you can use <b><tt>adduser</tt></b>.</p>

Der gleiche (diesmal in DocBook geschriebene) Absatz sieht folgendermaßen aus:

    <para>The system's passwords are stored in
      <filename>/etc/passwd</filename>. To edit this file you should use
      <command>vipw</command>. However, if you just want to add a new user
      you can use <command>adduser</command>.</para>

Wie Sie sehen, ist DocBook "ausdrucksstärker" als HTML. In HTML wird der Dateiname als "in Schreibenmaschinenschrift darzustellen" markiert. In DocBook wird der Dateiname hingegen als "filename" markiert. Es wird allerdings nicht angegeben, wie "filename" dargestellt werden soll.

Diese Vorgehensweise hat mehrere Vorteile:

Sie ist eindeutig und konsistent.

Sie verlieren keine Zeit mit Überlegungen wie "Hm, ich muss einen Dateinamen darstellen, nehme ich dafür 'tt', 'b', oder besser doch 'em'?"

Stattdessen verwenden Sie einfach das der jeweiligen Situation angepasste Tag.

Die Konvertierung von DocBook in andere Formate wie HTML oder PostScript® stellt sicher, dass alle Dateinamen innerhalb des Dokuments gleich dargestellt werden.
Sie müssen sich keine Gedanken mehr über die Darstellung Ihres Dokuments machen, sondern können sich auf den Inhalt konzentrieren.
Da die Dokumentation nicht an ein bestimmtes Format gebunden ist, kann die gleiche Dokumentation in viele verschiedene Formate (wie normalen Text, HTML, PostScript, RTF, PDF und andere mehr) konvertiert werden.
Die Dokumentation ist 'intelligenter' und erlaubt dadurch auch anspruchsvollere Dinge, wie die automatische Erstellung eines Index mit allen innerhalb des Dokuments verwendeten Befehlen.

Mit DocBook erstellte Dokumente haben eine gewisse Ähnlichkeit mit den von Microsoft® Word bekannten Dokumentvorlagen, sind aber sehr viel mächtiger.

Diese besonderen Fähigkeiten haben aber ihren Preis:

Da es sehr viele Tags gibt, dauert es länger, bis Sie alle kennen werden und optimal einsetzen können.

Um die Lernkurve zu verflachen, ist es sehr hilfreich, sich Dokumentationen anderer Autoren anzusehen, um zu sehen, wie diese ähnliche Informationen beschreiben.
Der Konvertierungsprozess ist relativ komplex.

Sie können kein DocBook. Können Sie das Documentation Project trotzdem unterstützen?

Natürlich. Jede Dokumentation ist besser als keine Dokumentation. Es ist kein großes Problem, wenn Ihr Beitrag nicht als DocBook formatiert ist.

Reichen Sie Ihren Beitrag einfach ein. Jemand aus dem Documentation Project wird Ihren Beitrag übernehmen, ihn in DocBook formatieren und committen. Vielleicht erhalten Sie den formatierten Text sogar zurück. Dann können Sie einen "Vorher-/Nachher-Vergleich" durchführen und so etwas mehr über DocBook lernen.

Da Ihr Beitrag in diesem Fall aber zuerst in DocBook formatiert werden muss, verlangsamt sich der Konvertierungsprozess etwas, es kann daher bis zu einigen Tagen dauern, bis Ihr Beitrag committet wird.

Gibt es weitere Informationen zu SGML und DocBook?

Lesen Sie zuerst den Documentation Project Primer. Dieser enthält eine ausführliche Beschreibung aller Dinge, die Sie zur Arbeit an der FreeBSD Dokumentation benötigen. Er ist in mehrere Abschnitte unterteilt, kann aber auch als eine einzelne große Seite aufgerufen werden.

http://www.oasis-open.org/cover/sgml-xml.html: Die offiziellen SGML/XML-Internetseiten mit zahlreichen Links zu SGML-Ressourcen.
http://www-sul.stanford.edu/tools/tutorials/html2.0/gentle.html: "The Gentle Introduction to SGML" ist für alle empfehlenswert, die mehr über SGML (insbesondere aus der Sicht eines Einsteigers) wissen wollen.
http://www.oasis-open.org/docbook/: Die offizielle DocBook DTD wird von OASIS gewartet. Diese Seiten richten sich besonders an Personen, die mit SGML bereits vertraut sind und nun DocBook lernen wollen.

Startseite des FreeBSD Documentation Projects

Last modified on: 19. Juni 2021 by Danilo G. Baio