Användbara DocBook-taggar

Här är några DocBook-taggar som är användbara när man dokumenterar koden.

För att länka till ett annat avsnitt i GTK-dokumentationen:

<link linkend="glib-Hash-Tables">Hashtabeller</link>
Länkslutet är XGML/XML-id:t för toppnivåobjektet på sidan du vill länka till. För de flesta sidorna är detta för närvarande delen (”gtk”, ”gdk”, ”glib”) och sedan sidans titel (”Hashtabeller”). För komponenter är detta helt enkelt klassnamnet. Blanksteg och understreck konverteras till ”-” för att överensstämma med SGML/XML.

För att referera till en extern funktion, t.ex. en standardfunktion i C:

<function>…</function>

För att inkludera exempelkod:

<example>
  <title>Att använda en hashtabell.</title>
  <programlisting>
      …
  </programlisting>
</example>
eller möjligen följande, för väldigt korta kodfragment som inte behöver en titel:
<informalexample>
  <programlisting>
  …
  </programlisting>
</informalexample>
För det senare fallet har GTK-Doc också stöd för förkortningen: |[ … ]|

För att inkludera punktlistor:

<itemizedlist>
  <listitem>
    <para>
      …
    </para>
  </listitem>
  <listitem>
    <para>
      …
    </para>
  </listitem>
</itemizedlist>

För att inkludera en not som skiljer sig från texten:

<note>
  <para>
    Säkerställ att du frigjort data efter användning.
  </para>
</note>

För att refera till en typ:

<type>unsigned char</type>

För att referera till en extern struktur (som inte beskrivs i GTK-dokumentationen):

<structname>XFontStruct</structname>

För att referera till ett fält för en struktur:

<structfield>len</structfield>

För att referera till ett klassnamn kan vi möjligen använda:

<classname>GtkWidget</classname>
men du kommer troligt att använda #GtkWidget istället (för att automatiskt skapa en länk till GtkWidget-sidan - se förkortningarna).

För att betona text:

<emphasis>Detta är viktigt</emphasis>

För filnamn använd:

<filename>/home/användare/dokument</filename>

För att referera till tangenter använd:

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