Úprava hlavního dokumentu
GTK-Doc produkuje dokumentaci v SGML/XML standardu DocBook. Když se zpracovávají komentáře vložené ve zdrojovém kódu, generují nástroje GTK-Doc pro každou třídu nebo modul jednu stránku dokumentace jako samostatný soubor. Všechny jsou pak uvedené seřazené v hlavním dokumentu.
Jakmile pro vás GTK-Doc vytvoří šablonu hlavního dokumentu, při pozdějším spuštění již do ní nezasahuje. To znamená, že můžete dokumentaci bez omezení strukturovat. A to včetně seskupování stránek a přidávání doplňujících stránek. GTK-Doc má v současnosti testovací sadu, ve které je také hlavní dokument vytvořen znovu od začátku. Je dobré se čas od času do něj nahlédnout, jestli se v něm neobjevily nějaké nové věci.
Nevytvářejte výukové dokumenty (tutorial) jako zvláštní dokumenty. Napište je jako zvláštní kapitolu. Výhodou přímého spojení výukového dokumentu k vaší knihovně s dokumentací API je snadné vytváření odkazů pro symboly. Zvyšuje se tím také šance, že výukový dokument bude reflektovat aktualizace v knihovně.
Nyní se podívejme, které věci můžete v hlavním dokumentu měnit. Pro začátek je to pouze název. Je zde několik zástupných hodnot (text v hranatých závorkách), o které byste se měli postarat.
<bookinfo> <title>Referenční příručka k NÁZEV_MODULU</title> <releaseinfo> pro NÁZEV_MODULU [VERSION] Nejvnovější verzi tohoto dokumentu můžete najít on-line na <ulink role="online-location" url="http://[SERVER]/NÁZEV_MODULU/index.html">http://[SERVER]/NÁZEV_MODULU/</ulink>. </releaseinfo> </bookinfo> <chapter> <title>[Insert title here]</title>
Navíc se vytvoří pár volitelných prvků ve formě komentáře. Můžete si je projít a případně povolit.
<!-- enable this when you use gobject introspection annotations <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include> -->
Nakonec musíte přidat nový oddíl, kdekoliv chcete. Nástroj gtkdoc-check vás upozorní na nově vygenerované soubory XML, které zatím nejsou v dokumentaci zahrnuté.
<chapter> <title>moje knihovna</title> <xi:include href="xml/object.xml"/> …