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.
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.
When resolving file names, 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:
Since 3.0 release, the entire plug-in can be installed in a zipped format, and run directly from a jar. A plug-in installation 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. 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.
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.)
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="../"another_plugin_id"/ref/ref1.html"/>
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="../org.eclipse.platform.doc.isv/guide/help.html"/>
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.