Beispiele und Abbildungen

Beispiele und Abbildungen lockern den Text auf

Beispiele und Abbildungen sind sehr hilfreich, weil sie das Geschriebene oft gut untermalen und verständlich mache können. In DocBook gibt es natürlich extra Elemente, um Beispiele oder Abbildungen oder Grafiken oder andere Medienobjekte einzubinden.

Beispiele

Um ein Beispiel zu erstellen, gibt es zwei mögliche Varianten: example erstellt ein Beispiel, welches einen Titel haben muss und auch im Beispielverzeichnis aufgeführt wird. Mit informalexample erstellt man ein informelles Beispiel ohne Titel, welches auch nicht im Beispielverzeichnis erwähnt wird.

Beispiele enthalten Absätze

Beispiele enthalten neben dem möglichen title alle üblichen Blockelemente, jedoch mindestens eins. Für Beispiele gibt es zwei besondere Attribute. Mit label, kann man ähnlich wie bei section und chapter eine Zeichenkette angeben, die zur Darstellung des Beispiels verwendet werden kann. Das Attribut width gibt die maximale Breite des Beispiels in Zeichen an, damit das Verarbeitungssystem das Beispiel unter Umständen verkleinern oder um 90° kippen kann.

Beispiel 2.22. Ein beispielhaftes Beispiel

<!DOCTYPE example PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
          "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<example>
<title>Hallo Welt in HTML</title>
<para>
Der folgende Code stellt das berühmte <quote>Hallo-Welt</quote> als
HTML-Datei dar.
</para>
<programlisting>
<html>
  <head>
    <title>Hallo Welt</title>
  </head>
  <body>
    <p>
      Hallo ... Welt!
    </p>
  </body>
</html>
</programlisting>
</example>

Und so sähe dieses Beispiel im fertigen Dokument aus:

Beispiel 2.23. Hallo Welt in HTML

Der folgende Code stellt das berühmte „Hallo-Welt“ als HTML-Datei dar.

<html>
  <head>
    <title>Hallo Welt</title>
  </head>
  <body>
    <p>
      Hallo ... Welt!
    </p>
  </body>
</html>

Grafiken und Medien

In der DocBook-DTD gibt es viele verschiedene Möglichkeiten, Grafiken darzustellen, ich werde jedoch nur auf einen eingehen. Das hat zwei Gründe:

  • Mit dieser Variante kann man auch andere Medien einbinden

  • Von den anderen Varianten werden in Zukunft viele aus der DTD gestrichen.

mediaobject bietet verschiedene Rückfalllösungen

Um Medien einzubinden verwendet man in DocBook das Element mediaobject. Wenn die Medien in der Zeile, also auf einer Ebene mit dem Fließtext erscheinen soll, so benutzt man das Element inlinemediaobject. Ich werde im Folgenden immer auf mediaobject verweisen, damit ist aber inlinemediaobject genau so gemeint, da sich die Elemente bis auf den Unterschied in der Positionierung weitestgehend nicht unterscheiden.

Ein mediaobject kann einen Titel haben, das title-Element muss jedoch im Element objectinfo enthalten sein. Danach folgt eine Auflistung in beliebiger Reihenfolge und Länge von videobject für Videos und Filme, audioobject für Musik und Sprachsequenzen, imageobject für Bilder und Grafiken oder textobject für textuelle Beschreibungen. Das Verarbeitungssystem bindet dann jeweils den Medientyp ein, der für das Medium angemessen ist. So könnte für HTML-Dateien der Inhalt von videobject verwendet werden und für die Druckausgabe der Inhalt von imageobject. Der Inhalt von textobject wird meist als alternative Beschreibung verwendet.

Nach der Abfolge der eigentlichen Objekte kann noch eine optionale caption, also einen beschreibenden Text, der anders als textobject nicht eine Alternative, sondern eine Ergänzung darstellen soll, haben.

videoobject

Nur wenige Ausgabemedien unterstützen videoobject

Mit dem XML-Element videoobject bindet man einen Film in ein DocBook-Dokument ein. Die Darstellung von videoobject ist abhängig von Kontext und der Ausgabeformat, so dass es unter Umständen nicht angezeigt wird. Meta-Informationen über den Film können in den optionalen Tag objectinfo plaziert werden, und der Verweis auf das einzubindende Video erfolgt in dem obligatorischen Element videodata. Für videodata ist das Attribut fileref entscheidend, denn es soll auf die einzubindende Datei verweisen.

audioobject

Mit dem XML-Element audioobject bindet man einen Audio-Dateien in ein DocBook-Dokument ein. Die Darstellung von audioobject ist abhängig von Kontext und der Ausgabeformat, so dass es unter Umständen nicht aufgeführt wird. Meta-Informationen über die Datei können in den optionalen Tag objectinfo plaziert werden, und der Verweis auf den einzubindenden Soundclip erfolgt in dem obligatorischen Element audiodata. Für audiodata ist das Attribut fileref entscheidend, denn es soll auf die einzubindende Datei verweisen.

imageobject

Bilder sind die häufigste Erscheinungsform von Medien

Mit dem XML-Element imageobject bindet man eine Bild in ein DocBook-Dokument ein. Die Darstellung von imageobject ist abhängig von Kontext und der Ausgabeformat, jedoch wird es im Allgemeinen angezeigt. Meta-Informationen über das Bild können in den optionalen Tag objectinfo plaziert werden, und der Verweis auf das einzubindende Bild erfolgt in dem obligatorischen Element imagedata. Für imagedata ist das Attribut fileref entscheidend, denn es soll auf die einzubindende Datei verweisen. Weiterhin bietet es sich an, mit dem Attribut format das Datei-Format des Bildes zu bestimmen.

textobject

Texte sind die absolute Notfalllösung und sollten nie weggelassen werden

Eine Besonderheit stellt textobject dar, mit dem Medien als Notlösung textuell beschrieben werden können. Dazu gibt es zwei Ansätze. Zum ersten können in textobject ganz normale Fließtexte und Blockelemente eingebunden werden, was sich anbietet, wenn das Zielmedium nicht einmal Bilder darstellen kann. Wenn das Zielmedium jedoch Bilder darstellen kann, wie z.B. HTML, aber für den Fall, das der Betrachter Bilder deaktiviert hat, nicht sehen kann oder die Referenz verloren geht und eine Rückfalllösung gesucht wird, sollte man mittels phrase einen kurzen alternativen Text angeben. phrase wiederum kann Blockelemente enthalten.

Beispiel 2.24. Medien in verschiedenen Formaten

<!DOCTYPE mediaobject PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
          "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<mediaobject>
  <objectinfo>
    <title>Steve Ballmer motivates his <quote>developers</quote>
    </title>
  </objectinfo>
  <videobject>
    <videodata filref="images/developers.mpeg"/>
  </videoobject>
  <imageobject>
    <imagedata fileref="images/developers.png" format="PNG" />
  </imageobject>
  <textobject>
    <phrase>
      Steve says: "Developers, developers, developers, developers, developers..."
    </phrase>
  </textobject>
</mediaobject>

Die Darstellung dieses Beispiels will ich dem Betrachter natürlich nicht entgehen lassen:

Abbildungen

Abbildungen sind formale Container für Grafiken

Abbildungen sind in der Regel ein formaler Container für Grafiken und Medienobjekte. Sie bieten sich dann an, wenn Grafiken nicht nur zur Illustration verwendet werden, sondern dann, wenn man im Text auf eine Grafik verweisen möchte. In formellen Texten sollten alle Grafiken nur in Abbildungen auftauchen. Weiterhin werden nur für Abbildungen, nicht jedoch für Grafiken Einträge im Abbildungsverzeichnis erstellt.

In DocBook erstellt man Abbildungen entweder mit figure, dann sind sie formell und brauchen einen Titel oder informalfigure, dann sind sie informell und dürfen keinen Titel haben. Innerhalb von figure und informalfigure dürfen Blockelemente, jedoch keine Absätze oder Tabellen erscheinen, insbesondere jedoch das Element mediaobject.

Es gibt drei Attribute mit denen man das weitere Erscheinungsbild einer Abbildung steuern kann. Wenn man den Wert des Attributs float auf „1“ setzt, so darf das Verarbeitungssystem die Abbildung an jeden Ort versetzen, der angemessen erscheint, wenn dieses Attribut nicht gesetzt ist, bleibt die Abbildung fest im Textfluss. Mit dem bekannten Attribut label kann man einen weiteren Text angeben, der für Präsentationszwecke bestimmt ist und durch Setzen des Attributs pgwide auf „1“ erreichen Sie, dass die Abbildung über die aktuelle Spalte hinaus auf die gesamte Breite der Seite ausgedehnt wird.

Beispiel 2.25. Abbildungen in der Praxis

<!DOCTYPE figure PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
          "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<figure><title>Die Titelseite von DocBook: The Definite Guide</title>
<mediaobject>
  <imageobject>
    <imagedata format="PNG" fileref="cover.png" />
  </imageobject>
</mediaobject>
</figure>

Und so sähe dieser Code im fertigen Dokument aus:

Abbildung 2.1. Die Titelseite von DocBook: The Definite Guide

Die Titelseite von DocBook: The Definite Guide