プラットフォームは、独自のドキュメンテーション・サーバーを使用して、プラグインのドキュメンテーション用の実際の Web ページを提供します。 カスタム・サーバーを使用すると、プラットフォームが、ブラウザーに依存しない方法で HTML コンテンツを処理し、プラグインに対応したサポートを提供することが可能になります。 プラグイン開発者にとっての主な違いは、より柔軟な方法でファイルの構造化とリンクの指定を行うことができるところにあります。
ドキュメンテーション・プラグインは、JAR ファイル
から実行することもできますが、インストール中に
プラグイン・ディレクトリーにアンパックすることも
できます。プラグイン・アーカイブ jar は
、フィーチャー
・マニフェストで plugin
エレメントの
unpack
属性の値に true が指定されている
場合、プラグイン・ディレクトリーに展開できません。
このようなプラグインでは、文書は、他のプラグイン・ファイルと共にプラグインの jar に圧縮されます。
アンパックした状態で実行するプラグインでは、 ドキュメンテーションは Zip ファイルで提供されます。これにより、 大量のファイルがプラグイン・ディレクトリーにある 場合に発生する可能性のある問題が、回避され ます。この例のプラグインでは、html というサブディレクトリーを作成しました。 あるいは別の方法として、html ファイルを doc.zip という ZIP ファイルに挿入することもできたでしょう。 この ZIP ファイルには、プラグイン・ディレクトリーの下のファイル構造をそのまま持ち込まなければなりません。 この例では、ZIP ファイルに、サブディレクトリー html、および html の下のすべての内容 が含まれている必要があります。
jar から実行しているプラグインの場合、文書を doc.zip に入れる必要はありません。このような分解 しないプラグイン jar の doc.zip のセットアップは、 ヘルプ・システムではサポートされていことに注意して ください。
ヘルプ・サーバーは、アンパックの状態で実行する プラグインでファイル名を解決するときに、doc.zip を調べて文書を探してから、プラグイン・ディレクトリー 自体を調べます。 href 内の引数は、リンクとして使用した 場合、現在のプラグインを基準にしたものと想定されます。 以下のリンクについて考えてみましょう。
<topic label="Ref1" href="html/ref/ref1.html"/>
ヘルプ・プラグインは、このファイルを以下のようにして探します。
Web 上のコンテンツを参照するためには、完全修飾リンクを使用できます。
<topic label="Ref1" href="http://www.example.com/myReference.html"/>
プラットフォーム・ヘルプ・システムは、翻訳済みファイルを検索するため、 プラットフォームのその他の部分によって使用されるものと同じ各国語ディレクトリー・ルックアップ方式を使用します。 (このディレクトリー構造の説明については、『ロケール特定ファイル』を参照してください。) doc.zip ファイルを使用する場合、ロケールごとに doc.zip ファイルを生成して、それを正しいロケール・ディレクトリーに置かなければなりません。 (doc.zip ファイル内に nl ロケール・ディレクトリー構造を複製することはできません。)
ヘルプ・システムは、ヘルプ・リソースを見つける 際に、ロケール固有のディレクトリーに加えて、ウィンドウ操作 システム・ディレクトリーとオペレーティング・ システム・ディレクトリーをチェックします。検索は 、ws、os、nl の各サブディレクトリー、プラグインのルートの順 で、リソースが見つかるまで実行されます。文書、 およびシステム間で異なるイメージなどの他のリソースは 、特定のプラットフォームの ws または os の ディレクトリーに配置されています。
href 引数も、別のプラグインのコンテンツを参照できます。 これは、ヘルプ・サーバーによって解決される次のような特殊なプラグイン間参照表記を使用して行われます。
<topic label="Ref1" href="../"another_plugin_id"/ref/ref1.html"/>
例えば、プログラマーズ・ガイドのこの章には、次のトピックを使用してリンクできます。
<topic label="Help Chapter in Platform Doc" href="../org.eclipse.platform.doc.isv/guide/help.html"/>
注: 別のプラグインのコンテンツを参照する場合、ディレクトリー名ではなく、plugin.xml ファイルに宣言してあるとおりのプラグインの ID を必ず使用してください。 実際にはこれらが同じであることが多いのですが、ディレクトリー名ではなく ID を使用しているかを確認することが重要です。
「製品の定義」 で説明されているように、多くの場合、製品情報が製品を定義する プラグインに配置されています。製品 プラグインのヘルプ・リソースは、プラグイン ID の 特別な識別子「PRODUCT_PLUGIN」を使用して、目次または トピックから参照することができます。例えば、以下の ようになります。
href="../PRODUCT_PLUGIN/book.css"
現在実行中の製品のプラグインの中にある スタイル・シートを参照します。