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 Perl-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 Dokumentatione 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 irgendwine GObject-Subklasse anzufragen, die sie exportiert. Es speichert Informtionen über jede Objektposition in der Klassenhierachie 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 der »Vorlage«-Dateien. gtkdoc-mktmpl erstellt einige Dateien im Unterordner tmpl/ mit Hilfe der Informationen aus dem ersten Schritt. (Bedenken Sie, dass dies wiederholt ausgeführt werden kann. Es wird versucht sicherzustellen, dass keine Dokumentation jemals verloren geht.)
Seit GTK-Doc 1.9 sind diese Vorlagen nicht mehr notwendig. Wir ermutigen die Entwickler, die Dokumentation innerhalb des Codes zu halten. gtkdocize unterstützt nun die Option --flavour no-tmpl, wodurch ein Makefile gewählt wird, welches die Verwendung der Vorlagen komplett umgeht. Falls Sie niemals Dateien im Vorlagenordner manuell bearbeitet oder aus älteren GTK-Doc-Versionen importiert haben, sollten Sie den Ordner löschen, z.B. in der Versionsverwaltung.
-
Erstellen des SGML/XML und HTML/PDF. gtkdoc-mkdb wandelt die Vorlagen-Dateien in SGML- oder XML-Dateien in den Unterordner sgml/ oder 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. Wir empfehlen Docbook XML zu verwenden.
gtkdoc-mkhtml konvertiert die SGML/XML-Dateien in HTML-Dateien im Unterordner html/. Ebenso konvertiert gtkdoc-mkpdf die SGML/XML-Dateien in ein PDF-Dokument namens <package>.pdf.
Dateien in sgml/ oder 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 die selbe Anwendung versuchen, Verweise zurück in lokale Verweise umzuwandeln (wo diese Dokumente installiert werden).