Modernizando a documentação
GTK-Doc está por aí já faz um tempo. Nesta seção, nós listamos novas funcionalidades juntamente da versão desde a qual está disponível.

GTK-Doc 1.9
Ao usar xml em vez de sgml, na verdade, é possível nomear o documento mestre <pacote>-docs.xml.
Essa versão provê suporte SCAN_OPTIONS=--rebuild-sections em Makefile.am. Quando esta opção está habilitada, o <package>-sections.txt é auto-gerado e pode ser removido a partir do VCS. Isso só funciona corretamente para projetos que têm uma estrutura muito regular (ex.: cada par .{c,h} vai criar uma nova seção). Se uma pessoa organiza um projeto próximo a isso atualizando um arquivo de seção mantido manualmente pode ser tão simples quanto executando meld <package>-decl-list.txt <package>-sections.txt.
A versão 1.8 já introduziu a sintaxe para documentação seções nos fontes em vez dos arquivos separados sob tmpl. Essa versão adiciona opções para alternar todo o módulo de documentação para não usar a etapa de compilação extra do tmpl, usando --flavour no-tmpl no configure.ac. Se você não possui um tmpl no seu sistema de controle de versão e ainda não trocou, basta adicionar uma opção ao configure.ac e está resolvido.

GTK-Doc 1.10
Essa versão provê suporte SCAN_OPTIONS=--rebuild-types no Makefile.am. Quando isso está habilitado, o <package>.types é auto-gerado e pode ser removido do VCS. Quando usando essa funcionalidade é importante também configurar o IGNORE_HFILES no Makefile.am para código que é compilado condicionalmente.

GTK-Doc 1.16
Essa versão inclui uma nova ferramenta chamada gtkdoc-check. Essa ferramenta pode executar um conjunto de verificações de sanidade na sua documentação. Ela é habilitada adicionando essas linhas ao final do Makefile.am.

Habilitar gtkdoc-check

if ENABLE_GTK_DOC
TESTS_ENVIRONMENT = \
  DOC_MODULE=$(DOC_MODULE) DOC_MAIN_SGML_FILE=$(DOC_MAIN_SGML_FILE) \
  SRCDIR=$(abs_srcdir) BUILDDIR=$(abs_builddir)
TESTS = $(GTKDOC_CHECK)
endif

GTK-Doc 1.20
A versão 1.18 trouxe algum suporte inicial a markdown. O uso de markdown em comentários de documentação é menos intrusiva do que escrever xml de docbook. Essa versão melhora em muito nisso e adiciona muito mais estilos. A seção que explica a sintaxe de comentário tem todos os detalhes.

GTK-Doc 1.25
Os makefiles fornecidos com esta versão geram um arquivo de entidade em xml/gtkdocentities.ent, contendo entidades para, por exemplo, nome-pacote e versão-pacote. Você pode usar isto, por exemplo, no arquivo xml principal para evitar ter que inserir diretamente o número de versão. Logo abaixo encontra-se um exemplo que mostra como o arquivo de entidade é incluído e como as entidades são usadas. As entidades também podem ser usadas em todos arquivos gerados, GTK-Doc usará o mesmo cabeçalho xml nos arquivos xml gerados.

Usando entradas geradas previamente

<?xml version="1.0"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
[
  <!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
  <!ENTITY % gtkdocentities SYSTEM "xml/gtkdocentities.ent">
  %gtkdocentities;
]>
<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
  <bookinfo>
    <title>Manual de referência do &nome-pacote;</title>
    <releaseinfo>
      para &versão-pacote;.
      A última versão desta documentação pode ser encontra on-line em
      <ulink role="online-location" url="http://[SERVIDOR]/&nome-pacote;/index.html">http://[SERVIDOR]/&nome-pacote;/</ulink>.
    </releaseinfo>
  </bookinfo>