ネストされた文書構造のビルド

一般に、プラグインがプラットフォームに機能を組み込む場合には、新しい機能を説明するドキュメンテーションを追加します。  多くの個別のコントリビューションの代わりに、まとまりのある完全な一連のドキュメンテーションをユーザーが表示できるようにするには、 このドキュメンテーションをどのように構成したらいいでしょうか?  目次定義は、ドキュメンテーションをトップダウン方式とボトムアップ方式の両方でビルドするメカニズムを提供します。

トップダウン・ネスト

トップダウン・ネストとは、組み込まれたその他すべての toc を参照するマスター目次を定義する技法のことです。  トップダウン・ネストは、認識された内容をより小さな断片に分割するときに便利なメソッドです。  トップダウン・ネストでは、目次定義内で href を指定するのではなく link 属性を使用して、リンクされた toc を参照します。 

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

基本構造 (Concepts、Tasks、Reference) は同じですが、個々の toc は自由に展開できます。  toc をさらに別のサブ toc にリンクさせることが可能です。

ボトムアップ構成

ボトムアップ構成は、toc 構造のどこにドキュメンテーションを置くかを新しいプラグインが決定できるという点で、より柔軟です。  ボトムアップ構成は、anchor 属性を使用して作成します。  toc は、他のプラグインがドキュメンテーションを組み込むことのできる、名前付きアンカー・ポイントを定義します。  以下の例では、概念、タスク、および参照セクションの間にプラグインが追加の資料を組み込むことを可能にするアンカーを追加できます。

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

次に、他のプラグインがプラグインからアンカーに組み込みを行うことができます。  これは、toc を定義するときに link_to 属性を使用して行います。

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