Verschachtelte Dokumentationsstrukturen erstellen

Wenn Plug-ins die Funktionalität der Plattform ergänzen, wird normalerweise eine Dokumentation hinzugefügt, die die neue Funktion beschreibt.  Die Dokumentation sollte 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, an welcher Stelle 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 Beispiel 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 bei der Definition einer TOC-Datei.

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