编辑主文档
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>