bundles/org.eclipse.platform.doc.isv/guide/ua_help_setup_infocenter.htm - gerrit/platform/eclipse.platform.common - Git at Google

 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
 <html lang="en">
 <head>
 <meta name="copyright" content="Copyright (c) IBM Corporation and others 2000, 2011. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." >
 <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
 <meta http-equiv="Content-Style-Type" content="text/css">
 <link rel="STYLESHEET" href="../book.css" charset="ISO-8859-1" type="text/css">
 <script language="JavaScript" src="PLUGINS_ROOT/org.eclipse.help/livehelp.js" type="text/javascript"></script>
 <title>Information Center</title>
 </head>
 <body>

 <h2>Information Center</h2>

 <p>
 You can allow your users to access the help system over the Internet or an
 intranet by installing an information center 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 information center help system can be used for both client
 and web applications, either of which can have their help accessed remotely.
 All features of help system except context help, active help, command support,
 and the help view are supported.
 </p>

 <p>
 The information center help system allows passing number of options that can be used to
 customize various aspects of the information center. The following options are
 supported:
 </p>

 <ul>
 	<li>
 	<strong>-eclipsehome</strong> <em>eclipseInstallPath</em> - specifies
 	the Eclipse installation directory. This directory is the parent of the
 	plugins directory and Eclipse executable. The option must be provided when
 	the current directory from which the information center is launched is not the same
 	as the Eclipse installation	directory.
 	</li>

 	<li>
 	<strong>-data</strong> <em>instanceArea</em> - specifies a path that Eclipse
 	can use to write instance data. The value can be the absolute path of a
 	directory or a path relative to Eclipse installation directory. The option
 	must be provided when Eclipse is installed in a read only location, or has
 	been customized to override the <code>osgi.instance.area</code> or <code>
 	osgi.instance.area.default</code> properties.
 	</li>

 	<li>
 	<strong>-host</strong> <em>helpServerHost</em> - specifies the host name of
 	the	interface that the help server will use. This overrides the host name
 	specified in the application server plugin preferences.
 	</li>

 	<li>
 	<strong>-port</strong> <em>helpServerPort</em> - specifies the port number
 	that the help server will use. This overrides the port number specified in
 	the	application server plugin preferences.
 	</li>

 	<li>
 	<strong>-locales</strong> <em>localeList</em> - specifies a list of locales
 	that the information center	will recognize and provide customized content for. If
 	the option is not specified, the information center will build navigation and index
 	documents for each preferred locale of the browsers accessing the
 	information center. When the option is present, locales from browser requests will
 	be matched with locales in the list. If no browser preferred locale exists
 	in the list, but its language part does, it will be used instead.
 	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) match 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 <code>-nl en -locales de en es fr it ja
 	ko pt_BR zh_CN zh_TW</code> will cause the information center to operate in 10 locales.
 	All	other locales will receive content from the <code>en</code> locale.
 	</li>

 	<li>
 	<strong>-dir ltr</strong> or <strong>-dir rtl</strong> - forces
 	left-to-right or right-to-left rendering direction of the help UI in the
 	browser for all languages. By default, the direction is determined by the
 	browser locale.
 	</li>

 	<li>
 	<strong>-noexec</strong> - indicates that the Eclipse executable should not
 	be used. You need to use this option when running on a platform for which
 	the Eclipse executable is not available.
 	</li>

 	<li>
 	Additionally, most
 	<a href="../../org.eclipse.platform.doc.user/tasks/running_eclipse.htm">
 	options accepted by the Eclipse executable</a> are allowed. They are
 	especially useful during debugging and for applying customization to
 	Eclipse. For example, passing options <code>-vmargs -Xmx256M</code>
 	increases memory available to the information center and will allow serving of a
 	larger book collection.
 	</li>
 </ul>

 <h3>Installation/packaging</h3>

 <p>
 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.
 </p>

 <ol>
 	<li>
 	Download the Eclipse Platform Runtime Binary driver from
 	<a target="_blank" href="http://www.eclipse.org/downloads/">eclipse.org</a>.
 	</li>

 	<li>
 	Install (unzip) the driver in a directory, say <code>d:\myApp</code>. This
 	will create an eclipse sub-directory, <code>d:\myApp\eclipse</code> that
 	contains the code required for the Eclipse platform (which includes the
 	help system).
 	</li>
 </ol>

 <h3>How to start or stop information center from command line</h3>

 <p>
 The <code>org.eclipse.help.standalone.Infocenter</code> class has a <code>
 main()</code> method that you can use to launch the information center from the command
 line. The command line argument syntax is:
 </p>

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

 <p>
 To start an information center on port 8081, issue a <code>start</code> command by running
 </p>

 <pre>java -classpath d:\myApp\eclipse\plugins\org.eclipse.help.base_[version].jar org.eclipse.help.standalone.Infocenter -command start -eclipsehome d:\myApp\eclipse -port 8081</pre>

 <p>
 To shut down the information center issue a <code>shutdown</code> command by running
 </p>

 <pre>java -classpath d:\myApp\eclipse\plugins\org.eclipse.help.base_[version].jar org.eclipse.help.standalone.Infocenter -command shutdown -eclipsehome d:\myApp\eclipse</pre>

 <h3>Using the information center</h3>

 <p>
 Start the information center using the instructions above. Point a web browser to the
 &quot;/help/index.jsp&quot; starting point for the Web application running on
 the port specified when starting the information center (e.g. 8081). For example, from
 the machine on which the information center is installed, this would be
 <code>http://localhost:8081/help/index.jsp</code>.
 </p>

 <h3>How to start and stop an information center from Java</h3>

 <p>
 When including an information center as part of another application, it may be more
 convenient to start it and stop it using Java API calls instead of system
 commands. If this is the case, follow the steps:
 </p>

 <ol>
 	<li>
 	Make sure <code>d:\myApp\eclipse\plugins\org.eclipse.help.base_[version].jar
 	</code> is on your application's classpath. The class you use to start and
 	shut down the information center is <code>org.eclipse.help.standalone.Infocenter
 	</code>.
 	</li>

 	<li>
 	Create an array of <code>String</code> objects containing options that you
 	want to pass to the information center. Typically, the <code>eclipsehome</code> and
 	<code>port</code> options are needed.
 	<pre>String[] options = new String[] { &quot;-eclipsehome&quot;, &quot;d:\\myApp\\eclipse&quot; , &quot;-port&quot;, &quot;8081&quot; };</pre>
 	</li>

 	<li>
 	In your application, create an instance of the <code>Help</code> class by
 	passing in the options.
 	<pre>Infocenter infocenter = new Infocenter(options);</pre>
 	</li>

 	<li>
 	To start the help system:
 	<pre>infocenter.start();</pre>
 	</li>

 	<li>
 	To shut down the information center:
 	<pre>infocenter.shutdown();</pre>
 	</li>
 </ol>

 <h3>Making information center available on the web</h3>

 <p>
 Eclipse contains a complete information center and does not require any other server
 software to run. However, in an unsecure environment like the Internet, it is
 not recommended to allow direct access by the clients, but instead 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, you can configure a proxy module of the Apache HTTP Server to
 redirect requests made to <code>http://mycompany.com/myproduct/infocenter</code>
 to <code>http://internalserver:8081/help</code> that runs an information center. Adding
 the lines
 </p>

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

 <p>
 to the <code>conf/httpd.conf</code> file of Apache server running the mycompany
 web site accomplishes this.
 </p>

 <p>
 Some versions of the Apache HTTP server may contain an AddDefaultCharset
 directive enabled in configuration file. Remove the directive or replace it with
 </p>

 <pre>AddDefaultCharset Off</pre>

 <p>
 to have browsers display documents using correct character set.
 </p>

 <h3>Running multiple instances of an information center</h3>

 <p>
 Multiple instances of an information center can be run on a machine from one
 installation. Each started instance must use its own port and must be provided
 with a workspace, hence the <code>-port</code> and <code>-data</code> options
 must be specified. The instances can serve documentation from different sets of
 plug-ins by providing a valid platform configuration with the
 <code>-configuration</code> option.
 </p>

 <p>
 If <code>-configuration</code> is not used and the configuration directory is
 shared among multiple information center instances with overlapping sets of locales,
 you must be ensure that all search indexes are created by one information center
 instance before another instance is started. Indexes are saved in the
 configuration directory, and write access is not synchronized across information center
 instances.
 </p>

 <h3>Filtering</h3>

 <p>
 <a href="ua_dynamic_filters.htm">Filtering</a> support is turned
 <strong>off</strong> when running in information center mode, causing all content,
 including filtered content, to be visible. If you intent to host your
 documentation in both workbench and information center modes, you should use filters in
 a way that makes sense even if filtering is turned off.
 </p>

 <p>
 Some documentation plug-ins may have dependencies on other plug-ins, usually by
 specifying the required plug-ins in their bundle manifest. The dependent
 plug-ins need to be installed on the information center as well.
 </p>

 <p>
 See the <a href="ua_help_setup_preferences.htm">Product customization</a>
 topic for more information on customizing the help system.
 </p>

 </body>
 </html>
	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
	<html lang="en">
	<head>
	<meta name="copyright" content="Copyright (c) IBM Corporation and others 2000, 2011. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." >
	<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
	<meta http-equiv="Content-Style-Type" content="text/css">
	<link rel="STYLESHEET" href="../book.css" charset="ISO-8859-1" type="text/css">
	<script language="JavaScript" src="PLUGINS_ROOT/org.eclipse.help/livehelp.js" type="text/javascript"></script>
	<title>Information Center</title>
	</head>
	<body>

	<h2>Information Center</h2>

	<p>
	You can allow your users to access the help system over the Internet or an
	intranet by installing an information center 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 information center help system can be used for both client
	and web applications, either of which can have their help accessed remotely.
	All features of help system except context help, active help, command support,
	and the help view are supported.
	</p>

	<p>
	The information center help system allows passing number of options that can be used to
	customize various aspects of the information center. The following options are
	supported:
	</p>

	<ul>
	<li>
	<strong>-eclipsehome</strong> <em>eclipseInstallPath</em> - specifies
	the Eclipse installation directory. This directory is the parent of the
	plugins directory and Eclipse executable. The option must be provided when
	the current directory from which the information center is launched is not the same
	as the Eclipse installation directory.
	</li>

	<li>
	<strong>-data</strong> <em>instanceArea</em> - specifies a path that Eclipse
	can use to write instance data. The value can be the absolute path of a
	directory or a path relative to Eclipse installation directory. The option
	must be provided when Eclipse is installed in a read only location, or has
	been customized to override the <code>osgi.instance.area</code> or <code>
	osgi.instance.area.default</code> properties.
	</li>

	<li>
	<strong>-host</strong> <em>helpServerHost</em> - specifies the host name of
	the interface that the help server will use. This overrides the host name
	specified in the application server plugin preferences.
	</li>

	<li>
	<strong>-port</strong> <em>helpServerPort</em> - specifies the port number
	that the help server will use. This overrides the port number specified in
	the application server plugin preferences.
	</li>

	<li>
	<strong>-locales</strong> <em>localeList</em> - specifies a list of locales
	that the information center will recognize and provide customized content for. If
	the option is not specified, the information center will build navigation and index
	documents for each preferred locale of the browsers accessing the
	information center. When the option is present, locales from browser requests will
	be matched with locales in the list. If no browser preferred locale exists
	in the list, but its language part does, it will be used instead.
	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) match 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 <code>-nl en -locales de en es fr it ja
	ko pt_BR zh_CN zh_TW</code> will cause the information center to operate in 10 locales.
	All other locales will receive content from the <code>en</code> locale.
	</li>

	<li>
	<strong>-dir ltr</strong> or <strong>-dir rtl</strong> - forces
	left-to-right or right-to-left rendering direction of the help UI in the
	browser for all languages. By default, the direction is determined by the
	browser locale.
	</li>

	<li>
	<strong>-noexec</strong> - indicates that the Eclipse executable should not
	be used. You need to use this option when running on a platform for which
	the Eclipse executable is not available.
	</li>

	<li>
	Additionally, most
	<a href="../../org.eclipse.platform.doc.user/tasks/running_eclipse.htm">
	options accepted by the Eclipse executable</a> are allowed. They are
	especially useful during debugging and for applying customization to
	Eclipse. For example, passing options <code>-vmargs -Xmx256M</code>
	increases memory available to the information center and will allow serving of a
	larger book collection.
	</li>
	</ul>

	<h3>Installation/packaging</h3>

	<p>
	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.
	</p>

	<ol>
	<li>
	Download the Eclipse Platform Runtime Binary driver from
	<a target="_blank" href="http://www.eclipse.org/downloads/">eclipse.org</a>.
	</li>

	<li>
	Install (unzip) the driver in a directory, say <code>d:\myApp</code>. This
	will create an eclipse sub-directory, <code>d:\myApp\eclipse</code> that
	contains the code required for the Eclipse platform (which includes the
	help system).
	</li>
	</ol>

	<h3>How to start or stop information center from command line</h3>

	<p>
	The <code>org.eclipse.help.standalone.Infocenter</code> class has a <code>
	main()</code> method that you can use to launch the information center from the command
	line. The command line argument syntax is:
	</p>

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

	<p>
	To start an information center on port 8081, issue a <code>start</code> command by running
	</p>

	<pre>java -classpath d:\myApp\eclipse\plugins\org.eclipse.help.base_[version].jar org.eclipse.help.standalone.Infocenter -command start -eclipsehome d:\myApp\eclipse -port 8081</pre>

	<p>
	To shut down the information center issue a <code>shutdown</code> command by running
	</p>

	<pre>java -classpath d:\myApp\eclipse\plugins\org.eclipse.help.base_[version].jar org.eclipse.help.standalone.Infocenter -command shutdown -eclipsehome d:\myApp\eclipse</pre>

	<h3>Using the information center</h3>

	<p>
	Start the information center using the instructions above. Point a web browser to the
	"/help/index.jsp" starting point for the Web application running on
	the port specified when starting the information center (e.g. 8081). For example, from
	the machine on which the information center is installed, this would be
	<code>http://localhost:8081/help/index.jsp</code>.
	</p>

	<h3>How to start and stop an information center from Java</h3>

	<p>
	When including an information center as part of another application, it may be more
	convenient to start it and stop it using Java API calls instead of system
	commands. If this is the case, follow the steps:
	</p>

	<ol>
	<li>
	Make sure <code>d:\myApp\eclipse\plugins\org.eclipse.help.base_[version].jar
	</code> is on your application's classpath. The class you use to start and
	shut down the information center is <code>org.eclipse.help.standalone.Infocenter
	</code>.
	</li>

	<li>
	Create an array of <code>String</code> objects containing options that you
	want to pass to the information center. Typically, the <code>eclipsehome</code> and
	<code>port</code> options are needed.
	<pre>String[] options = new String[] { "-eclipsehome", "d:\\myApp\\eclipse" , "-port", "8081" };</pre>
	</li>

	<li>
	In your application, create an instance of the <code>Help</code> class by
	passing in the options.
	<pre>Infocenter infocenter = new Infocenter(options);</pre>
	</li>

	<li>
	To start the help system:
	<pre>infocenter.start();</pre>
	</li>

	<li>
	To shut down the information center:
	<pre>infocenter.shutdown();</pre>
	</li>
	</ol>

	<h3>Making information center available on the web</h3>

	<p>
	Eclipse contains a complete information center and does not require any other server
	software to run. However, in an unsecure environment like the Internet, it is
	not recommended to allow direct access by the clients, but instead 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, you can configure a proxy module of the Apache HTTP Server to
	redirect requests made to <code>http://mycompany.com/myproduct/infocenter</code>
	to <code>http://internalserver:8081/help</code> that runs an information center. Adding
	the lines
	</p>

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

	<p>
	to the <code>conf/httpd.conf</code> file of Apache server running the mycompany
	web site accomplishes this.
	</p>

	<p>
	Some versions of the Apache HTTP server may contain an AddDefaultCharset
	directive enabled in configuration file. Remove the directive or replace it with
	</p>

	<pre>AddDefaultCharset Off</pre>

	<p>
	to have browsers display documents using correct character set.
	</p>

	<h3>Running multiple instances of an information center</h3>

	<p>
	Multiple instances of an information center can be run on a machine from one
	installation. Each started instance must use its own port and must be provided
	with a workspace, hence the <code>-port</code> and <code>-data</code> options
	must be specified. The instances can serve documentation from different sets of
	plug-ins by providing a valid platform configuration with the
	<code>-configuration</code> option.
	</p>

	<p>
	If <code>-configuration</code> is not used and the configuration directory is
	shared among multiple information center instances with overlapping sets of locales,
	you must be ensure that all search indexes are created by one information center
	instance before another instance is started. Indexes are saved in the
	configuration directory, and write access is not synchronized across information center
	instances.
	</p>

	<h3>Filtering</h3>

	<p>
	<a href="ua_dynamic_filters.htm">Filtering</a> support is turned
	<strong>off</strong> when running in information center mode, causing all content,
	including filtered content, to be visible. If you intent to host your
	documentation in both workbench and information center modes, you should use filters in
	a way that makes sense even if filtering is turned off.
	</p>

	<p>
	Some documentation plug-ins may have dependencies on other plug-ins, usually by
	specifying the required plug-ins in their bundle manifest. The dependent
	plug-ins need to be installed on the information center as well.
	</p>

	<p>
	See the <a href="ua_help_setup_preferences.htm">Product customization</a>
	topic for more information on customizing the help system.
	</p>

	</body>
	</html>