Redigera huvuddokumentet

GTK-Doc producerar dokumentation i DocBook SGML/XML. När infogade källkodskommentarer behandlas genererar GTK-Doc en dokumentationssida per klass eller modul som en separat fil. Huvuddokumentet inkluderar dem och placerar dem i en ordning.

Även om GTK-Doc skapar en mall för huvuddokumentet åt dig kommer senare körningar inte att röra det igen. Detta innebär att man är fri att strukturera om dokumentationen. Detta inkluderar att gruppera sidor och lägga till extra sidor. GTK-Doc har numera en testsvit där också huvuddokumentet återskapas från grunden. Det är en bra idé att titta på detta då och då för att se om några nya godsaker införts där.

Skapa inte handledningar som extra dokument. Skriv bara extra kapitel. Fördelen med att bädda in handledningen direkt i ditt biblioteks gränssnittsdokumentation är att det är enkelt att länka från handledningen till symboldokumentationen. Inbäddad är det större chans att handledningen blir uppdaterad tillsammans med biblioteket.

Så vilka saker ska ändras i huvuddokumentet? I början är det väldigt lite. Det finns en del platshållare (text i hakparenteser) som du bör ta hand om.

Exempel 4-2Huvuddokumentets huvud
<bookinfo>
  <title>MODULNAMN handbok</title>
  <releaseinfo>
    för MODULNAMN [VERSION]
    Den senaste versionen av detta dokument kan hittas på nätet på
    <ulink role="online-location" url="http://[SERVER]/MODULNAMN/index.html">http://[SERVER]/MODULNAMN/</ulink>.
  </releaseinfo>
</bookinfo>

<chapter>
  <title>[Infoga titel här]</title>

Dessutom finns det ett antal valfria element som skapas i kommenterad form. Du kan granska dessa och aktivera dem enligt dina egna önskemål.

Exempel 4-3Valfri del i huvuddokumentet
  <!-- aktivera detta om du vill använda gobject introspection-noteringar
  <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
  -->

Slutligen behöver du lägga till ett nytt avsnitt när du infogar det. Verktyget gtkdoc-check kommer att påminna dig om nyligen genererade xml-filer som ännu inte infogats i dokumentationen.

Exempel 4-4Inkludera genererade avsnitt
  <chapter>
    <title>mitt bibliotek</title>
      <xi:include href="xml/object.xml"/>
      ...