Anpassen mittels xrefstyle-Attribut

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

Falls Querverweise nur an bestimmten Stellen eine andere Darstellung erhalten sollen, verwenden Sie das Attribut xrefstyle. Es ist sowohl im Element xref als auch in biblioref, link und olink erlaubt.

Der Inhalt des Attributs xrefstyle darf folgende Werte annehmen:

template:

Nach template: wird Text mit Platzhaltern erwartet. Verschiedene Platzhalter bestimmen Titel, Nummer, Seite usw. Diese werden aufgelöst und durch Ihren Wert ersetzt.

select:

Nach select: werden Schlüsselwörter erwartet, die durch die Stylesheets aufgelöst werden.

Irgendein frei erfundener Name

Wird keines der oberen verwendet, wird der Inhalt als ein Name interpretiert, der in einer Sprachdatei als Stil definiert wurde.

 

Das template-Schlüsselwort

Wenn der Wert des Attributs xrefstyle mit template: beginnt, wird die nachfolgende Zeichenkette als unveränderlicher Text mit Platzhaltern interpretiert. Dies ist dann sinnvoll, wenn der aufgelöste Standardtext nicht passend erscheint oder sich nicht flüssig in den Text integriert.

Folgender Text enthält ein xrefstyle-Attribut:

Im <xref linkend="XPath" xrefstyle="template:Kapitel %n über %t"/> erfahren Sie mehr zu diesem Thema.

Wird der Text aufgelöst, erscheint:

Im Kapitel 13 über XPath erfahren Sie mehr zu diesem Thema.

Die verfügbaren Platzhalter sind in folgender Tabelle beschrieben:  

Tabelle: Verfügbare Platzhalter

Platzhalter Beschreibung
%d Richtung (wie "oben" bzw. "unten")
%n Nummerierung
%o Dokumentname (nur olinks)
%p Seitenzahl, falls anwendbar
%s Untertitel, falls verfügbar
%t Titel  

Anmerkung: Seitenzahlen sind nicht immer sinnvoll
Problematisch ist beim Platzhalter %p, dass er je nach Format keinen sinnvollen Wert ergeben kann. Schreiben Sie beispielweise template: Kapitel %n über %t auf Seite %p ergibt dies für %p in (X)HTML eine leere Zeichenkette und in (X)HTML einen verwirrenden Text. Falls Sie dennoch Seitenzahlen benötigen, ist es in diesem Fall besser die select-Methode einzusetzen.

Das select-Schlüsselwort

Nach select: werden bestimmte Schlüsselwörter erwartet, die durch die Stylesheets aufgelöst werden. Freier Text darf nicht erscheinen. Verwenden Sie diese Methode, wenn die Darstellung eines Verweises über das Format in den Sprachdateien aufgelöst werden soll. Folgendes Beispiel zeigt den Sachverhalt:

Im Kapitel <xref linkend="XPath" xrefstyle="select:labelnumber quotedtitle"/> erfahren Sie mehr zu diesem Thema.

Wird der Text aufgelöst, erscheint:

Im Kapitel 13: "XPath" erfahren Sie mehr zu diesem Thema.

Mit der select-Methode lassen sich folgende Komponenten einfügen:

  • Nummerierte Name eines Elements (Label)
  • Titel
  • Falls möglich, eine Seitennummer
  • Dokumentenname für olink-Elemente

Für jede dieser Komponenten gibt es verschiedene Schlüsselwörter, die eine bestimmte Darstellung erzeugen. Sie sind in folgender Liste aufgeführt:

Nummerierter Name

wählt einen Bezeichner, der auf das entsprechende Element zeigt. Sie sollten nur auf solche Elemente verweisen, die einen Titel besitzen, da nur in diesem Fall ein eindeutiger Name erhalten wird.

Schlüsselwort Beispiel Bedeutung
label Abschnitt 16.6 komplette Bezeichnung und Nummer
labelname Abschnitt nur die Bezeichnung
labelnumber 16.6 nur die Nummerierung
  
Titel

wählt den Titel der Referenz, sofern vorhanden.

Schlüsselwort Beispiel Bedeutung
title Querverweise anpassen Titel ohne Anführungszeichen
quotedtitle "Querverweise anpassen" Titel in Anführungszeichen

  

Seitenzahl

fügt verschiedene Formen einer Seitenzahl ein. Dies ist nur für XSL-FO sinnvoll, da Onlineformate keine Seite kennen.

Schlüsselwort Beispiel Bedeutung
unspezifiziert [389] Standard-Seitenformat für alle xref-Elemente, wenn insert.xref.page.number auf yes gesetzt wurde. Für andere Elemente wird dieses Format verwendet, wenn der Parameter insert.link.page.number auf yes gesetzt wurde.
page (Seite 389) Seitenzahl in Klammern
Page Seite 389 großgeschriebene Bezeichnung für Seite
pageabbrev (S. 389) abgekürzte Bezeichnung in Klammern
pagenumber 389 nur die Seitenzahl
nopage schaltet Seitenzahlen für dieses xref-Element ab, falls insert.xref.page.number auf yes gesetzt wurde. Für andere Elemente gilt dies, wenn der Parameter insert.link.page.number auf yes gesetzt wurde.

  

Dokumentenname

fügt den Dokumentennamen ein. Dies ist nur für olink sinnvoll.

Schlüsselwort Bedeutung
docname fügt den durch olink referenzierten Dokumententitel ein (siehe auch Sprachdatei unter dem selben Schlüsselwort)
docnamelong fügt eine längere Variante des referenzierten Dokumententitels ein (siehe auch Sprachdatei unter dem selben Schlüsselwort)
nodocname schaltet das Einfügen des Dokumentennamens aus, wenn der Parameter olink.doctitle den Wert yes enthält.

 

Inhalt ist ein Stilname

Diese Methode ist sicherlich am einfachsten zu schreiben, benötigt jedoch Anpassungen in den Sprachdateien. Vorteilhaft ist, dass sich zulässige Werte durch eine Schema-Anpassung beschränken lassen.

Gehen Sie wie folgt vor:

  1. Erzeugen Sie eine Sprachdatei (direkt im Stylesheet oder separat in einer eigenen Datei).
  2. Fügen Sie den Stil Ihres Querverweises ein. Je nach Element müssen Sie weitere l:template-Elemente einfügen:
<l:i18n xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0"> 
    <l:l10n language="de"> 
        <l:context name="xref-number-and-title"> 
            <l:template name="chapter" style="chapter-number-title" text="Kapitel %n: &#8220;%t&#8221;"/>
            <!-- ... --> 
        </l:context> 
    </l:l10n> 
</l:i18n> 

Zeile 4: style-Attribut - der Name Ihres Stils; text-Attribut - enthält den Ersetzungstext inklusive Platzhalter.

  1. Fügen Sie Ihren Stilnamen immer dort ein, wo Sie ihn benötigen:
<xref linkend="XPath" xrefstyle="chapter-number-title"/> 

Beachten Sie, dass der Stil nur verwendet wird, wenn er auch auf ein Kapitel zeigt. Benötigen Sie einen ähnlichen Stil für andere Elemente, müssen Sie für jedes Element ein Attribut style einfügen.

Verwenden Sie eine andere Nummerierung, müssen Sie möglicherweise einen zusätzlichen Kontext für xref in Ihre Sprachdatei einfügen.

  

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