Editar la sección maestra del documento
GTK-Doc produce documentación en DocBook SGML/XML. Cuando se procesan los comentarios en las líneas del código, las herramientas de GTK-Doc generan una página de documentación por clase o módulo en un archivo aparte. El documento maestro las incluye y ordena.
Puesto que GTK-Doc crea una documento maestro de plantilla, una posterior ejecución no lo modificará de nuevo. Esto significa que se puede estructurar libremente la documentación. Esto incluye agrupar páginas y añadir páginas adicionales. Ahora GTK-Doc tiene un entorno de pruebas, donde también el documento maestro se vuelve a crear desde cero. Es una buena idea mirarlo de vez en cuando para ver si se han introducido algunas mejoras.
No crear tutoriales como documentos adicionales. Solamente escriba capítulos adicionales. La ventaja de integrar directamente el tutorial para su biblioteca en la documentación de la API es que es fácil para el tutorial enlazar la documentación de símbolos. Además las posibilidades de actualizar el tutorial junto con la biblioteca son mayores.
¿Así que qué es lo que hay que cambiar en el documento maestro? Para empezar es muy poco. Existen algunos «placeholders» (texto entre corchetes) de los que habría que encargarse.
<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>
Se crean además unos pocos elementos de opciones de la manera comentada. Puede revisarlos y activarlos como quiera.
<!-- active esto cuando use anotaciones de introspección de gobject <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include> -->
Por último, necesita añadir una sección nueva siempre que quiera introducir una. La herramienta gtkdoc-check le recordará los nuevos archivos xml generados que no estén inclídos todavía en la documentación.
<chapter> <title>mi biblioteca</title> <xi:include href="xml/object.xml"/> ...