SimpleHelpUI Reference 1.2.0

Purpose

The plug-in com.bdaum.simpleHelpUI is targeted towards small Rich Client Applications, where footprint is a problem. The plug-in can be used in lieue of the following plug-ins: org.eclipse.help.base, org.eclipse.help.ui, org.eclipse.help.webapp, org.eclipse.help.appserver, org.eclipse.tomcat, org.apache.lucene and org.apache.ant. This will reduce the footprint of RCP application by 5 MB+.

Requirements

org.eclipse.ui
org.eclipse.core.runtime
org.eclipse.help

Restrictions

No client/server
No active help
No Search functionality (but an indexing facility)
Only static table of contents (no folding)
No bookmarks
No user preferences

Features

Supports table of contexts (org.eclipse.help.contexts). Converts TOCs (also TOCs combined from several plug-ins) into a Html-Pages. This page contains links to the individual topics
Supports optional frameset for TOC and help content.
Supports context sensitive help in the usual way via org.eclipse.help.contexts.
Support optinal generation of a simple or grouped index.
Supports CSS style sheets for both TOC and index.
I18n support in the usual way (/nl/-folders).
Generates an index page from <meta name="keywords" ...> declarations

Configuration

The configuration is defined in preferences.ini. Five preference values are used to configure com.bdaum.simpleHelpUI:

styleSheet: This preference defines the location of a style sheet used to transform the TOC-XML into HTML. The default stylesheet is default.xsl in com.bdaum.simpleHelpUI.
tocCSS: This preference defines the location of a CSS style sheet which is passed via attribute css to the TOC transformation style sheet. The default is toc.css in com.bdaum.simpleHelpUI.
tocHtmlPage: This preference defines the location the location of the translated TOC-HTML page. If no location is defined (default), the HTML page is stored in a temporary directory. Defining a specific location required when help pages contain references to the table of contents.
frameset: Use this preference to define the location of a custom frameset. If this preference is set, you must also specify tocHtmlPage and reference the URL specified there in the TOC section of your frameset. An example frameset is supplied in framesetExample.html.
index: Use this preference to generate an index from keywords defined in the elements of the HTML pages. Values are: none, simple, grouped. The default is none.
indexStyleSheet: This preference defines the location of a style sheet used to transform the index into HTML. The default stylesheet is index.xsl in com.bdaum.simpleHelpUI.
indexCSS: This preference defines the location of a CSS style sheet which is passed via attribute css to the index transformation style sheet. The default is index.css in com.bdaum.simpleHelpUI.

These preferences can be easily overwritten by defining a file plugin_customization.ini in another plug-in:

# location of converted toc page

com.bdaum.simpleHelpUI/tocHtmlPage=myPlugin/doc/index.html

# location of frameset

com.bdaum.simpleHelpUI/frameset=myPlugin/doc/myframeset.html

# location of contents style sheet

com.bdaum.simpleHelpUI/styleSheet=myPlugin/toc.xsl

# location of contents CSS

com.bdaum.simpleHelpUI/tocCSS=myPlugin/toc.css

# index page grouped by letters

com.bdaum.simpleHelpUI/index=grouped

# location of index style sheet

com.bdaum.simpleHelpUI/indexStyleSheet=myPlugin/index.xsl

# location of index CSS

com.bdaum.simpleHelpUI/indexCSS=myPlugin/index.css

Transformation

Content tables are generated in form of an XML file. This file has the following syntax:

<!ELEMENT tocs (toc*)>
<!ATTLIST tocs
             css CDATA #IMPLIED
>
<!ELEMENT toc (topic*)>
<!ATTLIST toc
             label CDATA #REQUIRED
             href CDATA #IMPLIED
>
<!ELEMENT topic (topic*)>
<!ATTLIST topic
               label CDATA #REQUIRED
               href CDATA #IMPLIED
>

An example stylesheet transforming the format in HTML output is given in default.xsl in com.bdaum.simpleHelpUI.

Index pages are generated in form of one (simple) or several (grouped) XML files. This file has the following syntax:

<!ELEMENT index (group* | keyword*)>
<!ATTLIST index
             name CDATA #REQUIRED
	     css CDATA #IMPLIED
>
<!ELEMENT group EMPTY>
<!ATTLIST group
             name CDATA #REQUIRED
             href CDATA #REQUIRED
>
<!ELEMENT keyword (ref+)>
<!ATTLIST keyword 
             name CDATA #REQUIRED
>
<!ELEMENT ref EMPTY>
<!ATTLIST ref 
               title CDATA #REQUIRED
               href CDATA #REQUIRED
>

An example stylesheet transforming the format in HTML output is given in index.xsl in com.bdaum.simpleHelpUI.

Conversion from simpleHelpUI 1.1.0

Custom stylesheets must be modified to include the new attributes (target=) and clauses (Test for @index) defined in default.xsl.