Building nested documentation structures

As plug-ins contribute functionality to the platform, it's common to add documentation that describes the new function.  How can this documentation be structured so that the user sees a cohesive and complete set of documentation instead of many individual contributions?  The table of contents definition provides mechanisms for building documentation in both a top-down and bottom-up fashion.

Top-down nesting

Top-down nesting refers to the technique of defining a master table of contents which refers to all other included tocs.  Top-down nesting is a convenient method for breaking up known content into smaller pieces.  With top-down nesting, the link attribute is used in the table of contents definition to refer to linked tocs rather than providing an href. 

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

The basic structure stays the same (Concepts, Tasks, Reference), but the individual tocs are free to evolve.  They in turn might link to other sub-tocs.

Bottom-up composition

Bottom-up composition is more flexible in that it lets new plug-ins decide where the documentation should exist in the toc structure.  Bottom-up composition is accomplished using anchor attributes.  A toc defines named anchor points where other plug-ins can contribute documentation.  In our example, we could add anchors so that plug-ins can contribute additional material between the concepts, tasks, and reference sections.

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

Other plug-ins can then contribute to the anchor from their plug-in.  This is done using the link_to attribute when defining a toc.

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