Building nested documentation structures
As plug-ins contribute function 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>
