Příručka ke GTK-Doc
Uživatelská příručka pro vývojáře s instrukcemi k používání GTK-Doc.

Úvod
Tato kapitola je úvodem do GTK-Doc a podává přehled o tom, co to je a jak to použít.

Co je to GTK-Doc?
GTK-Doc se používá k dokumentaci kódu jazyka C. Typické použití je pro dokumentaci veřejného API knihoven, jako jsou knihovny GTK+ a GNOME. Lze jej ale použít i k dokumentaci aplikačního kódu.

Jak GTK-Doc pracuje?
GTK-Doc pracuje na základě dokumentace funkcí umístěné přímo v souborech se zdrojovým kódem ve speciálně formátovaných komentářových blocích, nebo dokumentace přidané do souborů šablon, které GTK-Doc používá (ačkoliv je nutno poznamenat, že GTK-Doc dokumentuje pouze funkce, které jsou deklarované v hlavičkových souborech; pro statické funkce žádný výstup nevytváří).
GTK-Doc sestává z řady skriptů v jazyce Python, z nichž každý provádí jinou část procesu.
Celý proces se skládá z pěti hlavních kroků:
Psaní dokumentace. Autor doplní soubory se zdrojovým kódem dokumentací pro každou funkci, makro, strukturu atd. (Dříve se informace vkládaly do souborů s vygenerovanými šablonami, což se již nedoporučuje).
Shromáždění informací o kódu. gtkdoc-scan projde hlavičkové soubory kódu a vyhledá při tom deklarace funkcí, maker, výčtů, struktur a sjednocení. Tím se vytvoří soubor <module>-decl-list.txt obsahující seznam deklarací, které jsou rozdělené do oddílů podle hlavičkového souboru, ze kterého pochází. Při prvním spuštění se tento soubor zkopíruje do <module>-sections.txt. Autor může změnit uspořádání oddílů a jejich pořadí v rámci deklarací tak, jak to požaduje ve výsledku. Druhý soubor, který se vytvoří, je <module>-decl.txt. Tento soubor obsahuje úplné deklarace nalezené při procházení. Pokud byste z nějakého důvodu chtěli v dokumentaci zahrnout symbol, který při procházení nebyl nalezen, nebo jeho deklarace vypadá jinak, můžete jej umístit podobně jako v <module>-decl.txt do <module>-overrides.txt.
Dá se také použít gtkdoc-scanobj k dynamickým dotazům do knihoven na podtřídy objektu GObject, které exportují. Tím se uloží informace o pozici každého objektu v hierarchii tříd a o argumentech a signálech objektu GObject, které poskytují.
gtkdoc-scanobj by se ale již používat nemělo. Bylo zapotřebí v minulosti, kdy byl GObject ještě GtkObject v rámci gtk+.
Generování XML a HTML/PDF. gtkdoc-mkdb přemění soubory šablon na soubory XML v podsložce xml/. Pokud zdrojový kód obsahuje dokumentaci funkcí za použití speciálních komentářových bloků, tak zde se sloučí. V případě, že není použitý žádný soubor šablon, načte se dokumentace pouze ze zdrojového kódu a introspektivních dat.
gtkdoc-mkhtml převádí soubory XML na soubory HTML v podsložce html/. Obdobně gtkdoc-mkpdf převádí soubory XML na dokument PDF nazvaný <balíček>.pdf.
Soubory ve složkách xml/ a html/ jsou vždy přepsány. Nikdy by neměly být upravovány přímo.
Opravy křížových odkazů mezi dokumenty. Po nainstalování souborů HTML můžete spustit gtkdoc-fixxref, aby se opravily křížové odkazy mezi samostanými dokumenty. Například dokumentace GTK+ obsahuje křížové odkazy na typy zdokumentované v příručce GLib. Když vytváříte zdrojový balíček pro distribuci, gtkdoc-rebase předělá všechny externí odkazy na webové odkazy. Když se distribuovaná (předgenerovaná) dokumentace instaluje, pokusí se tatáž aplikace předělat odkazy zpátky na místní odkazy (na dokumenty, které jsou nainstalované).

Jak získat GTK-Doc?

Požadavky
Python 2/3 – hlavní skripty jsou v jazyce Python.
xsltproc – procesor xslt z knihovny libxslt xmlsoft.org/XSLT/
docbook-xsl – stylopisy XSL pro docbook sourceforge.net/projects/docbook/files/docbook-xsl
Něco z source-highlight, highlight nebo vim – (volitelné) používá se pro zvýraznění syntaxe u příkladů

O aplikaci GTK-Doc
(DOPLNIT)
(Historie, autoři, webové stránky, poštovní konference, licence, plány do budoucna, srovnání s ostatními podobnými systémy.)

O této příručce
(DOPLNIT)
(k čemu je určená, kde ji můžete získat, licence)