Markierungspunkte indirekt einfügen

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

Ist es nicht möglich, Markierungspunkte direkt im Textinhalt zu setzen, benötigen Sie Regionen. Folgende Voraussetzungen sind dazu erforderlich:

  1. Koordinaten: Legt die Stellen fest, an denen die Markierungspunkte erscheinen sollen.
  2. Containerelement: Textinhalt und Koordinaten müssen mit einem Containerelement umhüllt werden. Hierzu eignen sich programlistingco oder screenco.
  3. Erweiterungsfunktionen: Zum Zeitpunkt der Bucherstellung haben nur Saxon und Xalan Erweiterungsfunktionen, welche die Markierungspunkte an die korrekte Stelle setzen, siehe Erweiterungsfunktionen und Erweiterungselemente.

Vorteilhaft an diesem Verfahren ist, dass der Inhalt aus einer externen Datei eingefügt werden kann. Dadurch sind Quellcode und Markierungspunkte getrennt. Gerade wenn Sie den Quellcode für weitere Zwecke benötigen, oder sich häufiger ändert ist dies sinnvoll. Allerdings müssen Sie eventuell die Koordinaten anpassen.

Um dieses Verfahren anzuwenden, bestimmen Sie Koordinaten mit dem Sie auf die entsprechenden Stellen zeigen. Über das Element areaspec definieren Sie die Menge aller Koordinaten, mittels area geben Sie einen Markierungspunkt an. Mit dem Element calloutlist beschreiben Sie die einzelnen Markierungspunkte.

Beispiel: Definieren von Markierungspunkten

<areaspec units="...">
  <area ANKER="..." coords='...'/>
  <!-- Weitere Einträge -->
</areaspec>

Ersetzen Sie den Platzhalter ANKER durch id in DocBook 4 und xml:id in DocBook 5.

Zeile 1: Die Definition von Koordinaten wird mit areaspec eingeleitet. Die Einheit für die angegeben Koordinaten wird im Attribut units vermerkt (siehe Liste weiter unten). Der Standardwert ist abhängig davon, ob Markierungspunkte für Text oder Grafik erstellt werden. Für Text ist dies linecolumn, für Grafik calspair.
Zeile 2: Ein Markierungspunkt, anzugeben mit dem Element area. Das Attribut coords enthält die Koordinate, die in units von areaspec spezifiziert wurde.

Im Attribut units muss ein gültiger Wert für die Einheit eingetragen werden. Mögliche Werte sind:

calspair="x1, yx2, y2"

spezifiziert einen rechteckigen Bereich mit (x1, y1) für die linke untere Ecke und entsprechend (x2, y2) für die rechte obere Ecke. Die X- und Y-Werte sind Ganzzahlen im Bereich von 0 bis 10.000, werden jedoch als prozentualer Wert im Bereich von 0,00% bis 100,00% interpretiert. Dieses Attribut ist nur in einem grafischen Kontext sinnvoll.

linecolumn="Zeile"

bestimmt die Zeile; der Wert ist in einem grafischen Kontext undefiniert.

linerange="Startzeile Endzeile"

definiert Koordinate in Form von Start- und Endzeilen; dieses Attribut ist in einem grafischen Kontext undefiniert.

linecolumnpair="ZeileSpalte1 Zeile2 Spalte2"

kennzeichnet einen Bereich durch zwei Zeilen-/Spaltenpaare. Das heißt, alle Zeichen befinden sich im gekennzeichneten Bereich, wenn diese in Spalte1 von Zeile1 beginnen und in Spalte2 von Zeile2 enden. In einem grafischen Kontext ist die Bedeutung dieses Attributs undefiniert.

otherunits

kennzeichnet eine anwendungsspezifische Einheit, die durch die zu verarbeitende Anwendung definiert ist. Ist dieser Wert angegeben, muss das Attribut otherunits vorhanden sein.

Anmerkung: Vermeiden Sie ungeprüfte Werte in coords
Beachten Sie, dass der Inhalt von coords vom Schema nicht auf das korrekte Format überprüft werden kann. Sie müssen selbst darauf achten, dass Sie die korrekte Syntax eintragen.

Für Texte sind die Einheiten linecolumn und linecolumnpair am sinnvollsten. Das folgende Beispiel zeigt, wie Sie Koordinaten zeilenweise definieren.

Beispiel: Definieren von Zeilen-Koordinaten

<programlistingco>
  <areaspec units="linecolumn">
    <area ANKER="co.commands" coords="4"/>
    <area ANKER="co.cmd" coords="6"/>
    <area ANKER="co.join" coords="7"/>
    <area ANKER="co.run" coords="9"/>
  </areaspec>
  <programlisting language="python">#!/usr/bin/python -u
import sys
import string
import commands

cmd = ["file", sys.argv[1], "| cut -d',' -f2" ]
cmd = string.join(cmd)

(res, out) = commands.getstatusoutput(cmd)

print res, out</programlisting>
</programlistingco>

Ersetzen Sie den Platzhalter ANKER durch id in DocBook 4 und xml:id in DocBook 5.

Zeile 1: Das Containerelement, das sowohl Koordinaten als auch Listing enthält.
Zeile 2: Definiert alle Koordinaten, Einheit ist zeilenweise (Attribut units mit dem Wert linecolumn).
Zeile 3: Dieser Markierungspunkt wird in der 4. Zeile gesetzt.
Zeile 8: Das eigentliche Listing ohne Markierungspunkte.

Das vorige Beispiel definierte die Koordinaten zeilenweise. Standardmäßig platziert die Callout-Erweiterungsfunktion diese in der Spalte, die durch den Parameter callout.defaultcolumn angegeben wird. Dadurch erscheinen alle Markierungspunkte in derselben Spalte. Falls Sie dies nicht möchten, verwenden Sie im Attribut units den Wert linecolumnpair wie im folgenden Beispiel gezeigt:

Beispiel: Definieren von Zeilen-Spalten-Koordinaten

<programlistingco>
  <areaspec units="linecolumnpair">
    <area ANKER="co.commands" coords="4"/>
    <area ANKER="co.cmd" coords="6 48"/>
    <area ANKER="co.join" coords="7 1"/>
    <area ANKER="co.run" coords="9 44"/>
  </areaspec>
  <programlisting language="python">#!/usr/bin/python -u
import sys
import string
import commands

cmd = ["file", sys.argv[1], "| cut -d',' -f2" ]
cmd = string.join(cmd)

(res, out) = commands.getstatusoutput(cmd)

print res, out</programlisting>
</programlistingco>

Ersetzen Sie den Platzhalter ANKER durch id in DocBook 4 und xml:id in DocBook 5.

Zeile 2: Definiert alle Koordinaten, Einheit ist zeilen- und spaltenweise (Attribut units mit dem Wert linecolumnpair).
Zeile 3: Dieser Markierungspunkt besitzt nur die Zeile. Die Spalte wird aus dem Parameter callout.defaultcolumn entnommen.
Zeile 4: Dieser Markierungspunkt wird an der 6. Zeile und der 48. Spalte gesetzt.

  

<< 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