conref

(Auszug aus "DITA - Der neue Standard für Technische Dokumentation" von Johannes Hentrich)

Mit dem conref-Mechanismus können Sie Inhalte in Informationsstrukturen referenzieren und somit später wieder verwenden. Der Name des conref-Attributs leitet sich aus content reference ab, das heißt, die Referenzierung von Inhalten.

Mit dem conref-Attribut wird eine ID rerenziert, die zu den folgenden Informationsstrukturen gehören kann:

• Topic
• Elemente innerhalb eines Topics
• Element innerhalb einer Map

Damit Sie den conref-Mechanismus nutzen können, ist jedem Element eine eindeutige ID zuzuordnen. Das folgende Beispiel zeigt eine ID zu einem <ul>-Element.

Abbildung: Eine von der XMetal Enterprise Edition vergebene ID für das <ul>-Element

Um die mit einer ID ausgestatteten Elemente beispielsweise in einem anderen Topic zu referenzieren, wird das conref-Attribut in gleicher Weise verwendet wie das href-Attribut in HTML. Mit dem conref-Atrribut wird nichts weiter gesetzt als ein Link zu einem Element.

Abbildung: Definition eines conref-Attributs in der XMetal Enterprise Edition

Bei Elementen, die ein conref-Attribut mit einer gültigen Referenz zu einer ID besitzen, wird der Inhalt des Elements ignoriert und durch den Inhalt des referenzierten Elements ersetzt.

Werden neben dem conref-Attribut noch weitere Attribute in einem Element angegeben, so bleiben die Attribute und deren Werte nach der Inklusion der Inhalte bestehen. Durch dieses standardmäßige Verhalten bleiben alle Attribute erhalten, unabhängig davon, welche Attribute in dem referenzierten Element vorhanden und gesetzt sind.

Soll jedoch ein Attributwert des referenzierten Elements übernommen werden, so kann dies mit dem Attributwert -dita-use-conref-target erzwungen werden. Das folgende Beispiel zeigt, welche Wirkung der Attributwert -dita-use-conref-target hat.

Es sei in einem <topichead>-Element eine ID mit dem Wert h1_th definiert:

Wird in einem weiteren <topichead>-Element im conref-Attribut auf das <topichead>-Element mit der ID mit dem Wert h1_th referenziert:

so wird für das navititle-Attribut der Wert aus dem referenzierten <topichead>-Element übernommen. Erhalten bleibt das toc-Attribut mit dem Wert no. Übernommen aus dem referenzierten <topichead>-Elemen wird noch das print-Attribut mit dessen Wert yes. Damit sieht dann das Ergebnis wie folgt aus:

 <topichead navtitle="Überschrift" toc="no" print="yes"/> 

In den folgenden drei Abschnitten wird gezeigt, wie Sie die Werte für ein conref-Attribut setzen müssen, damit Sie

• Topics referenzieren,
• Elemente in Topics referenzieren,
• und Elemente in Maps referenzieren

können.

Topics referenzieren

Über das conref-Attribut können ganze Topics in bestehende Topics eingebunden werden.

Es gibt drei Möglichkeiten, auf ein Topic zu referenzieren:

• Das Topic befindet sich in der gleichen DITA XML-Datei:

 conref="#topic_id" 

Befindet sich das Topic in der gleichen DITA XML-Datei, wird vor der Topic ID ein # gesetzt.

• Das Topic ist das erste Topic in einer anderen DITA XML-Datei:

 conref="andere_datei.xml" 

Wird nur eine Datei beziehungsweise der Pfad zu einer Datei angegeben, so wird automatisch die erste gefundene Topic ID zur Referenzierung verwendet.

• Das Topic befindet sich an einer beliebigen Stelle in einer anderen DITA XML-Datei:

 conref="andere_datei.xml#topic_id" 

Soll innerhalb einer DITA XML-Datei auf ein bestimmtes Topic und damit auf eine bestimmte Topic ID verwiesen werden, so wird hinter dem Dateinamen ein # gesetzt, gefolgt von der entsprechenden Topic ID.

Elemente in Topics referenzieren

Der häufigste Anwendungsfall in der Praxis ist die Referenzierung von Elementen innerhalb eines Topics.

Es gibt zwei Möglichkeiten, ein Element innerhalb eines Topics zu referenzieren:

• Das Element befindet sich in der gleichen DITA XML-Datei:

 conref="#topic_id/element_id" 

Befindet sich die Topic ID in der gleichen DITA XML-Datei, so wird vor der Topic ID ein # gestellt. Danach folgt ein / (slash), mit nachfolgender Element ID.

• Das Element befindet sich in einer anderen DITA XML-Datei:

 conref="andere_datei.xml#topicid/elementid" 

Zuerst wird die Datei beziehungsweise der Pfad zu der Datei angegeben. Danach folgt ein # und die Topic ID, in der sich das zu referenzierende Element befindet. Nach der Topic ID folgt wieder ein / (slash) und die ID des Elements.

Elemente in Maps referenzieren

Es gibt zwei Möglichkeiten auf ein Element innerhalb einer Map zu referenzieren:

• Das Element befindet sich in der gleichen DITA Map-Datei:

 conref="#element_id" 

Befindet sich die Element ID in der gleichen DITA Map-Datei, so wird vor der Element ID ein # gestellt.

• Das Element befindet sich in einer anderen DITA Map-Datei:

 conref="andere_map_datei.xml#elementid" 

Zuerst wird die Datei beziehungsweise der Pfad zu der DITA Map-Datei angegeben. Danach folgt ein # und die Element ID des zu referenzierenden Elements in der Map.