Bearbeiten der Abschnittsdatei
Die Abschnittsdatei wird verwendet, um die Dokumentations-Ausgaben von GTK-Doc zu organisieren. Man gibt an, welches Symbol zu welchem Modul oder welcher Klasse gehört und regelt die Sichtbarkeit (öffentlich oder privat).
Die Abschnittsdatei ist eine reine Textdatei mit Markierungen, welche die Abschnitte voneinander trennen. Leere Zeilen werden ignoriert und Zeilen, die mit »#« beginnen, werden als Kommentarzeilen behandelt.
Zwar lassen die Markierungen die Datei wie XML erscheinen, doch der Schein trügt. Bitte schließen Sie keine Markierungen wie <SUBSECTION>.
<INCLUDE>libmeep/meep.h</INCLUDE> <SECTION> <FILE>meepapp</FILE> <TITLE>MeepApp</TITLE> MeepApp <SUBSECTION Standard> MEEP_APP ... MeepAppClass meep_app_get_type </SECTION>
Die Markierung <FILE> ... </FILE> wird verwendet, um den Dateinamen ohne Suffix anzugeben. Zum Beispiel wird »<FILE>gnome-config</FILE>« dazu führen, dass der Deklarationsabschnitt in die Vorlage-Datei tmpl/gnome-config.sgml ausgegeben wird, welche in die DocBook-XML-Datei sgml/gnome-config.sgml oder die DocBook-XML-Datei xml/gnome-config.xml umgewandelt wird. (Der Name der HTML-Datei basiert auf dem Modulnamen und dem Abschnittstitel. Für GObject basiert er auf dem GObject-Klassennamen in Kleinbuchstaben).
Das Tag <TITLE> ... </TITLE> wird zur Angabe des Abschnitttitels verwendet. Es ist nur nützlich bevor die Vorlagen (falls verwendet) anfangs erstellt werden, weil der Titel in der Vorlage diesen überschreibt. Wenn man das SECTION-Kommentar in den Quellen einsetzt, ist dies überflüssig.
Sie können Objekte im Abschnitt mittels der Markierung <SUBSECTION> gruppieren. Derzeit gibt es eine Leerzeile zwischen Unterabschnitten im Inhaltsangabe-Abschnitt aus. Sie können auch <SUBSECTION Standard> für Standard GObject-Deklarationen verwenden (z.B. Funktionen wie g_object_get_type und Makros wie G_OBJECT(), G_IS_OBJECT() etc.). Derzeit werden diese nicht in die Dokumentation aufgenommen. Sie können auch <SUBSECTION Private> für private Deklarationen verwenden, welche nicht ausgegeben werden. Dies ist eine praktische Möglichkeit, Warnmeldungen bezüglich ungenutzter Deklarationen zu vermeiden. Wenn Ihre Bibliothek private Typen enthält, die nicht in der Objekthierarchie und der Liste der implementierten oder benötigten Schnittstellen erscheinen sollen, fügen Sie diese zu einem »Private«-Unterabschnitt hinzu. Ob Sie GObject oder GObjectClass wie Structs im öffentlichen oder im Standardabschnitt einsetzen, hängt davon ab, ob öffentliche Einträge vorhanden sind (Variablen, vmethods).
Sie können auch <INCLUDE> ... </INCLUDE> verwenden, um die #include-Dateien anzugeben, die in den Abschnitten zur Inhaltsangabe gezeigt werden. Es enthält eine durch Kommata getrennte Liste von #include-Dateien ohne eckige Klammern. Wenn Sie es außerhalb aller Abschnitte festlegen, wirkt es in allen Abschnitten bis zum Dateiende. Wenn Sie es innerhalb eines Abschnitts festlegen, wirkt es nur in diesem Abschnitt.