This document describes a proposal to introduce dynamic and reusable content in the Eclipse Help System pages. This support will be part of the Eclipse 3.2 release and will be introduced in M4. It is expected that apis will be finalized by M5.
With the widespread popularity of the Eclipse platform as the base for many software products and with the increasing scope of the technology behind these products, the size of the online documentation is also scaling accordingly. This puts more emphasis on supporting reusable and dynamic content in the Eclipse Help System documentation pages. The requirement is that it should be possible to reuse content, and this can be accomplished in two ways: by including content from another existing page, or by contributing content to an existing help system page. Also, conditional filtering is needed to allow for exposing only the appropriate portion of the documentation to the end user. Portions of content can be made visible to the end user based on certain filtering criteria.
As of Eclipse 3.1, Help System documents where static. They where html documents that where served statically and as-is to the Help System browser. In order to enable dynamic content manipulation Help documents, the content of these files needs to be parsed, manipulated and then served to the browser. To enable this, a new support for using XHTML documents as pages in the Help System is added.
XHTML pages are contributed and used in a TOC just like any other html page. The only difference is that the declaring plugin that hosts these pages needs to declare to the Help system that it is a special plugin and that it needs to be consulted when pages are to be served from this plugin. This is done using an existing Help System extension point called org.eclipse.help.contentProducer. The only difference is that the plugin will reuse an existing pre-supplied class that will handle all the content from this plugin, including the XHTML pages. Here is how a plugin would declare itself as a plugin that needs to serve XHTML documents:
<extension point="org.eclipse.help.contentProducer" id="some.id.dynamicContentProducer" name="XHTML content producer"> <contentProducer producer="org.eclipse.help.internal.DynamicContentProducer"> </contentProducer> </extension>
With the above declaration, a plugin can then define and contribute XHTML pages in TOCs just like any other html page. These XHTML pages can now be displayed as is, or they can be manipulated to support dynamic content and filtering. The rest of the document will describe how conditional filtering and dynamic content will be supported.
Here is how an element (for example, a paragraph) in an XHTML document can be filtered using pre-defined filtering criteria:
filtering by OS: <p filter="os=win32,linux"> This text should only show up when running on a Win32 or a Linux based operating system. Short hand version of the filter element can only be used for a single filter criteria. Colon separated values of the filter attribute represent multiple values. </p> filtering by WS: <p filter="ws=win32"> This text should only show up when running on a machine using the Windows windowing system. </p> filtering by Eclipse Category: <p filter="category=org.eclipse.categories.developmentCategory"> This text should only show up when the Development category defined in the Eclipse SDK is enabled. </p> filtering by Eclipse Activity: <p filter="activity=org.eclipse.javaDevelopment"> This text should only show up when the Java Development activity defined in the Eclipse SDK is enabled. </p> filtering based on the existance of an Eclipse Plugin: <p filter="plugin=org.eclipse.platform"> This text should only show up if the org.eclpise.platform plugin is installed and is in an active state. </p> filtering by Eclipse Product: <p filter="product=org.eclipse.platform.ide"> This text should only show up when the platform is run as a product with id org.eclipse.platform.ide. </p> note: filtering by "product" and "plugin" is not implemented in M4. Will be in M5.
<p> This text should only show up when running product org.eclipse.platform.ide on a Win32 based operating system. <filter name="os" value="win32" /> <filter name="product" value="org.eclipse.platform.ide" /> </p> <p> This text should only show up when running on a Win32 or a Linux based operating system, and when Development category defined in the Eclipse SDK is enabled. <filter name="os" value="win32,linux" /> <filter name="category" value="org.eclipse.categories.developmentCategory" /> </p> note: filtering by multiple criteria is not implemented in M4. Will be in M5.
<p> This text should only show up on Linux when the Java system property "author" has the value "john smith". <filter name="os" value="linux"/> <filter name="author" value="john smith"./> </p>
Filtering can be essential in presenting to the end user the appropriate portion of the online documentation based on a set of criteria. However, there is also a need to support dynamic content in Help pages that follows the same architecture as the platform. Instead of static pages, Help system pages become dynamic pages that are assembled at runtime into coherent pages depending on the markup used in the page. This dynamic nature can be accomplished by two concepts: including content from existing pages and contributing content to existing pages.
To support content reuse, a new Eclipse-specific element is introduced to the XHTML markup. The <include> element enables documents to be built top down. Authors "include" content from any Help document by referencing the content in the target document as follows:
<include path="plugin_id/path_to_xhtml_file/id_of_element_to_include" />
The above markup can be included in a Help document. By specifying the id of the target plugin, the target page and the target element to be included, the markup can then be resolved at runtime and the content copied into the location where this include element was inserted.
Dynamic content can also be accomplished using content contribution into existing documents. The Eclipse-specific element <anchor> enables documents to be built bottom up. A Help document can define one or more anchors to declare its willingness to accept contributions. Anchors act as place holders that declare that their location is open for content contributions. Authors subsequently "contribute" content into any Help document by referencing an anchor in that document. A new extension point is introduced for this support.
<extension point= "org.eclipse.help.contentExtension"> <contentExtension file="contentExtensionFile.xml"/> </extension>The above extension specifies the file that defines the content to be contributed and the target location of where this content needs to be inserted. The file contentExtensionFile.xml is an XML file that has the following syntax:
<contentExtension> <topicExtension content="plugin/relative/path/topicExtensionFile.xhml" path="plugin_id/path_to_xhtml_file/anchor_id"/> <topicReplace content="topicReplaceFile.xhml" path="plugin_id/path_to_xhtml_file/element_id" /> </contentExtension>
topicExtension is the markup used to insert content at the target anchor location.
topicReplace is the markup used to replace the content of the target element by the specified content. In other words, content can be contributed that either adds to the target location or replaces the content of the target location.