Bearbeiten des Master-Dokuments
GTK-Doc erstellt die Dokumentation in DocBook-SGML/XML. Beim Verarbeiten der in den Quellcode eingebetteten Kommentare erzeugt GTK-Doc eine Dokumentationsseite pro Klasse oder Modul als separate Datei. Das Hauptdokument schließt diese ein und setzt sie in die passende Reihenfolge.
Während GTK-Doc ein Vorlagen-Hauptdokument für Sie erstellt, wird eine spätere Ausführung es nicht mehr verändern. Das bedeutet, dass Sie das Dokument beliebig strukturieren können. Dies schließt Gruppieren von Seiten und Hinzufügen von zusätzlichen Seiten ein. GTK-Doc hat eine neue Test-Suite, wo auch das Hauptdokument von Grund auf neu erstellt wird. Es ist ratsam, sich diese von Zeit zu Zeit anzusehen und zu schauen, ob dort einige Neuigkeiten eingeführt werden.
Erstellen Sie keine Schritt-für-Schritt-Anleitungen als zusätzliche Dokumente. Schreiben Sie lediglich zusätzliche Kapitel. Der Vorteil des direkten Einbettens einer Anleitung für Ihre Bibliothek in die API ist die Möglichkeit der einfachen Verknüpfung der Schritt-für-Schritt-Anleitung zur Symboldokumentation. Außerdem sind die Chancen größer, dass die Anleitung die gleichen Aktualisierungen erfährt wie die Bibliothek selbst.
Was sollte nun innerhalb des Master-Dokuments geändert werden? Zunächst recht wenig. Es gibt einige Platzhalter (Text in eckigen Klammern), die Sie beachten sollten.
<bookinfo> <title>MODULENAME Reference Manual</title> <releaseinfo> for MODULENAME [VERSION] The latest version of this documentation can be found on-line at <ulink role="online-location" url="http://[SERVER]/MODULENAME/index.html">http://[SERVER]/MODULENAME/</ulink>. </releaseinfo> </bookinfo> <chapter> <title>[Insert title here]</title>
Zusätzlich werden einige Optionselemente in Kommentarform erstellt. Sie können sich diese anschauen und aktivieren, wenn Sie wollen.
<!-- aktivieren Sie dieses, wenn sie gobject introspection-Anmerkungen verwenden <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include> -->
Schlussendlich müssen Sie einen neuen Abschnitt explizit einfügen, sobald Sie einen öffnen. Das Werkzeug gtkdoc-check erinnert Sie an neu erzeugte XML-Dateien, die in der Dokumentation noch nicht erfasst sind.
<chapter> <title>my library</title> <xi:include href="xml/object.xml"/> ...