Tags úteis do DocBook

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

Para vincular a outra seção nas documentações do GTK:

<link linkend="glib-Hash-Tables">Tabela de hashes</link>
O fim do link é o ID do 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 se referir a uma função externa, como, por exemplo, uma função padrão do C:

<function>...</function>

Para incluir um código de exemplo:

<example>
  <title>Usando uma GHashTable.</title>
  <programlisting>
      ...
  </programlisting>
</example>
ou possivelmente este, para fragmentos de código bem curtos que não precisam de um título:
<informalexample>
  <programlisting>
  ...
  </programlisting>
</informalexample>
Para este último, GTK-Doc também possui suporte a uma abreviação: |[ ... ]|

Para incluir listas com marcadores:

<itemizedlist>
  <listitem>
    <para>
      ...
    </para>
  </listitem>
  <listitem>
    <para>
      ...
    </para>
  </listitem>
</itemizedlist>

Para incluir uma nota que fique fora do texto:

<note>
  <para>
    Certifique-se de que você liberou os dados após usá-los.
  </para>
</note>

Para se referir a um tipo:

<type>unsigned char</type>

Para se referir a uma estrutura externa (não uma descrita nos documentos do GTK):

<structname>XFontStruct</structname>

Para se referir a um campo de uma estrutura:

<structfield>len</structfield>

Para se referir a um nome de classe, nós possivelmente poderíamos usar:

<classname>GtkWidget</classname>
mas você provavelmente vai estar usando #GtkWidget em vez disso (para criar automaticamente um link para a página do GtkWidget - veja as abreviações).

Para enfatizar um texto:

<emphasis>Isso é importante</emphasis>

Para nome de arquivos use:

<filename>/home/usuario/documentos</filename>

Para se referir a chaves use:

<keycombo><keycap>Control</keycap><keycap>L</keycap></keycombo>