Proposal: Platform Specific Documentation


The documentation in Eclipse currently lacks the ability for ISVs to override widget set specific screenshots and lacks the ability to turn off or override platform specific content. This proposal attempts to address these issues by adding support for resource overriding to the help system and by adding CSS class tags documentation with platform specific content.


A complete solution would satisfy the following requirements:

  1. Replaceable resources (screenshots, HTML files and CSS files)
  2. Control over the display of platform specific content
  3. The solution should allow the documentation to be customized without the need to modify the base documentation plug-ins


Replaceable Resources - Screenshots and HTML files

To allow ISVs the ability to provide their own platform / widget set specific resources in a custom fragment, the search path for resources in a documentation plug-in needs to be expanded. Currently, only the $nl$ directories are searched. The proposed search path adds widget set (ws) and operating system (os) to the existing natural language (nl) search path. An ISV can override files by contributing a fragment containing the files which need to be overridden in the correct directory. The search order will be ws, then os and finally nl. Compressed files in "" will continue to be searched before files that are not compressed.

As an example, the search path for zh_CN locale with gtk widget set on Linux would be:

This allows widget set and operating system specific documentation to be contributed (in fragments) and displayed without altering the existing doc plug-ins. If no fragment is installed the end result would be exactly the same as it is in the current help system. To accomplish this, the help system will have to use the system's nl, ws, and os settings to explicitly search the possible paths for the file. The use of $nl$, $ws$, and $os$, accepted by the Platform.find() API, must be avoided in the help system to ensure the root directory is not searched to early (or multiple times).

This solution allows ISVs to have a documentation fragment that contains either resources from a single language with multiple widget sets / operating systems or resources from the same widget set or operating system with different languages. The solution does not allow for all permutations of language, operating system and widget set to be placed in one fragment - separate fragments would still be required. For example, an ISV could make a fragment that has gtk-English and gtk-Chinese resources by placing the resources in the appropriate nl folders. In a separate fragment, this ISV could also support carbon-English and gtk-English by placing the files in the appropriate ws directory. This lack of support for all permutations is not problematic as this requirement is relatively rare and if the need should arise, there is a way to handle it. It should be noted that the Eclipse SDK language pack does not contain language specific screenshots.

Control Over The Display of Platform Specific Content

The current documentation in Eclipse SDK has a mix of both platform and widget set specific content. This content will be marked with appropriate CSS classes to give ISVs control over which of the platform and / or widget set specific content is displayed. The information described below is currently a draft of the final solution. The documentation from will be marked up over the next little while to test if this solution will work. There may be some minor changes.

Platform specific content will be marked with either:

Widget Set specific content will be marked with these:

The idea is that content common to most supported platforms and widget sets falls under the default category. This designation has nothing to do with the popularity of a given platform. Content specific to just a few platforms and widgets sets is tagged with the appropriate CSS classes described above. So far we have identified that only win32, gtk, and carbon classes are needed to differentiate content that is not common to all. The set of classes can be expanded if the need arises.

The CSS file will reside in the root of product plug-in (PRODUCT_PLUGIN/book.css). References to this CSS file will be prefixed with PRODUCT_PLUGIN in the HTML of all the documentation. This allows ISVs to override the default CSS file with a custom CSS file in the root of their branding plug-in. This CSS file would specify which platforms and widget sets should not be displayed.

The Eclipse SDK will ship with its CSS file in org.eclipse.platform/book.css, and this will call a bookos.css file that sets default_os, win32, default_ws, gtk, and carbon off (the remaining class, all_os_ws remains on).

ISVs can also achieve automatic selection of marked up content with multiple style sheets read by the help system; which CSS files are used is determined by the system settings. In this case the branding plug-in will have a book.css file and one or two additional CSS files, one to disable all but particular platform-specific content, and optionally a second to disable all but particular widget-set specific content. The help system resource resolution will apply the appropriate CSS files to the product (branding) plug-in.

Path namesHelp Keyall_os_ws
Linux Gtkoffononoffoffoff
Linux Otheroffonoffoffonoff
Unix Gtkoffononoffoffoff
Unix Otheroffonoffoffonoff

The directory structure is as follows:

The book.css for each of the cases noted above imports a single bookos.css file, because these cases have operating systems that imply the widget set, or a widget set that implies the operating system. An ISV that wants to release a version of Eclipse that runs under Windows, Unix gtk and some other Unix widget set would need to call a book.css that imports a bookos.css (which would disable either win32 or default_os) and a bookws (which would disable all_os_ws, carbon, and either gtk or default_ws).

Sample CSS files will be part of this solution so that ISVs can easily achieve this automatic selection.

All of this means that the documentation must be written in such a way that it makes sense both when the all_os_ws content is displayed and when only one class of content is displayed. Therefore the source HTML files will have duplicated content, but the help browser will show only the content that is appropriate for the user. This point will be stressed in the documentation style guide and an example will be given.

Solution Should Allow Customization Without Modification To The Doc Plug-ins

This solution allows the documentation to be customized without modification.


This section describes some of the issues that were encountered and possible solutions to these issues.

PDF Generation

Currently, the SDK PDFs on are generated with htmldoc which does not support CSS. This does not pose a problem for Eclipse SDK PDFs because they will be displaying content for all platforms. This will, however, pose a problem for ISVs who wish to generate PDFs that display content for only one platform and/or widget set.

A solution to this is to use fully validating XHTML for all of the documentation in the Eclipse SDK. This allows ISVs to convert to other formats by writing an XSLT style-sheet and/or by using one of the plethora of XML conversion tools that exist.

Unfortunately, certain doctypes (XHTML) are not properly supported in Internet Explorer and cause an unneeded scrollbar to appear, therefore this remains an outstanding issue.


The searching mechanism in the help system currently doesn't support CSS and thus a user will get inaccurate search results if an ISV chooses to hide some platform or widget set specific content. The easiest solution is to add rudimentary CSS support to the help system. The plan is to add support for only the CSS tags that are described in this document.

Remote Info Centres

By default, the Eclipse SDK will show content for all platforms and widget sets. If an administrator wishes to change this, they can add a custom branding plug-in, or fragments to the existing branding plug-in, to override the default CSS file. The administrator can also add fragments to the documentation with platform and widget set specific screenshots and HTML files.  As part of this proposal, we will add support for command line parameters that can override actual OS and WS of the system hosting the info center.



This proposal can be mostly blamed on Michael Behm, Konrad Kolosowski, Ben Konrath and Jeff Pound