Ú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.

Příklad 4-2Hlavička hlavního dokumentu
<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.

Příklad 4-3Volitelná část hlavního dokumentu
  <!-- 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é.

Příklad 4-4Vkládání generovaných oddílů
  <chapter>
    <title>moje knihovna</title>
      <xi:include href="xml/object.xml"/>
      …