サンプルのコンテンツ・ファイルを作成したので、トピック・ファイルを作成することができます。 トピック・ファイルは、いくつかの HTML ファイル内の 1 つのファイルの参照に トピック ID とラベルをマッピングすることにより、 重要なエントリー・ポイントを HTML コンテンツ・ファイルに定義します。 トピック・ファイルは、HTML の内容の目次のような働きをします。
プラットフォームに移行されるアプリケーションは、トピック・ファイルを使用して、 既存のドキュメンテーションにエントリー・ポイントを定義することにより、 そのドキュメンテーションを再利用することができます。
プラグインは 1 つまたは複数のトピック・ファイルを持つことができます。 トピック・ファイルは、HTML の内容をナビゲートする方法を記述しているので、 ナビゲーション・ファイルと呼ばれることもあります。 サンプルのドキュメンテーションは、概念、タスク、および参照という 3 つの主要カテゴリーに編成されます。 この構造を表すトピック・ファイルを作成するにはどのようにすればよいのでしょうか。
1 つの大きなトピック・ファイルを作成することもできます。 あるいは、内容のメイン・カテゴリーごとに個別のトピック・ファイルを作成することもできます。 ドキュメンテーション・チームの共同作業の仕方に従って、この決定を下す必要があります。 各カテゴリーが異なる作成者に所有されている場合は、 カテゴリーごとに個別のトピック・ファイルを保持することが望ましいでしょう。 トピック・ファイルはプラットフォームのアーキテクチャーの影響を受けません。
この例では、内容の主要カテゴリーごとにトピック・ファイルを作成します。 この例のように、わずかなファイル数の場合には、 カテゴリーごとに個別のトピック・ファイルを持つ必要はないこともあります。 ここでは、多くのファイルがある場合、 あるいは作成者がそれぞれ各内容カテゴリーを所有している場合を想定して、このサンプルをワイヤリングします。
ファイルは次のようになっています。
<topics id="conceptsAll">
<topic label="Concept1" href="doc/concepts/concept1.html">
<topic label="Concept1_1" href="doc/concepts/concept1_1.html"/>
<topic label="Concept1_2" href="doc/concepts/concept1_2.html"/>
</topic>
</topics>
<topics id="tasksAll">
<topic id="plainTasks" label="Plain Stuff">
<topic label="Task1" href="doc/tasks/task1.html"/>
<topic label="Task2" href="doc/tasks/task2.html"/>
</topic> <topic id="funTasks" label="Fun Stuff" >
<topic label="Task3_1" href="doc/tasks/task3_1.html"/>
<topic label="Task3_2" href="doc/tasks/task3_2.html"/>
</topic>
</topics>
<topics id="refAll">
<topic label="Ref1" href="doc/ref/ref1.html"/>
<topic label="Ref2" href="doc/ref/ref2.html"/>
</topics>
トピックは、トピック・コンテナー・エレメントの一部として追加されます。 トピックは、内容への単純リンクにすることができます。 たとえば、"Task1" は、内容にリンクする label と href を提供しています。 トピックは、それ自体は内容を持たないサブトピックの階層グループにすることもできます。 たとえば、"Fun Stuff" は、ラベルとサブトピックしか持たず、href はありません。 トピックは、どちらにすることもできます。 "Concept1" には href とサブトピックがあります。
リンクとして使用した場合、href 内の引き数は、現在のプラグインを基準にしたものと想定されます。
最初に、これらのトピックをドキュメンテーション Web 全体にワイヤリングすると、 トピックの ID を使用してトピックを参照することになります。 ある ID を持つトピックだけを操作することができます。 特定のトピックのサブトピックをすべてワイヤリングするために、親のトピックをワイヤリングすることができます。 たとえば、"Concept1" をワイヤリングすると、 "Concept1_1" と "Concept1_2" もワイヤリングされます。
後で、plugin.xml を変更して、これらのファイルを指す実際の追加を指定します。