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.
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 {
private Display display; private Command exitCommand = new Command( "Exit", Command.EXIT, 1 ); public MyMIDlet(){
} 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 {
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.