Erweitern der Dokumentation mit SGML

Das KDevelop-Programmierhandbuch: Leitfaden zur C++-Anwendungsentwicklung für das K Desktop Environment (KDE) mit Hilfe der KDevelop-IDE in der Version 1.2
Zurück |  | Vor

# 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 lässt, 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 erläutert Ihnen daher, wie man das Dokumentationsgerüst mit Leben füllt und was Sie zu tun haben, um den Anwender Ihre Erweiterungen zugänglich 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 lässt, nicht aber die Auszeichnungssprache selbst. Die Spezifikation einer Auszeichnungssprache nennt man DTD (Document Type Definition). Diese enthält die Struktur eines Dokuments sowie die zulässigen Auszeichnungen (Tags). Ein SGML-System bringt verschiedene Dateien mit, die die DTD-Tags ins gewünschte 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 gängig angesehen werden. KDE macht mit KDEHelp ausgiebig Gebrauch von HTML-Dokumentation: Dieses Programm listet alle installierten KDE-Anwendungen und bietet Zugriff auf deren Benutzerhandbücher. Über ein Hilfemenü erhält 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 früher unter dem Namen LinuxDoc bekannt war. Es enthält eine DTD namens `LinuxDoc`, eine Reihe Dateien, die die Umwandlung in verschiedene Ausgabeformate steuern, und die nötigen Werkzeuge, die die tatsächliche Ersetzung der `LinuxDoc`-Tags vornehmen. Die LinuxDoc-DTD basiert auf der Qwertz-DTD, die entwickelt wurde, um speziell Tag-Übersetzungen für das LaTeX-Satzsystem vorzunehmen. Daher eignet sie sich besonders zum Erzeugen von Dokumenten in vernünftiger Ausdruckqualität. Das Paket selbst bekam seinen Namen, weil es vom LDP (Linux Documentation Project) zur Dokumentation verwendet wurde. Er wurde lediglich deshalb geändert, weil ein SGML-System nicht notwendigerweise auf Linux beschränkt ist, sondern auf jedem Unix-System benutzt werden kann. Sie können natürlich auch Ihre eigene DTD und die zugehörigen "Mappings" schreiben, wenn Sie Lust dazu haben.

Mittlerweile erfüllt eine andere DTD genau so gut den selben Zweck: die DocBook-DTD. DocBook hat einige offensichtliche Vorteile gegenüber LinuxDoc, insbesondere, weil sie bessere Tags und Mappings für Tabellen und Grafikeinbindung enthält (was nicht heißt, dass LinuxDoc das nicht auch könnte...). Die SGML-Tools unterstützen 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 Gründe:

- Dokumentation in LinuxDoc lässt sich leicht schreiben.

- Die Installation der SGML-Tools der 1.x-Versionen zum Gebrauch mit LinuxDoc ist weitaus einfacher.

- KDE bringt ein zusätzliches Werkzeug namens `ksgml2html` mit, das die HTML-Ausgabe des 1.x-SGML-Tools `sgml2html` in den KDE-typischen Dokumentationsstil überführt.

Meine persönliche -- beim Schreiben der KDevelop-Handbücher gewonnene -- Erfahrung mit der LinuxDoc-DTD ist, dass sie sehr einfach ist und alle Bedürfnisse abdeckt, die beim Erstellen von Dokumentation so anfallen. Da die Lernkurve sehr steil verläuft, werden vermutlich auch Sie innerhalb kürzester Zeit zum SGML-Tools/LinuxDoc-Guru aufsteigen und eine Menge Zeit sparen, die es bräuchte, um sich in ein Formatierungssystem a la TeX (für die Druckausgabe Ihrer Dokumentation) oder eine Auszeichnungssprache für die HTML-Ausgabe einzuarbeiten.

Einer der Hauptgründe, immer noch die SGML-Tools 1.x zu verwenden, ist sicherlich auch der, dass die meisten Distributionen dieses Paket und all die zusätzlichen Werkzeuge mitbringen, die Sie zur Umwandlung in andere Ausgabeformate benötigen. Das macht die Installation so einfach wie möglich, und dass das Schreiben selbst nicht sehr kompliziert ist, werden Sie selbst sehen. Folgende Ausgabeformate können Sie mit den SGML-Tools erzeugen:

- HTML. Das spezielle KDE-Look&Feel erhalten Sie, wenn Sie zusätzlich `ksgml2html` benutzen.

- Einfachen, unformatierten Text.

- GNU-info.

- Das Lyx-Format.

- TeX, DVI, PostScript und PDF.

- Das Rich-Text-Format (RTF).

Zurück | Anfang | Vor
Kontexthilfe-Buttons |  | Was die Dokumentation schon enthält