ヘルプ・ファイルを提供する各プラグインは、通常、以下のことを行います。
オプションとして、index
エレメントを使用して検索索引を事前に構築し、登録して、最初の検索を試行することができます。登録できるのは、プラグインごとに 1 つの索引のみです。複数の index
エレメントがあると、予期せぬ動作が発生します。
<!ELEMENT extension (toc* , index?)>
<!ATTLIST extension
point CDATA #REQUIRED
id CDATA #IMPLIED
name CDATA #IMPLIED>
<!ELEMENT toc EMPTY>
<!ATTLIST toc
file CDATA #REQUIRED
primary (true | false) "false"
extradir CDATA #IMPLIED>
toc ファイルの構成マークアップ:
<!ELEMENT toc (topic | anchor | link)*>
<!ATTLIST toc link_to CDATA #IMPLIED >
<!ATTLIST toc label CDATA #REQUIRED >
<!ATTLIST toc topic CDATA #IMPLIED >
<!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 エレメントは、このファイルに定義されたトピックと他のエレメントをグループ化する目次です。ラベルは、 ユーザーに対して表示されたときに、ユーザーが目次を識別するためのものです。 オプションのトピック属性は 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 とを区切るための文字です。
<!ELEMENT index EMPTY>
<!ATTLIST index
path CDATA #REQUIRED>
(3.1 以降) このプラグインがコントリビュートする文書から作成された構築済み検索索引の宣言を可能にするオプションのエレメント
index/
、nl/ja/JP/index/
、nl/en/US/index/
など)。.(ファイル plugin.xml)
<extension point=
"org.eclipse.help.toc"
>
<toc file=
"maindocs.html"
primary=
"true"
/>
<toc file=
"task.xml"
/>
<toc file=
"sample.xml"
extradir=
"samples"
/>
<index path=
"index/"
/>
</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>
"samples" で始まるパスを持つ文書が他にも存在すると仮定すると、その文書はナビゲーション・ツリーには 表示されませんが、検索を使用してアクセスできます。 これは、plugin.xml ファイル内のエレメント <toc file="sample.xml" extradir="samples" /> に "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> ディレクトリーに配置する
ことによりローカライズできます。
ヘルプ・システムは、プラグイン・ディレクトリーをデフォルトにする前に、このディレクトリー下にある
ファイルを探します。
Copyright (c) 2000, 2005 IBM Corporation and others.
All rights reserved.
This program and the accompanying materials are made
available under the terms of the Eclipse Public License v1.0 which accompanies
this distribution, and is available at http://www.eclipse.org/legal/epl-v10.html