Das K Desktop Environment

9.3. Schreiben von SGML-Dokumentation

Die Erfahrung lehrt, dass SGML (um es genau zu sagen: die LinuxDoc-DTD) Neulingen doch gewisse Schwierigkeiten bereitet. Wirft man einen Blick auf eine Handvoll KDE-Anwendungen, so bemerkt man rasch, dass eine nicht unbedeutende Anzahl lediglich die SGML-Gerüstdatei enthält, während der Autor die generierten HTML-Dateien bearbeitete. Das führt zu Problemen bei der Übersetzung in andere Sprachen: Die jeweiligen Übersetzer müssen jede HTML-Datei einzeln bearbeiten, ohne eine Möglichkeit zu haben, ihre Arbeit auch in anderen Formaten wieder verwenden zu können (letzteres gilt natürlich auch für die originale englische Fassung). Eine ziemlich kurzsichtige und verfahrene Situation, deren Ursache meiner Meinung nach darin liegt, dass viele Autoren über HTML-Kenntnisse verfügen, jedoch kein SGML können. Das Erlernen einer neuen Auszeichnungssprache vermeidet man gern, und so muss das generierte HTML als Vorlage herhalten. Sobald Sie jedoch heraus finden, wie einfach (und nützlich) SGML mit LinuxDoc ist, werden Sie sicher einsehen, dass es sich lohnt, die paar Tags mehr zu lernen, aus denen SGML-Formatierung besteht.

Die folgenden Abschnitte stellen Ihnen die wichtigsten Bestandteile einer LinuxDoc-SGML-Datei vor und zeigen Ihnen, wie Sie Ihre Dokumentation erweitern.

9.3.1. Die DTD-Deklaration

Jede SGML-Datei, ganz gleich, welche DTD Sie verwenden, beginnt immer mit der DTD-Deklaration. Hier teilen Sie dem SGML-Parser mit, welche DTD er verwenden soll. Daher ist der erste Tag (ein spitz geklammerter Ausdruck wie &<;meintag&>; mein Inhalt &<;/meintag&>;) in einem SGML-Dokument immer der DOCTYPE:

&<;!doctype linuxdoc system&>;

Diese Zeile weist Ihren SGML-Formatierer an, die LinuxDoc-DTD zu verwenden.

9.3.1.1. Die Dokumentstruktur

Verwendet man LinuxDoc, folgt als Nächstes ein Tag, das den Anfang eines bestimmten Dokumenttyps markiert. Die DTD bietet eine ganze Reihe verschiedener Stile an, aus der Sie, abhängig von Zweck und Länge des Dokuments, einen passenden auswählen. Folgende Formate stehen zur Wahl:

  • &<;notes&>; für kurze Erläuterungen.

  • &<;article&>; wird für Artikel von ca. 10--20 Seiten empfohlen. Diesen Dokumenttyp verwenden die KDevelop-Vorlagen und die meisten KDE-Anwendungen.

  • Längere Artikel formatiert man als &<;report&>;.

  • &<;book&>; eignet sich zum Schreiben dicker Bücher -- die KDevelop-Handbücher wurden in diesem Format verfasst.

  • &<;slides&>; benutzt man für Präsentationen. Als Ausgabeformat werden Sie hier normalerweise auf LaTeX zurück greifen.

  • Briefe verfassen Sie mit &<;letter&>;,

  • Faxe mit &<;telefax&>; und

  • Manpages unter Zuhilfenahme von &<;manpage&>;.

Denken Sie daran, dass diese Stile lediglich die Struktur des Dokuments (also den allgemeinen Aufbau) beschreiben -- nicht jedoch, wie die Ausgabe letztendlich aussieht. Wie erwähnt benutzt die von KDevelop erzeugte Dokumentvorlage die &<;article&>;-Struktur. Die KDevelop-Dokumentation selbst bildet eine Ausnahme: Sie macht Gebrauch vom &<;book&>;-Format. Der HTML-Ausgabe sieht man diesen Unterschied nicht weiter an -- anders ist das z.B., wenn das Zielformat LaTeX heißt. Da werden die Handbücher zu echten Büchern, in denen -- im Unterschied zu einem Artikel -- jedes Kapitel auf einer separaten Seite beginnt.

Wenn man schon den Beginn eines Dokumentstrukturtyps extra auszeichnet, so liegt es nahe, dass es auch ein Ende-Tag am Schluss der SGML-Datei geben muss: Für einen &<;article&>; wäre das &</;article&>;.

9.3.2. Titelseiten

Auf die Festlegung der Dokumentstruktur folgt ein Abschnitt, der alle Elemente einer Titelseite beschreibt. Die automatisch erzeugte Vorlage macht davon zwar keinen großen Gebrauch, legt aber dennoch Titel (&<;title&>;), Autoren (&<;author&>;) und Datum (&<;date&>;) fest und deckt dabei das Wichtigste für die meisten Einsatzzwecke ab. Wenn Sie allerdings die &<;book&>;-Struktur einsetzen, liegt es nahe, eine komplette Titelseite zu definieren. Folgende Tags kommen dafür in Frage (die Liste wurde dem SGML-Quelltext dieses Handbuchs entnommen):

   1 &<;!doctype linuxdoc system&>;
   2 &<;book&>;
   3 &<;titlepag&>;
   4 &<;title&>;Das KDevelop-Programmierhandbuch
   5 &<;subtitle&>;Leitfaden zur C++-Anwendungsentwicklung für das K Desktop Environment (KDE) mit Hilfe der KDevelop-IDE in der Version 1.2
   6 &<;author&>;
   7 &<;name&>;Ralf Nolden &<;htmlurl url="mailto:Ralf.Nolden@post.rwth-aachen.de"
   8                                    name = "&<;Ralf.Nolden@post.rwth-aachen.de&>;"&>;
   9 &<;inst&>;Das KDevelop-Team
  10 &<;date&>;Version 1.2 , 21. März 2000
  11 &<;abstract&>;
  12 Dieses Handbuch ist selbst Bestandteil der integrierten Entwicklungsumgebung KDevelop 
  13 und unterliegt daher ebenso der GNU General Public License (siehe auch
  14 &<;ref id="Copyright" name="Copyright"&>;).
  15 &</;abstract&>;

Dieses Beispiel enthält alles, was eine gängige Titelseite ausmacht. Das &<;author&>;-Tag wird u.U. noch um ein &<;thanks&>;-Tag erweitert, mit dem Co-Autoren, Lektoren etc. gedankt wird. &<;inst&>; nennt die Organisation oder Firma, für die der Autor die Dokumentation verfasste; Sie könnten ebenso gut den Namen Ihres Teams an dieser Stelle einfügen, so, wie ich es hier getan habe. &<;abstract&>; wiederum enthält eine kurze Zusammenfassung des Inhalts und wird ebenfalls auf der Titelseite platziert. In einer gedruckten Ausgabe ist dies etwas ärgerlich, da Sie diese Kurzbeschreibung hier eher auf der Rückseite des Titels (gemeinsam mit dem Copyright etc.) erwarten würden. Doch auch das ist kein unüberwindbares Problem: Schließlich lässt sich das bei der LaTeX-Ausgabe erzeugte TeX-File editieren.

9.3.3. Indizes und Verzeichnisse

Die LinuxDoc-DTD definiert eine Reihe von Tags für die verschiedenen Verzeichnisarten, wie sie in nicht allzu exotischen Publikationsformen auftauchen. Dies sind

Diese Start-Tags müssen nicht unbedingt mit einem Ende-Tag abgeschlossen werden; sie werden einfach nach der Titelseite und vor dem tatsächlichen Dokumentanfang und den folgenden Kapiteln und Abschnitten eingefügt.

Wenn Sie später die Stichworte für den Index am Ende des Dokuments markieren wollen, können Sie sich aus einem Pool von vier verschiedenen Tags bedienen: Zwei belassen den indizierten Ausdruck auf der Seite, die anderen beiden markieren Indexeinträge, die nicht im Fließtext auftauchen sollen.

Alle Backends (Das sind Werkzeuge, die SGML-Tags in das jeweilige Dokumentenformat übersetzen.) außer sgml2latex ignorieren diese Tags. sgml2latex erstellt ein Index-File namens index.idx, dass sich mit makeindex index.idx in einen TeX-Index umwandeln lässt. Der Index selbst kann anschließend mit \printindex in die TeX-Ausgabedatei eingefügt werden. Ich habe mein LaTeX-Mapping so angepasst, dass es dies automatisch tut, allerdings weiß ich noch nicht genau, wie ich das Inhaltsverzeichnis um den Eintrag für den Index erweitere...

9.3.4. Der Inhalt

Nachdem wir uns bislang mit der Einzelheiten der Dokumentenstruktur auseinander gesetzt haben, kommen wir nun zum tatsächlichen Inhalt. Abhängig vom Strukturtyp leiten wir den mit einem &<;sect&>;-Tag ein, ein Dokument vom Typ &<;book&>; beginnt man hingegen mit &<;chapt&>;, das ein Kapitel beginnt.

Anschließend erlauben Ihnen vier Unterkapitelebenen (&<;sect1&>;, &<;sect2&>; etc.) pro Kapitel eine Feinstrukturierung des Inhalts.

Auf das Kapitelstarttag folgt gewöhnlich eine (optionale) Überschrift. Dafür nutzen Sie die Tags &<;title&>; und &</;title&>;. Mit einem &<;p&>; leiten Sie dann den tatsächlichen Unterkapiteltext ein. Innerhalb eines solchen Absatzes (das p stammt von paragraph) können Sie Ihr Dokument mit Aufzählungen, nummerierten und beschreibenden Listen füllen. Auch Zitate, Code-Schnipsel u.ä. finden hier -- von den entsprechenden Tags umrahmt -- ihren Platz. Eine komplette Aufzählung bieten die Dokumentationsrichtlinien zuu den sgmltools. Im Kapitel über "special characters" werden Sie fündig, wenn Sie nach der Schreibweise für Sonderzeichen (Umlaute u.a. Buchstaben aus nicht-englischen Alphabeten, Klammern, Schrägstriche, das Trademark-Symbol u.ä.) suchen.