Software-spezifische Elemente

DocBook ist gut für die Beschreibung von Software geeignet

Da dieses Tutorium den Bereich technischer Dokumentationen betont und DocBook in seiner Geschichte vor allem von Softwarefirmen geprägt worden ist, existieren sehr viele Elemente, die sich allein mit der Beschreibung von Software beschreiben. Wie bei den Metadaten habe ich auch hier eine Auswahl getroffen und der Rest kann ohne weiteres nachgeschlagen werden.

Programmcode

Die Darstellung von Programmcode erfolgt über das Element programlisting. Wenn es wichtig ist, dass Zeilenumbrüche und Einrückungen erhalten bleiben, so verwendet man das Attribut format und gibt ihm den Wert „linespecific“. Durch Setzen des Attributs linenumbering auf „numbered“ kann weiterhin eine Nummerierung der Zeilen erfolgen, wenn das erwünscht ist und das Verarbeitungssystem das unterstützt.

Beispiel 2.35. Das Programm „Hello World

' Hello World als QBASIC-Programm
CLS
PRINT "Hello World"
END
#! /usr/bin/perl
print "Hello World"

Interessant wird es, wenn im folgenden Text auf das Programm Bezug genommen werden soll, aber der Verweis auf die jeweiligen Zeilennummern zu aufwändig ist. In diesem Fall bietet es sich an, bestimmte Bereiche des Programms eindeutig zu markieren und sich dann auf diese eindeutigen Bezüge zu beziehen.

Stellen im Programmcode können hervorgehoben werden

Wenn man Programmcode mit solcherart markierten Bereichen verwenden will, so benutzt man das Element programlistingco. Dieses wiederum hat zwei Kind-Elemente: areaspec und das bekannte programmlisting, in welchem der Programmcode angegeben wird. Der Inhalt von areaspec besteht aus so vielen area-Elementen wie Punkte im Programmcode hervorgehoben werden sollen. Für jede area gibt es zwei Attribute, die gesetzt sein müssen: id, um die Zeile eindeutig zu bestimmen und coords, welches die Koordinaten des Bereichs bestimmen soll, also die Codezeile.

Beispiel 2.36. Ein etwas längeres Programm

import javax.microedition.lcdui.*;
import javax.microedition.midlet.*;

public class MyMIDlet extends MIDlet
                      implements CommandListener {
(1)


    private Display display;
    private Command exitCommand = new Command(
                         "Exit", Command.EXIT, 1 );

    public MyMIDlet(){
(2)

    }

    protected void destroyApp(
      boolean unconditional )
               throws MIDletStateChangeException {
        exitMIDlet();
    }

    protected void pauseApp(){
    }

    protected void startApp()
                throws MIDletStateChangeException {
        if( display == null ){
                            // first time called...
            initMIDlet();
        }
    }

    private void initMIDlet(){
        display = Display.getDisplay( this );
        new SplashScreen(
                       display, new TrivialForm() );
    }

    public void exitMIDlet(){
        notifyDestroyed();
    }

    public void commandAction(
                        Command c, Displayable d ){
        exitMIDlet();
    }

    // A trivial UI screen

    class TrivialForm extends Form {
(3)

        TrivialForm(){
            super( "MyMIDlet" );
            addCommand( exitCommand );
            setCommandListener( MyMIDlet.this );
        }
    }

Die eigentliche Erklärung der so hervorgehobenen Punkte erfolgt in einer Liste. Mit callcoutlist erzeugt man so eine Liste, die einen Titel haben kann und aus einer Aufreihung von callout-Elementen besteht. Jedes callout hat als erforderliches Attribut arearefs, welches auf die durch Leerzeichen getrennte Liste der ids der oben definierten Bereiche verweist. Der eigentliche Inhalt sind Blockelemente, die den betreffenden Code erklären.

Beispiel 2.37. Und eine kurze Erklärung

1

Diese hier erstellte Klasse setzt eine Programmierschnittstelle um.

2

Da es keine abstrakte Klasse ist, hat sie einen Konstruktor, auch wenn dieser nichts tut

3

In Java können Klassen sogenannte „innere Klassen“ haben.