注: ヘルプ・システムは現在開発中であり、安定版の完成までには変更が予想されます。 初期段階の採択者からは、現在、contribution メカニズムの詳細が予期しない形で変更される可能性のあることを理解した上で、 フィードバックを受け付けています。

Contribution

ID: org.eclipse.help.contributions

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

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

contributions 拡張ポイントの構成マークアップ:

    <!ELEMENT topics EMPTY>
    <!ATTLIST topics name CDATA #REQUIRED>

    <!ELEMENT actions EMPTY>
    <!ATTLIST actions name CDATA #REQUIRED>     <!ELEMENT infoset EMPTY>
    <!ATTLIST infoset 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">
 <insert from="org.eclipse.help.examples.ex1.topLevelTopics"
   to="org.eclipse.help.examples.ex1.topicsView" as="child"/>
</actions>
(ファイル topicsActions.xml)
<actions infoview="org.eclipse.help.examples.ex1.topicsView">
 <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>
 
 

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


 

非統合コンポーネント

プラグインは自動的にインストールされる場合や、 これを含むコンポーネントや製品の一部としてインストールされる場合があります。 自由なフローティング・プラグインの場合、情報セットは必ず可視にする必要があります。 トピックがより大きな Web に統合される場合は、独立した (standalone) ブックが可視にされても意味はありません。 このように非統合型、あるいは統合の度合いが緩いドキュメンテーションをサポートするため、 プラグインは情報セットおよび関連するアクションを定義して、その standalone 属性を true に設定することができます。 この結果、挿入アクションの実行は、これらのトピックが他のいずれの箇所でも提供されていない場合にのみ行われ、 情報セットは空でない場合にのみ表示されます。 アクションおよび情報セットに standalone 属性を設定することは、 ドキュメンテーションを既知の情報セットに提供することができず、 プラグイン・ドキュメンテーションが他所で可視とされているような 「キャッチ・オール (Catch all)」シナリオにおいて役立つ方法です。

ストリングの外部化

Plugin.xml ファイルは、ストリングをキー (例、%pluginName) に置き換え、 plugin.properties ファイルに次の形式のエントリーを作成して、ストリングを外部化します。
    pluginName = "Online Help Sample Plugin"
contribution XML ファイルも、同じ方法で外部化されます。 <topic id="plainTasks" label="Plain Stuff"> を外部化するには、そのラベルをキー %plainStuff に置き換えます。 トピックは次のようになります。
    <topic id="plainTasks" label="%plainStuff">
doc.properties ファイルに次のエントリーを含むエントリーを作成します。
    plainStuff = Plain Stuff
ヘルプ・システムは、オンライン・ヘルプ contribution により外部化されたストリングを参照する際に doc.properties を使用します。
 

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

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

Copyright IBM Corp. 2000, 2001.  All Rights Reserved.