Nützliche DocBook-Markierungen

Nachfolgend finden Sie einige DocBook-Markierungen, die beim Dokumentieren von Code nützlich sein können.

So erstellen Sie eine Verknüpfung zu einem anderen Abschnitt in den GTK-Docs:

<link linkend="glib-Hash-Tables">Hash Tables</link>
»linkend« ist dabei die SGML-XML-Kennung des obersten Elements der Seite, auf welche die Verknüpfung zielt (»gtk«, »gdk«, »glib«), danach folgt der Seitentitel ("Hash Tables"). Für Widgets ist dies einfach der Klassenname. Leerzeichen und Unterstriche werden SGML/XML-konform in »-« umgewandelt.

Für einen Bezug zu einer externen Funktion, z.B. einer C-Standardfunktion:

<function>...</function>

So fügen Sie Beispielcode ein: Vielleicht auch so, für sehr kurze Codeschnipsel, die keinen Titel benötigen:

<informalexample>
  <programlisting>
  ...
  </programlisting>
</informalexample>
Außerdem unterstützt GTK-Doc auch eine Abkürzung: |[ ... ]|

Für eine Liste mit Aufzählungszeichen:

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

Für eine nicht zum eigentlichen Text gehörende Notiz:

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

Für einen Bezug zu einem Typ:

<type>unsigned char</type>

Für einen Bezug zu einer externen Struktur (die nicht in den GTK-Docs beschrieben wird):

<structname>XFontStruct</structname>

Für einen Bezug zu einem Feld einer Struktur:

<structfield>len</structfield>

Um sich auf einen Klassennamen zu beziehen kann man möglicherweise folgendes verwenden:

<classname>GtkWidget</classname>
Aber Sie verwenden vermutlich stattdessen #GtkWidget (um automatisch eine Verknüpfung zur GtkWidget-Seite zu erstellen - lesen Sie die Abkürzungen).

Zum Hervorheben von Text:

<emphasis>This is important</emphasis>

Für Dateinamen:

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

Für einen Bezug zu einem Schlüssel:

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