Useful DocBook tags

Here are some DocBook tags which are most useful when documenting the code.

To link to another section in the GTK docs:

<link linkend="glib-Hash-Tables">Hash Tables</link>
The linkend is the SGML/XML id on the top item of the page you want to link to. For most pages this is currently the part ("gtk", "gdk", "glib") and then the page title ("Hash Tables"). For widgets it is just the class name. Spaces and underscores are converted to '-' to conform to SGML/XML.

To refer to an external function, e.g. a standard C function:

<function>...</function>

To include example code:

<example>
  <title>Using a GHashTable.</title>
  <programlisting>
      ...
  </programlisting>
</example>
or possibly this, for very short code fragments which don't need a title:
<informalexample>
  <programlisting>
  ...
  </programlisting>
</informalexample>
For the latter GTK-Doc also supports an abbreviation: |[ ... ]|

To include bulleted lists:

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

To include a note which stands out from the text:

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

To refer to a type:

<type>unsigned char</type>

To refer to an external structure (not one described in the GTK docs):

<structname>XFontStruct</structname>

To refer to a field of a structure:

<structfield>len</structfield>

To refer to a class name, we could possibly use:

<classname>GtkWidget</classname>
but you'll probably be using #GtkWidget instead (to automatically create a link to the GtkWidget page - see the abbreviations).

To emphasize text:

<emphasis>This is important</emphasis>

For filenames use:

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

To refer to keys use:

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