Balises DocBook utiles

Voici quelques balises DocBook très utiles pendant la conception de la documentation d'un code.

Pour créer un lien vers une autre section dans la documentation GTK :

<link linkend="glib-Hash-Tables">Hash Tables</link>

          
l'élément « linkend » est l'identifiant SGML/XML de l'élément le plus haut sur la page vers laquelle vous voulez pointer. Pour la plupart des pages, c'est en général la partie (« gtk », « gdk », « glib ») suivi du titre de la page (« Hash Tables »). Pour les éléments graphiques, c'est simplement le nom de la classe. Les espaces et les caractères de soulignement sont convertis en « - » pour être conforme au SGML/XML.

Pour faire référence à une fonction externe comme, par exemple, à une fonction C standard :

<function>...</function>

          

Pour inclure des extraits de code :

<example>
  <title>Using a GHashTable.</title>
  <programlisting>
      ...
  </programlisting>
</example>

          
ou ceci, pour des petits fragments de code qui ne nécessitent pas de titre :
<informalexample>
  <programlisting>
  ...
  </programlisting>
</informalexample>

          
Pour ces derniers, GTK-Doc prend également en charge une abréviation : |[ ... ]|

Pour ajouter une liste à puces :

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

          

Pour ajouter une note de bas de page :

<note>
  <para>
    Make sure you free the data after use.
  </para>
</note>

          

Pour se référer à un type :

<type>unsigned char</type>

          

Pour se référer à une structure externe (non décrite dans la documentation GTK) :

<structname>XFontStruct</structname>

          

Pour se référer à un champ d'une structure :

<structfield>len</structfield>

          

Pour se référer au nom d'une classe, il est possible d'utiliser :

<classname>GtkWidget</classname>

          
mais vous utiliserez probablement #GtkWidget à la place (pour créer automatiquement un lien vers la page GtkWidget - consultez les raccourcis).

Pour mettre en évidence un texte :

<emphasis>This is important</emphasis>

          

Pour les noms de fichiers :

<filename>/home/user/documents</filename>

          

Pour se référer à des touches :

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