The platform utilizes its own documentation server to provide the actual web pages for your plug-in's documentation. A custom server allows the platform to handle HTML content in a browser independent manner and to provide plug-in aware support. The main difference to you as a plug-in developer is that you have a little more flexibility in the way you structure your files and specify your links.
A documentation plug-in can run from a jar file or unpacked into plug-in directory
during installation. A plug-in archive jar is not
expanded into a plug-in directory when value of unpack attribute
of the plugin element is specified as true in the feature
manifest. In such plug-in, the documentation is compressed in the plug-in's
jar, together with other plug-in files.
In plug-ins that run unpacked, the documentation can be delivered in a zip file, avoiding problems that may result when a large number of files are present in a plug-in directory. In our example plug-in, we created a sub-directory called html. Alternatively, we could have placed our html files into a zip file called doc.zip. This zip file must mimic the file structure underneath the plug-in directory. In our case, it must contain the sub-directory html and all the contents underneath html.
Note that for plug-ins running from a jar, there is no need for documentation to be additionally contained in doc.zip, and such set-up of doc.zip in an unexploded plug-in jar is not supported by help system
When resolving file names in a plug-in that runs unpacked, the help server looks in the doc.zip file for documents before it looks in the plug-in directory itself. When used as a link, the argument in an href is assumed to be relative to the current plug-in. Consider the following link:
<topic label="Ref1" href="html/ref/ref1.html"/>
The help plug-in will look for this file as follows:
A fully qualified link can be used to refer to any content on the web.
<topic label="Ref1" href="http://www.example.com/myReference.html"/>
The platform help system uses the same national language directory lookup scheme used by the rest of the platform for finding translated files. (See Locale specific files for an explanation of this directory structure.) If you are using a doc.zip file, you should produce a doc.zip file for each locale and place it inside the correct locale directory. (You should not replicate the nl locale directory structure inside the doc.zip file.)
In addition to locale specific directories, help system checks windowing system and operating system directories when locating help resources. Look-up is performed in the following order: ws, os, nl subdirectories, then the root of the plug-in, until the resource is located. Documents, and other resource, like images which differ between system, should be placed under ws or os directories for specific platform.
The href argument can also refer to content from another plug-in. This is done by using a special cross plug-in referencing notation that is resolved by the help server:
<topic label="Ref1" href="PLUGINS_ROOT/another_plugin_id/ref/ref1.html"/>
Here PLUGINS_ROOT will be resolved at runtime and replaced with
the root directory for the plugins. You can specify your own plug-in id for
another_plugin_id. For example, you could link to this chapter
of the programmer's guide using the following topic:
<topic label="Help Chapter in Platform Doc" href="PLUGINS_ROOT/org.eclipse.platform.doc.isv/guide/help.html"/>
Prior to 3.2, references to documents in other plug-ins were made by using '..'
to go up to the plug-in level, then referencing the plug-in Id followed by the
HREF to the topic inside the plug-in. The recommended way to do this now is
to use PLUGINS_ROOT instead of '..'. Using this variable avoids
these up/down trips in references, and can be used for all the resource
URLs in the help documents (images, links, CSS files, java script files etc.)
Note: When referencing content from another plug-in, be sure to use the plug-in's id, as declared in its plugin.xml file, not its directory name. While these are often the same in practice, it's important to check that you are using the id and not the directory name.
Branding information is often placed in a plug-in defining a
product as explained in Defining a Product. Help
resources in the product plug-in can be referenced from the table of contents
or topics using special identifier PRODUCT_PLUGIN for the
plug-in ID. For example,
href="PLUGINS_ROOT/PRODUCT_PLUGIN/book.css"
refers to a style sheet residing in the plug-in for the currently running product.