Referenzseiten

(Auszug aus "DocBook-XML: Medienneutrales und plattformunabhängiges Publizieren" von Thomas Schraitle)

Innerhalb von reference dokumentieren Sie Funktionen, Befehle, Klassen und Ähnliches. Eine Referenz besteht hauptsächlich aus refentry-Elementen. Das folgende Beispiel zeigt Ihnen, wie Sie eine Referenz anwenden. Das gezeigte Beispiel ist ebenfalls in DocBook 5 gültig.

Beispiel: Aufbau einer Befehlsreferenz

<refentry>
    <refmeta>
        <refentrytitle>xmllint</refentrytitle>
        <manvolnum>1</manvolnum>
    </refmeta>
    <refnamediv>
        <refname>xmllint</refname>
        <refpurpose>XML-Kommandozeilentool</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Synopsis</title>
        <cmdsynopsis>
            <command>xmllint</command>
            <arg choice="opt">Option</arg>
            <arg choice="req">XML-Datei</arg>
        </cmdsynopsis>
    </refsynopsisdiv>
    <refsect1>
        <title>Einführung</title>
        <para>Eine kleine Beschreibung zu xmllint.</para>
    </refsect1>
    <refsect1>
        <title>Optionen</title>
        <variablelist>
            <varlistentry>
                <term><option>--version</option></term>
                <listitem>
                    <para>Gibt die Version von xmllint aus.</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term><option>--valid</option></term>
                <listitem>
                    <para>Validiert die XML-Datei.</para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsect1>
    <!-- ... -->    
</refentry>

Zeile 2: Enthält den Titel einer Referenzseite, den Bereich der Manpage und eventuell andere nützliche Informationen.
Zeile 3: Für Manpages legt dies die Kopf- und Fußzeile fest.
Zeile 4: kennzeichnet den Bereich, in der die Manpage eingeordnet werden soll (normalerweise die Kategorien 1 bis 9 und zusätzlich Kategorie n).
Zeile 7: legt den Namen des Befehls fest.
Zeile 8: Zweck des Befehls; in Manpages erscheint er direkt nach dem Befehlsnamen.
Zeile 10: kennzeichnet den Bereich, in dem der Befehl in Kurzform als Übersicht angezeigt wird.
Zeile 12: leitet die eigentliche Befehlszeile ein, in der Befehlsnamen inklusive Parameter aufgelistet werden.
Zeile 18: Eine Überschrift. Sie hätten an dieser Stelle auch refsection verwenden können. Bei refsect1 können Sie weitere Überschriften mittels refsect2 und refsect3 eingeben.

Das Ergebnis des vorigen Beispiels wird wie folgt dargestellt:

XMLLINT(1)                                                                                  XMLLINT(1)

  

NAME

          xmllint - XML Kommandozeilentool

SYNOPSIS

          xmllint [Option] {XML-Datei}

EINFÜHRUNG

          Eine kleine Beschreibung zu xmllint.

OPTIONEN

          --version

               Gibt die Version von xmllint aus.

          --valid

               Validiert die XML-Datei.

  

                                                                                                XMLLINT(1)

Entsprechend können auch Funktionen, Klassen und ähnliches dokumentiert werden. Weitere Informationen finden Sie in "Synopsen".

  

<< zurück vor >>
Tipp der data2type-Redaktion:
Zum Thema DocBook bieten wir auch folgende Schulungen zur Vertiefung und professionellen Fortbildung an:

Copyright © 2009 Millin Verlag
Für Ihren privaten Gebrauch dürfen Sie die Online-Version ausdrucken.
Ansonsten unterliegt dieses Kapitel aus dem Buch "DocBook-XML: Medienneutrales und plattformunabhängiges Publizieren" denselben Bestimmungen, wie die gebundene Ausgabe: Das Werk einschließlich aller seiner Teile ist urheberrechtlich geschützt. Alle Rechte vorbehalten einschließlich der Vervielfältigung, Übersetzung, Mikroverfilmung sowie Einspeicherung und Verarbeitung in elektronischen Systemen.

Millin Verlag, Siebengebirgsring 36, 53797 Lohmar, info(at)millin.de