<?xml version="1.0" encoding="utf-8" standalone="no"?>
<?xml-stylesheet type="text/xml" href="params.xsl"?>
<!-- vim: set ai tw=80 ts=3 sw=3: -->
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "
              http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
<!ENTITY FDL SYSTEM "fdl-appendix.xml">
<!ENTITY FDLlink "<link linkend='fdl'>included</link>">
]>
<!-- =============Document Header ============================= -->
<book id="index" lang="pt-BR">
  <bookinfo>
    <title>Manual do GTK-Doc</title>
    <edition>1.24.1</edition>
    <abstract role="description"><para>Manual de usuário para desenvolvedores com instruções do uso do GTK-Doc.</para></abstract>
    <authorgroup>
      <author><firstname>Chris</firstname> <surname>Lyttle</surname> <affiliation> <address> <email>chris@wilddev.net</email> </address> </affiliation></author>
      <author><firstname>Dan</firstname> <surname>Mueth</surname> <affiliation> <address> <email>d-mueth@uchicago.edu</email> </address> </affiliation></author>
      <author><firstname>Stefan</firstname> <surname>Sauer (Kost)</surname> <affiliation> <address> <email>ensonic@users.sf.net</email> </address> </affiliation></author>
    </authorgroup>
    <publisher role="maintainer"><publishername>Projeto GTK-Doc</publishername> <address><email>gtk-doc-list@gnome.org</email></address></publisher>
    <copyright><year>2000, 2005</year> <holder>Dan Mueth e Chris Lyttle</holder></copyright>
    <copyright>
      <year>2007-2019</year>
      <holder>Stefan Sauer (Kost)</holder>
    </copyright>

    <!-- translators: uncomment this:
    <copyright>
      <year>2000</year>
      <holder>ME-THE-TRANSLATOR (Latin translation)</holder>
    </copyright>
    -->

    <legalnotice>
      <para>Permissão concedida para copiar, distribuir e/ou modificar este documento sob os termos da <citetitle>Licença de Documentação Livre GNU</citetitle> (GNU Free Documentation License), Versão 1.1 ou qualquer versão mais recente publicada pela Free Software Foundation; sem Seções Invariantes, Textos de Capa Frontal, e sem Textos de Contracapa. Você pode encontrar uma cópia da licença está <link linkend="fdl">inclusa</link>.</para>
      <para>Muitos dos nomes usados por empresas para distinguir seus produtos e serviços são reivindicados como marcas registradas. Onde esses nomes aparecem em qualquer documentação do GNOME e os membros do Projeto de Documentação do GNOME estiverem cientes dessas marcas registradas, os nomes aparecerão impressos em letras maiúsculas ou com iniciais em maiúsculas.</para>
    </legalnotice>

    <revhistory>
      <revision>
         <revnumber>1.30.1</revnumber>
         <date>09 May 2019</date>
         <authorinitials>ss</authorinitials>
         <revremark>development</revremark>
      </revision>
      <revision>
         <revnumber>1.30</revnumber>
         <date>08 May 2019</date>
         <authorinitials>ss</authorinitials>
         <revremark>more test coverage</revremark>
      </revision>
      <revision>
         <revnumber>1.29</revnumber>
         <date>28 Aug 2018</date>
         <authorinitials>ss</authorinitials>
         <revremark>bug fixes</revremark>
      </revision>
      <revision><revnumber>1.28</revnumber> <date>24 Mar 2018</date> <authorinitials>ss</authorinitials> <revremark>correções de erros</revremark></revision>
      <revision><revnumber>1.27</revnumber> <date>07 Maio 2017</date> <authorinitials>ss</authorinitials> <revremark>ajustes do porte para Python</revremark></revision>
      <revision><revnumber>1.26</revnumber> <date>11 Ago 2017</date> <authorinitials>ss</authorinitials> <revremark>portadas todas ferramentas de perl/bash para Python</revremark></revision>
      <revision><revnumber>1.25</revnumber> <date>21 Mar 2016</date> <authorinitials>ss</authorinitials> <revremark>correção de erros, limpezas de testes</revremark></revision>
      <revision><revnumber>1.24</revnumber> <date>29 Maio 2015</date> <authorinitials>ss</authorinitials> <revremark>correção de erros</revremark></revision>
      <revision><revnumber>1.23</revnumber> <date>17 Maio 2015</date> <authorinitials>ss</authorinitials> <revremark>correção de erros</revremark></revision>
      <revision><revnumber>1.22</revnumber> <date>07 Maio 2015</date> <authorinitials>ss</authorinitials> <revremark>correção de erros, desativadas funcionalidades obsoletas</revremark></revision>
      <revision><revnumber>1.21</revnumber> <date>17 Jul 2014</date> <authorinitials>ss</authorinitials> <revremark>correção de erros, desativadas funcionalidades obsoletas</revremark></revision>
      <revision><revnumber>1.20</revnumber> <date>14 Fev 2014</date> <authorinitials>ss</authorinitials> <revremark>correção de erros, suporte a markdown, melhorias no estilo</revremark></revision>
      <revision><revnumber>1.19</revnumber> <date>05 Jun 2013</date> <authorinitials>ss</authorinitials> <revremark>correção de erros</revremark></revision>
      <revision><revnumber>1.18</revnumber> <date>14 Set 2011</date> <authorinitials>ss</authorinitials> <revremark>correção de erros, aceleração, suporte a markdown</revremark></revision>
      <revision><revnumber>1.17</revnumber> <date>26 Fev 2011</date> <authorinitials>sk</authorinitials> <revremark>atualização de correção de erro urgente</revremark></revision>
      <revision><revnumber>1.16</revnumber> <date>14 Jan 2011</date> <authorinitials>sk</authorinitials> <revremark>correção de erros, melhorias no layout</revremark></revision>
      <revision><revnumber>1.15</revnumber> <date>21 Maio 2010</date> <authorinitials>sk</authorinitials> <revremark>correção de erros e regressões</revremark></revision>
      <revision><revnumber>1.14</revnumber> <date>28 Mar 2010</date> <authorinitials>sk</authorinitials> <revremark>Correção de erro e melhorias na performance</revremark></revision>
      <revision><revnumber>1.13</revnumber> <date>18 Dez 2009</date> <authorinitials>sk</authorinitials> <revremark>atualização de tarball defeituoso</revremark></revision>
      <revision><revnumber>1.12</revnumber> <date>18 Dez 2009</date> <authorinitials>sk</authorinitials> <revremark>novas funcionalidades da ferramenta e correção de erros</revremark></revision>
      <revision><revnumber>1.11</revnumber> <date>16 Nov 2008</date> <authorinitials>mal</authorinitials> <revremark>migração do GNOME doc-utils</revremark></revision>
    </revhistory>

  
    <othercredit class="translator">
      <personname>
        <firstname>Marcelo Rodrigues</firstname>
      </personname>
      <email>marcelopires@mmsantos.com.br</email>
    </othercredit>
    <copyright>
      
        <year>2010</year>
      
      <holder>Marcelo Rodrigues</holder>
    </copyright>
  
    <othercredit class="translator">
      <personname>
        <firstname>Rafael Fontenelle</firstname>
      </personname>
      <email>rafaelff@gnome.org</email>
    </othercredit>
    <copyright>
      
        <year>2013-2018</year>
      
      <holder>Rafael Fontenelle</holder>
    </copyright>
  </bookinfo>

  <!-- ======== Chapter 1: Introduction ======================== -->

  <chapter id="introduction">
    <title>Introdução</title>

    <para>Este capítulo introduz GTK-Doc e dá um visão geral do que ele é e como ele é usado.</para>

    <sect1 id="whatisgtkdoc">
      <title>O que é GTK-Doc?</title>

      <para>GTK-Doc é usado para documentar código C. Ele é tipicamente usado para documentar a API pública das bibliotecas, como as bibliotecas do GTK+ e do GNOME. Mas ele também pode ser usado para documentar código de aplicativos.</para>
    </sect1>

    <sect1 id="howdoesgtkdocwork">
      <title>Como o GTK-Doc funciona?</title>

      <para>O GTK-Doc funciona usando a documentação de funções colocadas dentro dos arquivos fonte em blocos de comentários especialmente formatados ou documentação adicionada aos arquivos modelo que o GTK-Doc usa (apesar disso, note que o GTK-Doc vai documentar apenas funções que são declaradas em arquivos de cabeçalho; ele não irá produzir saída para funções estáticas).</para>

      <para>GTK-Doc consiste em um número de scripts em Python, cada um executando uma etapa diferente no processo.</para>

      <para>Há 5 etapas principais no processo:</para>

      <orderedlist>

        <listitem>
          <para><guilabel>Escrita da documentação.</guilabel> O autor preenche os arquivos fonte com a documentação para cada função, macro, structs ou unions, etc.</para>
        </listitem>

        <listitem>
          <para><guilabel>Coleta de informação sobre o código.</guilabel> <application>gtkdoc-scan</application> varre os arquivos de cabeçalho do código buscando por declarações de funções, macros, enums, structs e unions. Ele cria o arquivo <filename>&lt;módulo&gt;-decl-list.txt</filename> contendo uma lista de declarações, inserindo-as em seções da acordo com o arquivo de cabeçalho no qual se encontram. Na primeira execução, este arquivo é copiado para <filename>&lt;módulo&gt;-sections.txt</filename>. O autor pode reorganizar as seções, e a ordem das declarações dentro delas, para produzir a ordem final desejada. O segundo arquivo que ele gera é <filename>&lt;módulo&gt;-decl.txt</filename>. Este arquivo contém as declarações completas encontradas pela varredura. Se por algum motivo se quiser que alguns símbolos apareçam nos documentos, nos quais declarações completas não puderam ser encontradas pela varredura ou a declaração deveria aparecer de outra forma, pode-se colocar entidades similares aos do <filename>&lt;módulo&gt;-decl.txt</filename> no <filename>&lt;módulo&gt;-overrides.txt</filename>.</para>
         <para><application>gtkdoc-scangobj</application> também pode ser usado para consultar dinamicamente uma biblioteca sobre qualquer subclasse GObject que ele exporta. Ele salva informações sobre cada posição do objeto na hierarquia de classe e sobre quaisquer propriedades GObject e sinais que ela fornece.</para>
         <para><application>gtkdoc-scanobj</application> não deve mais ser usado. Ele era necessário no passado, quando GObject ainda era GtkObject dentro do gtk+.</para>
        </listitem>

        <listitem>
          <para><guilabel>Geração do XML e do HTML/PDF.</guilabel> <application>gtkdoc-mkdb</application> transforma os arquivos modelos em arquivos XML no subdiretório <filename class="directory">xml/</filename>. Se o código-fonte contém documentação nas funções, usando os blocos de comentários especiais, ela é mesclada aqui. Se não há arquivos tmpl sendo usados, ele apenas lê documentos dos dados de introspecção e dos fontes.</para>
          <para><application>gtkdoc-mkhtml</application> transforma os arquivos XML em arquivos HTML no subdiretório <filename class="directory">html/</filename>. Da mesma forma, <application>gtkdoc-mkpdf</application> transforma os arquivos XML em um documento PDF chamado <filename>&lt;pacote&gt;.pdf</filename>.</para>
          <para>Arquivos nos diretórios <filename class="directory">xml/</filename> e <filename class="directory">html/</filename> são sempre sobrescritos. Não devem ser editados manualmente.</para>
        </listitem>

        <listitem>
          <para><guilabel>Correção de referências cruzadas entre documentos.</guilabel> Após a instalação dos arquivos HTML, <application>gtkdoc-fixxref</application> pode ser executado para consertar referências cruzadas entre documentos separados. Por exemplo, a documentação do GTK+ contém muitas referências cruzadas a tipos documentados no manual do GLib. Ao criar um tarball fonte para distribuição, <application>gtkdoc-rebase</application> transforma todos os links externos em web-links. Ao instalar documentações distribuídas (geradas previamente), o mesmo aplicativo vai tentar transformar links de volta para links locais (onde aquelas documentações estão instaladas).</para>
        </listitem>
      </orderedlist>

    </sect1>

    <sect1 id="gettinggtkdoc">
      <title>Obtendo GTK-Doc</title>

      <sect2 id="requirements">
        <title>Requisitos</title>
        <para><guilabel>python 2/3</guilabel> – os scripts principais são escritos em Python.</para>
        <para><guilabel>xsltproc</guilabel> – o processador de xslt do libxslt <ulink url="http://xmlsoft.org/XSLT/" type="http">xmlsoft.org/XSLT/</ulink></para>
        <para><guilabel>docbook-xsl</guilabel> – as folhas de estilo xsl de docbook <ulink url="http://sourceforge.net/projects/docbook/files/docbook-xsl/" type="http">sourceforge.net/projects/docbook/files/docbook-xsl</ulink></para>
        <para>Um dentre <guilabel>source-highlight</guilabel>, <guilabel>highlight</guilabel> ou <guilabel>vim</guilabel> – opcional - usado para destaque de sintaxe de exemplos</para>
      </sect2>
    </sect1>

    <sect1 id="aboutgtkdoc">
      <title>Sobre GTK-Doc</title>

      <para>Historicamente, o GTK-Doc foi usado para gerar arquivos de modelo a partir do código-fonte. Esses arquivos de modelo poderiam ser usados pelos desenvolvedores para inserir a documentação da API. Essa abordagem era bastante inconveniente porque exigia manter os arquivos gerados sob controle de versão. Desde o GTK-Doc 1.9, tornou-se possível colocar todas as informações da API em comentários no fonte, o que tornou o suporte ao modelo obsoleto. Na versão 1.26 suporte ao modelo foi removido.</para>

      <para>(CORRIJA-ME)</para>

      <para>(autores, páginas web, lista de discussão, licença, planos futuros, comparação com outros sistemas similares.)</para>

    </sect1>

    <sect1 id="aboutthismanual">
      <title>Sobre este manual</title>

      <para>(CORRIJA-ME)</para>

      <para>(pra quem ele serve, onde você pode obtê-lo, licença)</para>

    </sect1>

  </chapter>

  <chapter id="settingup">
    <title>Configurando o projeto</title>

    <para>Este capítulo descreve os passos necessários para integrar o GTK-Doc ao seu projeto. A integração do GTK-Doc em um projeto inclui as seguintes etapas:</para>

    <itemizedlist>
      <listitem>
        <para>Preparação da estrutura de diretórios e criação dos arquivos de configuração necessários para sua documentação do GTK-Doc (consulte <link linkend="settingup_docfiles">Preparando o esqueleto de uma documentação</link>).</para>
      </listitem>
      <listitem>
        <para>Ajuste do sistema de compilação para compilar sua documentação usando as ferramentas do GTK-Doc. Há suporte a vários sistemas de compilação, neste manual descrevemos como integrar o GTK-Doc com <link linkend="settingup_autotools">Autotools</link>, <link linkend="settingup_cmake">CMake</link> e <link linkend="settingup_plain_makefiles">Makefiles simples</link>.</para>
      </listitem>
      <listitem>
        <para>Adição de arquivos específicos do GTK-Doc para o controle de versão e decisão de quais arquivos ignorar (veja <link linkend="settingup_vcs"> Integração com sistemas de controle de versão</link>).</para>
      </listitem>
    </itemizedlist>

    <para>As seções a seguir presumem que trabalhamos em um projeto chamado <code>meep</code>. Este projeto contém dois pacotes (ou módulos), uma biblioteca chamada <code>libmeep</code> e um aplicativo de usuário final chamado <code>meeper</code>.</para>

    <sect1 id="settingup_docfiles">
      <title>Preparando o esqueleto de uma documentação</title>

      <para>Uma convenção comum é colocar a documentação em uma pasta chamada <code>docs</code> dentro do seu diretório de projeto de nível superior. Costumamos distinguir entre a <emphasis>documentação de referência</emphasis> destinada aos programadores e um <emphasis>manual do usuário</emphasis> destinado aos usuários-finais. Novamente a convenção é ter pastas separadas para ambos. Geralmente, colocamos a documentação de referência em uma pasta chamada <code>reference</code> e o manual do usuário final em uma pasta chamada <code>help</code>. De acordo com a convenção acima, a documentação do nosso pacote <code>libmeep</code> seria colocada em: <code>docs/reference/libmeep</code>. Para pacotes com apenas uma biblioteca ou aplicativo, a documentação também pode ser colocada diretamente em <code>docs/reference</code>. Não é obrigatório usar a convenção acima, mas se você optar por usar uma estrutura de diretórios diferente, deverá ajustar a configuração do sistema de compilação para que corresponda à estrutura do diretório.</para>

      <para>Nas seções a seguir, vamos presumir uma estrutura de diretórios para o nosso projeto <emphasis>meep</emphasis> que usa as convenções acima. <example>
          <title>Exemplo de estrutura de diretórios de projeto <emphasis>meep</emphasis></title>
          <programlisting>
meep/
  docs/
    reference/  # documentação de referência
      libmeep/
      meeper/
    help/       # opcional: manual de usuário
      meeper/
  src/
    libmeep/
    meeper/
</programlisting>
        </example></para>
    </sect1>

    <sect1 id="settingup_autotools">
      <title>Integração com Autotools</title>
      <para>A integração do GTK-Doc em um sistema de compilação baseado em autotools requer as seguintes etapas:</para>
      <itemizedlist>
        <listitem>
          <para>Certificar-se de que <application>gtkdocize</application> seja executado uma vez antes do script <filename>configure</filename>. Se um script <filename>autogen.sh</filename> estiver presente, ajuste-o para verificar o GTK-Doc e adicione uma chamada ao <application>gtkdocize</application>.</para>

          <para>O principal objetivo do <application>gtkdocize</application> é fazer com que o arquivo Makefile <filename>gtk-doc.make</filename> e o arquivo de definição de macro <filename>gtk-doc.m4</filename> estejam disponíveis para a compilação sistema, seja copiando ou vinculando-o ao projeto.</para>
        </listitem>
        <listitem>
          <para>Adicionar as macros <application>autoconf</application> necessárias ao <filename>configure.ac</filename> para ativar o GTK-Doc em seu sistema de compilação para permitir a configuração do GTK-Doc através do script <filename>configure</filename> gerado.</para>
          <para>Entre outros, registra a opção <code>--enable-gtk-doc</code> com o script <filename>configure</filename>.</para>
        </listitem>
        <listitem>
          <para>Criar um script <application>automake</application> para cada aplicativo ou biblioteca em seu projeto. No exemplo usado nesta documentação, esta etapa se aplica tanto a <code>meeper</code> quanto a <code>libmeep</code>.</para>
        </listitem>
      </itemizedlist>

      <para>Nas seções a seguir, executaremos as etapas acima na ordem inversa. Começamos com os scripts <application>automake</application> e vamos trabalhando até o <filename>configure.ac</filename> e <filename>autogen.sh</filename>. Então, mostramos como habilitar o Gtk-Doc no sistema de compilação e como compilar a documentação.</para>

      <sect2 id="settingup_automake">
        <title>Integração com automake</title>

        <para>Primeiro copie o <filename>Makefile.am</filename> do subdiretório do <filename class="directory">exemplo</filename> do <ulink url="https://gitlab.gnome.org/GNOME/gtk-doc/raw/master/examples/Makefile.am"> gtkdoc-sources</ulink> para o diretório da documentação de referência do seu projeto (por exemplo, <filename class="directory">./docs/reference/&lt;pacote&gt;</filename>). Uma cópia local deveria estar disponível sob, por exemplo, <filename>/usr/share/doc/gtk-doc-tools/examples/Makefile.am</filename>. Se você tiver múltiplos pacotes de documentação, repita isso para cada um.</para>

        <note>
          <simpara>Não se esqueça de adicionar cada <filename>Makefile.am</filename> à macro <function>AC_CONFIG_FILES</function> em <filename>configure.ac</filename>. Para <filename>docs/reference/libmeep/Makefile.am</filename> você precisará adicionar a entrada <filename>docs/reference/libmeep/Makefile</filename> para <function>AC_CONFIG_FILES</function>.</simpara>
        </note>

        <example>
          <title>Exemplo de estrutura de diretório com <filename>Makefiles.am</filename></title>
          <programlisting>
meep/
  docs/
    reference/  # documentação de referência
      libmeep/
        Makefile.am
      meeper/
        Makefile.am
    help/       # opcional: manual de usuário
      meeper/
  src/
    libmeep/
    meeper/
</programlisting>
        </example>

        <para>Em seguida, você precisa personalizar os Makefiles copiados e fornecer valores para os vários parâmetros em cada <filename>Makefile.am</filename>. Todas as configurações têm um comentário sobre elas que descreve seu propósito e como personalizar a configuração. A maioria das configurações são usadas para fornecer opções extras para as respectivas ferramentas às quais elas se aplicam. Cada ferramenta tem uma variável na forma <option>&lt;NOME-FERRAMENTA&gt;_OPTIONS</option> (por exemplo, a ferramenta <application>gtkdoc-mkhtml</application> tem uma opção chamada <code>MKHTML_OPTIONS</code>). Todas as ferramentas têm suporte a <option>--help</option> pra listar os parâmetros disponíveis.</para>

        <para>A lista a seguir explica as opções mais relevantes. Verifique o exemplo <filename>Makefile.am</filename> para opções adicionais. <itemizedlist>
            <listitem>
              <para><option>DOC_MODULE</option> é usado para fornecer o nome do pacote que está sendo documentado (por exemplo, <code>meeper</code> ou <code>libmeep</code>).</para>
            </listitem>
            <listitem>
              <para><option>DOC_SOURCE_DIR</option> é usado para especificar a localização do diretório fonte que o GTK-Doc pesquisa na documentação da API. Isso geralmente será <code>DOC_SOURCE_DIR=$(top_srcdir)/src </code> ou um subdiretório desse diretório.</para>
            </listitem>

            <listitem>
              <para><option>HFILE_GLOB</option> e <option>CFILE_GLOB</option> são usados para dependências. Cada opção pega um arquivo glob (por exemplo, <code>HFILE_GLOB=$(top_srcdir)/src/*.c</code>). A documentação será recompilada se qualquer um dos arquivos correspondentes for alterado.</para>
            </listitem>

            <listitem>
              <para><option>EXTRA_HFILES</option> permite especificar arquivos de cabeçalho extras para incluir ao verificar a documentação da API, que não são encontrados em <code>DOC_SOURCE_DIR</code> (por exemplo, <code>EXTRA_HFILES=$(top_srcdir}/contrib/extra.h</code>).</para>
            </listitem>

            <listitem>
              <para><option>IGNORE_HFILES</option> permite especificar arquivos ou diretórios de cabeçalho a serem ignorados ao verificar a documentação da API. Use o nome de base do arquivo ou diretório (por exemplo, <code>IGNORE_HFILES=gtkdebug.h gtkintl.h private_code_folder</code>).</para>
            </listitem>

            <listitem>
              <para><option>HTML_IMAGES</option> permite especificar arquivos de imagens que serão copiados para o diretório <filename>html/</filename> da documentação gerada. Se a documentação da API incluir imagens, elas precisam ser adicionadas a essa opção (por exemplo, <code>HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png</code>).</para>
            </listitem>

            <listitem>
              <para><option>content_files</option> permite especificar arquivos extras incluídos por <code>$(DOC_MAIN_SGML_FILE)</code> (por exemplo, <code>content_files=running.xml building.xml changes-2.0.xml</code>).</para>
            </listitem>

            <listitem>
              <para><option>expand_content_files</option> permite especificar arquivos onde as <emphasis>abreviaturas gtk-doc</emphasis> como <code>#GtkWidget</code> são expandidas (por exemplo, <code>expand_content_files=running.xml</code>).</para>
            </listitem>
          </itemizedlist></para>

      </sect2>

      <sect2 id="settingup_autoconf">
        <title>Integração com autoconf</title>

        <para>A integração com <application>autoconf</application> é muito simples e inclui uma etapa obrigatória e uma etapa adicional opcional (mas recomendada). O primeiro passo é adicionar a macro <function>GTK_DOC_CHECK</function> ao seu script <filename>configure.ac</filename>. Isso registra várias opções de configuração para habilitar o GTK-Doc e permite definir argumentos padrão para <application>gtkdocize</application>.</para>

        <warning>
          <simpara>Certifique-se de que a macro <code>GTK_DOC_CHECK</code> não esteja recuada. A macro deve começar no início da linha e não deve começar com espaço em branco.</simpara>
        </warning>

        <para>O segundo passo é adicionar o <code>AC_CONFIG_MACRO_DIR(m4)</code> ao seu <filename>configure.ac</filename>. Isso não é necessário, mas ajuda o <application>gtkdocize</application> a copiar automaticamente a definição da macro (por exemplo, <filename>gtk-doc.m4</filename>) que contém a macro <function>GTK_DOC_CHECK</function> para o diretório de macro do seu projeto. Sem isso, a macro GTK_DOC_CHECK pode não ser encontrada e você precisaria informar explicitamente à ferramenta <application>aclocal</application> onde encontrar o arquivo de definição de macro.</para>

        <para>
          <example><title>Integração mínima com autoconf</title>
            <programlisting>
# recomendado: defina o diretório m4
AC_CONFIG_MACRO_DIR(m4)
# opcional: registre gtk-doc no configure
GTK_DOC_CHECK([1.28])
</programlisting>
          </example>
        </para>

        <para>O exemplo acima funciona, mas exigirá que todos os desenvolvedores tenham o gtk-doc instalado. Uma maneira melhor é tornar a documentação opcional, conforme mostrado no próximo exemplo: <example>
            <title>Integração com dependência opcional do gtk-doc</title>
            <programlisting>
m4_ifdef([GTK_DOC_CHECK], [
# recomendado: defina diretório m4
AC_CONFIG_MACRO_DIR(m4)
# opcional: registre gtk-doc no configure
GTK_DOC_CHECK([1.28])
],[
AM_CONDITIONAL([ENABLE_GTK_DOC], false)
])
</programlisting>
          </example></para>

        <para>O primeiro argumento é usado para verificar a versão do Gtk-Doc em tempo de compilação. O segundo argumento é opcional, sendo usado por <application>gtkdocize</application>. A macro <symbol>GTK_DOC_CHECK</symbol> também adiciona várias opções de configuração:</para>

        <orderedlist>
          <listitem><para>--with-html-dir=CAMINHO : caminho para as documentações instaladas</para></listitem>
          <listitem><para>--enable-gtk-doc : usa gtk-doc para compilar documentação [padrão=não]</para></listitem>
          <listitem><para>--enable-gtk-doc-html : compila documentação em formato html [padrão=sim]</para></listitem>
          <listitem><para>--enable-gtk-doc-pdf : compila documentação em formato pdf [padrão=não]</para></listitem>
        </orderedlist>

        <important>
          <para>GTK-Doc está desabilitado por padrão! Lembre-se de passar a opção <option>"--enable-gtk-doc"</option> à próxima execução do <filename>configure</filename>. Do contrário, uma documentação gerada previamente é instalada (o que faz sentido para usuários, mas não para desenvolvedores).</para>
        </important>

        <para>Após todas as alterações do <filename>configure.ac</filename> serem feitas, atualize o arquivo <filename>configure</filename>. Isso pode ser feito executando novamente <code>autogen.sh</code>.</para>
      </sect2>

      <sect2 id="settingup_autogen">
        <title>Integração com autogen</title>

        <para>A maioria dos projetos tem um script <filename>autogen.sh</filename> para configurar a infraestrutura de compilação após o checkout do projeto sistema de um controle de versão (como git ou svn). GTK-Doc vêm com um script chamado <application>gtkdocize</application> que pode ser usado para copiar os arquivos necessários pelo Gtk-Doc para o diretório fonte.</para>

        <para>Ele deve ser executado antes de autoreconf, autoheader, automake or autoconf.</para>

        <para>
          <example><title>Executando gtkdocize no autogen.sh</title>
            <programlisting>
gtkdocize || exit 1
</programlisting>
          </example>
        </para>

        <para>
          <example>
            <title>Executa condicionalmente gtkdocize no autogen.sh</title>
            <programlisting>
GTKDOCIZE=$(which gtkdocize 2&gt;/dev/null)
if test $? -ne 0; then
  echo "No gtk-doc support found. You can't build the docs."
else
  $GTKDOCIZE || exit 1
fi
</programlisting>
          </example>
        </para>

        <para>Ao executar <application>gtkdocize</application>, ele copia <filename>gtk-doc.make</filename> para a raiz do seu projeto (ou qualquer diretório especificado pela opção <option>--docdir</option>).</para>

        <para><application>gtkdocize</application> verifica seu script <filename>configure.ac</filename> para <function>GTK_DOC_CHECK</function>. A macro <function>GTK_DOC_CHECK</function> pode ser usada para passar parâmetros extras para o script <application>gtkdocize</application>.</para>

        <para>Alternativamente, argumentos adicionais também podem ser passados para <application>gtkdocsize</application> por meio da variável de ambiente <function>GTKDOCIZE_FLAGS</function> ou especificando-os diretamente ao <application>gtkdocsize</application> no <filename>autogen.sh</filename>.</para>

      </sect2>

      <sect2 id="settingup_firstrun">
        <title>Executando GTK-Doc a partir do sistema de compilação</title>

        <para>Após as etapas anteriores, é hora de executar a compilação. Primeiro, nós queremos executar novamente o <filename>autogen.sh</filename>. Se este script executa o configure para você, então forneça a este a opção <option>--enable-gtk-doc</option>. Do contrário, execute manualmente <filename>configure</filename> com esta opção em seguida.</para>
        <para>A primeira execução do make cria vários arquivos adicionais nos diretórios de documentação. Os importantes são: <filename>&lt;pacote&gt;.types</filename>, <filename>&lt;pacote&gt;-docs.xml</filename> (no passado, .sgml), <filename>&lt;pacote&gt;-sections.txt</filename>.</para>
        <para>
          <example><title>Executando a compilação da documentação</title>
            <programlisting>
./autogen.sh --enable-gtk-doc
make
</programlisting>
          </example>
        </para>

        <para>Agora você pode apontar seu navegador para <filename>docs/reference/&lt;pacote&gt;/index.html </filename>. Com esta configuração inicial, você verá apenas um documento muito simples. O próximo capítulo ensinará como adicionar documentação da API ao seu código por meio de blocos de comentários especiais. O capítulo seguinte depois introduz <link linkend="metafiles">arquivos adicionais</link> e mostra como editar o <link linkend="metafiles_master">modelo mestre</link> para adicionar capítulos e seções adicionais aos seus arquivos de documentação.</para>

      </sect2>

    </sect1>

    <sect1 id="settingup_cmake">
      <title>Integração com sistemas de compilação CMake</title>

      <para>GTK-Doc agora fornece um módulo <filename>GtkDocConfig.cmake</filename> (e o module <filename>GtkDocConfigVersion.cmake</filename> correspondente). Ele fornece um comando <literal>gtk_doc_add_module</literal> que você pode usar em seu arquivo <filename>CMakeLists.txt</filename>.</para>

      <para>O exemplo a seguir mostra como usar este comando. <example><title>Exemplo de uso do GTK-Doc no CMake</title>
          <programlisting>
find_package(GtkDoc 1.25 REQUIRED)

# Cria o alvo doc-libmeep.
gtk_doc_add_module(
   libmeep ${CMAKE_SOURCE_DIR}/libmeep
      XML meep-docs.xml
      LIBRARIES libmeep
)

# Compila doc-libmeep como parte do alvo padrão. Sem isso, você precisaria
# executar explicitamente algo como `make doc-libmeep` para compilar os
# documentos.
add_custom_target(documentation ALL DEPENDS doc-libmeep)

# Instala os documentos. (Isso presume que você está usando o módulo
# GNUInstallDirs do CMake para definir a variável CMAKE_INSTALL_DOCDIR
# corretamente).
install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html
        DESTINATION ${CMAKE_INSTALL_DOCDIR})
</programlisting>
        </example></para>
    </sect1>

    <sect1 id="settingup_plain_makefiles">
      <title>Integração com makefiles simples ou outros sistemas de compilação</title>

      <para>Neste caso, não se deseja usar o automake e, portanto, <filename>gtk-doc.mak</filename>. Será necessário chamar as ferramentas do gtkdoc na ordem correta nos makefiles devidos (ou outras ferramentas de compilação).</para>

      <para>
        <example><title>Etapas de compilação da documentação</title>
          <programlisting>
DOC_MODULE=meep
// fontes foram alterados
gtkdoc-scan --module=$(DOC_MODULE) &lt;source-dir=&gt;
gtkdoc-scangobj --module=$(DOC_MODULE)
gtkdoc-mkdb --module=$(DOC_MODULE) --output-format=xml --source-dir=&lt;source-dir&gt;
// arquivos xml foram alterados 
mkdir html
cd html &amp;&amp; gtkdoc-mkhtml $(DOC_MODULE) ../meep-docs.xml
gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html
</programlisting>
        </example>
      </para>

      <para>Será necessário olhar no <filename>Makefile.am</filename> e no <filename>gtk-doc.mak</filename> para obter as opções extras necessárias.</para>
    </sect1>

    <sect1 id="settingup_vcs">
      <title>Integração com sistemas de controle de versão</title>

      <para>Como uma regra de ouro, são aqueles arquivos que você edita que devem entrar no controle de versão. Para projetos normais, esses são os arquivos: <filename>&lt;pacote&gt;.types</filename>, <filename>&lt;pacote&gt;-docs.xml</filename> (no passado, .sgml), <filename>&lt;pacote&gt;-sections.txt</filename>, <filename>Makefile.am</filename>.</para>
      <para>Arquivos nos diretórios <filename>xml/</filename> e <filename>html/</filename> não devem entrar no controle de versão. Da mesma forma, não devem entrar arquivos <filename>.stamp</filename>.</para>
    </sect1>

  </chapter>

  <chapter id="documenting">
    <title>Documentando o código</title>

    <para>GTK-Doc usa comentários do código-fonte com uma sintaxe especial para documentação do código. Além disso, ele obtém informações sobre a estrutura do seu projeto a partir de outros fontes. Na próxima seção, você vai descobrir todas as informações sobre a sintaxe dos comentários.</para>

    <para>O verificador do GTK-Doc sabe lidar com a maioria dos cabeçalhos de C sem problemas. Caso se receba avisos (warnings) na varredura que pareça ser um caso especial, pode-se informar ao GTK-Doc para ignorá-los. <example><title>Bloco de comentário do GTK-Doc</title>
        <programlisting>
#ifndef __GTK_DOC_IGNORE__
/* código não analisável aqui */
#endif
</programlisting>
      </example></para>

    <note>
      <title>Limitações</title>
      <para>Note que o GTK-Doc oferece suporte a <code>#ifndef(__GTK_DOC_IGNORE__)</code>, mas não a <code>#if !defined(__GTK_DOC_IGNORE__)</code> ou outras combinações.</para>
    </note>

    <!--  -->

    <sect1 id="documenting_syntax">
      <title>Comentários de documentação</title>

      <para>Um comentário multilinha que comece com um “*” adicional marca um bloco de documentação que será processado pelas ferramentas do GTK-Doc. <example><title>Bloco de comentário do GTK-Doc</title>
          <programlisting>
/**
 * identificador:
 * documentação ...
 */
</programlisting>
        </example></para>

      <para>O “identificador” é uma linha com o nome do item ao qual o comentário está relacionado. A sintaxe difere um pouco dependendo do item.</para>

      <para>O bloco “documentação” também é diferente para cada tipo de símbolo. Tipos de símbolos que levam parâmetros, como funções e macros, têm a descrição de parâmetro começando com uma linha vazia (apenas com um “*”). Posteriormente, segue com a descrição detalhada. Todas as linhas (fora das listagens do programa e seções CDATA) contendo apenas um “ *” (espaço em branco e asterisco) são convertidas para quebras de parágrafos. Se você não quiser uma quebra de parágrafo, altere isso para “ * “ (espaço, asterisco, espaço e espaço). Isso é útil em textos pré-formatados (listagens de código).</para>

      <tip>
        <para>Ao documentar um código, descreva dois aspectos: <itemizedlist>
             <listitem>
               <para>O que é: O nome de uma classe ou função pode, em alguns casos, levar a um entendimento equivocado pessoas com experiências diferentes.</para>
             </listitem>
             <listitem>
               <para>O que ele faz: Fale sobre usos comuns. Coloque em relação com a outra API.</para>
             </listitem>
           </itemizedlist></para>
      </tip>

      <para>Uma vantagem do hipertexto de texto simples é a habilidade de ter links no documento. Porém, escrever a marcação correta para cada link pode ser entediante. GTK-Doc vem para ajudar fornecendo abreviações úteis. <itemizedlist>
          <listitem>
            <para>Use function() para se referir às funções ou macros que levam argumentos.</para>
          </listitem>
          <listitem>
            <para>Use @param para se referir a parâmetros. Também, use isso ao se referir a parâmetros de outras funções, relacionadas àquele sendo descrito.</para>
          </listitem>
          <listitem>
            <para>Use %constant para se referir a uma constante, ex.: %G_TRAVERSE_LEAFS.</para>
          </listitem>
          <listitem>
            <para>Use #symbol para se referir a outros tipos de símbolos, ex.: structs, enums e macros que não levam argumentos.</para>
          </listitem>
          <listitem>
            <para>Use #Object::signal para se referir a um sinal de GObject.</para>
          </listitem>
          <listitem>
            <para>Use #Object:property para se referir a uma propriedade de GObject.</para>
          </listitem>
          <listitem>
            <para>Use #Struct.field para se referir a um campo dentro de uma estrutura e #GObjectClass.foo_bar() para se referir a um vmethod.</para>
          </listitem>
        </itemizedlist></para>

      <tip>
        <para>Se você precisar usar os caracteres especiais “&lt;”, “&gt;”, “()”, “@”, “%” ou “#” em sua documentação sem GTK-Doc alterando-os, você pode usar as entidades XML “&amp;lt;”, “&amp;gt;”, “&amp;lpar;”, “&amp;rpar;”, “&amp;commat;”, “&amp;percnt;” e “&amp;num;”, respectivamente, ou escapá-los com uma contrabarra “\”.</para>
      </tip>

      <para>DocBook pode fazer mais do que apenas links. Ele também pode ter listas, exemplos, títulos e imagens. A partir da versão 1.20, a forma preferível é usar um subconjunto de sintaxe de formatação de texto básica chamada <ulink url="http://daringfireball.net/projects/markdown/">Markdown</ulink>. Em versões mais antigas do GTK-Doc, qualquer documentação que inclui Markdown será renderizada como está. Por exemplo, itens de lista aparecerão como linhas começando com um traço.</para>

      <para>Enquanto markdown é agora preferível, é possível misturar ambos. Uma limitação aqui é que é possível usar docbook xml no markdown, mas não há suporte a markdown no docbook xml.</para>

      <para>Em versões mais antigas do GTK-Doc, se você precisasse de suporte para formatação adicional, você precisaria de habilitar o uso de tags de XML de docbook dentro de comentários de documentação colocando <option>--xml-mode</option> (ou <option>--sgml-mode</option>) na variável <symbol>MKDB_OPTIONS</symbol> dentro de <filename>Makefile.am</filename>.</para>

      <para>
        <example><title>Bloco de comentário do GTK-Doc usando Markdown</title>
          <programlisting>
/**
 * identificador:
 *
 * parágrafo de documentação ...
 *
 * # Subtítulo #
 *
 * ## Segundo subtítulo
 *
 * # Subtítulo com um link âncora # {#titulo-dois}
 *
 * mais documentação:
 *
 * - item 1 da lista
 *
 *   Parágrafo dentro de um item de lista.
 *
 * - item 2 da lista
 *
 * 1. item numerado da lista
 *
 * 2. outro item numerado da lista
 *
 * Outro parágrafo. [Um link para o site do GNOME](http://www.gnome.org/)
 *
 * ![uma imagem embutida](plot-result.png)
 *
 * [Um link para um título acima][titulo-dois]
 *
 * Um exemplo em linguagem C:
 * |[&lt;!-- language="C" --&gt;
 * GtkWidget *label = gtk_label_new ("Esplêndido!");
 * ]|
 */
</programlisting>
        </example>
      </para>

      <para>Mais exemplos de quais tags de markdown tags possui suporte podem ser encontrados na <ulink url="https://wiki.gnome.org/Projects/GTK%2B/DocumentationSyntax/Markdown">Referência de sintaxe de markdown de documentação</ulink>.</para>

      <tip>
        <para>Como já mencionado anteriormente, GTK-Doc serve para documentar API pública. Portanto, não é possível escrever documentação para símbolos estáticos. Não obstante, é bom comentar estes símbolos também. Isso ajuda outros desenvolvedores a entender seu código. Portanto, é recomendado comentá-los usando comentários normais (sem o segundo “*” na primeira linha). Se, posteriormente, a função precisar ser publicada, tudo que precisa ser feito é adicionar outro “*” no bloco de comentário e inserir o nome do símbolo no lugar correto do arquivo e seções.</para>
      </tip>
    </sect1>

    <sect1 id="documenting_sections">
      <title>Documentando seções</title>

      <para>Cada seção da documentação contém informações sobre uma classe ou um módulo. Para introduzir o componente, pode-se escrever um bloco de seção. A descrição curta também é usada dentro da tabela de conteúdo (sumário). Todos os @fields são opcionais.</para>

      <para>
        <example><title>Bloco de comentário de sessão</title>
          <programlisting>
/**
 * SECTION:meepapp
 * @short_description: A classe do aplicativo
 * @title: Aplicativo Meep
 * @section_id:
 * @see_also: #MeepSettings
 * @stability: Estável
 * @include: meep/app.h
 * @image: aplicativo.png
 *
 * A classe do aplicativo cuida de ...
 */
</programlisting>
        </example>
      </para>

      <variablelist>
        <varlistentry>
          <term>SECTION:&lt;nome&gt;</term>
          <listitem>
            <para>O nome vincula a documentação da seção à respectiva parte do arquivo <filename>&lt;pacote&gt;-sections.txt</filename>. O nome informado aqui deve corresponder à tag &lt;FILE&gt; no arquivo <filename>&lt;pacote&gt;-sections.txt</filename>.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>@short_description</term>
          <listitem>
            <para>Uma descrição de uma linha da sessão,que mais tarde aparecerá após os links no TOC (sumário) no topo da página da sessão.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>@title</term>
          <listitem>
            <para>O padrão para título de seção é &lt;nome&gt; da declaração da SECTION. Ele pode ser sobrescrito com o campo @title.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>@section_id</term>
          <listitem>
            <para>Sobrescreve o uso do título como um identificador de seção. Para GObjects, o &lt;title&gt; é usado como um section_id e para outras seções ele é &lt;MÓDULO&gt;-&lt;title&gt;.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>@see_also</term>
          <listitem>
            <para>Uma lista de símbolos que estão relacionados a esta sessão.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>@stability</term>
          <listitem>
            <para>Uma descrição informal do nível de estabilidade que esta API tem. Nós recomendamos o uso de um desses termos: <itemizedlist>
                <listitem>
                  <para>Estável – A intenção de uma interface estável é permitir terceiros arbitrários desenvolverem aplicativos para essas interfaces, lançá-los e ter a confiança de que eles vão funcionar em todos os lançamentos menores do produto (após aquele no qual a interface foi introduzida e naquele mesmo lançamento maior). Atém mesmo em um lançamento maior, espera-se que alterações incompatíveis sejam raras e que tenham fortes justificativas.</para>
                </listitem>
                <listitem>
                  <para>Instável – Interfaces instáveis são experimentais ou transicionais. Elas são normalmente usadas para dar a desenvolvedores externos um acesso prévio a nova tecnologia ou em rápida alteração, ou para fornecer uma solução interina para um problema que uma solução mais genérica foi antecipada. Nenhuma responsabilidade é assumida pela compatbilidade dos binários ou dos fontes de uma versão menor para a próxima.</para>
                </listitem>
                <listitem>
                  <para>Privado – Uma interface que pode ser usada dentro da própria pilha do GNOME, mas que não está documentada para usuários finais. Tais funções deveriam ser usadas nas formas especificadas e documentadas.</para>
                </listitem>
                <listitem>
                  <para>Interna – Uma interface que é interna a um módulo e não requer documentação para o usuário final. Funções que não estão documentadas são presumidas como sendo “Interna”.</para>
                </listitem>
              </itemizedlist></para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>@include</term>
          <listitem>
            <para>Os arquivos <literal>#include</literal> a ser mostrado na sinopse da seção (uma lista separada por vírgulas), sobrescrevendo o valor global do <link linkend="metafiles_sections">arquivo de seção</link> ou linha de comando. Este item é opcional.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>@image</term>
          <listitem>
            <para>A imagem a ser exibida no topo da página de referência desta seção. Isso frequentemente será um tipo de diagrama para ilustrar a aparência visual de uma classe ou uma diagrama de suas relações a outras classes. Este item é opcional.</para>
          </listitem>
        </varlistentry>
      </variablelist>

      <tip>
        <para>Para evitar recompilação desnecessária após alterações de documentação inseridas nas documentações de seção no fonte em C onde possível.</para>
      </tip>

    </sect1>

    <sect1 id="documenting_symbols">
      <title>Documentando símbolos</title>

      <para>Cada símbolo (função, macro, struct, enum, signal e property) é documentado em uma bloco separado. O bloco é melhor localizado perto da definição dos símbolos, de forma que seja fácil de mantê-los em sincronia. Portanto, as funções são normalmente documentadas no fonte em C e macros, scructs e enums no arquivo de header.</para>

      <sect2><title>Tags gerais</title>

        <para>Você pode adicionar informação sobre versionamento em todos os elementos de documentação para informar quando uma API foi introduzida ou quando ela se tornou obsoleta.</para>

        <variablelist><title>Tags de versionamento</title>
          <varlistentry><term>Since:</term>
            <listitem>
              <para>Descrição de desde qual versão do código a API está disponível.</para>
            </listitem>
          </varlistentry>
          <varlistentry><term>Deprecated:</term>
            <listitem>
              <para>Parágrafo denotando que esta função deveria não mais ser usada. A descrição deveria apontar o leitor para a nova API.</para>
            </listitem>
          </varlistentry>
        </variablelist>

        <para>Você também pode adicionar informação sobre estabilidade em todos os elementos de documentação para indicar se a estabilidade de uma API é garantida para eles para futuros lançamentos menores do projeto.</para>

        <para>O nível de estabilidade padrão para todos os elementos de documentação pode ser definido passando o argumento <option>--default-stability</option> para <application>gtkdoc-mkdb</application> com um dos valores abaixo.</para>

        <variablelist><title>Tags de estabilidade</title>
          <varlistentry><term>Stability: Stable</term>
            <listitem>
              <para>Marca o elemento como estável. Isto é para APIs públicas cuja estabilidade é garantida para todos os próximos lançamentos menores do projeto.</para>
            </listitem>
          </varlistentry>
          <varlistentry><term>Stability: Unstable</term>
            <listitem>
              <para>Marca o elemento como instável. Isto é para APIs públicas que são publicados como versão de desenvolvimento antes de se tornar estável.</para>
            </listitem>
          </varlistentry>
          <varlistentry><term>Stability: Private</term>
            <listitem>
              <para>Marca o elemento como privado. Isto é para interfaces que podem ser usadas por um conjunto pequeno de módulos, mas não por terceiros.</para>
            </listitem>
          </varlistentry>
        </variablelist>

        <example><title>Tags gerais</title>
          <programlisting>
/**
 * foo_get_bar:
 * @foo: Um foo
 *
 * Obtém o bar do @foo.
 *
 * Returns: bar do @foo
 *
 * Since: 2.6
 * Deprecated: 2.12: Use foo_baz_get_bar() no seu lugar.
 */
Bar *
foo_get_bar(Foo *foo)
{
...
</programlisting>
        </example>
      </sect2>

      <sect2><title>Anotações</title>

        <para>Blocos de documentação podem conter tags de anotação. Essas tags serão renderizadas com dicas de ferramentas descrevendo seu significados. As tags são usadas pelo gobject-introspection para garantir associações (bindings) de linguagens. Uma lista detalhada tags aceitas podem ser encontrada <ulink url="http://live.gnome.org/GObjectIntrospection/Annotations" type="http">no wiki</ulink>.</para>

        <example><title>Anotações</title>
          <programlisting>
/**
 * foo_get_bar: (anotação)
 * @foo: (anotação): algum foo
 *
 * Obtém bar do @foo.
 *
 * Returns: (anotação): bar do @foo
 */
...
/**
 * foo_set_bar_using_the_frobnicator: (anotação) (outra anotação)
 *                                    (e uma outra anotação)
 * @foo: (anotação) (uma outra anotação): algum foo
 *
 * Define bar no @foo.
 */
</programlisting>
        </example>
      </sect2>

      <sect2><title>Bloco de comentário de função</title>

        <para>Por favor, lembre-se de: <itemizedlist>
            <listitem>
              <para>Documente se objetos, listas, strings, etc. retornados devem ser não usados/não referenciados/liberada.</para>
            </listitem>
            <listitem>
              <para>Documente se parâmetros pode ser NULL e o que acontece se eles o forem.</para>
            </listitem>
            <listitem>
              <para>Mencione pré-condições e pós-condições interessantes onde for apropriado.</para>
            </listitem>
          </itemizedlist></para>

        <para>Gtk-doc presume que todos os símbolos (macros, funções) começando com “_” são privados. Eles são tratados como funções estáticas.</para>

        <example><title>Bloco de comentário de função</title>
          <programlisting>
/**
 * nome_da_função:
 * @par1:  descrição do parâmetro 1. Esta pode se estender por mais de
 * uma linha.
 * @par2:  descrição do parâmetro 2
 * @...: uma lista de bars terminada em %NULL
 *
 * A descrição da função vai aqui. Você pode usar @par1 para se referir a parâmetros
 * de forma que eles ficam em destaque na saída. Você também pode usar %constant
 * para constantes, nome_da_função2() para funções e #GtkWidget para links para
 * outras declarações (que pode ser documentada em outro lugar).
 *
 * Returns: um inteiro.
 *
 * Since: 2.2
 * Deprecated: 2.18: Use outra_função() em seu lugar.
 */
</programlisting>
        </example>

        <variablelist><title>Tags de função</title>
          <varlistentry><term>Returns:</term>
            <listitem>
              <para>Parágrafo descrevendo o resultado retornado.</para>
            </listitem>
          </varlistentry>
          <varlistentry><term>@...:</term>
            <listitem>
              <para>No caso da função possuir argumentos variados, você deveria usar esta tag (@Varargs: também funciona por motivos de histórico).</para>
            </listitem>
          </varlistentry>
        </variablelist>

      </sect2>

      <sect2><title>Bloco de comentário de propriedade</title>

        <example><title>Bloco de comentário de propriedade</title>
          <programlisting>
/**
 * AlgumWidget:alguma-propriedade:
 *
 * Aqui você pode documentar uma propriedade.
 */
g_object_propriedade_install_classe (object_classe, PROP_ALGUMA_PROPRIEDADE, ...);
</programlisting>
        </example>

      </sect2>

      <sect2><title>Bloco de comentário de sinal</title>

        <para>Por favor, lembre-se de: <itemizedlist>
            <listitem>
              <para>Documente quando o sinal é emitido e se ele é emitido antes ou após outros sinais.</para>
            </listitem>
            <listitem>
              <para>Documente o que um aplicativo pode fazer no manipulador do sinal.</para>
            </listitem>
          </itemizedlist></para>

        <example><title>Bloco de comentário de sinal</title>
          <programlisting>
/**
 * FooWidget::foobarizado:
 * @widget: o widget que recebeu o sinal
 * @foo: algum foo
 * @bar: algum bar
 *
 * O sinal ::foobarized é emitido cada vez que alguém tenta foobarizar @widget.
 */
foo_sinais[FOOBARIZADO] =
  g_signal_novo ("foobarizado",
                ...
</programlisting>
        </example>

      </sect2>

      <sect2><title>Bloco de comentário de struct</title>
        <example><title>Bloco de comentário de struct</title>
          <programlisting>
/**
 * FooWidget:
 * @bar: algum #gboolean
 *
 * Este é o melhor widget, já mais visto.
 */
typedef struct _FooWidget {
  GtkWidget parent_intance;

  gboolean bar;
} FooWidget;
</programlisting>
        </example>

        <para>Use <code>/*&lt; private &gt;*/</code> antes dos campos da struct privada que você deseja esconder. Use <code>/*&lt; public &gt;*/</code> para o comportamento inverso.</para>

        <para>Se o primeiro campo for “g_iface”, “parent_instance” ou “parent_class”, ele será automaticamente considerado como privado e não precisará ser mencionado no bloco de comentário.</para>

        <para>Blocos de comentário de struct também podem ser usados para GObjects e GObjectClasses. É normalmente uma boa ideia adicionar um bloco de comentário para uma classe, se ela possui vmethods (pois assim é como elas podem ser documentadas). Para o próprio GOBject pode-se usar os documentos de seção relacionados, tendo um bloco separado para a instância do struct seria útil se a instância possui campos públicos. Uma desvantagem aqui é que isso cria duas entradas no índice do mesmo nome (a estrutura e a seção).</para>

      </sect2>

      <sect2><title>Bloco de comentário de enum</title>
        <example><title>Bloco de comentário de enum</title>
          <programlisting>
/**
 * Alguma coisa:
 * @ALGUMACOISA_FOO: alguma coisa foo
 * @ALGUMCAOISA_BAR: alguma coisa bar
 *
 * Valores de enum usados para a coisa, para especificar a coisa.
 */
typedef enum {
  ALGUMACOISA_FOO,
  ALGUMACOISA_BAR,
  /*&lt; private &gt;*/
  ALGUMACOISA_CONTAGEM
} Alguma coisa;
</programlisting>
        </example>

        <para>Use <code>/*&lt; private &gt;*/</code> antes de valores privados de enum que você deseja ocultar. Use <code>/*&lt; public &gt;*/</code> para o comportamento inverso.</para>

      </sect2>
    </sect1>


    <sect1 id="documenting_inline_program">
      <title>Documentação de programa em-linha</title>
      <para>Você pode documentar programas e sua interface de linha de comando usando documentação em-linha.</para>

      <variablelist>
      <title>Tags</title>

      <varlistentry><term>PROGRAM</term>

      <listitem>
      <para>Define o início da documentação de um programa.</para>
      </listitem>
      </varlistentry>

      <varlistentry>
      <term>@short_description:</term>
      <listitem>
      <para>Define uma descrição breve do programa. (Opcional)</para>
      </listitem>
      </varlistentry>

      <varlistentry>
      <term>@synopsis:</term>
      <listitem>
      <para>Define os argumentos, ou lista de argumentos, que o programa pode receber. (Opcional)</para>
      </listitem>
      </varlistentry>

      <varlistentry>
      <term>@see_also:</term>
      <listitem>
      <para>A seção “See Also” (Veja Também) de páginas de manual. (Opcional)</para>
      </listitem>
      </varlistentry>

      <varlistentry>
      <term>@arg:</term>
      <listitem>
      <para>Argumento(s) passado(s) para o programa e sua descrição. (Opcional)</para>
      </listitem>
      </varlistentry>

      <varlistentry>
      <term>Description:</term>
      <listitem>
      <para>Um descrição mais longa do programa.</para>
      </listitem>
      </varlistentry>

      <varlistentry>
      <term>Returns:</term>
      <listitem>
      <para>Especifique qual(is) valor(es) o programa retorna. (Opcional)</para>
      </listitem>
      </varlistentry>

      </variablelist>

      <sect2>
        <title>Exemplo de documentação de programa.</title>
        <example><title>Bloco de documentação de programa</title>
        <programlisting>
/**
 * PROGRAM:programa-teste
 * @short_description: Um programa teste
 * @synopsis: programa-teste [*OPÇÕES*...] --arg1 *arg* *ARQUIVO*
 * @see_also: teste(1)
 * @--arg1 *arg*: define arg1 para *arg*
 * @--arg2 *arg*: define arg2 para *arg*
 * @-v, --version: Exibe o número da versão
 * @-h, --help: Exibe a mensagem de ajuda
 *
 * Descrição longa do programa.
 *
 * Returns: Zero no caso de sucesso, não-zero no caso de falha
 */
int main(int argc, char *argv[])
{
	return 0;
}
</programlisting>
        </example>

      </sect2>
    </sect1>

    <sect1 id="documenting_docbook">
      <title>Tags úteis do DocBook</title>

      <para>Aqui estão algumas tags de DocBook que são muito úteis quando se está documentado o código.</para>

      <para>Para vincular a outra seção nas documentações do GTK: <informalexample>
          <programlisting>
&lt;link linkend="glib-Hash-Tables"&gt;Tabela de hashes&lt;/link&gt;
</programlisting>
        </informalexample> O "linked" é a identificação SGML/XML no item superior da página a qual você deseja vincular. Para a maioria das páginas isto é atualmente a parte (“gtk”, “gdk”, “glib”) e, então, o título da página (“Hash Tables”). Para os widgets isso é apenas o nome da classe. Espaços e sublinhados são convertidos em '-' para estar em conformidade com SGML/XML.</para>

      <para>Para se referir a uma função externa, como, por exemplo, uma função padrão do C: <informalexample>
          <programlisting>
&lt;function&gt;...&lt;/function&gt;
</programlisting>
        </informalexample></para>

      <para>
        To include example code:
        <informalexample>
          <programlisting><![CDATA[
<example>
  <title>Using a GHashTable.</title>
  <programlisting language="C">
      ...
  </programlisting>
</example>
]]></programlisting>
        </informalexample>
        or possibly this, for very short code fragments which don't need a title:
        <informalexample>
          <programlisting><![CDATA[
<informalexample>
  <programlisting language="C">
  ...
  </programlisting>
</informalexample>
]]></programlisting>
        </informalexample>
        In both cases, the language attribute is optional and is used as a hint
        to the syntax highlighting engine (pygments for html output).
        For the latter GTK-Doc also supports an abbreviation:
        <informalexample>
          <programlisting><![CDATA[
|[<!-- language="C" -->
  ...
]|
]]></programlisting>
        </informalexample>
      </para>

      <para>Para incluir listas com marcadores: <informalexample>
          <programlisting>
&lt;itemizedlist&gt;
  &lt;listitem&gt;
    &lt;para&gt;
      ...
    &lt;/para&gt;
  &lt;/listitem&gt;
  &lt;listitem&gt;
    &lt;para&gt;
      ...
    &lt;/para&gt;
  &lt;/listitem&gt;
&lt;/itemizedlist&gt;
</programlisting>
        </informalexample></para>

      <para>Para incluir uma nota que fique fora do texto: <informalexample>
          <programlisting>
&lt;note&gt;
  &lt;para&gt;
    Certifique-se de que você liberou os dados após usá-los.
  &lt;/para&gt;
&lt;/note&gt;
</programlisting>
        </informalexample></para>

      <para>Para se referir a um tipo: <informalexample>
          <programlisting>
&lt;type&gt;unsigned char&lt;/type&gt;
</programlisting>
        </informalexample></para>

      <para>Para se referir a uma estrutura externa (não uma descrita nos documentos do GTK): <informalexample>
          <programlisting>
&lt;structname&gt;XFontStruct&lt;/structname&gt;
</programlisting>
        </informalexample></para>

      <para>Para se referir a um campo de uma estrutura: <informalexample>
          <programlisting>
&lt;structfield&gt;len&lt;/structfield&gt;
</programlisting>
        </informalexample></para>

      <para>Para se referir a um nome de classe, nós possivelmente poderíamos usar: <informalexample>
          <programlisting>
&lt;classname&gt;GtkWidget&lt;/classname&gt;
</programlisting>
        </informalexample> mas você provavelmente vai estar usando #GtkWidget em vez disso (para criar automaticamente um link para a página do GtkWidget – veja <link linkend="documenting_syntax">as abreviações</link>).</para>

      <para>Para enfatizar um texto: <informalexample>
          <programlisting>
&lt;emphasis&gt;Isso é importante&lt;/emphasis&gt;
</programlisting>
        </informalexample></para>

      <para>Para nome de arquivos use: <informalexample>
          <programlisting>
&lt;filename&gt;/home/usuario/documentos&lt;/filename&gt;
</programlisting>
        </informalexample></para>

      <para>Para se referir a chaves use: <informalexample>
          <programlisting>
&lt;keycombo&gt;&lt;keycap&gt;Control&lt;/keycap&gt;&lt;keycap&gt;L&lt;/keycap&gt;&lt;/keycombo&gt;
</programlisting>
        </informalexample></para>

    </sect1>
  </chapter>

  <chapter id="metafiles">
    <title>Preenchendo os arquivos extras</title>

    <para>Há alguns poucos arquivos extras, que precisam ser mantidos junto com os comentários inseridos no código-fonte: <filename>&lt;pacote&gt;.types</filename>, <filename>&lt;pacote&gt;-docs.xml</filename> (no passado, .sgml), <filename>&lt;pacote&gt;-sections.txt</filename>.</para>

    <sect1 id="metafiles_types">
      <title>Editando o arquivo de tipos</title>

      <para>Se sua biblioteca ou aplicativo inclui GObjects, você deseja que seus sinais, argumentos/parâmetros e posição na hierarquia sejam mostrados na documentação. Tudo que você precisa fazer é listar as funções <function>xxx_get_type</function> junto com seus include dentro do arquivo <filename>&lt;pacote&gt;.types</filename>.</para>

      <para>
        <example><title>Exemplo de arquivo &lt;pacote&gt;.types</title>
          <programlisting>
#include &lt;gtk/gtk.h&gt;

gtk_accel_label_get_type
gtk_adjustment_get_type
gtk_alignment_get_type
gtk_arrow_get_type
</programlisting>
        </example>
      </para>

      <para>Desde o GTK-Doc 1.8, o <application>gtkdoc-scan</application> pode gerar esta lista para você. Basta adicionar “--rebuild-types” a SCAN_OPTIONS no <filename>Makefile.am</filename>. Se você usar esta abordagem, você não deveria distribuir o arquivo de tipos nem tê-lo sob um controle de versão.</para>

    </sect1>

    <sect1 id="metafiles_master">
      <title>Editando o documento mestre</title>

      <para>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.</para>

      <para>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á.</para>

      <tip>
        <para>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.</para>
      </tip>

      <para>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.</para>

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

&lt;chapter&gt;
  &lt;title&gt;[Insira o título aqui]&lt;/title&gt;
</programlisting>
        </example>
      </para>

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

      <para>
        <example><title>Parte opcional do documento mestre</title>
          <programlisting>
  &lt;!-- habilite isso se você usa anotações do gobject introspection
  &lt;xi:include href="xml/annotation-glossary.xml"&gt;&lt;xi:fallback /&gt;&lt;/xi:include&gt;
  --&gt;
</programlisting>
        </example>
      </para>

      <para>Finalmente você precisa adicionar nova seção sempre que você a introduzir. A ferramenta <link linkend="modernizing-gtk-doc-1-16">gtkdoc-check</link> vai lembrar você de arquivos xml recentemente gerados que ainda não foram incluídos na documentação.</para>

      <para>
        <example><title>Incluindo seções geradas</title>
          <programlisting>
  &lt;chapter&gt;
    &lt;title&gt;minha biblioteca&lt;/title&gt;
      &lt;xi:include href="xml/object.xml"/&gt;
      ...
</programlisting>
        </example>
      </para>

    </sect1>

    <sect1 id="metafiles_sections">
      <title>Editando o arquivo de seção</title>

      <para>O arquivo de seção é usado para organizar a saída da documentação pelo GTK-Doc. Aqui pode-se especificar qual símbolo pertence a qual módulo ou classe e controla a visibilidade (pública ou privada).</para>

      <para>O arquivo de seção é uma arquivo texto simples com seções delimitadas por tags. Linhas em branco são ignoradas e linhas começando com um “#” são tratadas como linhas de comentários.</para>

      <note>
        <para>Enquanto as tags fazem o arquivo se parecer xml, ele não é. Por favor, não feche tags como &lt;SUBSECTION&gt;.</para>
      </note>

      <para>
        <example><title>Incluindo seções geradas</title>
          <programlisting>
&lt;INCLUDE&gt;libmeep/meep.h&lt;/INCLUDE&gt;

&lt;SECTION&gt;
&lt;FILE&gt;meepapp&lt;/FILE&gt;
&lt;TITLE&gt;MeepApp&lt;/TITLE&gt;
MeepApp
&lt;SUBSECTION Standard&gt;
MEEP_APP
...
MeepAppClass
meep_app_get_type
&lt;/SECTION&gt;
</programlisting>
        </example>
      </para>

      <para>A tag &lt;FILE&gt; ... &lt;/FILE&gt; é usada para especificar o nome de arquivo, sem qualquer sufixo. Por exemplo, ao usar “&lt;FILE&gt;gnome-config&lt;/FILE&gt;” resultará nas declarações da seção serem retornadas no arquivo modelo <filename>tmpl/gnome-config.sgml</filename>, o qual será convertido no arquivo DocBook XML <filename>xml/gnome-config.sgml</filename> ou no arquivo DocBook XML <filename>xml/gnome-config.xml</filename>. (O nome do arquivo HTML é baseado no nome do módulo e no título da seção ou, para GObjects, é baseado no nome da classe GObjects convertidos os caracteres para minúsculos).</para>

      <para>A tag &lt;TITLE&gt; ... &lt;/TITLE&gt; é usada para especificar o título da seção. Ela é usada apenas antes do modelo (se usado) ser criado inicialmente, já que o título definido no arquivo de modelo sobrescreve este. Também, se for usado o comentário SECTION nos fontes, isso está obsoleto.</para>

      <para>Você pode agrupar itens na seção usando a tag &lt;SUBSECTION&gt;. Atualmente, ela retorna uma linha em branco entre as subseções na seção de sinopse. Você também pode usar &lt;SUBSECTION Standard&gt; para declarações padrão do GObject (ex.: as funções como g_object_get_type e macros como G_OBJECT(), G_IS_OBJECT() etc.). Atualmente, estas são deixadas fora da documentação. Você também pode usar &lt;SUBSECTION Private&gt; para declarações privadas que não serão retornadas (é uma forma prática de evitar mensagens de aviso sobre declarações não usadas). Se sua biblioteca contém tipos privados que você não deseja que apareçam na hierarquia do objeto e a linha de classes implementadas ou exigidas, adicione-as a uma subseção privada. Se você colocaria o GObject e GObjectClass como structs numa seção padrão ou pública depende se há entradas públicas (variáveis, vmethods).</para>

      <para>Você também pode usar &lt;INCLUDE&gt; ... &lt;/INCLUDE&gt; para especificar os arquivos #include que são mostrados nas seções de sinopse. Ela contém uma lista separada por vírgula de arquivos #include, sem os sinais de maior que e menor que. Se você define-a fora de quaisquer seções, ela age para todas as seções até o fim do arquivo. Se você define-a em uma seção, ela só vai se aplicar àquela seção.</para>

    </sect1>

  </chapter>

  <chapter id="reports">
    <title>Controlando o resultado</title>

    <para>Uma execução do GTK-Doc gera arquivos de relatórios dentro do diretório de documentação. Os arquivos gerados são chamados: <filename>&lt;pacote&gt;-undocumented.txt</filename>, <filename>&lt;pacote&gt;-undeclared.txt</filename> e <filename>&lt;pacote&gt;-unused.txt</filename>. Todos eles são arquivos texto simples que podem ser facilmente visualizados e pós-processados.</para>

    <para>O arquivo <filename>&lt;pacote&gt;-undocumented.txt</filename> começa com um sumário de cobertura da documentação. Abaixo estão duas seções divididas por linhas brancas. A primeira seção lista símbolos não documentados e incompletos. A segunda seção faz o mesmo para os documentos de seção. Entradas incompletas são aquelas que foram documentadas, mas nas quais, por exemplo, um novo parâmetro foi adicionado.</para>

    <para>O arquivo <filename>&lt;pacote&gt;-undeclared.txt</filename> lista símbolos dados no <filename>&lt;pacote&gt;-sections.txt</filename>, mas não encontrados nos fontes. Verifique se eles foram removidos ou se eles foram escritos incorretamente.</para>

    <para>O arquivo <filename>&lt;pacote&gt;-unused.txt</filename> lista nomes de símbolo cuja documentação foi localizada na varredura do GTK-Doc, mas que não sabe onde colocá-los. Isso significa que o símbolo não foi adicionado ainda ao arquivo <filename>&lt;pacote&gt;-sections.txt</filename>.</para>

    <tip>
      <para>Habilite ou adicione a linha <option>TESTS=$(GTKDOC_CHECK)</option> no Makefile.am. Se pelo menos GTK-Doc 1.9 estiver instalado, isso vai executar verificações de sanidade durante a execução de <command>make check</command>.</para>
    </tip>

    <para>Também pode-se buscar nos arquivos produzidos pela varredura do código-fonte: <filename>&lt;pacote&gt;-decl-list.txt</filename> e <filename>&lt;pacote&gt;-decl.txt</filename>. O primeiro pode ser comparado com o arquivo de seção, se ele for mantido manualmente. O segundo lista todas as declarações de cabeçalhos. Se um símbolo está faltando, pode-se verificar se este arquivo o contém.</para>

    <para>Se o projeto é baseado em GObject, pode-se também procurar nos arquivos produzidos pela varredura de objetos: <filename>&lt;pacote&gt;.args.txt</filename>, <filename>&lt;pacote&gt;.hierarchy.txt</filename>, <filename>&lt;pacote&gt;.interfaces.txt</filename>, <filename>&lt;pacote&gt;.prerequisites.txt</filename> e <filename>&lt;pacote&gt;.signals.txt</filename>. Se há símbolos faltando em qualquer um deles, pode-se exigir que o GTK-Doc mantenha o arquivo intermediário de varredura para análise posterior, executando <command>GTK_DOC_KEEP_INTERMEDIATE=1 make</command>.</para>
  </chapter>

  <chapter id="modernizing">
    <title>Modernizando a documentação</title>

    <para>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.</para>

    <sect1 id="modernizing-gtk-doc-1-9">
      <title>GTK-Doc 1.9</title>

      <para>Ao usar xml em vez de sgml, na verdade, é possível nomear o documento mestre <filename>&lt;pacote&gt;-docs.xml</filename>.</para>

      <para>Essa versão provê suporte <option>SCAN_OPTIONS=--rebuild-sections</option> em <filename>Makefile.am</filename>. Quando esta opção está habilitada, o <filename>&lt;package&gt;-sections.txt</filename> é 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 <code>meld &lt;package&gt;-decl-list.txt &lt;package&gt;-sections.txt</code>.</para>

      <para>A versão 1.8 já introduziu a sintaxe para documentação seções nos fontes em vez dos arquivos separados sob <filename class="directory">tmpl</filename>. 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 <option>--flavour no-tmpl</option> no <filename>configure.ac</filename>. Se você não possui um <filename class="directory">tmpl</filename> no seu sistema de controle de versão e ainda não trocou, basta adicionar uma opção ao <filename>configure.ac</filename> e está resolvido.</para>
    </sect1>

    <sect1 id="modernizing-gtk-doc-1-10">
      <title>GTK-Doc 1.10</title>

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

    <sect1 id="modernizing-gtk-doc-1-16">
      <title>GTK-Doc 1.16</title>

      <para>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 <filename>Makefile.am</filename>. <example><title>Habilitar gtkdoc-check</title>
          <programlisting>
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
</programlisting>
        </example></para>
    </sect1>

    <sect1 id="modernizing-gtk-doc-1-20">
      <title>GTK-Doc 1.20</title>

      <para>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 <link linkend="documenting_syntax">sintaxe de comentário</link> tem todos os detalhes.</para>
    </sect1>

    <sect1 id="modernizing-gtk-doc-1-25">
      <title>GTK-Doc 1.25</title>

      <para>Os makefiles fornecidos com esta versão geram um arquivo de entidade em <filename>xml/gtkdocentities.ent</filename>, 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 no modelo mestre 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. <example><title>Usando entradas geradas previamente</title>
          <programlisting>
&lt;?xml version="1.0"?&gt;
&lt;!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
[
  &lt;!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'"&gt;
  &lt;!ENTITY % gtkdocentities SYSTEM "xml/gtkdocentities.ent"&gt;
  %gtkdocentities;
]&gt;
&lt;book id="index" xmlns:xi="http://www.w3.org/2003/XInclude"&gt;
  &lt;bookinfo&gt;
    &lt;title&gt;Manual de referência do &amp;nome-pacote;&lt;/title&gt;
    &lt;releaseinfo&gt;
      para &amp;versão-pacote;.
      A última versão desta documentação pode ser encontra on-line em
      &lt;ulink role="online-location" url="http://[SERVIDOR]/&amp;nome-pacote;/index.html"&gt;http://[SERVIDOR]/&amp;nome-pacote;/&lt;/ulink&gt;.
    &lt;/releaseinfo&gt;
  &lt;/bookinfo&gt;
</programlisting>
        </example></para>
    </sect1>
  </chapter>

  <chapter id="documenting-others">
    <title>Documentando outras interfaces</title>

    <para>Até agora nós temos usado o GTK-Doc para documentar a API de um código. As próximas sessões contêm sugestões de como as ferramentas podem ser usadas para documentar outras interfaces, também.</para>

    <sect1 id="commandline-interfaces">
      <title>Opções de linha de comando e de páginas man</title>

      <para>Já que também é possível gerar páginas man para um refentry do docbook, soa como uma boa ideia usá-lo para este propósito. Desta forma, a interface é parte da referência e é possível obter a página man livremente.</para>

      <sect2 id="commandline-interfaces-file">
        <title>Documentar a ferramenta</title>

        <para>Crie um arquivo refentry por ferramenta. Segundo <link linkend="settingup_docfiles">nosso exemplo</link> nós chamaríamos ele de <filename>meep/docs/reference/meeper/meep.xml</filename>. Para as tags xml que devem ser usadas e podem parecer no arquivo gerado no subdiretório xml assim como exemplos, por exemplo, em glib.</para>
      </sect2>

      <sect2 id="commandline-interfaces-configure">
        <title>Adicionando a verificação extra ao configure</title>

        <para>
          <example><title>Verificações extra no configure</title>
            <programlisting>
AC_ARG_ENABLE(man,
              [AC_HELP_STRING([--enable-man],
                              [regenerate man pages from Docbook [default=no]])],enable_man=yes,
              enable_man=no)

AC_PATH_PROG([XSLTPROC], [xsltproc])
AM_CONDITIONAL(ENABLE_MAN, test x$enable_man != xno)
</programlisting>
          </example>
        </para>
      </sect2>

      <sect2 id="commandline-interfaces-make">
        <title>Adicionando as regras extras ao makefile</title>

        <para>
          <example><title>Verificações extra no configure</title>
            <programlisting>
man_MANS = \
       meeper.1

if ENABLE_GTK_DOC
if ENABLE_MAN

%.1 : %.xml
        @XSLTPROC@ -nonet http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl $&lt;

endif
endif

BUILT_EXTRA_DIST = $(man_MANS)
EXTRA_DIST += meep.xml
</programlisting>
          </example>
        </para>
      </sect2>
    </sect1>

    <sect1 id="dbus-interfaces">
      <title>Interfaces DBus</title>

      <para>(CORRIJA-ME: http://hal.freedesktop.org/docs/DeviceKit/DeviceKit.html, http://cgit.freedesktop.org/DeviceKit/DeviceKit/tree/doc/dbus)</para>
    </sect1>

  </chapter>

  <chapter id="faq">
    <title>Perguntas frequentes</title>

    <segmentedlist>
      <?dbhtml list-presentation="list"?>
      <segtitle>Questão</segtitle>
      <segtitle>Resposta</segtitle>
      <seglistitem>
        <seg>Sem hierarquia de classe.</seg>
        <seg>A função de objetos <function>xxx_get_type()</function> não foi inserida no arquivo <filename>&lt;pacote&gt;.types</filename>.</seg>
      </seglistitem>
      <seglistitem>
        <seg>Ainda sem hierarquia.</seg>
        <seg>Nomenclatura faltando ou incorreta no arquivo <filename>&lt;pacote&gt;-sections.txt</filename> (veja a <ulink url="http://mail.gnome.org/archives/gtk-doc-list/2003-October/msg00006.html">explicação</ulink>).</seg>
      </seglistitem>
      <seglistitem>
        <seg>Droga. Eu ainda não tenho hierarquia de classes.</seg>
        <seg>Por acaso o nome do objeto (nome da struct da instância, ex. <type>GtkWidget</type>) faz parte da seção normal (não coloque isso em subseções Standard ou Private)?</seg>
      </seglistitem>
      <seglistitem>
        <seg>Nenhum símbolo de índice.</seg>
        <seg>O <filename>&lt;pacote&gt;-docs.{xml,sgml}</filename> contém um índice que “xi:inclui” o índice gerado?</seg>
      </seglistitem>
      <seglistitem>
        <seg>Símbolos não estão vinculados ao seus doc-section.</seg>
        <seg>O doc-comment está usando a marcação correta (adicionado #,% or ())? Verifique se o gtkdoc-fixxref avisa sobre xrefs não resolvidos.</seg>
      </seglistitem>
      <seglistitem>
        <seg>Uma nova classe não aparece nos documentos.</seg>
        <seg>A nova página foi “xi:incluída” do <filename>&lt;pacote&gt;-docs.{xml,sgml}</filename>?</seg>
      </seglistitem>
      <seglistitem>
        <seg>Um novo símbolo não aparece nos documentos.</seg>
        <seg>O doc-comment está formatado adequadamente? Verifique erros de escrita no começo do comentário. Verifique se o gtkdoc-fixxref avisa sobre xrefs não resolvíveis. Verifique se o símbolo está listado corretamente no <filename>&lt;pacote&gt;-sections.txt</filename> em uma subseção pública.</seg>
      </seglistitem>
      <seglistitem>
        <seg>Um tipo está faltando da hierarquia de classe.</seg>
        <seg>Se o tipo está listado no <filename>&lt;pacote&gt;.hierarchy</filename>, mas não em <filename>xml/tree_index.sgml</filename>, então certifique-se de que o tipo está colocado corretamente no <filename>&lt;pacote&gt;-sections.txt</filename>. Se a instância do tipo (ex.: <type>GtkWidget</type>) não está listada ou incidentalmente marcada como privada, ela não será mostrada.</seg>
      </seglistitem>
      <seglistitem>
        <seg>Obtenho links de seguimento de documentos para todas as anotações gobject.</seg>
        <seg>Verifique se <filename>xml/annotation-glossary.xml</filename> está “xi:incluído” de <filename>&lt;pacote&gt;-docs.{xml,sgml}</filename>.</seg>
      </seglistitem>

      <!-- gtk-doc warnings: -->
      <seglistitem>
        <seg>Parâmetro descrito no bloco de comentário do código-fonte não existe</seg>
        <seg>Verifique se o protótipo no cabeçalho tem nomes de parâmetros diferentes da fonte.</seg>
      </seglistitem>

      <!-- docbook warnings: -->
      <seglistitem>
        <seg>múltiplos “IDs” para restrições do fim do link XYZ</seg>
        <seg>O símbolo XYZ aparece duas vezes no arquivo <filename>&lt;pacote&gt;-sections.txt</filename>.</seg>
      </seglistitem>
      <seglistitem>
        <seg>Elemento typename no espaço de nome '' encontrado em para, mas nenhum modelo correspondeu.</seg>
        <seg/>
      </seglistitem>
    </segmentedlist>
  </chapter>

  <chapter id="contrib">
    <title>Ferramentas relacionadas ao gtk-doc</title>

    <para>GtkDocPlugin – um plug-in de integração com <ulink url="http://trac-hacks.org/wiki/GtkDocPlugin">Trac GTK-Doc</ulink>, que adiciona documentos de API a um site trac e integra com a pesquisa do trac.</para>
    <para>Gtkdoc-depscan – uma ferramenta (parte do gtk-doc) para verificar APIs usadas, a partir de suas tags, para determinar a versão mínima necessária.</para>

  </chapter>

  <!-- ======== Appendix: FDL ================================== -->
  <!--  
     The GNU Free Documentation License 1.1 in DocBook
     Markup by Eric Baudais <baudais@okstate.edu>
     Maintained by the GNOME Documentation Project
     http://developer.gnome.org/projects/gdp
     Version: 1.0.1
     Last Modified: Nov 16, 2000
-->

<appendix id="fdl">
  <appendixinfo>
    <releaseinfo>Versão 1.1, Março de 2000</releaseinfo>
    <copyright><year>2000</year><holder>Free Software Foundation, Inc.</holder></copyright>
    <legalnotice id="fdl-legalnotice">
      <para><address>Free Software Foundation, Inc. <street>51 Franklin Street, 
        Suite 330</street>, <city>Boston</city>, <state>MA</state>  
        <postcode>02110-1301</postcode>  <country>USA</country></address> É permitido a qualquer um copiar e distribuir cópias exatas deste documento de licença, embora não seja permitido alterá-lo.</para>
    </legalnotice>
  </appendixinfo>
  <title>Licença de Documentação Livre GNU</title>

  <sect1 id="fdl-preamble">
    <title>0. PREÂMBULO</title>
    <para>O objetivo desta Licença é tornar um manual, livro didático ou outro documento funcional e útil “livre” no sentido de liberdade: assegurar a todos a liberdade efetiva de copiá-lo e redistribuí-lo, com ou sem modificação do mesmo, comercialmente ou não. Em segundo lugar, esta Licença preserva para o autor e o editor uma maneira de obter crédito por seu trabalho, sem ser considerado responsável por modificações feitas por outros.</para>
    
    <para>Esta licença é um tipo de “copyleft”, o que significa que trabalhos derivados do documento devem ser livres no mesmo sentido. Ela complementa a Licença Pública Geral GNU (GNU General Public License), que é uma licença com copyleft projetada para software livre.</para>
    
    <para>Criamos esta Licença para usá-la para manuais para software livre, porque software livre precisa de documentação livre: um programa livre deve ser fornecido com manuais que proporcionam as mesmas liberdades que o software. Mas esta Licença não está limitada aos manuais de software; pode ser usada para qualquer trabalho textual, independentemente do assunto ou dele ser publicado como um livro impresso. Recomendamos esta Licença principalmente para trabalhos cujo propósito seja instrução ou referência.</para>
  </sect1>
  <sect1 id="fdl-section1">
    <title>1. APLICABILIDADE E DEFINIÇÕES</title>
    <para id="fdl-document">Esta Licença aplica-se a qualquer manual ou outro trabalho, em qualquer meio, que contenha um aviso colocado pelo detentor dos direitos autorais dizendo que pode ser distribuído nos termos desta Licença. Tal aviso concede uma licença mundial, sem royalties, de duração ilimitada, para usar esse trabalho nas condições aqui estabelecidas. O “Documento”, a seguir, refere-se a qualquer manual ou trabalho. Qualquer membro do público é um licenciado e é referido como “você”. Você aceita a licença se você copiar, modificar ou distribuir o trabalho de forma a exigir permissão de acordo com a lei de direitos autorais.</para>
    
    <para id="fdl-modified">Uma “Versão Modificada” do Documento significa qualquer trabalho contendo o Documento ou uma porção deste, seja uma cópia literal ou com modificações e/ou traduzido em outro idioma.</para>
	
    <para id="fdl-secondary">A “Seção Secundária” é um apêndice nomeado ou uma seção anterior do Documento que trata exclusivamente do relacionamento dos editores ou autores do <link linkend="fdl-document">Documento</link> com o assunto geral do documento (ou assuntos relacionados) e não contém nada que possa estar diretamente dentro desse assunto geral. (Assim, se o Documento for, em parte, um livro de texto de matemática, uma Seção Secundária pode não explicar qualquer matemática.) O relacionamento poderia ser uma questão de conexão histórica com o assunto ou com assuntos relacionados, ou de posição legal, comercial, filosófica, ética ou política em relação a eles.</para>

    <para id="fdl-invariant">As “Seções Invariantes” são certas <link linkend="fdl-secondary">Seções Secundárias</link> cujos títulos são designados, como sendo daquelas de Seções Invariantes, no aviso que diz que o <link linkend="fdl-document">Documento</link> é liberado sob esta Licença.</para>
    
    <para id="fdl-cover-texts">Os “Textos de Capa” são certas passagens de texto que são listadas como Textos de Capa Frontal ou Textos de Contracapa, no aviso que afirma que o <link linkend="fdl-document">Documento</link> foi publicado sob esta Licença.</para>
	
    <para id="fdl-transparent">Uma cópia “Transparente” do <link linkend="fdl-document"> Documento</link> significa uma cópia legível por máquina, representada em um formato cuja especificação está disponível para o público em geral, cujo conteúdo possa ser visto e editado diretamente com editores de texto genéricos ou (para imagens compostas de pixels) programas gráficos genéricos ou (para desenhos) algum editor de desenho amplamente disponível, e isso seja adequado para entrada para formatadores de texto ou para tradução automática para uma variedade de formatos adequados para entrada de formatadores de texto. Uma cópia feita em um formato de arquivo Transparente cuja marcação tenha sido projetada para frustrar ou desencorajar a modificação subsequente pelos leitores não é Transparente. Uma cópia que não é “Transparente” é chamada de “Opaca”.</para>
    
    <para>Exemplos de formatos adequados para cópias Transparentes incluem ASCII simples sem marcação, formato de entrada Texinfo, formato de entrada LaTeX, SGML ou XML usando DTD publicamente disponível e HTML simples, conforme padrão, projetados para modificação humana. Os formatos Opacos incluem PostScript, PDF, formatos proprietários que podem ser lidos e editados apenas por processadores de texto proprietários, SGML ou XML para os quais o DTD e/ou ferramentas de processamento não estão geralmente disponíveis e o HTML gerado por máquina produzido por alguns processadores de texto para apenas para fins de saída.</para>
    
    <para id="fdl-title-page">A “Página de Título” significa, para um livro impresso, a própria página do título, além das páginas subsequentes necessárias para conter, de forma legível, o material que esta Licença requer que apareça na página do título. Para trabalhos em formatos que não possuem qualquer página de título semelhante, “Página de Título” significa o texto próximo à ocorrência mais proeminente do título do trabalho, precedendo o início do corpo do texto.</para>
  </sect1>
    
  <sect1 id="fdl-section2">
    <title>2. CÓPIA LITERAL</title>
    <para>Você pode copiar e distribuir o <link linkend="fdl-document">Documento</link> em qualquer meio, seja este de forma comercial ou não, desde que esta Licença, os avisos de direitos autorais e o aviso de licença afirmando que esta Licença se aplica ao Documento sejam reproduzidos em todas as cópias, e que você adicione nenhuma outra condição, qualquer que seja, às condições desta Licença. Você não pode usar de medidas técnicas para obstruir ou controlar a leitura ou cópia futura das cópias que você fizer ou distribuir. Contudo, você pode aceitar compensação em troca das cópias. Se você distribuir um número suficientemente grande de cópias, você deve também respeitar as condições descritas na <link linkend="fdl-section3">seção 3</link>.</para>
    
    <para>Você também pode emprestar cópias, nas mesmas condições acima mencionadas, e você pode publicar cópias.</para>
    </sect1>
    
  <sect1 id="fdl-section3">
    <title>3. COPIANDO EM QUANTIDADE</title>
    <para>Se você publicar cópias impressas do <link linkend="fdl-document">Documento</link> em número maior que 100, e o aviso de licença do Documento exigir os <link linkend="fdl-cover-texts">Textos de Capa</link>, você deve incluir as cópias nas capas que carregam, de forma clara e legível, todas essas Textos de Capa: Textos de Capa Frontal na capa frontal e Textos de Contracapa na contracapa. Ambas as capas também devem identificá-lo claramente e legivelmente como o editor dessas cópias. A capa frontal deve apresentar o título completo com todas as palavras do título igualmente proeminentes e visíveis. Você também pode adicionar outros materiais nas capas. Copiar com as alterações limitadas às capas, desde que preservem o título do <link linkend="fdl-document">Documento</link> e satisfaçam estas condições, podem ser tratadas como cópias literais em outros aspectos.</para>
    
    <para>Se os textos necessários para qualquer uma das coberturas forem demasiado volumosos para se ajustar de forma legível, você deve colocar os primeiros listados (tanto quanto encaixar razoavelmente) na capa real e continuar o resto em páginas adjacentes.</para>
    
    <para>Se você publicar ou distribuir cópias <link linkend="fdl-transparent">Opacas</link> do <link linkend="fdl-document">Documento</link> em número superior a 100, você deve incluir uma cópia <link linkend="fdl-transparent">Transparente</link> legível por máquina junto com cada cópia Opaca ou estabelecer em ou com cada cópia Opaca uma localização de rede de computador publicamente acessível contendo uma cópia transparente completa do documento, sem material adicional, a partir da qual o público geral usuário de rede tem acesso para baixar anonimamente sem custo, usando protocolos de rede padrão público. Se você usar a última opção, você deve tomar medidas razoavelmente prudentes, quando você começar a distribuir cópias Opacas em quantidade, para garantir que esta cópia Transparente permanecerá acessível no local indicado até pelo menos um ano após a última vez que você distribuir uma cópia Opaca (diretamente ou através de seus agentes ou varejistas) dessa edição para o público.</para>
    
    <para>É solicitado, mas não é necessário, que você contate os autores do <link linkend="fdl-document">Documento</link> muito antes de redistribuir qualquer grande número de cópias, para dar a eles uma chance de lhe fornecer uma versão atualizada do Documento.</para>
    </sect1>
    
  <sect1 id="fdl-section4">
    <title>4. MODIFICAÇÕES</title>
    <para>Você pode copiar e distribuir uma <link linkend="fdl-modified">Versão Modificada</link> do <link linkend="fdl-document">Documento</link> sob as condições das seções <link linkend="fdl-section2">2</link> e <link linkend="fdl-section3">3</link> acima, desde que você forneça a Versão Modificada estritamente sob esta Licença, com a Versão Modificada preenchendo a função de Documento, permitindo assim a distribuição e modificação da Versão Modificada a quem quer que possua uma cópia desta. Além disso, você deve executar os seguintes procedimentos na Versão Modificada:</para>
    
    <itemizedlist mark="opencircle">
      <listitem>
	<formalpara>
	  <title>A</title>
	  <para>Usar na <link linkend="fdl-title-page">Página de Título</link> (e nas capas, se existirem) um título distinto em relação ao do <link linkend="fdl-document">Documento</link>, e daqueles de versões anteriores (os quais devem, havendo algum, ser listados na seção “Histórico” do Documento). Você pode usar o mesmo título de uma versão anterior se o editor original daquela versão lhe conceder permissão.</para>
	</formalpara>
      </listitem>
      
      <listitem>
	<formalpara>
	  <title>B</title>
	  <para>Listar na <link linkend="fdl-title-page">Página de Título</link>, como autores, uma ou mais pessoas ou entidades responsáveis pela autoria das modificações na <link linkend="fdl-modified">Versão Modificada</link>, juntamente com pelo menos cinco dos autores principais do <link linkend="fdl-document">Documento</link> (todos os seus principais autores, se tiverem menos de cinco).</para>
	</formalpara>
      </listitem>
      
      <listitem>
	<formalpara>
	  <title>C</title>
	  <para>Indicar na  <link linkend="fdl-title-page">Página de Título</link> o nome do editor da <link linkend="fdl-modified">Versão Modificada</link>, como editor.</para>
	</formalpara>
      </listitem>
      
      <listitem>
	<formalpara>
	  <title>D</title>
	  <para>Preservar todas as avisos de direitos autorais do <link linkend="fdl-document">Documento</link>.</para>
	</formalpara>
      </listitem>
      
      <listitem>
	<formalpara>
	  <title>E</title>
	  <para>Adicionar um aviso de direitos autorais apropriado para suas modificações adjacentes aos outros avisos de direitos autorais.</para>
	</formalpara>
      </listitem>
      
      <listitem>
	<formalpara>
	  <title>F</title>
	  <para>Incluir, imediatamente após os avisos de direitos autorais, um aviso de licença que dê permissão ao público para usar a <link linkend="fdl-modified">Versão Modificada</link> sob os termos desta Licença, na forma mostrada no Adendo abaixo.</para>
	</formalpara>
      </listitem>
      
      <listitem>
	<formalpara>
	  <title>G</title>
	  <para>Preservar nesse aviso de licença as listas completas de <link linkend="fdl-invariant">Seções Invariantes</link> e os <link linkend="fdl-cover-texts">Textos de Capa</link> necessários fornecidos no aviso de licença do <link linkend="fdl-document">Documento</link>.</para>
	</formalpara>
      </listitem>
      
      <listitem>
	<formalpara>
	  <title>H</title>
	  <para>Incluir uma cópia inalterada desta Licença.</para>
	</formalpara>
      </listitem>
      
      <listitem>
	<formalpara>
	  <title>I</title>
	  <para>Preservar a seção intitulada “Histórico”, e seu título, e adicionar a ele um item que indique pelo menos o título, o ano, os novos autores e o editor da <link linkend="fdl-modified">Versão Modificada</link> conforme indicado na <link linkend="fdl-title-page">Página de Título</link>. Se não houver uma seção intitulada “Histórico” no <link linkend="fdl-document">Documento</link>, crie um que declare o título, o ano, os autores e o editor do Documento conforme indicado em sua Página de Título e, em seguida, adicione um item descrevendo a Versão Modificada, como indicado na frase anterior.</para>
	</formalpara>
      </listitem>
      
      <listitem>
	<formalpara>
	  <title>J</title>
	  <para>Preservar a localização de rede, se for o caso, fornecida no <link linkend="fdl-document">Documento</link> para acesso público a uma cópia <link linkend="fdl-transparent">Transparente</link> do Documento, e também as localizações de rede fornecidas no Documento para versões anteriores nas quais ele foi baseado. Estas podem ser colocadas na seção “Histórico”. Você pode omitir uma localização de rede para um trabalho que foi publicado pelo menos quatro anos antes do Documento em si, ou se o editor original da versão a que se refere der permissão.</para>
	</formalpara>
      </listitem>
      
      <listitem>
	<formalpara>
	  <title>K</title>
	  <para>Em qualquer seção intitulada “Agradecimentos” ou “Dedicatórias”, preservar o título da seção, e preservar na seção toda a substância e tom de cada um dos agradecimentos e/ou das dedicatórias dados nela.</para>
	</formalpara>
      </listitem>
      
      <listitem>
	<formalpara>
	  <title>L</title>
	  <para>Preservar todas as <link linkend="fdl-invariant">Seções Invariantes</link> do <link linkend="fdl-document">Documento</link>, inalteradas em seus textos e em seus títulos. Os números de seção ou o equivalente não são considerados parte dos títulos das seções.</para>
	</formalpara>
      </listitem>
      
      <listitem>
	<formalpara>
	  <title>M</title>
	  <para>Excluir qualquer seção intitulada “Endossos”. Essa seção pode não estar incluída na <link linkend="fdl-modified">Versão Modificada</link>.</para>
	</formalpara>
      </listitem>
      
      <listitem>
	<formalpara>
	  <title>N</title>
	  <para>Não mudar o título de qualquer seção existente para “Endossos” ou para conflitar em título com qualquer <link linkend="fdl-invariant">Seção Invariante</link>.</para>
	</formalpara>
      </listitem>
    </itemizedlist>
    
    <para>Se a <link linkend="fdl-modified">Versão Modificada</link> incluir novas seções ou apêndices de primeira linha que se qualifiquem como <link linkend="fdl-secondary">Seções Secundárias</link> e não contenham material copiado do Documento, você pode, a sua escolha, designar algumas ou todas essas seções como invariantes. Para fazer isso, adicione seus títulos à lista de <link linkend="fdl-invariant">Seções Invariantes</link> no aviso de licença da Versão Modificada. Esses títulos devem ser distintos de qualquer outro título de seção.</para>
    
    <para>Você pode incluir uma seção intitulada “Endossos”, desde que contenha nada além do endosso da sua <link linkend="fdl-modified">Versão Modificada</link> por várias terceiros – por exemplo, declarações de revisão por pares ou de que o texto foi aprovado por uma organização como a definição oficial de um padrão.</para>
    
    <para>Você pode adicionar uma passagem de até cinco palavras como um <link linkend="fdl-cover-texts">Texto de Capa Frontal</link> e uma passagem de até 25 palavras como um <link linkend="fdl-cover-texts">Texto de Contracapa</link>, até o final da lista de <link linkend="fdl-cover-texts">Textos de Capa</link> na <link linkend="fdl-modified">Versão Modificada</link>. Apenas uma passagem de Texto de Capa Frontal e um de Texto de Contracapa pode ser adicionada por (ou por meio de acordos feitos por) qualquer entidade. Se o <link linkend="fdl-document">Documento</link> já incluir um texto de capa para a mesma capa, previamente adicionado por você ou por acordo feito pela mesma entidade em que você está agindo em nome de, você não pode adicionar outro; mas você pode substituir o antigo, mediante permissão explícita do editor anterior que adicionou o antigo.</para>
    
    <para>O(s) autor(es) e editor(es) do <link linkend="fdl-document">Documento</link> não concedem por esta Licença permissão para usar seus nomes para publicidade ou afirmar ou implicar o endosso de qualquer <link linkend="fdl-modified">Versão Modificada</link>.</para>
  </sect1>
    
  <sect1 id="fdl-section5">
    <title>5. COMBINANDO DOCUMENTOS</title>
    <para>Você pode combinar o <link linkend="fdl-document">Documento</link> com outros documentos publicados sob esta Licença, nos termos definidos na <link linkend="fdl-section4">seção 4</link> acima para versões modificadas, desde que você inclua na combinação de todas as <link linkend="fdl-invariant">Seções Invariantes</link> de todos os documentos originais, não modificados, e liste todos eles como Seções Invariantes do seu trabalho combinado em seu aviso de licença.</para>
    
    <para>O trabalho combinado precisa conter somente uma cópia desta Licença, e várias <link linkend="fdl-invariant">Seções Invariantes</link> idênticas podem ser substituídas por uma única cópia. Se existirem várias Seções Invariantes de mesmo nome, porém com conteúdos diferentes, você deve tornar o título de cada uma destas seções único, adicionando ao fim deste, entre parênteses, o nome do autor ou, se conhecido, o editor original desta seção, ou ainda um número único. Faça o mesmo ajuste nos títulos de seção na lista de Seções Invariantes no aviso de licença do trabalho combinado.</para>
    
    <para>Na combinação, você deve combinar todas as seções intituladas “Histórico” nos vários documentos originais, formando uma seção intitulada “Histórico”; da mesma forma, combinar todas as seções intituladas “Agradecimentos” e quaisquer seções intituladas “Dedicatórias”. Você deve excluir todas as seções intituladas “Endossos”.</para>
    </sect1>
    
  <sect1 id="fdl-section6">
    <title>6. COLEÇÕES DE DOCUMENTOS</title>
    <para>Você pode fazer uma coleção que consiste do <link linkend="fdl-document">Documento</link> e outros documentos publicados sob esta Licença, e substituir as cópias individuais desta Licença, nos vários documentos, por uma única cópia a ser incluída na coleção, desde que você siga as regras desta Licença para cópias literais de cada documento em todos os outros aspectos.</para>
    
    <para>Você pode extrair um único documento de tal coleção e distribuí-lo individualmente sob esta Licença, desde que você insira uma cópia desta Licença no documento extraído e siga esta Licença em todos os outros aspectos referentes à cópia literal desse documento.</para>
    </sect1>
    
  <sect1 id="fdl-section7">
    <title>7. AGREGAÇÃO COM TRABALHOS INDEPENDENTES</title>
    <para>Uma compilação do <link linkend="fdl-document">Documento</link> ou seus derivados com outros documentos ou trabalhos separados e independentes, em ou sobre um volume de um meio de armazenamento ou distribuição, não como um todo conta como uma <link linkend="fdl-modified">Versão Modificada</link> do Documento, desde que nenhuma compilação de direitos autorais seja reivindicada para a compilação. Tal compilação é chamada de “agregado” (aggregate), e esta Licença não se aplica aos outros trabalhos autônomos assim compilados com o Documento, por conta de serem assim compilados, se eles não forem eles próprios trabalhos derivados do Documento. Se o requisito do <link linkend="fdl-cover-texts">Texto da Capa</link> da <link linkend="fdl-section3">seção 3</link> for aplicável a essas cópias do Documento, então, se o Documento for inferior a um quarto do agregado inteiro, os Textos de Capa do Documento poderão ser colocados em capas que envolvam apenas o Documento no agregado. Caso contrário, eles devem aparecer nas capas envolvem todo o agregado.</para>
    </sect1>
    
  <sect1 id="fdl-section8">
    <title>8. TRADUÇÃO</title>
    <para>A tradução é considerada um tipo de modificação, então você pode distribuir as traduções do <link linkend="fdl-document">Documento</link> nos termos da <link linkend="fdl-section4">seção 4</link>. A substituição das <link linkend="fdl-invariant">Seções Invariantes</link> com traduções requer permissão especial de seus detentores de direitos autorais, mas você pode incluir traduções de algumas ou todas as Seções Invariantes além das versões originais destas Seções Invariantes. Você pode incluir uma tradução desta Licença, desde que você também inclua a versão original em inglês desta Licença. Em caso de desacordo entre a tradução e a versão original desta Licença, a versão original prevalecerá.</para>
    </sect1>
    
  <sect1 id="fdl-section9">
    <title>9. TERMINAÇÃO</title>
    <para>Você não pode copiar, modificar, sublicenciar ou distribuir o <link linkend="fdl-document">Documento</link>, exceto conforme expressamente previsto nesta Licença. Qualquer tentativa de copiar, modificar, sublicenciar ou distribuir o Documento é anulada e terminará automaticamente seus direitos sob esta Licença. No entanto, as partes que receberam cópias ou direitos de você sob esta Licença não terão suas licenças terminadas, desde que tais partes permaneçam em plena conformidade.</para>
    </sect1>
    
  <sect1 id="fdl-section10">
    <title>10. FUTURAS REVISÕES DESTA LICENÇA</title>
    <para>A <ulink type="http" url="http://www.gnu.org/fsf/fsf.html">Free Software Foundation</ulink> pode publicar novas e revisadas versões da Licença de Documentação Livre GNU de vez em quando. Essas novas versões serão semelhantes em espírito à versão atual, mas podem diferir em detalhes para resolver novos problemas ou preocupações. Veja <ulink type="http" url="http://www.gnu.org/copyleft">http://www.gnu.org/copyleft/</ulink>.A <ulink type="http" url="http://www.gnu.org/fsf/fsf.html">Free Software Foundation</ulink> pode publicar novas versões, revisadas, da Licença de Documentação Livre GNU de tempos em tempos. Tais versões posteriores terão ideologia similar à presente versão, embora possam diferir em detalhes a fim de abordar novos problemas ou preocupações. Consulte: <ulink type="http" url="http://www.gnu.org/copyleft">http://www.gnu.org/copyleft/</ulink>.</para>
    
    <para>Cada versão da Licença recebe um número de versão distinto. Se o <link linkend="fdl-document">Documento</link> especifica que uma versão numerada específica desta Licença “ou qualquer versão posterior” aplica-se a ele, você tem a opção de seguir os termos e condições daquela versão especificada ou de qualquer versão posterior que tenha sido publicada (não como um rascunho) pela Free Software Foundation. Se o Documento não especificar um número de versão desta Licença, você pode escolher qualquer versão publicada (não como um rascunho) pela Free Software Foundation.</para>
  </sect1>

  <sect1 id="fdl-using">
    <title>Adendo</title>
    <para>Para usar esta Licença em um documento que você escreveu, inclua uma cópia da Licença no documento e coloque os seguintes avisos de direitos autorais e de licenças logo após a página de título:</para>
    
    <blockquote>
      <para>Copyright ANO SEU NOME.</para>
      <para>Permissão concedida para copiar, distribuir e/ou modificar este documento sob os termos da Licença de Documentação Livre GNU, Versão 1.1 ou qualquer versão mais recente publicada pela Free Software Foundation; com as <link linkend="fdl-invariant">Seções Invariantes</link> sendo LISTE SEUS TÍTULOS, com os <link linkend="fdl-cover-texts">Textos de Capa Frontal</link> sendo LISTA e os <link linkend="fdl-cover-texts">Textos de Contracapa</link> sendo LISTA. Uma cópia da licença está incluída na seção intitulada "Licença de Documentação Livre GNU" (GNU Free Documentation License).</para>
    </blockquote>
      
    <para>Se você não tiver <link linkend="fdl-invariant">Seção Invariante</link>, escreva “sem Seções Invariantes” em vez de dizer quais são invariantes. Se você não tiver <link linkend="fdl-cover-texts">Textos de Capa Frontal</link>, escreva “sem Textos da Capa Frontal” em vez de “Textos de Capa Frontal sendo LIST”; Da mesma forma para <link linkend="fdl-cover-texts">Textos de Contracapa</link>.</para>
    
    <para>Se o seu documento contiver exemplos não triviais do código do programa, recomendamos que apresente esses exemplos em paralelo, sob sua escolha de licença de software livre, como a <ulink type="http" url="http://www.gnu.org/copyleft/gpl.html">Licença Pública Geral GNU</ulink> (GNU General Public License), para permitir sua utilização em software livre.</para>
  </sect1>
</appendix>  








</book>
