プラットフォームは、独自のドキュメンテーション・サーバーを使用して、プラグインのドキュメンテーション用の実際の 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="PLUGINS_ROOT/another_plugin_id/ref/ref1.html"/>
ここで、PLUGINS_ROOT
は、ランタイム時に解決され、プラグインに応じてルート・ディレクトリーに置き換えられます。
another_plugin_id
に、ユーザー自身のプラグイン ID を指定できます。例えば、プログラマーズ・ガイドのこの章には、次のトピックを使用してリンクできます。
<topic label="Help Chapter in Platform Doc" href="PLUGINS_ROOT/org.eclipse.platform.doc.isv/guide/help.html"/>
3.2 より前は、他のプラグインの文書への参照は、プラグイン・レベルを上げるために '..' を使用して行われ、プラグイン ID の後にプラグイン内のトピックに対する HREF を指定して参照しました。現在では、'..' ではなく PLUGINS_ROOT
を使用する方法が推奨されています。この変数を使用することにより、参照においてこのようなレベル間の上下の移動を回避できます。この変数は、ヘルプ文書 (イメージ、リンク、CSS ファイル、Java スクリプト・ファイルなど) のすべてのリソース URL に使用できます。
注: 別のプラグインのコンテンツを参照する場合、ディレクトリー名ではなく、plugin.xml ファイルに宣言してあるとおりのプラグインの ID を必ず使用してください。 実際にはこれらが同じであることが多いのですが、ディレクトリー名ではなく ID を使用しているかを確認することが重要です。
「製品の定義」で説明されているように、多くの場合、製品情報が製品を定義するプラグインに配置されています。製品プラグインのヘルプ・リソースは、プラグイン ID に特殊な識別子 PRODUCT_PLUGIN
を使用して、目次またはトピックから参照することができます。以下に例を示します。
href="PLUGINS_ROOT/PRODUCT_PLUGIN/book.css"
現在実行中の製品のプラグインの中にあるスタイル・シートを参照します。