Editing the master document

GTK-Doc produces documentation in DocBook SGML/XML. When processing the inline source comments, the GTK-Doc tools generate one documentation page per class or module as a separate file. The master document includes them and place them in an order.

While GTK-Doc creates a template master document for you, later runs will not touch it again. This means that one can freely structure the documentation. That includes grouping pages and adding extra pages. GTK-Doc has now a test suite, where also the master-document is recreated from scratch. Its a good idea to look at this from time to time to see if there are some new goodies introduced there.

Do not create tutorials as extra documents. Just write extra chapters. The benefit of directly embedding the tutorial for your library into the API documentation is that it is easy to link for the tutorial to symbol documentation. Apart chances are higher that the tutorial gets updates along with the library.

So what are the things to change inside the master document? For a start is only a little. There are some placeholders (text in square brackets) there which you should take care of.

Example 4-2 Master document header

<bookinfo>
  <title>MODULENAME Reference Manual</title>
  <releaseinfo>
    for MODULENAME [VERSION]
    The latest version of this documentation can be found on-line at
    <ulink role="online-location" url="http://[SERVER]/MODULENAME/index.html">http://[SERVER]/MODULENAME/</ulink>.
  </releaseinfo>
</bookinfo>

<chapter>
  <title>[Insert title here]</title>

In addition a few option elements are created in commented form. You can review these and enable them as you like.

Example 4-3 Optional part in the master document

  <!-- enable this when you use gobject introspection annotations
  <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
  -->

Finally you need to add new section whenever you introduce one. The gtkdoc-check tool will remind you of newly generated xml files that are not yet included into the doc.

Example 4-4 Including generated sections

  <chapter>
    <title>my library</title>
      <xi:include href="xml/object.xml"/>
      ...

Editing the master document

About