编辑主文档
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文档的好处就是教程与符号文档之间的链接很容易。另外教程与库一同升级时分离的机会也更高。
那么什么是主文档内部要修改的东西呢?开始只是一点点东西。有一些占位标识(在方括号内部的文本)你应当多留意。
<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.
<!-- 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.
<chapter> <title>my library</title> <xi:include href="xml/object.xml"/> ...