Handbok för GTK-Doc
Användarhandbok för utvecklare med användningsinstruktioner för GTK-Doc.

Introduktion
Detta kapitel introducerar GTK-Doc och ger en överblick över vad det är och hur det används.

Vad är GTK-Doc?
GTK-Doc används för att dokumentera C-kod. Det används vanligen för att dokumentera det publika API:t för bibliotek, så som GTK+- och GNOME-biblioteken. Men det kan också användas för att dokumentera programkod.

Hur fungerar GTK-Doc?
GTK-Doc fungerar så att det använder dokumentation för funktioner placerad inuti källkodsfilerna i speciellt formaterade kommentarsblock, eller dokumentation som lagts till i mallfilerna som GTK-Doc använder (notera dock att GTK-Doc endast kommer att dokumentera funktioner som deklarerats i huvudfiler; det kommer inte att producera utdata för statiska funktioner).
GTK-Doc består av ett antal python-skript som vart och ett utför olika steg i processen.
Det finns 5 huvudsteg i processen:
Skriva dokumentationen. Författaren fyller i källkodsfilerna med dokumentation för varje funktion, makro, union, etc. (Tidigare matades informationen in i genererade mallfiler, något som inte rekommenderas längre).
Samla ihop information om koden. gtkdoc-scan söker genom huvudfilerna för koden och letar efter deklarationer av funktioner, makron, uppräkningar, strukturer och unioner. Det skapar sedan filen <module>-decl-list.txt som innehåller en lista över deklarationerna, och placerar dem i avsnitt efter vilken huvudfil de finns i. Vid första körningen kommer denna fil att kopieras till <module>-sections.txt. Författaren kan, genom att omarrangera avsnitten och ändra ordningen för deklarationerna inom dem, framställa den önskade, slutgiltiga ordningen. Den andra filen det genererar är <module>-decl.txt. Denna fil innehåller de fullständiga deklarationerna som hittats av detektorn. Om man av något skäl vill att vissa symboler ska visas i dokumentation då den fullständiga deklarationen inte kan hittas av detektorn, eller om deklarationen ska visas annorlunda, kan man placera rader liknande de som finns i <module>-decl.txt i <module>-overrides.txt.
gtkdoc-scangobj kan också användas för att dynamiskt fråga ett bibliotek om vilka GObject-underklasser det exporterar. Det sparar information om varje objekts position i klasshierarkin och om vilka GObject-egenskaper och signaler det tillhandahåller.
gtkdoc-scanobj bör inte användas längre. Det behövdes tidigare när GObject fortfarande var GtkObject inuti gtk+.
Generera XML och HTML/PDF. gtkdoc-mkdb förvandlar mallfilerna till XML-filer i underkatalogen xml/. Om källkoden innehåller dokumentation över funktioner i speciella kommentarsblock, så kommer denna att sammanfogas här. Om det inte finns några tmpl-filer som används så kommer det endast att läsa dokumentation från källkoden och introspektionsdata.
gtkdoc-mkhtml förvandlar XML-filer till HTML-filer i underkatalogen html/. På samma sätt förvandlar gtkdoc-mkpdf XML-filerna till ett PDF-dokument kallat <package>.pdf.
Filer i xml/- och html/-katalogerna skrivs alltid över. Man bör aldrig redigera dem direkt.
Fixa korsreferenser mellan dokument. Efter att ha installerat HTML-filerna kan gtkdoc-fixxref köras för att fixa korsreferenser mellan separata dokument. Till exempel GTK+-dokumentationen innehåller många korsreferenser till typer som dokumenterats i GLib-manualen. När tar-arkivet med källkod skapas för distribution, förvandlar gtkdoc-rebase alla externa länkar till webblänkar. När (förgenererad) distribuerad dokumentation installeras kommer samma program att försöka att förvandla länkarna tillbaka till lokala länkar (i de fall där dokumentationen finns installerad).

Hämta GTK-Doc

Krav
python 2/3 - huvudskripten är skrivna i python.
xsltproc - xslt-processorn från libxslt xmlsoft.org/XSLT/
docbook-xsl - docbook xsl-stilmallar sourceforge.net/projects/docbook/files/docbook-xsl
Endera av source-highlight, highlight eller vim - valfritt - används för syntaxfärgning av exempel

Om GTK-Doc
(FIXME)
(Historia, författare, webbsidor, sändlistor, licens, framtida planer, jämförelse med andra liknande system.)

Om denna handbok
(FIXME)
(vem är den avsett för, var kan du få tag i den, licens)