## Help system customization

The Eclipse help system can be configured and branded to suit your product by specifying custom defaults for number of help preferences.

The Help system itself is divided up into a number of separate plug-ins. These tables shows available preferences, and which plug-in defines them.

### org.eclipse.help plug-in:

Preference key | Usage | Default

`HELP_DATA`

Specifies the path of an XML file containing help data, such as the order in which the table of contents should be displayed, and which books and index contributions should be hidden from the user. The path may either be of the form PLUGINS_ROOT/ pluginId/path or "path". If the value does not start with PLUGINS_ROOT the path is resolved relative to the product plugin. For example, "`helpData.xml`" or "PLUGINS_ROOT/org.eclipse.platform/helpData.xml". Consult the schema documentation for details.

`baseTOCS` (deprecated; use `HELP_DATA` instead) | Toc ordering. Ordered list of help TOC's (books) or TOC categories as they would appear on the bookshelf. All the other TOCS and categories will follow these. Non-present TOCs or categories on this list will be ignored. For TOCs, use the location of the TOC as /pluginId/path/to/toc.xml. For categories, use the category id. |

`ignoredTOCS` (deprecated; use `HELP_DATA` instead)

Disabling TOCs. List of help TOCs (books) or TOC categories that will be ignored by the help system. The disabled TOCs/categories will not appear in the list of books, cannot be linked. Topics defined by disabled TOCs will not be available from search. Non-present TOCs or categories in this list will be ignored. For TOCs, use the location of the TOC as /pluginId/path/to/toc.xml. For categories, use the category id.

`ignoredIndexes` (deprecated; use `HELP_DATA` instead) | Disabling keyword indexes. List of help keyword index contributions that will be ignored by the help system. Keywords from the disabled indexes will not appear in the index view. For index XML files, use the path to the file in the form /pluginId/path/to/index.xml. |

### org.eclipse.help.base plug-in:

Preference key | Usage | Default
`banner` | Location of the banner page to display in the top frame Example: `banner=/org.eclipse.help.webapp/advanced/banner.html` |
`banner_height` | Height of the banner frame Example: `banner_height=60` |
`titleResource` | The name of a project resource of the form <plugin_name>/<resource_name> which contains the title of the help page. Example: `titleResource=org.eclipse.help.webapp/help_webapp_plugin_name` |
`help_home` | The page to show in the content area when opening help. Specify your html page as `/pluginId/path/to/home.html`. | `/org.eclipse.help.base/doc/help_home.html`
`page_not_found` | The page to show in the content area when a topic file cannot be opened. If this variable is not specified the browser will show it's default 404 error page. | `/org.eclipse.help.base/doc/page_not_found.html`
`showBreadcrumbs` | Set to `true` or `false` to control the visibility of breadcrumbs. | `true`
`bookmarksView` | Set to `true` or `false` to control the visibility of the bookmarks view. Note: this option has no effect in the infocenter. | `true`
`indexView` | Set to `true` or `false` to control the visibility of the index view. | `true`
`windowTitlePrefix` | Set to `true` or `false` to control the title of the browser window. If `true`, the title will have a form "Help - `<PRODUCT_NAME>`", otherwise the title will be "`<PRODUCT_NAME>`", where `<PRODUCT_NAME>` is the name of Eclipse product set in the primary feature. | `true`
`imagesDirectory` | Directory containing images used in the help view. Images must have the same name as those in the org.eclipse.help.webapp plug-in. Use the `/pluginID/directory` format. | `images`
`advanced.toolbarBackground` | CSS background for toolbars. Value is used in browsers that display advanced help UI. | `ButtonFace`
`advanced.viewBackground` | CSS background for navigation views. Value is used in browsers that display advanced help UI. May be the empty string. |
`advanced.toolbarFont` | CSS font for toolbars. Value is used in browsers that display advanced help UI. | `icon`
`advanced.viewFont` | CSS font for navigation views. Value is used in browsers that display advanced help UI. | `icon`
`advanced.syncDefault` | The default boolean value for whether the toc should automatically be synchronized with the contents. | `true`
`basic.toolbarBackground` | Background color for toolbars. Value is used in browsers displaying basic help UI. | `#D4D0C8`
`basic.viewBackground` | Background color for navigation views. Value is used in browsers displaying basic help UI. | `#FFFFFF`

`locales`

List of locales that infocenter will recognize and provide a customized content for; if locales (or languages) accepted by client browser are not matched with any locales in this list, the browser will be served content for default locale - the server locale, or locale specified by eclipse `-nl` command line option; if list is not specified, the browser will be served contents for its preferred locale; note: not providing this option may result in a large memory and disk space requirements as navigations and indexes will be created for each distinct preferred locale among browsers accessing the infocenter.
Example: `locales=en ja zh_CN zh_TW`

`productIndex` | If per-product, pre-built documentation index is provided with the product, the ID of the plug-in delivering the index must be specified to the help system here. |
`always_external_browser` | Use embedded when possible (on Windows or Linux), or always external. Setting to true will force use of external browser. Option has no effect if embedded browser is not available on a given platform. | `false`

`default_browser`

Default external browser. ID of one of the external web browsers contributed to org.eclipse.help.base.browser extension point that help system will use. The browser's adapter `available()` method must return true on the current system.

This preference controls external browsers in stand-alone help mode. In the workbench mode, help uses browsers provided by workbench browser support.

default dynamically set based on the browser available on a given system

`custom_browser_path` | Executable path for custom browser This preference controls external browsers in stand-alone help mode. In the workbench mode, help uses browsers provided by workbench browser support. | `C:\Program Files\Internet Explorer\IEXPLORE.EXE" %1` - on Windows, `"konqueror %1"` - on Linux `"mozilla %1"` - on other platforms

`showDisabledActivityTopics`

Help system filters topics from disabled capabilities. This option controls this behavior and existence of Show All Topics button.
Accepted values: `never`, `off`, `on`, `always`
`never` - topic from disabled capabilities are not shown
`off` - user can choose to show all topics, disabled topics initially hidden
`on` - user can choose to show all topics, all topics initially shown
`always` - topic from disabled capabilities are shown (filtering disabled)

`off`

`activeHelp` | Allows enabling and disabling execution of active help. The option has no effect in the infocenter setup, where active help is disabled. Accepted values: `true` - default active help actions enabled `false` - active help framework disabled | `true`
`restrictTopicParameter` | Since 3.4. When true prevents topic parameters with an http or other protocol from causing an external URL to open in the content frame of the infocenter. This improves security and the recommended setting is true. | `true`
`window_infopop` | Allows enabling the old-style infopops when help key is pressed in workbench windows. If false, the new dynamic help view will open instead. | `false`
`dialog_infopop` | Allows enabling the old-style infopops when help key is pressed in dialogs. If false, the new dynamic help window will open instead. | `false`
help_view_open_mode | Controls where links in the help view are opened. Accepted values: `in_place` - open documents in the help view `in_editor` - open document in an editor `in_browser` - open document in a browser | in_place
`remoteHelpOn` | Controls whether or not remote help is enabled. Accepted values: `true` - remote help enabled `false` - remote help disabled | `false`
The 5 remote help preferences below can each have multiple comma separated values if there is more than one infocenter contributing remote content.
remoteHostName | Specifies a name for this remote host which will appear in the table on the preference page |
`remoteHelpHost` | Specifies the host name to access for remote help content. This must be specified as a host name and cannot be a URL (i.e. do not include "http://"). |
`remoteHelpPath` | Specifies the context root of the Infocenter application running on the specified host. |
`remoteHelpPort` | Specifies the port to use to access remote help content. |
remoteHelpICEnabled | Specifies that the infocenter will contribute remote content |

The four css preferences allow for the control of page appearance by inserting css files into every page served by the help server. Each can each contain zero or more comma separated paths of the form /plugin/path. These paths should contain only ASCII characters.
If a path contains ${os} then that will be replaced with the name of the OS, any other parameters of the form ${parameter} are reserved for future use.

`topic_css` | A list of css file(s) to include in every non navigation page served by help system. |
`nav_css` | A list of css file(s) to include in every navigation page served by help system | `/PRODUCT_PLUGIN/book.css`
`narrow_css` | A list of css file(s) to include in every page displayed in the help view or help tray . | `/PRODUCT_PLUGIN/narrow_book.css,/PRODUCT_PLUGIN/${os}_narrow_book.css`
`disabled_css` | A list of css file(s) to include in every page served by help system from a capability that is not enabled.. | `/PRODUCT_PLUGIN/disabled_book.css`

### org.eclipse.help.appserver plug-in:

Deprecated: This plug-in is no longer used by help. See table for alternative usage.

Preference key | Usage | Default
`port` (deprecated) | The port number on which the sever listens for http requests. If port is not given, an arbitrary port is picked by the system. Start Eclipse with "-vmargs -Dserver_port=<port>" instead |

`host` (deprecated)

The host address or name to use for connecting to the server. The default is nothing, and eclipse will pick up an available local address.

Products using help in local mode (workbench or stand-alone, not infocenter), can set this preference to "`127.0.0.1`" to ensure help server is not exposed to other users on the network.

Start Eclipse with "-vmargs -Dserver_host=<host>" instead

### org.eclipse.tomcat plug-in:

Deprecated: This plug-in is no longer used by help. No alternative commands available.

Preference key | Usage | Default
`acceptCount` (deprecated) | The maximum queue length for incoming connection requests when all possible request processing threads are in use. Any requests received when the queue is full will be refused. | `100`
`maxProcessors` (deprecated) | The maximum number of request processing threads to be created by this Connector, which therefore determines the maximum number of simultaneous requests that can be handled. | `75`
`minProcessors` (deprecated) | The number of request processing threads that will be created when this Connector is first started. This attribute should be set to a value smaller than that set for maxProcessors. | `5`