编辑主文档

GTK-Doc 以 DocBook SGML/XML 格式生成文档。当处理源代码内嵌注释时, GTK-Doc 工具以独立文件为每个类或模块生成一个文档页。主文档包含了它们并且将它们按顺序排列。

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.

不要把教程(tutorial)当作额外的文档来编写。写成额外的章节即可。把你的库教程直接放入API文档的好处就是教程与符号文档之间的链接很容易。另外教程与库一同升级时分离的机会也更高。

那么什么是主文档内部要修改的东西呢?开始只是一点点东西。有一些占位标识(在方括号内部的文本)你应当多留意。

Example 4-2主文档头部
<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-3Optional 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-4Including generated sections
  <chapter>
    <title>my library</title>
      <xi:include href="xml/object.xml"/>
      ...