目次 (TOC)

ID: org.eclipse.help.toc

説明: 個々のプラグインのオンライン・ヘルプ contribution を登録します。

ヘルプ・ファイルを提供する各プラグインは、通常、以下のことを行います。

toc 拡張ポイントの構成マークアップ (plugin.xml ファイルの内容):

    <!ELEMENT toc EMPTY>
    <!ATTLIST toc file CDATA #REQUIRED>
    <!ATTLIST toc primary (true | false) "false">
    <!ATTLIST toc extradir CDATA #IMPLIED>

toc の構成マークアップ (TOC ファイルの内容):

    <!ELEMENT toc (topic | anchor | link)*>
    <!ATTLIST toc link_to CDATA #IMPLIED >
    <!ATTLIST toc label CDATA #REQUIRED >

    <!ELEMENT topic (topic | anchor | link )*>
    <!ATTLIST topic label CDATA #REQUIRED >
    <!ATTLIST topic href CDATA #IMPLIED >

    <!ELEMENT anchor EMPTY >
    <!ATTLIST anchor id ID  #REQUIRED>

    <!ELEMENT link EMPTY >
    <!ATTLIST link toc CDATA #REQUIRED >

通常、オンライン・ヘルプを提供する必要のあるプラグインは、それ自体の TOC ファイルを定義します。 ヘルプ・システムは最終的に、アクションとして起動するよう構成され、これには TOC ファイルのパスが 使用されます。

トピック・エレメント

すべてのヘルプ・トピック・エレメントは、toc コンテナー・エレメントの一部として追加されます。 これらは、階層構造またはフラット・リストにすることができます。

トピック・エレメントは、目次には欠かせないエレメントです。 トピック・エレメントには、主に次の 2 つの用途があります。

1.  ドキュメンテーション・ファイル (通常は HTML ファイル) へのリンクを提供します。
2.  同じマニフェストまたは他のマニフェスト内の他の toc のコンテナーとして機能します。

1. リンクとしてのトピック
トピックの最も基本的な用途は、ドキュメンテーション・ファイルへのリンクです。

<topic label="Some concept file" href="concepts/some_file.html" />

href 属性は、マニフェスト・ファイルが属するプラグインに対する相対参照となります。 他のプラグインのファイルにアクセスするには、次の構文を使用します。

<topic label="topic in another plug-in" href="../other.plugin.id/concepts/some_other_file.html" />

2.  コンテナーとしてのトピック
次に一般的な用途は、その他の toc のコンテナーとして使用することです。 コンテナー・トピック自体も、常に特定のファイルを参照します。

<topic label="Integrated Development Environment" href="concepts/ciover.htm" >
  <topic label="Starting the IDE" href="concepts/blah.htm" />
  ...
</topic>

リンク・エレメント

リンク・エレメントを使用すれば、別の toc ファイルに定義された目次をリンクできます。 toc 属性に指定された toc ファイルからの全トピックが、リンク・エレメントではなく直接定義されたかの ように目次に表示されます。 toc を api.xml ファイルからインクルードするには、以下のように書くことができます。

<topic label="References" >
  ...
  <link toc="api.xml" />
  ...
</topic>

アンカー・エレメント

アンカー・エレメントは、他の toc ファイルをこのナビゲーションにリンクし、リンク・エレメントを 使用せずに、ここから他の toc ファイルを参照することを可能にするポイントを定義します。 "ZZZ" 文書の後に、さらにトピックを持つ目次を挿入することを可能にするためには、以下のように アンカーを定義します。

...
<topic label="zzz" href="zzz.html" />
<anchor id="moreapi" />
...

toc エレメント

toc エレメントは、このファイルに定義されたトピックと他のエレメントをグループ化する目次です。 ラベルは、ユーザーに対して表示されたときに、ユーザーが目次を識別するためのものです。 オプションの link_to 属性を使用すると、toc をこのファイルから、ナビゲーション階層で上になる別の toc ファイルにリンクできます。 link_to 属性は、別の toc ファイル内のアンカーを指定している必要があります。 myapi.xml からの toc を、別のプラグインに指定された api.xml ファイルにリンクするには、 次の構文を使用してください。

<toc link_to="../anotherPlugin/api.xml#moreapi" label="My Tool API"/>
...
<toc />

# は、toc ファイル名とアンカー ID とを区切るための文字です。

例:

toc 拡張ポイントの例を次に示します。 例では、ID が  "org.eclipse.help.examples.ex1" のプラグインを想定しています。 (この例は一般的なサンプル用であり、別の toc ファイルの様々な組み合わせで、以下のすべての toc ファイルを基にした同じドキュメンテーション階層を作成することができます。)

(ファイル plugin.xml)

 <extension point="org.eclipse.help.toc">
  <toc file="maindocs.xml" primary="true" />
  <toc file="task.xml" />
  <toc file="sample.xml" extradir="samples" />
 </extension>
 

(ファイル maindocs.xml)

<toc label="Help System Example">
 <topic label="Introduction" href="intro.html"/>
 <topic label="Tasks">
  <topic label="Creating a Project" href="tasks/task1.html">
   <topic label="Creating a Web Project" href="tasks/task11.html"/>
   <topic label="Creating a Java Project" href="tasks/task12.html"/>
  </topic>
  <link toc="task.xml" />
  <topic label="Testing a Project" href="tasks/taskn.html"/>
 </topic>
 <topic label="Samples">
  <topic label="Creating Java Project" href="samples/sample1.html">
   <topic label="Launch a Wizard" href="samples/sample11.html"/>
   <topic label="Set Options" href="samples/sample12.html"/>
   <topic label="Finish Creating Project" href="samples/sample13.html"/>
  </topic>
  <anchor id="samples" />
 </topic>
</toc>


(ファイル tasks.xml)

<toc label="Building a Project">
 <topic label="Building a Project" href="build/building.html">
  <topic label="Building a Web Project" href="build/web.html"/>
  <topic label="Building a Java Project" href="build/java.html"/>
 </topic>
</toc>


(ファイル samples.xml)

<toc link_to="maindocs.xml#samples" label="Using The Compile Tool">
 <topic label="The Compile Tool Sample" href="compilesample/example.html">
  <topic label="Step 1" href="compilesample/step1.html"/>
  <topic label="Step 2" href="compilesample/step2.html"/>
  <topic label="Step 3" href="compilesample/step3.html"/>
  <topic label="Step 4" href="compilesample/step4.html"/>
 </topic>
</toc>


次に、Eclipse ワークベンチで作成されるドキュメンテーション階層を示します。

ヘルプ・サンプル

"samples" で開始するパスを持つ文書が他にも存在すると仮定すると、それらはナビゲーション・ツリーには表示されませんが、 検索を使用してアクセスできます。  <toc file="sample.xml" extradir="samples" /> inside plugin.xml ファイル内のエレメントに "extradir" 属性が存在するためです。 たとえば、"Creating Java Project" を検索すると、パスが samples/sample2.html の "Other Ways of Creating Java Project" という文書が返されます。

国際化対応

TOC XML ファイルは変換可能で、結果のコピー (変換されたラベル付き) は nl/<language>/<country> または nl/<language> ディレクトリーに配置されます。 <language> と <country> はロケール・コードで使用される言語と国別コードを示す 2 文字です。 たとえば、中国語 (繁体字) 変換は nl/zh/TW ディレクトリーに配置されます。 nl/<language>/<country> ディレクトリーは nl/<language> より高い優先順位を持ちます。 nl/<language>/<country> にファイルが見つからない場合のみ、nl/<language> にあるファイルが 使用されます。 プラグインのルート・ディレクトリーは最後に検索されます。

doc.zip に含まれるドキュメンテーションは、変換されたバージョンの文書で doc.zip ファイルを作成し、 doc.zip を
nl/<language>/<country> または nl/<language> ディレクトリーに配置する ことによりローカライズできます。 ヘルプ・システムは、プラグイン・ディレクトリーをデフォルトにする前に、このディレクトリー下にある ファイルを探します。
 

API 情報: この拡張ポイントには、コードは必要ありません。 plugin.xml ファイルに記された適切なマニフェスト・ファイルを指定するだけです。
 

提供されるインプリメンテーション: Eclipse プラットフォームで提供される ヘルプ・システム UI のデフォルト・インプリメンテーションは、toc 拡張ポイントを 完全にサポートします。


Copyright IBM Corp. and others 2000, 2002. All Rights Reserved.