Installing the help system as an infocenter

You can allow your users to access the help system over the Internet or an intranet, by
installing the infocenter and the documentation plug-ins on a server. Clients view help
by navigating to a URL, and the help system is shown in their web browser. The
infocenter help system can be used both for client applications and for web
applications, either of which can have their help accessed remotely. All features
of help system except infopops and active help are supported.

The infocenter help system allows passing number of options that can be used to
customize various aspects of the infocenter. The following options are supported:

• -eclipsehome eclipseInstallPath - specifies Eclipse installation directory.
  This directory is a parent to "plugins" directory and eclipse executable.
  The option must be provided, when current directory from which infocenter
  is launched, is not the same as Eclipse installation directory.
• -data instanceArea - specifies a path that Eclipse can use to write instance data.
  The value can be an absolute path of a directory, or a path relative to Eclipse
  installation directory. The option must be provided when Eclipse is installed in
  the read only location, or has been customized to override osgi.instance.area
  or osgi.instance.area.default properties.
• -host helpServerHost - specifies host name of the interface that help server
  will use. It overrides host name specified in the application server plugin preferences.
• -port helpServerPort - specifies port number that help server will use. It overrides
  port number specified in the application server plugin preferences.
• -locales localeList - specifies a list of locales that infocenter will recognize and
  provide a customized content for. If the option is not specified, infocenter will
  build navigation, and index documents for each preferred locale of the browsers
  accessing the infocenter. When the option is present, locales from browser
  requests will be matched with locales in the list. If browser preferred locale
  does not exist in the list, but its language part does, it will be used. Subsequently,
  additional browser locales in decreased order of preference will be matched
  against the list. If none of the browser locales (or its language part) matches any
  locale on the list, the client will be served content in the default locale - server
  locale or locale passed with -nl option. For example using options

  -nl en -locales de en es fr it ja ko pt_BR zh_CN zh_TW

  will cause infocenter operating in 10 locales. All other locales will receive content
  for en locale.
• -dir rtl - sets right-to-left rendering direction of help UI in the browser.
• -noexec - indicates that Eclipse executable should not be used. You may need to use
  this option when running on a platform for which Eclipse executable is not available.
• Additionally, most options accepted by Eclipse executable can be passed. They are
  especially useful during debugging and for applying customization to Eclipse.
  For example, passing options

  -vmargs -Xmx256M 

  increases memory available to the infocenter and will allow serving a larger book collection.

Installation/packaging

These steps are for the help system integrator and are not meant to address all the possible scenarios.
 It is assumed that all your documentation is delivered as Eclipse plug-ins and, in general, you are
familiar with the eclipse help system.

1. Download the Eclipse Platform Runtime Binary driver from www.eclipse.org.
2. Install (unzip) the driver in a directory, d:\myApp. This will create an eclipse sub-directory,
   d:\myApp\eclipse that contains the code required for the Eclipse platform
   (which includes the help system).

How to start or stop infocenter from command line

The org.eclipse.help.standalone.Infocenter class has a main method that you can use to
launch infocenter from a command line. The command line arguments syntax is:

-command start | shutdown | [-eclipsehome eclipseInstallPath] 
[-data instanceArea] [-host helpServerHost] [-locales localeList] 
[-port helpServerPort] [-dir rtl] [-noexec] [platform options] 
[-vmargs JavaVMarguments]

To start an infocenter on port 8081 issue a start command by running

java -classpath d:\myApp\eclipse\plugins\org.eclipse.help.base_3.1.0.jar 
org.eclipse.help.standalone.Infocenter -command start -eclipsehome 
d:\myApp\eclipse -port 8081

To shut the infocenter down issue a shutdown command by running

java -classpath d:\myApp\eclipse\plugins\org.eclipse.help.base_3.1.0.jar 
org.eclipse.help.standalone.Infocenter -command shutdown -eclipsehome 
d:\myApp\eclipse

Using the infocenter

Start the web server. Point a web browser to the path "help" web application running on a port
specified when starting the infocenter.  On the machine the infocenter is installed, this would be
http://localhost:8081/help/.

How to start or stop infocenter from Java

When including infocenter as part of another application, it may be more convenient to start it
and stop using Java APIs instead of using system commands. Follow the steps if it is the case:

1. Make sure d:\myApp\eclipse\plugins\org.eclipse.help.base_3.1.0.jar is on your app classpath.
   The class you use to start, and shut down the infocenter isorg.eclipse.help.standalone.Infocenter.
2. Create an array of String containing options that you want to pass to the infocenter. Typically,
   the eclipsehome and port options are needed.

   String[] options = new String[] { "-eclipsehome", "d:\\myApp\\eclipse" ,
    "-port", "8081" }; 

3. In your application, create an instance of the Help class by passing the options.

   Infocenter infocenter = new Help(options); 

4. To start the help system:

   helpSystem.start();

5. To shut the infocenter down:

   helpSystem.shutdown(); 

Making infocenter available on the web

Eclipse contains a complete infocenter and does not require other server software to run.
However, in unsecure environment like Internet, it is recommended infocenter is not accessed
directly by clients, but is made available through an HTTP server or an application server.
Most servers come with modules or servlets for delegating certain request to other web
resources. For example, one may configure a proxy module of Apache HTTP Server to
redirect requests made to http://mycompany.com/myproduct/infocenter to
http://internalserver:8081/help that runs an infocenter. Adding the lines

LoadModule proxy_module modules/ApacheModuleProxy.dll
ProxyPass /myproduct/infocenter http://internalserver:8081/help
ProxyPassReverse /myproduct/infocenter http://internalserver:8081/help

to conf/httpd.conf file of Apache server running mycompany web site accomplishes this.

Some versions of Apache HTTP server, may contain AddDefaultCharset directive enabled in
configuration file. Remove the directive or replace with

AddDefaultCharset Off

to have browsers display documents using correct character set.

Running multiple instance of infocenter

Multiple instances of infocenter can be run on a machine from one installation. Each started
instance must use its own port and be provided with a workspace, hence -port and -data
options must be specified. The instances can serve documentation from different set of plug-ins,
by providing a valid platform configuration with -configuration option.

If -configuration is not used and configuration directory is shared among multiple infocenter
instances, with overlapping set of locales, it must be ensured that all search indexes are created
by one infocenter instance before another instance is started. Indexes are saved in the configuration
directory, and write access is not synchronized across infocenter processes.

[Optional] Installing a minimal set of plug-ins

The infocenter does not require the entire  Eclipse Platform package. It is possible to run the
infocenter with the following plug-ins (located in the  eclipse\plugins directory):

org.apache.lucene
org.eclipse.core.runtime
org.eclipse.help
org.eclipse.help.appserver
org.eclipse.help.base
org.eclipse.help.webapp
org.eclipse.osgi
org.eclipse.tomcat
org.eclipse.update.configurator


Some documentation plug-ins may have dependencies on other plug-ins, usually by specifying required
plug-ins in their plugin.xml. The dependent plug-ins need to be installed on the infocenter as well.
Additionally, plug-ins that were designed for earlier than 3.0 version of Eclipse implicitly require an org.eclipse.core.runtime.compatibility being present plug-in to work.

Infocenter plug-ins can be updated without restarting the infocenter, using commands explained
in Updating a running infocenter from command line topic. To use this functionality, the minimal
set of plug-ins must include org.eclipse.update.core plug-in.

See Help System Preferences for more information on customizing help system.

版权所有 罗明