编辑主文档

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

GTK-Doc为你创建一个模板主文档,之后的运行就不会再动它了。这意味着你可以自由地组织这个文档,包括分组页和加入的额外页面。GTK-Doc现在有一个测试套件,它的主文档也重新生成。建议您经常关注它,又了解是否引入了新的功能特性。

不要把教程(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>