注: ヘルプ・システムは現在開発中であり、安定版の完成までには変更が予想されます。 初期段階の採択者からは、現在、contribution メカニズムの詳細が予期しない形で変更される可能性のあることを理解した上で、 フィードバックを受け付けています。 |
説明: 個々のプラグインのオンライン・ヘルプ contribution を登録します。
ヘルプ・ファイルを提供する各プラグインは、通常、以下のことを行います。
<!ELEMENT topics EMPTY>
<!ATTLIST topics name CDATA #REQUIRED>
<!ELEMENT topics (topic)*) >
<!ATTLIST topics id ID #REQUIRED >
<!ELEMENT topic (topic)* >
<!ATTLIST topic id ID #IMPLIED >
<!ATTLIST topic label CDATA #REQUIRED >
<!ATTLIST topic href CDATA #IMPLIED
>
情報セットの構成マークアップ (infoset マニフェスト・ファイルの内容):
<!ELEMENT infoset (infoview)* >
<!ATTLIST infoset id ID
#REQUIRED >
<!ATTLIST infoset label CDATA
#REQUIRED >
<!ATTLIST infoset href CDATA
#IMPLIED >
<!ATTLIST infoset standalone
(false|true) false #IMPLIED >
<!ELEMENT infoview EMPTY>
<!ATTLIST infoview id ID #REQUIRED >
<!ATTLIST infoview label CDATA #IMPLIED >
挿入アクションの構成マークアップ (アクション・マニフェスト・ファイルの内容):
<!ELEMENT actions (insert)* >
<!ATTLIST actions infoview CDATA #REQUIRED
>
<!ATTLIST actions standalone (true | false)
false #IMPLIED >
<!ELEMENT insert (insert) >
<!ATTLIST insert from CDATA #REQUIRED >
<!ATTLIST insert to CDATA #REQUIRED >
<!ATTLIST insert as (child
| first-child | last-child | prev-sib | next-sib) "child" >
<!ATTLIST insert label CDATA #IMPLIED >
通常、オンライン・ヘルプを提供するプラグインは、 そのトピックのマニフェストと、トピックの正しい位置を指定するためのアクション・マニフェストを定義します。 ヘルプ・システムは最終的に、アクションとして起動するよう構成され、 これには情報セットの ID が使用されます。
プラグインが使用することのできる XML エレメントには、トピック、情報セット、アクション、および挿入の 4 つがあります。
トピック・エレメント
トピック・エレメントに関連して、すべてのトピックはトピック・コンテナー・エレメントのパーツとして提供されます。 これらは、階層構造またはフラット・リストにすることができます。 トピック・マニフェストは、トピックのインターリービング、および、 各種のビュー・パースペクティブを持つ統合 Web の編成のためのデータ・ソースと見なされます。 また、トピックは、その ID を指定することにより、アクションを行うことができますが、 含まれるトピックやトピック・エレメントの ID を指定することにより、トピックのグループに対するアクションも可能です。 その後、トピックをビューや他のトピックに関連付ける場合、 トピックのマニフェスト内に定義された構造は (挿入アクションにより行われる変更に従って) 保持されます。
トピック・エレメントは、ナビゲーション構造には欠かせないエレメントです。 トピック・エレメントには、主に次の 3 つの用途があります。
1. ドキュメンテーション・ファイル (通常は HTML ファイル) へのリンクを提供します。
2. 同じマニフェストまたは他のマニフェスト内の他のトピックのコンテナーとして機能します。
3. 同じマニフェストまたは他のマニフェスト内の他のトピックの挿入ポイントとなります。
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. コンテナーとしてのトピック
次に一般的な用途は、その他のトピックのコンテナーとして使用することです。
コンテナー・トピック自体も、常に特定のファイルを参照します。
<topic label="Integrated Development Environment" href="concepts/ciover.htm"
>
<topic label="Starting the IDE" href="concepts/blah.htm"
/>
...
</topic>
3. 挿入ポイントとしてのトピック
トピックは、挿入ポイントとして使用することができます。
これは、他のトピックを参照しマージするための論理位置となります。
トピックを挿入ポイントとするには、id 属性が必要です。
情報セット・エレメント
情報セットは、ドキュメンテーション Web へのエントリー・ポイントです。 これは、ビューの集合と見なすことができます。
ビューは、ドキュメンテーション Web 内における 上位のセマンティック・グループを提供するためのものです。 これらは、情報セット内に定義された infoview エレメントを使用して定義されます。 ドキュメンテーション・チームはビュー (または製品チームが定義したビュー) を使用して、 入門、タスク、参照セクションを作成することができます。 プラットフォームは実際のセクションを指定しません。 これを定義するためのメカニズムを提供するだけです。
たとえば、「how to do something」パースペクティブのトピックをすべてマージして、 「タスク・ビュー」を定義することができます。 また他のビューとして、すべてのコンポーネントとそのドキュメンテーションを表示するトピック・ツリーである 「コンポーネント・ビュー」も定義することができます。
情報ビュー・エレメントは、プラグイン間で「共用」が可能なトピックのコンテナーを表します。 これは、ドキュメンテーション全体についてのパースペクティブです。 いくつかの各種プラグインが、ドキュメンテーションの同じ論理コンポーネントを提供する場合があります。 このエレメントにより、それらのコンポーネントが正しくマージされ、 整合性のあるビューになっていることが「コンポーネント・ビュー」内で確認することができます。
アクション・エレメント
アクション・マニフェストは、トピックおよびビューに対して実行されるスクリプト・アクションを含みます。 現在は、1 種類のアクション (挿入アクション) のみが存在し、 これはトピックやビューを、複数のビューを持つ 1 つの統合情報 Web に編成するために使用されます。
アクションは構造に関するアクション (挿入) で、特定の情報ビューに適用されます。 したがって、マニフェスト内のすべての挿入アクションにより、1 つの情報ビューにトピック階層が構築されます。
挿入エレメント
コンポーネント化したナビゲーションにおける最も複雑な部分は、 連続的なナビゲーション・フローを持つ統合情報構造の作成方法です。 これを作成するには、挿入ポイントをパブリッシュし、使用する挿入ポイントを選択して、 トピックの挿入位置 (親子、前後) を指示するためのメカニズムが必要です。
挿入ポイントは、トピックまたはビューとすることができます。 トピックは、ID を指定されることにより、挿入ポイントになります。 ビューには ID が必要です。参照には完全修飾された ID のみが使用されます。 たとえば、org.eclipse.help.examples.ex1 プラグイン における <topic id="concepts" label="concepts"> の完全修飾トピック ID は、 org.eclipse.help.examples.ex1.concepts です。
通常、挿入ポイントは他のプラグイン内に配置されており、これらのプラグインがインストールされないことがあるため、 代替の挿入ポイントを指定する必要があります。 デフォルトでは、いずれの選択項目も選択されなかった場合、 トピックはそのコンポーネント階層以下に置かれたままとなります。 "to" 属性は、ターゲットの挿入ポイントを指定します。 "from" 属性により指定されたトピックは、現在挿入されているトピックです。 トピックを挿入する方法をいくつか次に示します。これは、as 属性を使用して指定されています。
挿入オプションが実行できなかった場合には、その後、代替の挿入オプションが実行されます。
挿入エレメントのネストされた挿入サブエレメントがこれらの代替オプションを提供します。
これは、挿入アクションが失敗した場合に、
ネストされた挿入アクションが実行されるようにする「フォールバック」メカニズムと考えることができます。
最初に選択した挿入ポイントが満たされると、
その他の代替挿入ポイントは無視されます。
例:
contributions 拡張ポイントの例を次に示します。 例では、ID が "org.eclipse.help.examples.ex1" のプラグインを想定しています。 (この例は一般的なサンプル用であり、トピックおよびアクション・ファイルの各種組み合わせを用いることにより、 以下のすべての contribution ファイルを基にした同じドキュメンテーション階層を作成することができます。)
(ファイル plugin.xml)
<!-- Use the Help System contribution extension
point to define Infosets, topics, -->
<!-- and actions contribution files. For clarity,
the extension point is used -->
<!-- twice, once to define the Infoset and it's
view, and another to define the -->
<!-- Topics and their associated actions.
-->
<extension point="org.eclipse.help.contributions">
<infoset name="infoset.xml"/>
</extension>
<extension point="org.eclipse.help.contributions">
<topics name="infosetTopics.xml"/>
<actions name="infosetActions.xml"/>
</extension>
<!-- Configure the help contribution for this plugin
-->
<!-- This part should be in a documentation plugin
-->
<extension point="org.eclipse.help.contributions">
<topics name="topics.xml"/>
<actions name="topicsActions.xml"
/>
</extension>
(ファイル infoset.xml)
<!-- Define the Infoset, and any views it has. -->
<infoset id="ex1InfosetId" label="%help_system_example">
<infoview id="topicsView" label="%topics"/>
</infoset>
(ファイル infosetTopics.xml)
<!-- Now define a "container" topic that holds your general topics. This makes it -->
<!-- easier to quickly insert all these general topics under the view in the -->
<!-- Infoset. -->
<topics id="topLevelTopics">
<topic id="concepts" label="%concepts"/>
<topic id="tasks" label="%tasks"/>
<topic id="references" label="%references"/>
<topic id="samples" label="%samples"/>
</topics>
上記の汎用トピックに含まれるトピックを定義します。
(ファイル topics.xml)
<topics id="topics">
<topic id="aConceptId" label="%introduction" href="concepts/concept.html"/>
<topic id="aTaskId" label="%creating_a_project" href="tasks/task1.html">
<topic id="aSubTaskId1" label="%creating_a_web_project" href="tasks/task2.html"/>
<topic id="aSubTaskId2" label="%creating_a_java_project" href="tasks/task3.html"/>
</topic>
<topic id="aReferenceId" label="%interfaces" href="ref/ref1.html"/>
<topic id="aSampleId" label="%help_system_sample" href="MissingFile.html"/>
</topics>
ドキュメンテーション階層の作成に必要な挿入アクションを定義します。
(ファイル infosetActions.xml)
<actions infoview="org.eclipse.help.examples.ex1.topicsView">(ファイル topicsActions.xml)
<insert from="org.eclipse.help.examples.ex1.topLevelTopics"
to="org.eclipse.help.examples.ex1.topicsView" as="child"/>
</actions>
<actions infoview="org.eclipse.help.examples.ex1.topicsView">次に、Eclipse ワークベンチで作成されるドキュメンテーション階層を示します。
<insert from="org.eclipse.help.examples.ex1.aConceptId"
to="org.eclipse.help.examples.ex1.concepts" as="child"/><insert from="org.eclipse.help.examples.ex1.aTaskId"
to="org.eclipse.help.examples.ex1.tasks" as="child"/><insert from="org.eclipse.help.examples.ex1.aReferenceId"
to="org.eclipse.help.examples.ex1.references" as="child"/><insert from="org.eclipse.help.examples.ex1.aSampleId"
to="org.eclipse.help.examples.ex1.samples" as="child"/>
</actions>
API 情報: この拡張ポイントには、コードは必要ありません。
plugin.xml ファイルに記された適切なマニフェスト・ファイルを指定するだけです。
提供されるインプリメンテーション: Eclipse プラットフォームに提供されるヘルプ・システム UI の オプションのデフォルト・インプリメンテーションは、 contributions 拡張ポイントを完全にサポートします。