Follow Techotopia on Twitter

On-line Guides
All Guides
eBook Store
iOS / Android
Linux for Beginners
Office Productivity
Linux Installation
Linux Security
Linux Utilities
Linux Virtualization
Linux Kernel
System/Network Admin
Programming
Scripting Languages
Development Tools
Web Development
GUI Toolkits/Desktop
Databases
Mail Systems
openSolaris
Eclipse Documentation
Techotopia.com
Virtuatopia.com

How To Guides
Virtualization
General System Admin
Linux Security
Linux Filesystems
Web Servers
Graphics & Desktop
PC Hardware
Windows
Problem Solutions
Privacy Policy

  




 

 

Eclipse Plug-in Developer Guide
Previous Page Home Next Page

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>

 
 
  Published under the terms of the Eclipse Public License Version 1.0 ("EPL") Design by Interspire