Editando o documento mestre

O Gtk-Doc produz documentação em DocBook SGML/XML. Ao processar os comentários inseridos nos fontes, as ferramentas do GTK-Doc geram uma página de documentação por classe ou módulo como um arquivo separado. O documento mestre os inclui e os coloca em uma ordem.

Enquanto o Gtk-Doc cria um modelo de documento mestre para você, execuções posteriores não vão tocá-lo novamente. Isso significa que se pode estruturar a documentação livremente. Isso inclui agrupamento de páginas e adição de páginas extras. O Gtk-Doc agora possui uma suíte de teste, na qual também o documento mestre é recriado do zero. É uma boa ideia verificar isso de tempo em tempo para ver se há itens a serem introduzidos lá.

Não crie tutoriais como documentos extras. Apenas escreva capítulos extras. O benefício de embutir diretamente o tutorial para sua biblioteca na documentação da API é que é mais fácil vincular o tutorial a um símbolo da documentação. Além disso, as chances são mais altas que o tutorial obtenha atualizações junto com a biblioteca.

Então, quais são as coisas para se alterar dentro do documento mestre? Para começar é apenas um pouco. Existem alguns mantedores de espaço (texto em colchetes) que você deve cuidar.

Example 4-2Cabeçalho do documento mestre
<bookinfo>
  <title>Manual de referência do NOMEDOMÓDULO</title>
  <releaseinfo>
    for NOMEDOMÓDULO [VERSÃO]
    A última versão desta documentação também pode ser encontrada on-line em
    <ulink role="online-location" url="http://[SERVIDOR]/NOMEDOMÓDULO/index.html">http://[SERVIDOR]/NOMEDOMÓDULO/</ulink>.
  </releaseinfo>
</bookinfo>

<chapter>
  <title>[Insira o título aqui]</title>

Além disso, alguns elementos de opção são criados na forma comentada. Você pode revisá-los e habilitá-los como preferir.

Example 4-3Parte opcional do documento mestre
  <!-- habilite isso se você usa anotações do gobject introspection
  <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
  -->

Finalmente você precisa adicionar nova seção sempre que você a introduzir. A ferramenta gtkdoc-check vai lembrar você de arquivos xml recentemente gerados que ainda não foram incluídos na documentação.

Example 4-4Incluindo seções geradas
  <chapter>
    <title>minha biblioteca</title>
      <xi:include href="xml/object.xml"/>
      ...