GTK-Doc-Handbuch
Benutzerhandbuch für Entwickler mit Anweisungen für die Benutzung von GTK-Doc.

Einführung
Dieses Kapitel führt in GTK-Doc ein und gibt einen Überblick darüber, worum es sich dabei handelt und wie es benutzt wird.

Was ist GTK-Doc?
GTL-Doc wird zur Dokumentation von C-Code verwendet. Üblicherweise wird damit die öffentliche API von Bibliotheken dokumentiert, wie die der GTK+- und GNOME-Bibliotheken. Es kann aber auch zur Dokumentation von Anwendungscode verwendet werden.

Wie funktioniert GTK-Doc?
GTK-Doc verwendet Funktionsdokumentationen, die sich in den Quelldateien innerhalb speziell formatierter Kommentarblöcke befinden, oder Dokumentation, die zu den von GTK-Doc verwendeten Vorlagendateien hinzugefügt wurde. Beachten Sie jedoch, dass GTK-Doc nur Funktionen dokumentieren wird, die in den Header-Dateien deklariert sind. Es erstellt keine Ausgaben für statische Funktionen.
GTK-Doc besteht aus einer Anzahl von Python-Skripten, wovon jedes einen bestimmten Schritt in dem Prozess ausführt.
Dieser Vorgang umfasst fünf Hauptschritte:
Schreiben der Dokumentation. Der Autor ergänzt die Quelldateien um die Dokumentation für jede Funktion, jedes Makro usw. In der Vergangenheit wurden diese Informationen in erstellte Vorlagendateien eingegeben. Dies wird nicht mehr empfohlen.
Informationen über den Code sammeln. gtkdoc-scan analysiert die Header-Dateien des Code und sucht nach Funktionsdeklarationen, Macros, enum (Aufzählung), struct (Strukturen) und »unions«. Es erstellt die Datei <module>-decl-list.txt, welche eine Liste der Deklarationen enthält, und platziert diese in Abschnitte entsprechend der Header-Dateien, in der sie sind. Bei erster Ausführung wird diese Datei nach <module>-sections.txt kopiert. Der Autor kann die Abschnitte und die Reihenfolge der Deklarationen in gewünschter Reihenfolge neu anordnen. Die zweite erstellte Datei ist <module>-decl.txt. Diese Datei enthält alle Deklarationen, die vom Scanner gefunden wurden. Wenn aus irgendeinem Grund einige Symbole in der Dokumentation erscheinen sollen, wenn die volle Deklaration nicht vom Scanner gefunden werden kann oder die Deklaration anders erscheinen soll, kann man Entitäten ähnlich derer in<module>-decl.txt innerhalb <module>-overrides.txt platzieren.
gtkdoc-scangobj kann ebenso dazu verwendet werden, dynamisch eine Bibliothek über irgendeine GObject-Subklasse anzufragen, die sie exportiert. Es speichert Informationen über jede Objektposition in der Klassenhierarchie und über alle GObjekt-Eigenschaften und -Signale, die es bietet.
gtkdoc-scanobj sollte nicht weiter verwendet werden. Es war in der Vergangenheit notwendig, als GObject noch ein GtkObject innerhalb von gtk+ war.
Erstellen des SGML/XML und HTML/PDF. gtkdoc-mkdb wandelt die Vorlagen-Dateien in XML-Dateien in den Unterordner xml/ um. Wenn der Quellcode Dokumentation über Funktionen mittels speziellen Kommentarblöcken enthält, so wird diese hier eingepflegt. Wenn keine tmpl-Dateien eingesetzt werden, so wird nur Dokumentation von den Quell- und introspection-Daten gelesen.
gtkdoc-mkhtml konvertiert die XML-Dateien in HTML-Dateien im Unterordner html/. Ebenso konvertiert gtkdoc-mkpdf die XML-Dateien in ein PDF-Dokument namens <package>.pdf.
Dateien in xml/ und html/-Ordnern werden immer überschrieben. Niemand sollte diese direkt bearbeiten.
Querverweise zwischen Dokumenten korrigieren. Nach Intallation der HTML-Dateien kann gtkdoc-fixxref ausgeführt werden, um alle Querverweise zwischen separaten Dokumenten zu korrigieren. Die GTK+-Dokumentation zum Beispiel enthält viele Querverweise zu Typen, die im GLib-Handbuch dokumentiert sind. Beim Erstellen des Quellen-tarball zur Verteilung wandelt gtkdoc-rebase alle externen Verweise in Web-Verweise um. Beim Installieren verteilter (zuvor erstellter) Dokumente wird dieselbe Anwendung versuchen, Verweise zurück in lokale Verweise umzuwandeln (wo diese Dokumente installiert werden).

GTK-Doc bekommen

Erfordernisse
Python 2/3 - Die Hauptskripte wurden in Python geschrieben.
xsltproc - der xslt-Verarbeiter von libxslt xmlsoft.org/XSLT/
docbook-xsl - die docbook xsl-Stilvorlagen sourceforge.net/projects/docbook/files/docbook-xsl
source-highlight, highlight oder vim - optional - für Syntax-Hervorhebung von Beispielen

Info zu GTK-Doc
(FIXME)
(Geschichte, Autoren, Webseiten, Mailingliste, Lizenz, Zukunftspläne, Vergleich mit ähnlichen Systemen)

Über dieses Handbuch
(FIXME)
(wofür es bestimmt ist, wo Sie es erhalten können, Lizenz)