Das KDevelop-Programmierhandbuch: Leitfaden zur C++-Anwendungsentwicklung fr das K Desktop Environment (KDE) mit Hilfe der KDevelop-IDE in der Version 1.2 | ||
---|---|---|
Zurück | Kapitel 9. Erweitern der Dokumentation mit SGML | Vor |
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-Gerstdatei enthlt, whrend der Autor die generierten HTML-Dateien bearbeitete. Das fhrt zu Problemen bei der bersetzung in andere Sprachen: Die jeweiligen bersetzer mssen jede HTML-Datei einzeln bearbeiten, ohne eine Mglichkeit zu haben, ihre Arbeit auch in anderen Formaten wieder verwenden zu knnen (letzteres gilt natrlich auch fr die originale englische Fassung). Eine ziemlich kurzsichtige und verfahrene Situation, deren Ursache meiner Meinung nach darin liegt, dass viele Autoren ber HTML-Kenntnisse verfgen, jedoch kein SGML knnen. 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 ntzlich) 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.
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.
Verwendet man LinuxDoc, folgt als Nchstes ein Tag, das den Anfang eines bestimmten Dokumenttyps markiert. Die DTD bietet eine ganze Reihe verschiedener Stile an, aus der Sie, abhngig von Zweck und Lnge des Dokuments, einen passenden auswhlen. Folgende Formate stehen zur Wahl:
&;notes&; fr kurze Erluterungen.
&;article&; wird fr Artikel von ca. 10--20 Seiten empfohlen. Diesen Dokumenttyp verwenden die KDevelop-Vorlagen und die meisten KDE-Anwendungen.
Lngere Artikel formatiert man als &;report&;.
&;book&; eignet sich zum Schreiben dicker Bcher -- die KDevelop-Handbcher wurden in diesem Format verfasst.
&;slides&; benutzt man fr Prsentationen. Als Ausgabeformat werden Sie hier normalerweise auf LaTeX zurck 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 erwhnt 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 heit. Da werden die Handbcher zu echten Bchern, 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: Fr einen &;article&; wre das &</;article&;.
Auf die Festlegung der Dokumentstruktur folgt ein Abschnitt, der alle Elemente einer Titelseite beschreibt. Die automatisch erzeugte Vorlage macht davon zwar keinen groen Gebrauch, legt aber dennoch Titel (&;title&;), Autoren (&;author&;) und Datum (&;date&;) fest und deckt dabei das Wichtigste fr die meisten Einsatzzwecke ab. Wenn Sie allerdings die &;book&;-Struktur einsetzen, liegt es nahe, eine komplette Titelseite zu definieren. Folgende Tags kommen dafr 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 fr 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. Mrz 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 enthlt alles, was eine gngige 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, fr die der Autor die Dokumentation verfasste; Sie knnten ebenso gut den Namen Ihres Teams an dieser Stelle einfgen, so, wie ich es hier getan habe. &;abstract&; wiederum enthlt 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 Rckseite des Titels (gemeinsam mit dem Copyright etc.) erwarten wrden. Doch auch das ist kein unberwindbares Problem: Schlielich lsst sich das bei der LaTeX-Ausgabe erzeugte TeX-File editieren.
Die LinuxDoc-DTD definiert eine Reihe von Tags fr die verschiedenen Verzeichnisarten, wie sie in nicht allzu exotischen Publikationsformen auftauchen. Dies sind
&;toc&; fr das Inhaltsverzeichnis,
&;lof&; fr das Abbildungsverzeichnis und
&;lot&; fr das Tabellenverzeichnis.
Diese Start-Tags mssen nicht unbedingt mit einem Ende-Tag abgeschlossen werden; sie werden einfach nach der Titelseite und vor dem tatschlichen Dokumentanfang und den folgenden Kapiteln und Abschnitten eingefgt.
Wenn Sie spter die Stichworte fr den Index am Ende des Dokuments markieren wollen, knnen Sie sich aus einem Pool von vier verschiedenen Tags bedienen: Zwei belassen den indizierten Ausdruck auf der Seite, die anderen beiden markieren Indexeintrge, die nicht im Flietext auftauchen sollen.
&;idx&; markiert einen "ganz normalen" Indexeintrag,
&;cdx&; einen, der in Listingsschrift erscheinen soll,
&;nidx&; leitet einen Indexeintrag ein, der nicht im Flietext erscheinen soll, und
&;ncdx&; ist das im Flietext "unsichtbare" quivalent zum cdx-Indexeintrag.
Alle Backends (Das sind Werkzeuge, die SGML-Tags in das jeweilige Dokumentenformat bersetzen.) auer sgml2latex ignorieren diese Tags. sgml2latex erstellt ein Index-File namens index.idx, dass sich mit makeindex index.idx in einen TeX-Index umwandeln lsst. Der Index selbst kann anschlieend mit \printindex in die TeX-Ausgabedatei eingefgt 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 fr den Index erweitere...
Nachdem wir uns bislang mit der Einzelheiten der Dokumentenstruktur auseinander gesetzt haben, kommen wir nun zum tatschlichen Inhalt. Abhngig vom Strukturtyp leiten wir den mit einem &;sect&;-Tag ein, ein Dokument vom Typ &;book&; beginnt man hingegen mit &;chapt&;, das ein Kapitel beginnt.
Anschlieend erlauben Ihnen vier Unterkapitelebenen (&;sect1&;, &;sect2&; etc.) pro Kapitel eine Feinstrukturierung des Inhalts.
Auf das Kapitelstarttag folgt gewhnlich eine (optionale) berschrift. Dafr nutzen Sie die Tags &;title&; und &</;title&;. Mit einem &;p&; leiten Sie dann den tatschlichen Unterkapiteltext ein. Innerhalb eines solchen Absatzes (das p stammt von paragraph) knnen Sie Ihr Dokument mit Aufzhlungen, nummerierten und beschreibenden Listen fllen. Auch Zitate, Code-Schnipsel u.. finden hier -- von den entsprechenden Tags umrahmt -- ihren Platz. Eine komplette Aufzhlung bieten die Dokumentationsrichtlinien zuu den sgmltools. Im Kapitel ber "special characters" werden Sie fndig, wenn Sie nach der Schreibweise fr Sonderzeichen (Umlaute u.a. Buchstaben aus nicht-englischen Alphabeten, Klammern, Schrgstriche, das Trademark-Symbol u..) suchen.