Verschachtelte Dokumentationsstrukturen erstellen

Wenn Plug-ins die Plattform durch Funktionalität ergänzen, wird normalerweise eine Dokumentation hinzugefügt, die die neue Funktion beschreibt.  Die Dokumentation sollte nun so strukturiert sein, dass der Benutzer eine in sich geschlossene und vollständige Dokumentationsgruppe anstelle vieler einzelner Ergänzungen angezeigt bekommt.   Die Definition des Inhaltsverzeichnisses bietet Mechanismen, mit denen Dokumentation sowohl in einer Abwärts- als auch einer Aufwärtshierarchie erstellt werden kann.

Abwärtsverschachtelung

Bei der Abwärtsverschachtelung (Top-down) wird ein Hauptinhaltsverzeichnis definiert, das auf alle anderen enthaltenen Themen (TOC-Dateien) verweist.   Diese Vorgehensweise eignet sich gut, um bekannten Inhalt in kleinere Abschnitte zu untergliedern.  Bei der Abwärtsverschachtelung wird kein Argument href angegeben, sondern vielmehr das Attribut link in der Definition des Inhaltsverzeichnisses verwendet, um auf verlinkte Abschnitte zu verweisen. 

<toc label="Online Help Sample" topic="html/book.html">
	<topic label="Concepts">
		<link toc="toc_Concepts.xml" />
	</topic>
	<topic label="Tasks">
		<link toc="toc_Tasks.xml" />
	</topic>
	<topic label="Reference">
		<link toc="toc_Ref.xml" />
	</topic>
</toc>

Die Basisstruktur (Concepts, Tasks, Reference) bleibt identisch, aber die einzelnen TOC-Dateien können ganz wie gewünscht platziert werden. Außerdem können diese Dateien wiederum Links zu anderen Unterthemen enthalten.

Aufwärtszusammensetzung

Die Aufwärtszusammensetzung (Bottom-up) ist insofern flexibler, als sie neuen Plug-ins die Entscheidung ermöglicht, ob die Dokumentation in die TOC-Struktur aufgenommen werden soll.  Die Aufwärtszusammensetzung wird durch Attribute anchor realisiert.  Eine TOC-Datei definiert benannte Ankerpunkte, an denen andere Plug-ins Dokumentation ergänzen können.  Im verwendeten Beisiel könnten Attribute anchor hinzugefügt werden, damit Plug-ins in den Abschnitten "Concepts", "Tasks" und "Reference" zusätzlichen Inhalt ergänzen könnten.

<toc label="Online Help Sample" topic="html/book.html">
	<topic label="Concepts">
		<link toc="toc_Concepts.xml" />
		<anchor id="postConcepts" />
	</topic>
	<topic label="Tasks">
		<link toc="toc_Tasks.xml" />
		<anchor id="postTasks" />
	</topic>
	<topic label="Reference">
		<link toc="toc_Ref.xml" />		
		<anchor id="postReference" />
	</topic>
</toc>

Bei dieser Struktur können andere Plug-ins am Ankerpunkt eine Ergänzung aus ihrem Plug-in bereitstellen.  Dies erfolgt durch die Verwendung eines Attributs link_to beim Definieren einer TOC-Datei.

<toc link_to="../com.example.helpexample/toc.xml#postConcepts" label="Late breaking info about concepts">
	<topic>
		...
	</topic>
</toc>

Copyright IBM Corporation und Andere 2000, 2003.