平台利用它自己的文档服务器来为插件文档提供实际的 Web 页面。定制服务器允许平台以独立于浏览器的方式来处理 HTML 内容和提供插件所需的支持。对于作为插件开发者的您来说,主要的区别就是您在构造文件和指定链接的方式上将具有更大的灵活性。
在安装期间,可以从 jar 文件中运行文档插件或将其解压缩到插件目录中。如果在功能部件清单中将
plugin
元素的 unpack
属性值指定为 true,则插件归档
JAR 不会在插件目录中展开。在这种插件中,文档是在插件的 JAR 中与其它插件文件一起压缩的。
在以不解压缩方式运行的插件中,可以用压缩文件来交付文档,从而避免在插件目录中提供大量文件时可能导致的问题。在示例插件中,创建了一个称为 html 的子目录。或者,我们可能已经将 HTML 文件放入称为 doc.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 文件中所声明的),而不是目录名。由于实际情况下它们通常是相同的,因此检查您在使用标识而不是目录名很重要。
品牌信息通常放在用于定义产品的插件中,如定义产品所述。通过使用特殊标识“PRODUCT_PLUGIN”作为插件标识,可以从目录或主题中引用产品插件中的帮助资源。例如,
href="../PRODUCT_PLUGIN/book.css"
引用驻留在当前正在运行的产品的插件中的样式表。