org.eclipse.ua.tests/data/help/performance/search/ua_help_setup_standalone.htm - platform/eclipse.platform.ua - Git at Google

 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
 <html>
 <head>
 <meta name="copyright" content="Copyright (c) IBM Corporation and others 2000, 2006. 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 type="text/javascript" src="PLUGINS_ROOT/org.eclipse.help/livehelp.js"></script>
 <title>Standalone help</title>
 </head>
 <body>

 <h2>Standalone help</h2>

 <p>If you are creating an application that is not based on
 the Eclipse framework, you can still use the Eclipse help system. Your
 application can package and install the stand-alone help system, a very small
 version of Eclipse that has everything except the help system stripped out
 of it. Then, your application can make API calls from its Help menu, or from UI
 objects, to launch the help browser. The stand-alone help system has all the
 features of the integrated help system, except workbench-integrated context help,
 the help view, and active help. When an application is not Java based, or help is
 required when the application is not running, it is possible to use stand-alone
 help from a system shell, a shell script or a desktop shortcut and provide command
 line options instead of calling Java APIs.</p>
 <P>The stand-alone help system allows passing number of options that can be used to customize various aspects of the help system. The following options are supported:</P><UL>
 	<LI><B>-eclipsehome</B> <I>eclipseInstallPath</I> - 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.</LI>
 	<LI><B>-host</B> <I>helpServerHost</I> - specifies host name of the
 	interface that help server will use. It overrides host name specified
 	the application server plugin preferences.</LI>
 	<LI><B>-data</B> <I>instanceArea</I> - 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. </LI>
 	<LI><B>-port</B> <I>helpServerPort</I> - specifies port number that
 	help server will use. It overrides port number specified the
 	application server plugin preferences.</LI>
 	<LI><B>-dir ltr </B> or<B> -dir rtl</B> - sets left-to right or right-to-left
 	  rendering direction of help UI in the browser.</LI>
 	<LI>Additionally, most <A
 		href="../../org.eclipse.platform.doc.user/tasks/running_eclipse.htm">options
 	accepted by Eclipse executable</A> can be passed. They are especially useful during debugging and for applying customization to Eclipse.
 	For example, passing an option
 	<PRE><EM><SPAN style="font-style: normal">-nl fr_FR</SPAN></EM> </PRE>
 	will start help system in French language instead of a language specified by the machine's locale.</LI>
 </UL>

 <h3>Installation/packaging</h3>

 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.
 <ol>
   <li>Download the eclipse Platform Runtime Binary driver from
   <a target="_blank" href="http://eclipse.org/downloads/">eclipse.org</a>.</li>
   <li>Install (unzip) the driver under your application directory, for
   example, <var>d:\myApp</var>. This will create an eclipse sub-directory,
   d:\myApp\eclipse that contains the code required for the eclipse platform
   (which includes the help system). </li>
 </ol>

 <h3>How to call the help classes from Java</h3>

 <ol>
   <li>Make sure <code>d:\myApp\eclipse\plugins\org.eclipse.help.base_[version].jar</code>
   is on your classpath, where <code>[version]</code> is the version of the plugin
   you're using (e.g. <code>org.eclipse.help.base_3.2.0.jar</code>). The class you use
   to start, launch, and shut down the help system is
   <code>org.eclipse.help.standalone.Help</code>.
   </li>
   <li>Create an array of <code>String</code> objects containing options that you want
   to pass to help system support. Typically, the <code>eclipsehome</code> option is
   needed.

   <pre>String[] options = new String[] { &quot;-eclipsehome&quot;, &quot;d:\\myApp\\eclipse&quot; };</pre>

   </li>
 	<LI>In your application, create an instance of the <code>Help</code> class by
 	passing in the options. This object should be held onto until the end of your
 	application.
 	<pre>Help helpSystem = new Help(options);</pre>
 	</LI>
 	<li>To start the help system:
   <pre><em><span style="font-style: normal">helpSystem.start();</span></em> </pre>
   </li>
   <li>To invoke help when needed:
   <pre><em><span style="font-style: normal">helpSystem.displayHelp();</span></em> </pre>
   <p>You can also call help on specific primary TOC files or topics:</p>
   <pre>helpSystem.displayHelp(&quot;/com.mycompany.mytool.doc/toc.xml&quot;);
 helpSystem.displayHelp(&quot;/com.mycompany.mytool.doc/tasks/task1.htm&quot;);</pre>
   </li>
   <li>To launch context sensitive help, call
   helpSystem.displayContext(contextId, x, y) where contextId is a fully
   qualified context id. The screen coordinates, x and y, are not currently used.
   </li>
 	<LI>
 	<P>At the end of your application, to shutdown the help system:</P>
 	<PRE><EM><SPAN style="font-style: normal">helpSystem.shutdown();</SPAN></EM> </PRE></LI>
 </ol>

 <h3>How to call the help from the command line</h3>

 <p>
 The <code>org.eclipse.help.standalone.Help</code> class has a main method you can
 use to launch stand-alone help from the command line. The command line arguments
 syntax is:
 </p>
 <pre><em><span style="font-style: normal">-command start | shutdown | (displayHelp [href]) [-eclipsehome eclipseInstallPath] [-data instanceArea] [-host helpServerHost] [-port helpServerPort] [-dir rtl] [platform options] [-vmargs JavaVMarguments]</span></em></pre>
 <P>A simple way to display help is to invoke</P>
 <pre>java -classpath d:\myApp\eclipse\plugins\org.eclipse.help.base_[version].jar org.eclipse.help.standalone.Help -command displayHelp</pre><P>from within d:\myApp\eclipse directory, where <code>version</code> is the plug-in's version. To display a specific TOC file or topic use</P>
 <PRE>java -classpath d:\myApp\eclipse\plugins\org.eclipse.help.base_[version].jar org.eclipse.help.standalone.Help -command displayHelp /com.mycompany.mytool.doc/tasks/task1.htm</PRE>
 <P>The calls above to display help will cause help system to start, display help, and keep running to allow a user to continue browsing  help after the command is executed. To control the life cycle of the help system, use start and shutdown commands, in addition to the displayHelp command. For example, you may call</P>
 <PRE>java -classpath d:\myApp\eclipse\plugins\org.eclipse.help.base_[version].jar org.eclipse.help.standalone.Help -command start</PRE>

 <h3>[Optional] Installing a minimal stand-alone help system</h3>

 <p>
 The stand-alone help does not require the entire eclipse Platform package. It is
 possible to run the stand-alone help using only those plugins from the feature
 org.eclipse.help. To do this perform the following steps.</p>

 <ol>
   <li>Download an eclipse SDK build and upzip it into two different locations,
   &lt;location1&gt; and &lt;location1&gt;</li>
   <li>Remove the eclipse plugins directory from location1</li>
   <li>Start Eclipse in location2 and import the org.eclipse.help feature into
   your workspace using File/Import/Plug-in Development/Features</li>
   <li>Export the help feature and it's plugins to location1/eclipse using
   File/Export/Plug-in Development/Deployable Features. The plugins directory
   which was just deleted will be replaced by a directory containing a smaller
   number of plugins.</li>
   <li>From location1 start standalone help from the command line as described in
   the previous section.</li>
 </ol>

 <p>
 Some documentation plug-ins may have dependencies on other plug-ins, usually by
 specifying required plug-ins in their manifest. The dependent plug-ins need to be
 installed as well. Additionally, plug-ins that were designed for earlier than 3.0
 version of eclipse implicitly require
 <code>org.eclipse.core.runtime.compatibility</code> plug-in being present to work.
 </p>

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

 </body>
 </html>
	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
	<html>
	<head>
	<meta name="copyright" content="Copyright (c) IBM Corporation and others 2000, 2006. 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 type="text/javascript" src="PLUGINS_ROOT/org.eclipse.help/livehelp.js"></script>
	<title>Standalone help</title>
	</head>
	<body>

	<h2>Standalone help</h2>

	<p>If you are creating an application that is not based on
	the Eclipse framework, you can still use the Eclipse help system. Your
	application can package and install the stand-alone help system, a very small
	version of Eclipse that has everything except the help system stripped out
	of it. Then, your application can make API calls from its Help menu, or from UI
	objects, to launch the help browser. The stand-alone help system has all the
	features of the integrated help system, except workbench-integrated context help,
	the help view, and active help. When an application is not Java based, or help is
	required when the application is not running, it is possible to use stand-alone
	help from a system shell, a shell script or a desktop shortcut and provide command
	line options instead of calling Java APIs.</p>
	<P>The stand-alone help system allows passing number of options that can be used to customize various aspects of the help system. The following options are supported:</P><UL>
	<LI><B>-eclipsehome</B> <I>eclipseInstallPath</I> - 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.</LI>
	<LI><B>-host</B> <I>helpServerHost</I> - specifies host name of the
	interface that help server will use. It overrides host name specified
	the application server plugin preferences.</LI>
	<LI><B>-data</B> <I>instanceArea</I> - 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. </LI>
	<LI><B>-port</B> <I>helpServerPort</I> - specifies port number that
	help server will use. It overrides port number specified the
	application server plugin preferences.</LI>
	<LI><B>-dir ltr </B> or<B> -dir rtl</B> - sets left-to right or right-to-left
	rendering direction of help UI in the browser.</LI>
	<LI>Additionally, most <A
	href="../../org.eclipse.platform.doc.user/tasks/running_eclipse.htm">options
	accepted by Eclipse executable</A> can be passed. They are especially useful during debugging and for applying customization to Eclipse.
	For example, passing an option
	<PRE><EM><SPAN style="font-style: normal">-nl fr_FR</SPAN></EM> </PRE>
	will start help system in French language instead of a language specified by the machine's locale.</LI>
	</UL>

	<h3>Installation/packaging</h3>

	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.
	<ol>
	<li>Download the eclipse Platform Runtime Binary driver from
	<a target="_blank" href="http://eclipse.org/downloads/">eclipse.org</a>.</li>
	<li>Install (unzip) the driver under your application directory, for
	example, <var>d:\myApp</var>. This will create an eclipse sub-directory,
	d:\myApp\eclipse that contains the code required for the eclipse platform
	(which includes the help system). </li>
	</ol>

	<h3>How to call the help classes from Java</h3>

	<ol>
	<li>Make sure <code>d:\myApp\eclipse\plugins\org.eclipse.help.base_[version].jar</code>
	is on your classpath, where <code>[version]</code> is the version of the plugin
	you're using (e.g. <code>org.eclipse.help.base_3.2.0.jar</code>). The class you use
	to start, launch, and shut down the help system is
	<code>org.eclipse.help.standalone.Help</code>.
	</li>
	<li>Create an array of <code>String</code> objects containing options that you want
	to pass to help system support. Typically, the <code>eclipsehome</code> option is
	needed.

	<pre>String[] options = new String[] { "-eclipsehome", "d:\\myApp\\eclipse" };</pre>

	</li>
	<LI>In your application, create an instance of the <code>Help</code> class by
	passing in the options. This object should be held onto until the end of your
	application.
	<pre>Help helpSystem = new Help(options);</pre>
	</LI>
	<li>To start the help system:
	<pre><em><span style="font-style: normal">helpSystem.start();</span></em> </pre>
	</li>
	<li>To invoke help when needed:
	<pre><em><span style="font-style: normal">helpSystem.displayHelp();</span></em> </pre>
	<p>You can also call help on specific primary TOC files or topics:</p>
	<pre>helpSystem.displayHelp("/com.mycompany.mytool.doc/toc.xml");
	helpSystem.displayHelp("/com.mycompany.mytool.doc/tasks/task1.htm");</pre>
	</li>
	<li>To launch context sensitive help, call
	helpSystem.displayContext(contextId, x, y) where contextId is a fully
	qualified context id. The screen coordinates, x and y, are not currently used.
	</li>
	<LI>
	<P>At the end of your application, to shutdown the help system:</P>
	<PRE><EM><SPAN style="font-style: normal">helpSystem.shutdown();</SPAN></EM> </PRE></LI>
	</ol>

	<h3>How to call the help from the command line</h3>

	<p>
	The <code>org.eclipse.help.standalone.Help</code> class has a main method you can
	use to launch stand-alone help from the command line. The command line arguments
	syntax is:
	</p>
	<pre><em><span style="font-style: normal">-command start \| shutdown \| (displayHelp [href]) [-eclipsehome eclipseInstallPath] [-data instanceArea] [-host helpServerHost] [-port helpServerPort] [-dir rtl] [platform options] [-vmargs JavaVMarguments]</span></em></pre>
	<P>A simple way to display help is to invoke</P>
	<pre>java -classpath d:\myApp\eclipse\plugins\org.eclipse.help.base_[version].jar org.eclipse.help.standalone.Help -command displayHelp</pre><P>from within d:\myApp\eclipse directory, where <code>version</code> is the plug-in's version. To display a specific TOC file or topic use</P>
	<PRE>java -classpath d:\myApp\eclipse\plugins\org.eclipse.help.base_[version].jar org.eclipse.help.standalone.Help -command displayHelp /com.mycompany.mytool.doc/tasks/task1.htm</PRE>
	<P>The calls above to display help will cause help system to start, display help, and keep running to allow a user to continue browsing help after the command is executed. To control the life cycle of the help system, use start and shutdown commands, in addition to the displayHelp command. For example, you may call</P>
	<PRE>java -classpath d:\myApp\eclipse\plugins\org.eclipse.help.base_[version].jar org.eclipse.help.standalone.Help -command start</PRE>

	<h3>[Optional] Installing a minimal stand-alone help system</h3>

	<p>
	The stand-alone help does not require the entire eclipse Platform package. It is
	possible to run the stand-alone help using only those plugins from the feature
	org.eclipse.help. To do this perform the following steps.</p>

	<ol>
	<li>Download an eclipse SDK build and upzip it into two different locations,
	<location1> and <location1></li>
	<li>Remove the eclipse plugins directory from location1</li>
	<li>Start Eclipse in location2 and import the org.eclipse.help feature into
	your workspace using File/Import/Plug-in Development/Features</li>
	<li>Export the help feature and it's plugins to location1/eclipse using
	File/Export/Plug-in Development/Deployable Features. The plugins directory
	which was just deleted will be replaced by a directory containing a smaller
	number of plugins.</li>
	<li>From location1 start standalone help from the command line as described in
	the previous section.</li>
	</ol>

	<p>
	Some documentation plug-ins may have dependencies on other plug-ins, usually by
	specifying required plug-ins in their manifest. The dependent plug-ins need to be
	installed as well. Additionally, plug-ins that were designed for earlier than 3.0
	version of eclipse implicitly require
	<code>org.eclipse.core.runtime.compatibility</code> plug-in being present to work.
	</p>

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

	</body>
	</html>