Das K Desktop Environment

Kapitel 9. Erweitern der Dokumentation mit SGML

Gerade bei der Dokumentation lassen viele Softwarepakete ihre Anwender im Regen stehen. Um dem zu begegnen, enthalten alle KDevelop-Projekte ein vorgefertigtes Handbuch, das sich leicht anpassen lsst, und kommen damit dem Ziel von KDE entgegen, Benutzern, die den Umgang mit der Software erlernen wollen, ausreichend Online-Hilfe an die Hand zu geben. Dieses Kapitel erlutert Ihnen daher, wie man das Dokumentationsgerst mit Leben fllt und was Sie zu tun haben, um den Anwender Ihre Erweiterungen zugnglich zu machen.

9.1. Warum SGML?

SGML (Standard Generalized Markup Language) ist eine Sprache, mit der sich die Spezifikation von Auszeichnungssprachen (engl.: markup languages) beschreiben lsst, nicht aber die Auszeichnungssprache selbst. Die Spezifikation einer Auszeichnungssprache nennt man DTD (Document Type Definition). Diese enthlt die Struktur eines Dokuments sowie die zulssigen Auszeichnungen (Tags). Ein SGML-System bringt verschiedene Dateien mit, die die DTD-Tags ins gewnschte Ausgabeformat bersetzen -- und das ist schon das ganze Geheimnis. Das am weitesten verbreitete Ausgabeformat ist vermutlich HTML -- Online-Hilfe via WWebbrowser kann in einer Zeit, in der Internetstandards bis zum Einzelplatzrechner vorgedrungen sind, als gngig angesehen werden. KDE macht mit KDEHelp ausgiebig Gebrauch von HTML-Dokumentation: Dieses Programm listet alle installierten KDE-Anwendungen und bietet Zugriff auf deren Benutzerhandbcher. ber ein Hilfemen erhlt der Benutzer direkt aus der jeweiligen Anwendung Zugang zur Online-Hilfe.

KDE (und daher auch KDevelop) nutzt das SGML-Tools-1.x-Paket (vgl. \|\|), das frher unter dem Namen LinuxDoc bekannt war. Es enthlt eine DTD namens LinuxDoc, eine Reihe Dateien, die die Umwandlung in verschiedene Ausgabeformate steuern, und die ntigen Werkzeuge, die die tatschliche Ersetzung der LinuxDoc-Tags vornehmen. Die LinuxDoc-DTD basiert auf der Qwertz-DTD, die entwickelt wurde, um speziell Tag-bersetzungen fr das LaTeX-Satzsystem vorzunehmen. Daher eignet sie sich besonders zum Erzeugen von Dokumenten in vernnftiger Ausdruckqualitt. Das Paket selbst bekam seinen Namen, weil es vom LDP (Linux Documentation Project) zur Dokumentation verwendet wurde. Er wurde lediglich deshalb gendert, weil ein SGML-System nicht notwendigerweise auf Linux beschrnkt ist, sondern auf jedem Unix-System benutzt werden kann. Sie knnen natrlich auch Ihre eigene DTD und die zugehrigen "Mappings" schreiben, wenn Sie Lust dazu haben.

Mittlerweile erfllt eine andere DTD genau so gut den selben Zweck: die DocBook-DTD. DocBook hat einige offensichtliche Vorteile gegenber LinuxDoc, insbesondere, weil sie bessere Tags und Mappings fr Tabellen und Grafikeinbindung enthlt (was nicht heit, dass LinuxDoc das nicht auch knnte...). Die SGML-Tools untersttzen daher in den 2.x-Versionen die DocBook-DTD und enthalten einen Konverter, der aus LinuxDoc-Dokumenten DocBook-SGML erzeugt.

Augenblicklich setzen wir bei der KDE-Entwicklung allerdings weiterhin auf die LinuxDoc-DTD. Das hat folgende Grnde:

Meine persnliche -- beim Schreiben der KDevelop-Handbcher gewonnene -- Erfahrung mit der LinuxDoc-DTD ist, dass sie sehr einfach ist und alle Bedrfnisse abdeckt, die beim Erstellen von Dokumentation so anfallen. Da die Lernkurve sehr steil verluft, werden vermutlich auch Sie innerhalb krzester Zeit zum SGML-Tools/LinuxDoc-Guru aufsteigen und eine Menge Zeit sparen, die es bruchte, um sich in ein Formatierungssystem a la TeX (fr die Druckausgabe Ihrer Dokumentation) oder eine Auszeichnungssprache fr die HTML-Ausgabe einzuarbeiten.

Einer der Hauptgrnde, immer noch die SGML-Tools 1.x zu verwenden, ist sicherlich auch der, dass die meisten Distributionen dieses Paket und all die zustzlichen Werkzeuge mitbringen, die Sie zur Umwandlung in andere Ausgabeformate bentigen. Das macht die Installation so einfach wie mglich, und dass das Schreiben selbst nicht sehr kompliziert ist, werden Sie selbst sehen. Folgende Ausgabeformate knnen Sie mit den SGML-Tools erzeugen: