diff options
Diffstat (limited to 'org.eclipse.ua.tests/data/help')
33 files changed, 2951 insertions, 0 deletions
diff --git a/org.eclipse.ua.tests/data/help/performance/search/ua_help.htm b/org.eclipse.ua.tests/data/help/performance/search/ua_help.htm new file mode 100644 index 000000000..04305a291 --- /dev/null +++ b/org.eclipse.ua.tests/data/help/performance/search/ua_help.htm @@ -0,0 +1,35 @@ +<!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 language="JavaScript" src="PLUGINS_ROOT/org.eclipse.help/livehelp.js"></script> +<title>Help</title> +</head> +<body> + +<h2>Help</h2> + +<P > +The Eclipse platform's help facilities provide you with the raw building blocks to structure and contribute +documentation to the platform. It does not dictate structure or granularity of documentation. +You can choose the tools and structure for your documentation that suits your +needs. The help plug-in allows you to describe your documentation +structure to the platform using a table of contents (toc) file.</P> +<P >Your plug-in's online help is contributed using the <a href="../reference/extension-points/org_eclipse_help_toc.html"> <b> org.eclipse.help.toc</b></a> extension point. You can either contribute the online help as part of your code plug-in or provide it separately in its own documentation plug-in.</P> +<P > +Separating the documentation into a separate plug-in is beneficial in those situations where the code and documentation teams are different groups or where you want to reduce the coupling between the documentation and code. </P> +<P > +Advanced features of the help system include context-sensitive help with +reference links and the ability to invoke platform +code from the documentation. A help browser lets you view, print, and +search your documentation. Since 3.1, the new Help view adds dynamic help and +federated information search capability.</P> +<P > +The best way to demonstrate the contribution of help is to create a +documentation plug-in.</P> + +</body> +</html> diff --git a/org.eclipse.ua.tests/data/help/performance/search/ua_help_content.htm b/org.eclipse.ua.tests/data/help/performance/search/ua_help_content.htm new file mode 100644 index 000000000..e22ac2496 --- /dev/null +++ b/org.eclipse.ua.tests/data/help/performance/search/ua_help_content.htm @@ -0,0 +1,56 @@ +<!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 language="JavaScript" src="PLUGINS_ROOT/org.eclipse.help/livehelp.js"></script> +<title>Help content</title> +</head> +<body> + +<h2>Help content</h2> + +<p><b>Building a help plug-in</b></p> + +<P > +In this example, we assume that a documentation author has already supplied you with the raw documentation in the form of HTML files. The granularity +and structure of these files is completely up to the documentation team. Once the documentation is delivered, setting up the plug-in and topics can be done independently.</P> + +<P > +We start by assuming that the documentation has already been provided in the following tree.</P> +<pre> + html/ + concepts/ + concept1.html + concept1_1.html + concept1_2.html + tasks/ + task1.html + task2.html + task3_1.html + task3_2.html + ref/ + ref1.html + ref2.html +</pre> +<P > +We will assume that the plug-in name is <b>com.example.helpexample</b>.</P> +<P > +The first step is to create a plug-in directory, <b>com.example.helpexample</b> underneath the platform +<b>plugins</b> directory. The <b>doc\</b> +sub tree shown above should be copied into the directory. </P> +<P > +Documentation plug-ins need a manifest just like code plug-ins. The following markup defines the documentation plug-in.</P> + +<pre> + <?xml version="1.0" ?> + <plugin name="Online Help Sample" + id="com.example.helpexample" + version="1.0" + provider-name="MyExample" /> +</pre> + +</body> +</html> diff --git a/org.eclipse.ua.tests/data/help/performance/search/ua_help_content_active.htm b/org.eclipse.ua.tests/data/help/performance/search/ua_help_content_active.htm new file mode 100644 index 000000000..337b76489 --- /dev/null +++ b/org.eclipse.ua.tests/data/help/performance/search/ua_help_content_active.htm @@ -0,0 +1,34 @@ +<!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 language="JavaScript" src="PLUGINS_ROOT/org.eclipse.help/livehelp.js"></script> +<title>Active help</title> +</head> +<body> + +<h2>Active help</h2> + +<p>Active help is the ability to invoke Eclipse code from on-line +documentation. It is implemented by including some JavaScript in your +documentation that describes a class that should be run inside the Eclipse +platform. </p> + +<p>For example, instead of writing, "Go to the Window Menu and open the +message dialog," your on-line help can include a link that will open your +application's message dialog for the user. Active help links look like hyperlinks in +the on-line help.</p> + +<p>Below is an active help link that opens the cheatsheet "Check out a CVS project". +We will take a look at how to create and reference your own actions.</p> + +<p><a href='javascript:liveAction( + "org.eclipse.ui.cheatsheets", + "org.eclipse.ui.cheatsheets.OpenCheatSheetFromHelpAction", + "org.eclipse.platform.cvs.checkout")'>Open a cheatsheet.</a></p> + +</body> +</html> diff --git a/org.eclipse.ua.tests/data/help/performance/search/ua_help_content_active_action.htm b/org.eclipse.ua.tests/data/help/performance/search/ua_help_content_active_action.htm new file mode 100644 index 000000000..d57f2a513 --- /dev/null +++ b/org.eclipse.ua.tests/data/help/performance/search/ua_help_content_active_action.htm @@ -0,0 +1,81 @@ +<!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 language="JavaScript" src="PLUGINS_ROOT/org.eclipse.help/livehelp.js"></script> +<title>Writing the help action</title> +</head> +<body> + +<h3>Writing the help action</h3> + +<p>The interface <a href="../reference/api/org/eclipse/help/ILiveHelpAction.html"><b>ILiveHelpAction</b></a> +is used to build an active help action.</p> + + +<p>It is straightforward to implement an <a href="../reference/api/org/eclipse/help/ILiveHelpAction.html"><b>ILiveHelpAction</b></a><b>.</b> +You must implement two methods.</p> + + +<ul> + <li><b>run()</b> - This method is called to run the live help action. + This method will be called by the help system from a non-UI thread, so UI + access must be wrapped in a <b><a href="../reference/api/org/eclipse/swt/widgets/Display.html">Display.syncExec()</a></b> + method. </li> + <li><b>setInitializationString(String)</b> - This method is called to + initialize your action with a String data parameter you can specify in the + HTML which runs the JavaScript <b>liveAction</b>. +If you don't need initialization data, you can just implement +this method to do nothing. This method is called before <b>run()</b>.</li> +</ul> + + +<p>Here is a simple implementation of a live help action that opens a message +dialog. We don't need any information from the JavaScript, so the +initialization data is ignored.</p> + + +<pre>package org.eclipse.platform.doc.isv.activeHelp; + +import org.eclipse.help.ILiveHelpAction; +import org.eclipse.jface.dialogs.MessageDialog; +import org.eclipse.swt.widgets.*; +import org.eclipse.ui.*; +/** + * Sample Active Help action. + */ +public class ActiveHelpOpenDialogAction implements ILiveHelpAction { + + public void setInitializationString(String data) { + // ignore the data. We do not use any javascript parameters. + } + + public void run() { + // Active help does not run on the UI thread, so we must use syncExec + Display.getDefault().syncExec(new Runnable() { + public void run() { + IWorkbenchWindow window = + PlatformUI.getWorkbench().getActiveWorkbenchWindow(); + if (window != null) { + // Bring the Workbench window to the top of other windows; + // On some Windows systems, it will only flash the Workbench + // icon on the task bar + Shell shell = window.getShell(); + shell.setMinimized(false); + shell.forceActive(); + // Open a message dialog + MessageDialog.openInformation( + window.getShell(), + "Hello World.", + "Hello World."); + } + } + }); + } +}</pre> + +</body> +</html> diff --git a/org.eclipse.ua.tests/data/help/performance/search/ua_help_content_active_debug.htm b/org.eclipse.ua.tests/data/help/performance/search/ua_help_content_active_debug.htm new file mode 100644 index 000000000..42e7c5378 --- /dev/null +++ b/org.eclipse.ua.tests/data/help/performance/search/ua_help_content_active_debug.htm @@ -0,0 +1,91 @@ +<!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 language="JavaScript" src="PLUGINS_ROOT/org.eclipse.help/livehelp.js"></script> +<title>Tips for debugging active help</title> +</head> +<body> + +<h2>Tips for debugging active help</h2> + + +<p>The code and markup that triggered our active help link looks pretty +straightforward. But what do you do if your active help link doesn't seem +to work?</p> + + +<h4>Test your action ahead of time</h4> + + +<p>If your action implementation is fairly involved, you should invoke the +action yourself with some test code inside Eclipse. This way, you'll know +that the action is error-free before invoking it from the JavaScript. </p> + + +<h4>Ensure the JavaScript is running</h4> + + +<p>You can modify "<b>liveHelp.js</b>" (make a copy of this from the plugins/org.eclipse.help +plugin and change your <code>script</code> statement to refer to your local copy) +to include a call to the <b>alert</b> function as the first statement in the <b>liveAction</b> +function:</p> + + +<pre>function liveAction(pluginId, className, argument) +{ +<b> alert("liveAction called"); + ...</b></pre> + + +<p>The <b>alert</b> function opens a warning dialog in the browser and can be +used to verify that the <b>liveAction</b> was properly invoked in your +HTML. If you don't see a warning dialog when you click on your help link, +then you have a problem in the HTML markup.</p> + + +<h4>Debug the active help action</h4> + + +<p>Once you know that the JavaScript is running, you can debug your action from +inside Eclipse. To do this, you can set a breakpoint in your help action +class and start up a self-hosted Eclipse instance. You must test your +active help with the Help browser from the newly launched Eclipse instance, not +from your host instance, since the JavaScript from your help HTML calls a +servlet on the Eclipse help server that launched the browser.</p> + + +<p>If nothing happens after you've set up the breakpoint and clicked on the +active help link, it's likely that your plug-in and active help class were not +correctly specified in the JavaScript. </p> + + +<p>Once you've managed to stop at the breakpoint in your action, you can debug +the action as you would any other Java code.</p> + + +<h4>Make sure your UI code is wrapped in Display.syncExec</h4> + + +<p>A common runtime problem is improperly accessing UI code from the thread that +invokes the active help. If your live help action came from code that ran +originally in a UI thread, it will need to be modified to handle the fact that +it is running from a non-UI thread. </p> + + +<pre>public void run() { + // Active help does not run on the UI thread, so we must use syncExec + Display.getDefault().syncExec(new Runnable() { + public void run() { + //do the UI work in here; + } + }); + } + +</pre> + +</body> +</html> diff --git a/org.eclipse.ua.tests/data/help/performance/search/ua_help_content_active_invoke.htm b/org.eclipse.ua.tests/data/help/performance/search/ua_help_content_active_invoke.htm new file mode 100644 index 000000000..46c419d9b --- /dev/null +++ b/org.eclipse.ua.tests/data/help/performance/search/ua_help_content_active_invoke.htm @@ -0,0 +1,47 @@ +<!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 language="JavaScript" src="PLUGINS_ROOT/org.eclipse.help/livehelp.js"></script> +<title>Invoking the action from HTML</title> +</head> +<body> + +<h2>Invoking the action from HTML</h2> + +<P> +To include active help links in your documentation, you must first declare the +use of the supporting JavaScript code. The live help JavaScript is located in the <b>org.eclipse.help</b> +plug-in. You refer to it using the help system's <a href="ua_help_content_files.htm#help_plugin_files_xref">cross +plug-in referencing</a> technique. This script reference should be placed in the <b>HEAD</b> section of your HTML: +</P> + +<pre ><script language="JavaScript" src="PLUGINS_ROOT/org.eclipse.help/livehelp.js"> </script></pre> + +<P > + In the body of your documentation, you invoke the liveAction script. </P> + + +<pre ><a href='javascript:liveAction( + "org.eclipse.platform.doc.isv", + "org.eclipse.platform.doc.isv.activeHelp.ActiveHelpOpenDialogAction", + "")'>Click here for a Message.</a></pre> + + +<P >The parameters for <b>liveAction </b> are </P> + + +<ul> + <li> the ID of the plug-in that +contains the action</li> + <li>the name of the class that implements the action</li> + <li>the String that will be passed to the live help action using <b>setInitializationString</b>. + We don't need to pass any information from the HTML page, so we just + pass an empty string.</li> +</ul> + +</body> +</html> diff --git a/org.eclipse.ua.tests/data/help/performance/search/ua_help_content_command.htm b/org.eclipse.ua.tests/data/help/performance/search/ua_help_content_command.htm new file mode 100644 index 000000000..515b39bac --- /dev/null +++ b/org.eclipse.ua.tests/data/help/performance/search/ua_help_content_command.htm @@ -0,0 +1,130 @@ +<!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 language="JavaScript" src="PLUGINS_ROOT/org.eclipse.help/livehelp.js"></script> +<title>Embedding commands in help</title> +</head> +<body> + +<h2>Embedding commands in help</h2> + +<p>It is possible to create links to workbench commands in help content. When +the user clicks the link, the command will be executed. This feature is similar +to <a href="ua_help_content_active.htm">Active Help</a> in that it uses JavaScript to bridge between the documentation +HTML and the Eclipse Java runtime. Also like Active Help, the command framework is extensible; +so you can contribute new commands with interesting behaviors. +However, unlike Active Help, there are a large number of useful commands already defined +in the workbench and more are being added all the time. This should be appealing to +documentation authors because linking to an existing command does not require +writing any Java code. +</p> +<p> +Command links can be used to: +</p> +<ul> +<li> +Open a specific preference page, such as + +<a class="command-link" href='javascript:executeCommand("org.eclipse.ui.window.preferences(preferencePageId=org.eclipse.ui.preferencePages.Views)")'> +<img src="PLUGINS_ROOT/org.eclipse.help/command_link.png"> +<b>General > Appearance</b></a>. + +</li> +<li> + +<a class="command-link" href='javascript:executeCommand("org.eclipse.ui.perspectives.showPerspective")'> +<img src="PLUGINS_ROOT/org.eclipse.help/command_link.png"> +Select a new perspective</a> + +or switch to a pre-determined perspective like the + +<a class="command-link" href='javascript:executeCommand("org.eclipse.ui.perspectives.showPerspective(org.eclipse.ui.perspectives.showPerspective.perspectiveId=org.eclipse.jdt.ui.JavaBrowsingPerspective)")'> +<img src="PLUGINS_ROOT/org.eclipse.help/command_link.png"> +<b>Java Browsing</b></a>. + +perspective +</li> +<li> + +<a class="command-link" href='javascript:executeCommand("org.eclipse.ui.views.showView")'> +<img src="PLUGINS_ROOT/org.eclipse.help/command_link.png"> +Select a view to open</a> + +or open a pre-determined view like the + +<a class="command-link" href='javascript:executeCommand("org.eclipse.ui.views.showView(org.eclipse.ui.views.showView.viewId=org.eclipse.ui.views.BookmarkView)")'> +<img src="PLUGINS_ROOT/org.eclipse.help/command_link.png"> +<b>Bookmarks</b></a>. + +view +</li> +<li> +Open wizards like the + +<a class="command-link" href='javascript:executeCommand("org.eclipse.ui.newWizard(newWizardId=org.eclipse.pde.ui.NewProjectWizard)")'> +<img src="PLUGINS_ROOT/org.eclipse.help/command_link.png"> +<b>New Plug-in Project</b></a> + +wizard and the + +<a class="command-link" href='javascript:executeCommand("org.eclipse.ui.file.export(exportWizardId=org.eclipse.ui.wizards.export.Preferences)")'> +<img src="PLUGINS_ROOT/org.eclipse.help/command_link.png"> +<b>Export Preferences</b></a>. + +wizard +</li> +<li> + +<a class="command-link" href='javascript:executeCommand("org.eclipse.ui.cheatsheets.openCheatSheet(cheatSheetId=org.eclipse.jdt.helloworld)")'> +<img src="PLUGINS_ROOT/org.eclipse.help/command_link.png"> +Open a Cheat Sheet</a>. + +</li> +<li> +Open a + +<a class="command-link" href='javascript:executeCommand("org.eclipse.ui.dialogs.openMessageDialog(imageType=3,buttonLabel2=Maybe,title=Opinion Poll,message=Do you like command links?,buttonLabel0=Yes,defaultIndex=0,buttonLabel1=No)")'> +<img src="PLUGINS_ROOT/org.eclipse.help/command_link.png"> +message dialog</a>. + +</li> +<li> +Open the + +<a class="command-link" href='javascript:executeCommand("org.eclipse.ui.help.aboutAction")'> +<img src="PLUGINS_ROOT/org.eclipse.help/command_link.png"> +<b>About Eclipse SDK</b></a> + +dialog. +</li> +<li> +And much more! +</li> +</ul> + +<p> +To get an idea of the range of commands available, look at the + +<a class="command-link" href='javascript:executeCommand("org.eclipse.ui.window.preferences(preferencePageId=org.eclipse.ui.preferencePages.Keys)")'> +<img src="PLUGINS_ROOT/org.eclipse.help/command_link.png"> +<b>General > Keys</b></a> + +preference page. This page is used to bind key sequences to commands +so it shows the list of available commands. <i>Note that not every command will do something useful from +help content. Many commands are designed to work within a somewhat narrow context (like a particular view, +or expecting a certain type of selection).</i> +</p> + +<p> +If you want to define your own commands, refer to the documentation for the +<a href="../reference/api/org/eclipse/core/commands/package-summary.html"><tt>org.eclipse.core.commands</tt></a> API package +and the <a href="../reference/extension-points/org_eclipse_ui_commands.html"><tt>org.eclipse.ui.commands</tt></a> and +<a href="../reference/extension-points/org_eclipse_ui_handlers.html"><tt>org.eclipse.ui.handlers</tt></a> extension-points. +</p> + +</body> +</html> diff --git a/org.eclipse.ua.tests/data/help/performance/search/ua_help_content_command_authoring.htm b/org.eclipse.ua.tests/data/help/performance/search/ua_help_content_command_authoring.htm new file mode 100644 index 000000000..621d90608 --- /dev/null +++ b/org.eclipse.ua.tests/data/help/performance/search/ua_help_content_command_authoring.htm @@ -0,0 +1,76 @@ +<!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 language="JavaScript" src="PLUGINS_ROOT/org.eclipse.help/livehelp.js"></script> +<title>Authoring a command link</title> +</head> +<body> + +<h2>Authoring a command link</h2> + +<P> +To include command links in your documentation, you must first declare the +use of the supporting JavaScript code. The live help JavaScript is located in the <b>org.eclipse.help</b> +plug-in. You refer to it using the help system's <a href="ua_help_content_files.htm#help_plugin_files_xref">cross +plug-in referencing</a> technique. This script reference should be placed in the <b>HEAD</b> section of your HTML: +</P> + +<pre ><script type="text/javascript" src="PLUGINS_ROOT/org.eclipse.help/livehelp.js"> +</script></pre> + +<P> +Now in the body of your documentation you may invoke the <b>executeCommand</b> function. +Here is an example: +</P> + +<pre><a href='javascript:executeCommand("org.eclipse.ui.help.aboutAction")'> +Open the About dialog</a></pre> + +<P> +The parameter for the <b>executeCommand</b> function is a serialized +<a href="../reference/api/org/eclipse/core/commands/ParameterizedCommand.html"> +<b>ParameterizedCommand</b></a>. +See the +<a href="../reference/api/org/eclipse/core/commands/ParameterizedCommand.html#serialize()"> +<b>ParameterizedCommand.serialize()</b></a> method for full details on this format. +</P> + +<P> +The example above shows the bare minimum required to embed a command in an HTML link. +The Eclipse documentation supplements this with two extra pieces of information. +First a <tt>class</tt> attribute is specified to allow for tuning the look of the link +via CSS. Second, an image tag is included before the link text. The image serves +to distinguish command links from ordinary links to other HTML pages. Supplementing +our initial example with these two extra features will look like this: +</P> + +<pre><a class="command-link" href='javascript:executeCommand("org.eclipse.ui.help.aboutAction")'> +<img src="PLUGINS_ROOT/org.eclipse.help/command_link.png"> +Open the About dialog</a></pre> + +<P> +In the examples above, the About dialog command does not require any parameters, so the +serialization is merely its command id: <tt>org.eclipse.ui.help.aboutAction</tt>. +Below is another example showing a command with a parameter. Note the command id is +followed by the parameter id and value in parentheses: +</P> + +<pre><a href='javascript:executeCommand( + "org.eclipse.ui.window.preferences(preferencePageId=org.eclipse.ui.preferencePages.Views)")'> + Show a preference page</a></pre> + +<P> +Another example demonstrates that multiple parameters are possible. They are comma +separated and the order of the parameters is not important. +</P> + +<pre><a href='javascript:executeCommand( + "org.eclipse.ui.dialogs.openMessageDialog(imageType=3,buttonLabel2=Maybe,title=Opinion Poll,message=Do you like command links?,buttonLabel0=Yes,defaultIndex=0,buttonLabel1=No)")'> + Open a message dialog</a></pre> + +</body> +</html>
\ No newline at end of file diff --git a/org.eclipse.ua.tests/data/help/performance/search/ua_help_content_files.htm b/org.eclipse.ua.tests/data/help/performance/search/ua_help_content_files.htm new file mode 100644 index 000000000..a314da78d --- /dev/null +++ b/org.eclipse.ua.tests/data/help/performance/search/ua_help_content_files.htm @@ -0,0 +1,133 @@ +<!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 language="JavaScript" src="PLUGINS_ROOT/org.eclipse.help/livehelp.js"></script> +<title>Help server and file locations</title> +</head> +<body> + +<h2>Help server and file locations</h2> + +<P > +The platform utilizes its own documentation server to provide the actual web pages +for your plug-in's documentation. A custom server allows the platform to handle HTML content +in a browser independent manner and to provide plug-in aware support. The +main difference to you as a plug-in developer is that you have a little more +flexibility in the way you structure your files and specify your links. </P> +<P > +A documentation plug-in can run from a jar file or unpacked into plug-in directory +during installation. A plug-in archive jar is not + expanded into a plug-in directory when value of <code>unpack</code> attribute + of the <code>plugin</code> element is specified as true in the <a href="../reference/misc/feature_manifest.html">feature + manifest</a>. In such plug-in, the documentation is compressed in the plug-in's +jar, together with other plug-in files. </P> +<P >In plug-ins that run unpacked, the documentation can be delivered + in a zip file, avoiding problems that may result + when a large number of files + are + present + in a plug-in + directory. + In + our example +plug-in, we created a sub-directory called <b>html</b>. +Alternatively, we could have placed our html files into a zip file called +<b>doc.zip</b>. This zip file must mimic the file +structure underneath the plug-in directory. In our case, it must contain +the sub-directory <b>html</b> and all the contents +underneath <b>html</b>.</P> +<P >Note that for plug-ins running from a jar, there is no need for documentation + to be additionally contained in doc.zip, and such set-up of doc.zip in an unexploded + plug-in jar +is not supported by help system</P> +<P >When resolving file names in a plug-in that runs unpacked, the help server + looks in the <b>doc.zip</b> +file for documents before it looks in the plug-in directory itself. When +used as a link, the argument in an +<b> href</b> is assumed to be relative to the current plug-in. Consider +the following link: </P> + + +<pre> <topic label="Ref1" href="html/ref/ref1.html"/></pre> + + +<P>The help plug-in will look for this file as follows: </P> + + +<ul> + <li>look in <b> doc.zip</b> for the file <b>/html/ref/ref1.html</b></li> + <li>look for the file <b>ref1.html</b> in the <b>/html/ref </b>sub-directory structure underneath the plug-in + directory.</li> +</ul> +<P >A fully qualified link can be used to refer to any content on the web. </P> + + +<pre > <topic label="Ref1" href="http://www.example.com/myReference.html"/></pre> + + +<h4 >National language and translated documentation</h4> + + +<p >The platform help system uses the same national language directory lookup +scheme used by the rest of the platform for finding translated files. (See +<a href="product_def_nl.htm#platform">Locale specific files</a> for an +explanation of this directory structure.) If you are using a <b>doc.zip</b> +file, you should produce a <b>doc.zip</b> file for <b>each</b> locale and place +it inside the correct locale directory. (You should not replicate the <b>nl</b> +locale directory structure inside the doc.zip file.)</p> +<p >In addition to locale specific directories, help system checks windowing + system and operating system directories when locating help resources. Look-up + is performed in the following order: <strong>ws</strong>, <strong>os</strong>, <strong>nl</strong> subdirectories, then + the root of the plug-in, until the resource is located. Documents, and other + resource, like images which differ between system, should be placed under ws + or os directories for specific platform.</p> + +<h4 ><a name="help_plugin_files_xref">Cross plug-in referencing</a></h4> + +<P >The <b>href</b> argument can also refer to content from another +plug-in. This is done by using a special cross plug-in referencing +notation that is resolved by the help server: </P> + +<pre > <topic label="Ref1" href="<b>PLUGINS_ROOT/another_plugin_id</b>/ref/ref1.html"/></pre> + +<p> +Here <code><b>PLUGINS_ROOT</b></code> will be resolved at runtime and replaced with +the root directory for the plugins. You can specify your own plug-in id for +<code><b>another_plugin_id</b></code>. For example, you could link to this chapter +of the programmer's guide using the following topic: +</p> + +<pre > <topic label="Help Chapter in Platform Doc" href="<b>PLUGINS_ROOT/org.eclipse.platform.doc.isv/guide/help.html</b>"/></pre> + +<p> +Prior to 3.2, references to documents in other plug-ins were made by using '..' +to go up to the plug-in level, then referencing the plug-in Id followed by the +HREF to the topic inside the plug-in. The recommended way to do this now is +to use <code>PLUGINS_ROOT</code> instead of '..'. Using this variable avoids +avoids these up/down trips in references, and can be used for all the resource +URLs in the help documents (images, links, CSS files, java script files etc.) +</p> + +<p class="Note">Note: When referencing content from another plug-in, be +sure to use the plug-in's <b>id</b>, as declared in its <b>plugin.xml </b>file, +not its directory name. While these are often the same in practice, it's +important to check that you are using the id and not the directory name.</p> + +<h4 >Referencing the Product Plug-in.</h4> + +<p>Branding information is often placed in a plug-in defining a + product as explained in <a href="product_def.htm">Defining a Product</a>. Help + resources in the product plug-in can be referenced from the table of contents + or topics using special identifier <code><b>PRODUCT_PLUGIN</b></code> for the + plug-in ID. For example,</p> +<pre > href="PLUGINS_ROOT/<b>PRODUCT_PLUGIN</b>/book.css"</pre> +<p>refers to a style sheet residing in the plug-in for the currently running +product. + </p> + +</body> +</html> diff --git a/org.eclipse.ua.tests/data/help/performance/search/ua_help_content_manifest.htm b/org.eclipse.ua.tests/data/help/performance/search/ua_help_content_manifest.htm new file mode 100644 index 000000000..d976a2297 --- /dev/null +++ b/org.eclipse.ua.tests/data/help/performance/search/ua_help_content_manifest.htm @@ -0,0 +1,70 @@ +<!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 language="JavaScript" src="PLUGINS_ROOT/org.eclipse.help/livehelp.js"></script> +<title>Completing the plug-in manifest</title> +</head> +<body> + +<h2>Completing the plug-in manifest</h2> + +<P > +We started this example by creating our plug-in and document files. Next we created +toc files to describe the organization of our content. +The remaining piece of work is to pull everything together into a master toc and +update our <b> plugin.xml</b> to actually contribute the master toc. </P> + +<P > + We start by creating a <b>toc.xml</b> to contribute the three tocs we created + initially. Instead of providing an <b>href</b> for each topic, we use the + <b>link</b> attribute to refer to our existing toc files. </P> + +<pre><toc label="Online Help Sample" topic="html/book.html"> + <topic label="Concepts"> + <link toc="toc_Concepts.xml" /> + </topic> + <topic label="Tasks"> + <link toc="toc_Tasks.xml" /> + </topic> + <topic label="Reference"> + <link toc="toc_Ref.xml" /> + </topic> +</toc></pre> + +<P > + Then we update the <b>plugin.xml</b> to contribute our master toc: </P> +<pre> + <extension point="org.eclipse.help.toc"> + <toc file="toc.xml" <b>primary</b>="true" /> + </extension></pre> +<P >Note the use of the <b>primary</b> attribute. Setting this attribute +to true indicates that the toc should always appear in the navigation, even if +it is not referenced by any other toc. This way, our "master" +toc is always guaranteed to show up in the topics list. It appears at the +top level list of books since no other toc references it. <I><BR> +Note</I>: +If more files were associated with this toc but not present in the navigation, but just linked from other topics, then to have those topics available to the search engine we would have to use the <B>extradir</B> attribute in the toc.</P> +<P >Finally, we contribute our individual toc files. </P> +<pre> <extension point="org.eclipse.help.toc"> + <toc file="toc_Concepts.xml" /> + <toc file="toc_Tasks.xml" /> + <toc file="toc_Reference.xml" /> + </extension></pre> +<P >These toc files will not appear in the top level list of books because we +did not set the <b>primary</b> attribute. Toc files that are not +designated as primary will only appear in the documentation web if they are +referred to from some toc that is a primary toc or is linked in by a primary +toc. </P> + +<P >That's it. If you copy your plug-in directory to the platform's <b> plugins</b> directory, start the platform, and choose +<b> Help->Help Contents</b>, you should see your example appear in the list +of books. If you click on the "Online Help Sample", you'll see your toc structure:</P> + +<p><img src="images/help_contents.png" alt="On-line help browser with sample book structure" border="0" ></p> + +</body> +</html> diff --git a/org.eclipse.ua.tests/data/help/performance/search/ua_help_content_nested.htm b/org.eclipse.ua.tests/data/help/performance/search/ua_help_content_nested.htm new file mode 100644 index 000000000..8ad1311d5 --- /dev/null +++ b/org.eclipse.ua.tests/data/help/performance/search/ua_help_content_nested.htm @@ -0,0 +1,79 @@ +<!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 language="JavaScript" src="PLUGINS_ROOT/org.eclipse.help/livehelp.js"></script> +<title>Building nested documentation structures</title> +</head> +<body> + +<h2>Building nested documentation structures</h2> + +<p>As plug-ins contribute function to the platform, it's common to add +documentation that describes the new function. How can this documentation +be structured so that the user sees a cohesive and complete set of documentation +instead of many individual contributions? The table of contents definition +provides mechanisms for building documentation in both a top-down and bottom-up +fashion.</p> + +<h4>Top-down nesting</h4> + +<p>Top-down nesting refers to the technique of defining a master table of +contents which refers to all other included tocs. Top-down nesting is a +convenient method for breaking up known content into smaller pieces. With +top-down nesting, the <b>link</b> attribute is used in the table of contents +definition to refer to linked tocs rather than providing an <b>href</b>. </p> + +<pre><toc label="Online Help Sample" topic="html/book.html"> + <topic label="Concepts"> + <link toc="toc_Concepts.xml" /> + </topic> + <topic label="Tasks"> + <link toc="toc_Tasks.xml" /> + </topic> + <topic label="Reference"> + <link toc="toc_Ref.xml" /> + </topic> +</toc></pre> + + +<p>The basic structure stays the same (Concepts, Tasks, Reference), but the +individual tocs are free to evolve. They in turn might link to other sub-tocs. +</p> + +<h4>Bottom-up composition</h4> + +<p>Bottom-up composition is more flexible in that it lets new plug-ins decide +where the documentation should exist in the toc structure. Bottom-up +composition is accomplished using <b>anchor</b> attributes. A toc defines +named anchor points where other plug-ins can contribute documentation. In +our example, we could add anchors so that plug-ins can contribute additional +material between the concepts, tasks, and reference sections.</p> + +<pre><toc label="Online Help Sample" topic="html/book.html"> + <topic label="Concepts"> + <link toc="toc_Concepts.xml" /> + <<b>anchor</b> id="postConcepts" /> + </topic> + <topic label="Tasks"> + <link toc="toc_Tasks.xml" /> + <<b>anchor</b> id="postTasks" /> + </topic> + <topic label="Reference"> + <link toc="toc_Ref.xml" /> + <<b>anchor</b> id="postReference" /> + </topic> +</toc></pre> +<p>Other plug-ins can then contribute to the anchor from their plug-in. +This is done using the <b>link_to</b> attribute when defining a toc.</p> +<pre><toc <b>link_to="../com.example.helpexample/toc.xml#postConcepts"</b> label="Late breaking info about concepts"> + <topic> + ... + </topic> +</toc></pre> + +</body> +</html> diff --git a/org.eclipse.ua.tests/data/help/performance/search/ua_help_content_process.htm b/org.eclipse.ua.tests/data/help/performance/search/ua_help_content_process.htm new file mode 100644 index 000000000..09bdbcbfb --- /dev/null +++ b/org.eclipse.ua.tests/data/help/performance/search/ua_help_content_process.htm @@ -0,0 +1,25 @@ +<!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 language="JavaScript" src="PLUGINS_ROOT/org.eclipse.help/livehelp.js"></script> +<title>Processing Help Content</title> +</head> +<body> + +<h2>Processing Help Content</h2> + +<p> +The Eclipse help system performs preprocessing on html and xhtml pages to add breadcrumbs +and JavaScript. The processing is performed by output filter which operate on the output stream. Since Eclipse 3.5 +Eclipse has had an extension point to allow user defined filters to be added. This can be used for example to inject javascript +into every help page. See the extension point <a href = +"../reference/extension-points/org_eclipse_help_webapp_contentFilter.html"> org.eclipse.help.webapp.contentFilter</a> +for more information. +</p> + +</body> +</html>
\ No newline at end of file diff --git a/org.eclipse.ua.tests/data/help/performance/search/ua_help_content_remote.htm b/org.eclipse.ua.tests/data/help/performance/search/ua_help_content_remote.htm new file mode 100644 index 000000000..b06cc5012 --- /dev/null +++ b/org.eclipse.ua.tests/data/help/performance/search/ua_help_content_remote.htm @@ -0,0 +1,62 @@ +<!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 language="JavaScript" src="PLUGINS_ROOT/org.eclipse.help/livehelp.js"></script> +<title>Remote Help</title> +</head> +<body> + +<h2>Remote Help</h2> + +<p><b>What is remote help?</b></p> + +<p> +The help system provides the ability to retrieve content, not only from plug-ins +installed in the local instance of Eclipse, but also from one or more remote servers running +help in <a href="ua_help_setup_infocenter.htm">infocenter</a> mode. This allows +products to ship without help content and provide it from a server to reduce their +download and install size. It also allows user the ability to include help content +from plug-ins not installed in their environment. +</p> + +<p><b>How does remote help work?</b></p> + +<p> +Content from the remote help servers is merged seamlessly with the local content. There +will be no difference perceptible to the user other than potential network delays. This +is done by adding a second implementation of <code>AbstractTocProvider</code> called +<code>RemoteTocProvider</code> that supplies the content from the remote help server +alongside the local <code>TocFileProvider</code>. For performance reasons, where both +are available, local content will be supplied rather than remote content. +</p> + +<p><b>How do I setup a remote help server?</b></p> + +<p> +All you have to do to setup a remote help server is run the help system (version 3.3 +or later) in <a href="ua_help_setup_infocenter.htm">infocenter</a> mode. +</p> + +<p><b>How do I access a remote help server?</b></p> + +<p> +A remote help server can be specified in two ways as follows:</p> +<ul> +<li><a href="ua_help_setup_preferences.htm#remoteHelp">Product customization</a>: There are +6 options that can be included in the <code>plugin_customization.ini</code> file to +setup remote help defaults. They are <code>remoteHelpOn</code>, <code>remoteHelpHost</code>, +<code>remoteHelpPath</code>, +<code>remoteHelpPort, remoteHelpName, remoteHelpICEnabled.</code>. +</li> +<li><a href="PLUGINS_ROOT/org.eclipse.platform.doc.user/reference/help_preferences_content.htm"> +Help Content preferences</a>: There is a preference page that allows users to +configure remote help server settings manually.</li> +</ul> + + +</body> +</html>
\ No newline at end of file diff --git a/org.eclipse.ua.tests/data/help/performance/search/ua_help_content_toc.htm b/org.eclipse.ua.tests/data/help/performance/search/ua_help_content_toc.htm new file mode 100644 index 000000000..aef17b64d --- /dev/null +++ b/org.eclipse.ua.tests/data/help/performance/search/ua_help_content_toc.htm @@ -0,0 +1,95 @@ +<!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 language="JavaScript" src="PLUGINS_ROOT/org.eclipse.help/livehelp.js"></script> +<title>Table of contents (toc) files</title> +</head> +<body> + +<h2>Table of contents (toc) files</h2> + +<P > +Now that we have our sample content files we can create a table of contents (<b>toc</b>) +file. A toc file defines the key entry points into the HTML content files by mapping a topic +label to a reference in one of the HTML files. </P> +<P > +Applications that are being migrated to the platform can reuse existing documentation by +using the toc file to define entry points into that documentation. </P> +<P > +A plug-in can have one or more toc files. Our example documentation is organized into three main categories: concepts, tasks and reference. How do we make +toc files that represent this structure?</P> +<P > +We could make one large toc file, or we could create a separate toc file for each main category of content. This decision should be made according to the way your documentation teams work together. +If a different author owns each category, it might be preferable to keep +separate toc files for each category. It is not dictated by the platform architecture. </P> +<P > +In this example, we will create a toc file for each major content category. For such a small number of files, +having separate toc files for each category may not be necessary. We +will build this example as if we had many more files or had separate authors who +own each content category.</P> +<P > +Our files look like this:</P> + +<H4>toc_Concepts.xml</H4> +<pre> + <toc label="Concepts"> + <topic label="Concept1" href="html/concepts/concept1.html"> + <topic label="Concept1_1" href="html/concepts/concept1_1.html"/> + <topic label="Concept1_2" href="html/concepts/concept1_2.html"/> + </topic> + </toc> +</pre> + +<H4> +toc_Tasks.xml</H4> +<pre> + <toc label="Tasks"> + <topic id="plainTasks" label="Plain Stuff"> + <topic label="Task1" href="html/tasks/task1.html"/> + <topic label="Task2" href="html/tasks/task2.html"/> + </topic> + <topic id="funTasks" label="Fun Stuff" > + <topic label="Task3_1" href="html/tasks/task3_1.html"/> + <topic label="Task3_2" href="html/tasks/task3_2.html"/> + </topic> + </toc> +</pre> + +<H4> +toc_Ref.xml</H4> +<pre> + <toc label="Reference"> + <topic label="Ref1" href="html/ref/ref1.html"/> + <topic label="Ref2" href="html/ref/ref2.html"/> + </toc> +</pre> +<P > + A topic can be a simple link to content. +For example, "Task1" provides a <b>label</b> +and an <b>href</b> linking to the content. A +topic can also be a hierarchical grouping of sub topics with no content of its +own. For example, "Fun Stuff" has only a <b>label</b> +and sub topics, but no <b>href</b> . Topics can +do both, too. "Concept1" has an <b>href</b> +and sub topics. </P> + +<p><b>Dynamic content</b></p> + +<p> +Dynamic content is available for the table of contents in the form of +<a href="ua_dynamic_filters.htm">filters</a> and <a href="ua_dynamic_extensions.htm"> +extensions</a>. For example, you may want a topic to show up in the table of contents +only when running on a specific operating system. +</p> + +<p> +<a href="ua_dynamic_includes.htm">Includes</a> are not supported here because they +are not needed; use <a href="ua_help_content_nested.htm">links</a> instead. +</p> + +</body> +</html> diff --git a/org.eclipse.ua.tests/data/help/performance/search/ua_help_content_xhtml.htm b/org.eclipse.ua.tests/data/help/performance/search/ua_help_content_xhtml.htm new file mode 100644 index 000000000..012fd2472 --- /dev/null +++ b/org.eclipse.ua.tests/data/help/performance/search/ua_help_content_xhtml.htm @@ -0,0 +1,97 @@ +<!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 language="JavaScript" src="PLUGINS_ROOT/org.eclipse.help/livehelp.js"></script> +<title>Contributing XHTML help documents</title> +</head> +<body> + +<h2>Contributing XHTML help documents</h2> + +<p><b>Why use XHTML?</b></p> + +<p> +The help system provides the ability to produce <a href="ua_dynamic.htm">dynamic help +content</a> by annotating your XHTML markup with special tags to +<a href="ua_dynamic_filters.htm">filter</a>, +<a href="ua_dynamic_includes.htm">include</a>, and +<a href="ua_dynamic_extensions.htm">extend</a> documents. These features are not +available when using HTML. +</p> + +<p><b>How to contribute XHTML</b></p> + +<p> +XHTML help documents are contributed in much the same way as HTML, except there +is an important difference that must be there in order to support dynamic content. +</p> + +<ul> + <li> + <p> + If using dyamic content, you <b>must</b> bind the XHTML dynamic content + producer to your doc plugin. + </p> + <p> + If you want to produce dynamic content using the XML annotations, you need + to tell the help system that it should process your documents. This is + done by binding the XHTML dynamic content producer to your plugin. + </p> + <pre> <extension + point="org.eclipse.help.contentProducer"> + <binding producerId="org.eclipse.help.dynamic"/> + </extension></pre> + <p>Since Eclipse 3.4 it is no longer necessary to bind the "org.eclipse.help.base.xhtml" search participant to your + doc plugin.</p> + </li> +</ul> + +<p><a name="include_format"><b>XHTML include format</b></a></p> + +<p> +If you wish to use <a href="ua_dynamic_includes.htm">includes</a> in your XHTML, +the format of the <code>path</code> attribute is as follow: (explained below) +</p> + +<pre> <plugin_id>/<path_to_xhtml_file>/<filename_xhtml>/<element_id> +</pre> + +<p> +Where the fields are: +</p> + +<ul> + <li> + <b>plugin_id</b>: The id of the plug-in containing the content to include + (e.g. <code>org.eclipse.help</code>) + </li> + <li> + <b>path_to_xhtml_file</b>: The plug-in relative path to the file (e.g. <code> + /my_folder/my_sub_folder/</code>) + </li> + <li> + <b>filename_xhtml</b>: The name of the XHTML file, including extension (e.g. + <code>my_file.xhtml</code>) + </li> + <li> + <b>element_id</b>: The unique identifier for the element you wish to include. This + is set by adding an <code>id</code> attribute to that element (e.g. <code> + my.element.id</code>) + </li> +</ul> + +<p> +For example, if you wish to include the paragraph (<code><p></code> element) +with the id <code>my_copyright</code> from the file <code>/copyrights/copyright.xhtml +</code> in plugin <code>my.product.plugin</code>, you would specify the following: +</p> + +<pre> my.product.plugin/copyrights/copyright.xhtml/my_copyright +</pre> + +</body> +</html>
\ No newline at end of file diff --git a/org.eclipse.ua.tests/data/help/performance/search/ua_help_context.htm b/org.eclipse.ua.tests/data/help/performance/search/ua_help_context.htm new file mode 100644 index 000000000..c17bd0891 --- /dev/null +++ b/org.eclipse.ua.tests/data/help/performance/search/ua_help_context.htm @@ -0,0 +1,27 @@ +<!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 language="JavaScript" src="PLUGINS_ROOT/org.eclipse.help/livehelp.js"></script> +<title>Context-sensitive help</title> +</head> +<body> + +<h2>Context-sensitive help</h2> + +<p>A focused set of help topics that is related to the current context can be +shown to users on demand using <b>context-sensitive help</b>. This form of user +assistance is delivered to users when a platform-specific trigger is activated +(e.g. F1 key on Windows, Ctrl+F1 on GTK, Help key on Carbon). Until Eclipse 3.1, +context-sensitive help was presented in infopop windows. Since 3.1, a new Help +view is the preferred way to deliver context-sensitive information to the user.</p> +<p>Context-sensitive help can be associated with widgets statically using +context IDs, or dynamically using context providers. The new help view also adds +dynamic help capability by searching help for topics relevant for the current +context.</p> + +</body> +</html> diff --git a/org.eclipse.ua.tests/data/help/performance/search/ua_help_context_dynamic.htm b/org.eclipse.ua.tests/data/help/performance/search/ua_help_context_dynamic.htm new file mode 100644 index 000000000..e9055fec3 --- /dev/null +++ b/org.eclipse.ua.tests/data/help/performance/search/ua_help_context_dynamic.htm @@ -0,0 +1,69 @@ +<!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 language="JavaScript" src="PLUGINS_ROOT/org.eclipse.help/livehelp.js"></script> +<title>Dynamic context help</title> +</head> +<body> + +<h2>Dynamic context help</h2> + +<p> +In addition to statically associating widgets and context Ids, it is possible to +provide this information dynamically for a more dynamic context-sensitive help +capability. Help system uses context Ids to locate the matching +<a href="../reference/api/org/eclipse/help/IContext.html"> +org.eclipse.help.IContext</a> object. The new Help view tracks activation of the +workbench parts (views and editors) and checks if they adapt to +<a href="../reference/api/org/eclipse/help/IContextProvider.html"> +org.eclipse.help.IContextProvider</a> interface. If they do, the view will use +the context provider to locate the <code>IContext</code> object and get the +required information from it. This object can be cached or created on the fly.</p> +<p> +Workbench parts that want to create the context object dynamically should adapt +to the <code>IContextProvider.class</code> object as a key:</p> +<blockquote> + <pre>public Object getAdapter(Class key) { + if (key.equals(IContextProvider.class)) { + return new MyContextProvider(); + } + return super.getAdapter(key); +}</pre> +</blockquote> +<p>The context provider interface requires implementation of three methods:</p> +<blockquote> + <pre>public class MyContextProvider implements IContextProvider { + int getContextChangeMask() { + return NONE; + } + IContext getContext(Object target) { + return myContext; + } + String getSearchExpression(Object target) { + return null; + } +}</pre> +</blockquote> +<p>If context change mask returns <code>NONE</code>, context object will need to +be provided when the workbench part is activated. If <code>SELECTION</code> is +returned, you will need to provide context object that is sensitive to the +current selection in the part. Each time part selection provider fires a +selection change event, the context provider will be asked to provide context +object.</p> +<p>Optionally, search expression for the dynamic help can be provided. +Otherwise, a combination of the part name and perspective name will be used with +good results in most cases. +</p> + +<p> +<b>Note:</b> In addition to using context providers (or alternatively), you can use +XML annotations to <a href="ua_dynamic_filters.htm">filter</a> topics in context +help. +</p> + +</body> +</html> diff --git a/org.eclipse.ua.tests/data/help/performance/search/ua_help_context_id.htm b/org.eclipse.ua.tests/data/help/performance/search/ua_help_context_id.htm new file mode 100644 index 000000000..1c0e98322 --- /dev/null +++ b/org.eclipse.ua.tests/data/help/performance/search/ua_help_context_id.htm @@ -0,0 +1,56 @@ +<!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 language="JavaScript" src="PLUGINS_ROOT/org.eclipse.help/livehelp.js"></script> +<title>Declaring a context id</title> +</head> +<body> + +<h2>Declaring a context id</h2> + +<p> +The <b>setHelp</b> method in +<b><a href="../reference/api/org/eclipse/ui/help/IWorkbenchHelpSystem.html">org.eclipse.ui.help.IWorkbenchHelpSystem</a></b> +is used to associate a context id with a <code>Control</code>, <code>IAction</code>, +<code>Menu</code>, or <code>MenuItem</code>. The context id should be fully +qualified with the plug-in id. For example, the following snippet associates +the id "com.example.helpexample.panic_button" with a button in the +application. +</p> + +<pre>PlatformUI.getWorkbench().getHelpSystem().setHelp(myButton, com.example.helpexample.panic_button);</pre> + +<p> +The following UI controls cannot have context ids (and therefore cannot have +context-sensitive help): +</p> + +<ul> + <li>Toolbar buttons (ToolItem)</li> + <li>CTabItem</li> + <li>TabItem</li> + <li>TableColumn</li> + <li>TableItem</li> + <li>TableTreeItem</li> + <li>TreeItem</li> +</ul> + +<p> +Widgets that do not get focus should not be assigned context ids, since they +will never trigger a context-sensitive help. +</p> + +<p> +<em> +Note: The default implementation of help will display the help dialog tray only if +the dialog is either large enough to accomodate it, or is resizable. Otherwise, +an infopop will be shown. +</em> +</p> + +</body> +</html> diff --git a/org.eclipse.ua.tests/data/help/performance/search/ua_help_context_infopops.htm b/org.eclipse.ua.tests/data/help/performance/search/ua_help_context_infopops.htm new file mode 100644 index 000000000..1db679751 --- /dev/null +++ b/org.eclipse.ua.tests/data/help/performance/search/ua_help_context_infopops.htm @@ -0,0 +1,32 @@ +<!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 language="JavaScript" src="PLUGINS_ROOT/org.eclipse.help/livehelp.js"></script> +<title>Infopops</title> +</head> +<body> + +<h2>Infopops</h2> + +<p>An infopop is a small window associated with a +particular SWT widget in a plug-in's user interface. It displays +context-sensitive help and links to related help topics for the widget. It +is activated when the user puts focus on the widget and presses the <code>F1</code> +key (<code>Ctrl+F1</code> on GTK, and <code>Help</code> key on Carbon).</p> +<p>Since Eclipse 3.1, the preferred way to show the context help is in the help +window. However, it is still possible to configure context help presentation to +use infopops in the Help preferences. For example, here is an infopop that has been defined on +the General/Search page: </p> +<p align="center"> +<img border="0" src="images/infopops.png" alt="Image showing an infopop"> +</p> + +<p>Since Eclipse 3.1, infopops have a link to show the currently displayed +context help in the new Help view.</p> + +</body> +</html> diff --git a/org.eclipse.ua.tests/data/help/performance/search/ua_help_context_xml.htm b/org.eclipse.ua.tests/data/help/performance/search/ua_help_context_xml.htm new file mode 100644 index 000000000..ad7ed8112 --- /dev/null +++ b/org.eclipse.ua.tests/data/help/performance/search/ua_help_context_xml.htm @@ -0,0 +1,110 @@ +<!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 language="JavaScript" src="PLUGINS_ROOT/org.eclipse.help/livehelp.js"></script> +<title>Describing and packaging context-sensitive help content</title> +</head> +<body> + +<h2>Describing and packaging context-sensitive help content</h2> + +<p> +Context-sensitive help is described by associating the context id declared in +the UI code with a description and list of links to related topics or commands +in the online help. These associations are made inside an XML file located +within the plug-in that contains the topics in question. You can create any number +of XML files containing context help associations for each plug-in. The +description and links for each context id is made inside +<strong><context></strong> elements in the XML file. Each context element +can have an optional <strong><description></strong> element which is used +to describe the UI object and any number of <strong><topic></strong> +elements which link to the on-line documentation, as well as command links +to perform any operation for the user, e.g. open a cheat sheet. +</p> + +<p> +Since 3.1, context elements can optionally override the default title used to +present the context help information in the Help view. +</p> + +<pre><contexts> + <context id="panic_button" title="Panic Button Title"> + <description>This is the panic button.</description> + <command serialization="org.eclipse.ui.cheatsheets.openCheatSheet(cheatSheetId=org.eclipse.panic.button.cheatsheet)quot; label="Pushing the panic button"/> + <topic href="reference/panic_button.htm" label="Panic Button Reference"/> + </context> + ... +</contexts> +</pre> + +<p> +Once the contexts have been described in the XML file (or files), you are ready +to refer to the context files in your plug-in manifest. Note that the context id +is not qualified. +</p> + +<p>A plug-in containing context files contributes them using the <b><a href="../reference/extension-points/org_eclipse_help_contexts.html">org.eclipse.help.contexts</a></b> +extension point. +</p> + +<pre> <extension point="org.eclipse.help.contexts"> + <contexts file="myContextHelp.xml" /> + </extension> +</pre> + +<p>You can reference context files from other plug-ins by including the <b>plugin</b> +attribute. This allows you to group all of your documentation, including +content-sensitive help, in one plug-in, and refer to it from the UI code plug-in or some other +related plug-in.</p> + +<pre> <extension point="org.eclipse.help.contexts"> + <contexts file="myContextHelp.xml" <b>plugin</b>="com.example.helpExample" /> + </extension></pre> + +<p>When a context id is declared in an extension point the Eclipse help system will create a fully qualified +context id of the form <code><plug-in name>.<context id></code> and use this when matching against the context +ids used in the Java source. <plug-in name> is the value of the "plugin" attribute, or if not specified the +name of the plug-in in which the org.eclipse.help.contexts extension is declared. + +<h4> +Context-sensitive help from multiple plug-ins</h4> + + +<p>Another level of flexibility is the ability to contribute context-sensitive +help for the +same context id from different plug-ins. This is useful, for example, if +there are different sets of documentation plug-ins that may or may not be +installed in a user's configuration. This allows each documentation +plug-in to declare its contexts independently. The end user will see the +merged context-sensitive help content for all plug-ins that contributed contexts for the +widget's id.</p> + +<p>Note that the plugin attribute must be used in the extensions if multiple plugins will +contribute to the same context. When multiple plug-ins contribute +context-sensitive help for +the same context ID, the content defined in the plug-in that declared the +context (the UI plug-in) is shown first. Additional descriptions and links +are appended in no guaranteed order.</p> + +<h4>Dynamic content</h4> + +<p> +Dynamic content is available for the context help in the form of +<a href="ua_dynamic_filters.htm">filters</a> on context help topic links. For +example, you may want a topic link to show up in the context help only when running +on a specific operating system. +</p> + +<h4> +Adding Context Help to your Java Code</h4> + +<p> +See <a href="ua_help_context_id.htm">declaring a context Id</a> for more +information.</p> + +</body> +</html>
\ No newline at end of file diff --git a/org.eclipse.ua.tests/data/help/performance/search/ua_help_menu.htm b/org.eclipse.ua.tests/data/help/performance/search/ua_help_menu.htm new file mode 100644 index 000000000..01041f01b --- /dev/null +++ b/org.eclipse.ua.tests/data/help/performance/search/ua_help_menu.htm @@ -0,0 +1,36 @@ +<!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 language="JavaScript" src="PLUGINS_ROOT/org.eclipse.help/livehelp.js"></script> +<title>Help content</title> +</head> +<body> + +<h2>The Help Menu</h2> + +<p>The Eclipse Platform and SDK contain menu items for Help Contents, Search and +Dynamic Help. A menu item to show the keyword index can be added to the help +menu in an Eclipse based product by adding the following extension point to the +plugin.xml file of the product plugin. The same approach will work equally well +for a Rich Client application.</p> +<p><br> +<extension point="org.eclipse.ui.menus"><br> + <menuContribution locationURI="menu:help?before=group.assist"><br> + <command commandId="org.eclipse.help.ui.indexcommand"<br> + +mnemonic="I"<br> + +style="push"><br> + </command><br> + </menuContribution><br> +</extension></p> + +<pre> +</pre> + +</body> +</html>
\ No newline at end of file diff --git a/org.eclipse.ua.tests/data/help/performance/search/ua_help_search.htm b/org.eclipse.ua.tests/data/help/performance/search/ua_help_search.htm new file mode 100644 index 000000000..c9488e58e --- /dev/null +++ b/org.eclipse.ua.tests/data/help/performance/search/ua_help_search.htm @@ -0,0 +1,26 @@ +<!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 language="JavaScript" src="PLUGINS_ROOT/org.eclipse.help/livehelp.js"></script> +<title>Help search</title> +</head> +<body> + +<h2>Help search</h2> + +<p>Since Eclipse 3.1, search in the workbench has been partitioned into two +major categories: development artifact search and information search. The former +is handled by the search dialog opened from the Search menu. The later is +available from Help>Search menu item which opens the new Help view into the +Search page.</p> +<p>The new information search facility uses multiple search engines run in +parallel using the same search expression. Eclipse provides a number of +preconfigured search engines. New engines can be added programmatically or by +the user. All the results are collated in the Search page directly.</p> + +</body> +</html> diff --git a/org.eclipse.ua.tests/data/help/performance/search/ua_help_search_types.htm b/org.eclipse.ua.tests/data/help/performance/search/ua_help_search_types.htm new file mode 100644 index 000000000..7274700fe --- /dev/null +++ b/org.eclipse.ua.tests/data/help/performance/search/ua_help_search_types.htm @@ -0,0 +1,94 @@ +<!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 language="JavaScript" src="PLUGINS_ROOT/org.eclipse.help/livehelp.js"></script> +<title>Plugging in search engines</title> +</head> +<body> + +<h2>Plugging in search engines</h2> + +<p> +The new federated information search in Help system uses the notion of <b>search +engine types</b> and <b>search engines</b>. An engine type is a meta-engine from +which a number of concrete search engines can be created by parameterization.</p> +<p>New engine types are contributed through the +<a href="../reference/extension-points/org_eclipse_help_ui_searchEngine.html"> +org.eclipse.help.ui.searchEngine</a>:</p> +<blockquote> + <pre><extension point="org.eclipse.help.ui.searchEngine"> + <engineType + scopeFactory="com.example.xyz.XYZScopeFactory" + label="XYZ Search" + class="com.example.xyz.search.XYZSearch" + icon="icons/etool16/xyzsearch.gif" + pageClass="com.example.xyz.search.XYZSearchPage" + id="com.example.xyz.XYZSearch"> + <description> + Instances of XYZ Search search the XYZ site. + </description> + </engineType></pre> +</blockquote> +This extension point is used to plug in search participants in the information +search. Each search engine can be configured individually. When search is +initiated, each search engine is executed as a background job, and the results +are collated in the help view immediately under the query. +<p>Search engines defined here will not automatically show up as federated +search participants until engine product binding is established, unless <code> +productId</code> attribute is left undefined. For engines that define it, only +those bound to a particular product will show up when that product is running. +</p> +<p>Search engines can simply compose a URL and provide only one hit containing +that URL as <code>href</code>. Popular search engines for which API support +requires license can be plugged in like this. On the other end of the spectrum, +search engines can communicate with the server and receive individual hits with +information like label, href, short description, score etc. Local help engine +can produce hits this way.</p> +<p>Regardless of the search mechanism, engines can provide various search scope +settings using JFace preference pages. These pages are shown when 'Advanced +Settings' link is followed from the Help view. In addition to root preference +pages defined with the engine, additional preference sub-pages can be plugged in +for more advanced settings. </p> +<p>Scope settings are loaded and stored using <code>IPreferenceStore</code> +objects. Scope settings for all engines are grouped together under a named <b> +scope set</b>. When first opened, default scope set ('Default') is created, but +users can define more scope sets and flip between them. </p> +<p>Since federated search support is part of <code>org.eclipse.help.base</code> +plug-in, a factory is needed to create search scope objects from the data in the +preference store. Clients that plug in scope preference pages are required to +plug in scope factories as well. </p> +<p>Engines defined in this extension point do not show up in the UI by default. +What is shown there is a concrete <b>instance</b> of a search engine that can be +individually modified. Products can pre-configure the help system with a number +of instances of the registered engine types, possibly parameterized to perform +in a desired way. In addition, users can add their own instances of the +registered engines and configure them to their liking:</p> +<blockquote> + <pre> +<engine + enabled="true" + engineTypeId="com.example.xyz.search.XYZSearch" + id="com.example.xyz.XYZSearch" + label="XYZ Search"> +</engine> +<engine + enabled="true" + engineTypeId="org.eclipse.help.ui.web" + id="org.eclipse.sdk.Eclipse" + label="%search.Eclipse.label"> + <description> + %search.Eclipse.desc + </description> + <param + name="url" + value="http://eclipse.org/search/search.cgi?q={expression}&amp;ul=&amp;ps=20&amp;m=all"> + </param> +</engine></pre> +</blockquote> + +</body> +</html> diff --git a/org.eclipse.ua.tests/data/help/performance/search/ua_help_setup.htm b/org.eclipse.ua.tests/data/help/performance/search/ua_help_setup.htm new file mode 100644 index 000000000..0e8bed319 --- /dev/null +++ b/org.eclipse.ua.tests/data/help/performance/search/ua_help_setup.htm @@ -0,0 +1,61 @@ +<!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 language="JavaScript" src="PLUGINS_ROOT/org.eclipse.help/livehelp.js"></script> +<title>Configuration/setup</title> +</head> +<body> + +<h2>Configuration/setup</h2> + +<p> +This section contains topics related to installing, configuring, and customizing +the help system to work in different environments and products. +</p> + +<h3>Help modes</h3> + +<p> +The help system can run in three modes: workbench (normal), +<a href="ua_help_setup_infocenter.htm">infocenter</a>, and +<a href="ua_help_setup_standalone.htm">standalone</a>. Workbench mode is used +for serving help integrated with the product, usually via a Help menu. This mode +also offers context help and the help view, which are not available in the two other +modes. <strong>Standalone</strong> mode has the same goal as workbench mode, but is +for products that are not eclipse-based (the help will be less integrated). +<strong>Infocenter</strong> mode is used to serve help content to the masses +over the Web. Consult the links above for details. +</p> + +<h3>Rich Client Platform (RCP) support</h3> + +<p> +The Help system is an <em>optional</em> Rich Client Platform (RCP) component. That +is, it is not part of the minimal RCP, but <a href="ua_help_setup_rcp.htm">can be +added</a> to it to provide help in your RCP application. +</p> + +<h3>Product customization</h3> + +<p> +Help provides <a href="ua_help_setup_preferences.htm">preferences</a> that products +can use to <strong>customize</strong> the help system to their needs. These include +ways to customize branding, appearance, turn on/off functionality, etc. +</p> + +<h3>Pre-indexing</h3> + +<p> +For products that offer a large number of help documents, the initial indexing +phase that occurs when searching for the first time can be lengthy. To avoid this +delay, you can <a href="ua_help_setup_preindex.htm">pre-index</a> your help contents +and ship the pre-built index along with your documentation. This is a trade-off +between performance (avoiding the indexing phase) and space (to store the index). +</p> + +</body> +</html> diff --git a/org.eclipse.ua.tests/data/help/performance/search/ua_help_setup_about.htm b/org.eclipse.ua.tests/data/help/performance/search/ua_help_setup_about.htm new file mode 100644 index 000000000..095eaaa70 --- /dev/null +++ b/org.eclipse.ua.tests/data/help/performance/search/ua_help_setup_about.htm @@ -0,0 +1,31 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> +<html> +<head><meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> +<title>Using about.html to debug infocenters</title> +<link rel="stylesheet" href="../book.css" charset="utf-8" type="text/css"> +</head> +<body> + +<h1>Using about.html to debug infocenters</h1> + +<p> +When developing an infocenter sometimes not all of the books show as expected or +customizations do not have the desired effect. The about.html page can be used to get information +about installed plug-ins and help system preferences. If the home page of the help system is +<pre>http://<hostname>:<port>/help/index.jsp</pre> the about page has a url of +<pre>http://<hostname>:<port>/help/about.html</pre> +Without any parameters the about page shows a list of all plug-ins installed on the system. +Parameters can be added to show other kinds of information as follows: +<ul> +<li> +<code>about.html?show=preferences</code> shows the values of the help system preferences. +</li> +<li> +<code>about.html?show=agent</code> shows the user agent information from the Web Browser used to +read the page. +</li> +</ul> +</p> + +</body> +</html> diff --git a/org.eclipse.ua.tests/data/help/performance/search/ua_help_setup_help_data.htm b/org.eclipse.ua.tests/data/help/performance/search/ua_help_setup_help_data.htm new file mode 100644 index 000000000..1ce3f112c --- /dev/null +++ b/org.eclipse.ua.tests/data/help/performance/search/ua_help_setup_help_data.htm @@ -0,0 +1,113 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> +<HTML> +<HEAD><meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> +<title>Help Data</title> +<link rel="stylesheet" href="../schema.css" charset="utf-8" type="text/css"> +<link rel="stylesheet" href="../book.css" charset="utf-8" type="text/css"> +</HEAD> +<BODY> +<CENTER> +<H1>Help Data</H1></CENTER> +<p></p> +<h6 class=CaptionFigColumn id=header>Identifier: </h6>org.eclipse.help.HELP_DATA<p></p> +<h6 class=CaptionFigColumn id=header>Since: </h6>3.3 +<p></p> + +<p></p> +<h6 class=CaptionFigColumn id=header>Description: </h6> +<p>The help data XML file is used by products to control the order of books in the help table of contents, as well whether or not books or keyword index sets should be displayed at all. The file must be referenced in the product's <code>plugin_customization.ini</code> file using the <code>org.eclipse.help/HELP_DATA</code> property.</p> +<h6 class=CaptionFigColumn id=header>Configuration Markup:</h6> +<p class=code id=dtd><!ELEMENT <a name="e.extensions">extensions</a> (<a href="#e.tocOrder">tocOrder</a>? , <a href="#e.hidden">hidden</a>?)></p> +<p></p> +<p class=ConfigMarkup id=elementDesc> +The extension data for Help.</p> +<br><br> +<p class=code id=dtd><!ELEMENT <a name="e.tocOrder">tocOrder</a> (<a href="#e.toc">toc</a> | <a href="#e.category">category</a>)*></p> +<p></p> +<p class=ConfigMarkup id=elementDesc> +Specifies the order in which top-level table of contents entries (also called "books") or categories of books should appear in Help. If one of the items listed is not available, it is ignored. If there are items available that are not listed and not hidden, they will be displayed after the ones listed here.</p> +<br><br> +<p class=code id=dtd><!ELEMENT <a name="e.toc">toc</a> EMPTY></p> +<p class=code id=dtd><!ATTLIST toc</p> +<p class=code id=dtdAttlist>id CDATA #REQUIRED></p> +<p></p> +<p class=ConfigMarkup id=elementDesc> +A reference to a top-level table of contents (TOC) entry, also called a "book".</p> +<br> +<ul class=ConfigMarkup id=attlistDesc> +<li><b>id</b> - The unique identifier for this book. For XML file TOC contributions, this is a path to the file in the form "<code>/<plugin_id>/<path>/<file></code>" (e.g., "<code>/org.eclipse.platform.doc.user/toc.xml</code>"). In general, this is the ID of the <code>TocContribution</code> supplied by its originating <code>AbstractTocProvider</code>.</li> +</ul> +<br><p class=code id=dtd><!ELEMENT <a name="e.category">category</a> EMPTY></p> +<p class=code id=dtd><!ATTLIST category</p> +<p class=code id=dtdAttlist>id CDATA #REQUIRED></p> +<p></p> +<p class=ConfigMarkup id=elementDesc> +A reference to a category of top-level table of contents (TOC) entries (books). Categories are implicitly created when a table of contents contribution declares itself to be of that category, for example, by specifying a <code>category</code> attribute for the <code>toc</code> element in the <code>org.eclipse.help.toc</code> extension point.</p> +<br> +<ul class=ConfigMarkup id=attlistDesc> +<li><b>id</b> - The unique id of the category.</li> +</ul> +<br><p class=code id=dtd><!ELEMENT <a name="e.hidden">hidden</a> (<a href="#e.toc">toc</a> | <a href="#e.category">category</a> | <a href="#e.index">index</a>)*></p> +<p></p> +<p class=ConfigMarkup id=elementDesc> +Contains a set of help items that should be hidden from the user.</p> +<br><br> +<p class=code id=dtd><!ELEMENT <a name="e.index">index</a> EMPTY></p> +<p class=code id=dtd><!ATTLIST index</p> +<p class=code id=dtdAttlist>id CDATA #REQUIRED></p> +<p></p> +<p class=ConfigMarkup id=elementDesc> +A reference to a contribution of help index keywords.</p> +<br> +<ul class=ConfigMarkup id=attlistDesc> +<li><b>id</b> - The unique identifier for this contribution of keywords. For XML file index contributions, this is a path to the file in the form "<code>/<plugin_id>/<path>/<file></code>" (e.g., "<code>/org.eclipse.platform.doc.user/index.xml</code>"). In general, this is the ID of the <code>IndexContribution</code> supplied by its originating <code>AbstractIndexProvider</code>.</li> +</ul> +<br><h6 class=CaptionFigColumn id=header>Examples: </h6><p> +The following example shows how to arrange the following books in the order shown: +</p> + +<ul> +<li>Book #1: "Introduction to XYZ" (category: "<code>user.intro</code>") in <code>/com.xyz.doc.user/introToc.xml</code></li> +<li>Book #2: "Using XYZ" (category: "<code>user.content</code>") in <code>/com.xyz.doc.user/usingToc.xml</code></li> +<li>Book #3: "Troubleshooting" (category: "<code>user.reference</code>") in <code>/com.xyz.doc.user/refToc.xml</code></li> +</ul> + +<p> +As well as hide the following books/categories and related keyword indexes: +</p> + +<ul> +<li>Book #4: "Platform ABC" (category: <code>none</code>) in <code>/org.abc.doc.isv/toc.xml</code></li> +<li>Book #5: "DEF Toolkit" (category: "<code>isv.reference</code>") in <code>/com.def.doc.isv/toc.xml</code></li> +<li>Book #6: "GHI Support" (category: "<code>isv.reference</code>") in <code>/com.ghi.doc.isv/toc.xml</code></li> +</ul> + +<p> +The markup would be the following: +</p> + +<pre> +<font color="#0000ff"><extensions> + <tocOrder> + <toc id=</font><font color="#008000">"/com.xyz.doc.user/introToc.xml"</font><font color="#0000ff">/> + <category id=</font><font color="#008000">"user.content"</font><font color="#0000ff">/> + <toc id=</font><font color="#008000">"/com.xyz.doc.user/refToc.xml"</font><font color="#0000ff">/> + </tocOrder> + <hidden> + <toc id=</font><font color="#008000">"/org.abc.doc.isv/toc.xml"</font><font color="#0000ff">/> + <category id=</font><font color="#008000">"isv.reference"</font><font color="#0000ff">/> + <index id=</font><font color="#008000">"/org.abc.doc.isv/index.xml"</font><font color="#0000ff">/> + <index id=</font><font color="#008000">"/com.def.doc.isv/index.xml"</font><font color="#0000ff">/> + </hidden> +</extensions></font> +</pre> + +<h6 class=CaptionFigColumn id=header>Supplied Implementation: </h6>This API is supported by any help implementation that is based on <code>org.eclipse.help</code>, including the default help implementation provided by Eclipse. +<p class=note id=copyright> +Copyright (c) 2006 IBM Corporation and others.<br> +All rights reserved. This program and the accompanying materials are made +available under the terms of the Eclipse Public License v1.0 which accompanies +this distribution, and is available at <a href="http://www.eclipse.org/legal/epl-v10.html">http://www.eclipse.org/legal/epl-v10.html</a> +</p> +</BODY> +</HTML> diff --git a/org.eclipse.ua.tests/data/help/performance/search/ua_help_setup_infocenter.htm b/org.eclipse.ua.tests/data/help/performance/search/ua_help_setup_infocenter.htm new file mode 100644 index 000000000..6b4863ebb --- /dev/null +++ b/org.eclipse.ua.tests/data/help/performance/search/ua_help_setup_infocenter.htm @@ -0,0 +1,294 @@ +<!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 language="JavaScript" src="PLUGINS_ROOT/org.eclipse.help/livehelp.js"></script> +<title>Infocenter</title> +</head> +<body> + +<h2>Infocenter</h2> + +<p> +You can allow your users to access the help system over the Internet or an +intranet by installing an 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 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 infocenter help system allows passing number of options that can be used to +customize various aspects of the infocenter. 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 infocenter 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 infocenter will recognize and provide customized content for. If + the option is not specified, the 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 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 infocenter 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 infocenter 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 infocenter 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 infocenter 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 infocenter 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 infocenter 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 infocenter</h3> + +<p> +Start the infocenter 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 infocenter (e.g. 8081). For example, from +the machine on which the infocenter is installed, this would be +<code>http://localhost:8081/help/index.jsp</code>. +</p> + +<h3>How to start and stop an infocenter from Java</h3> + +<p> +When including an infocenter 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 infocenter 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 infocenter. 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 Help(options);</pre> + </li> + + <li> + To start the help system: + <pre>infocenter.start();</pre> + </li> + + <li> + To shut down the infocenter: + <pre>infocenter.shutdown();</pre> + </li> +</ol> + +<h3>Making infocenter available on the web</h3> + +<p> +Eclipse contains a complete infocenter 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, one may 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 infocenter. 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 infocenter</h3> + +<p> +Multiple instances of an infocenter 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 infocenter instances with overlapping sets of locales, +you must be ensure 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 +instances. +</p> + +<h3>Filtering</h3> + +<p> +<a href="ua_dynamic_filters.htm">Filtering</a> support is turned +<strong>off</strong> when running in infocenter mode, causing all content, +including filtered content, to be visible. If you intent to host your +documentation in both workbench and infocenter modes, you should use filters in +a way that makes sense even if filtering is turned off. +</p> + +<h3>[Optional] Installing a minimal set of plug-ins</h3> + +<p>The infocenter does not require the entire Eclipse Platform package. It is +possible to run an infocenter with the following plug-ins (located in the +<code>eclipse\plugins</code> directory): +</p> + +<p> +<code> +org.apache.lucene<br> +org.eclipse.core.runtime<br> +org.eclipse.help<br> +org.eclipse.help.appserver<br> +org.eclipse.help.base<br> +org.eclipse.help.webapp<br> +org.eclipse.osgi<br> +org.eclipse.tomcat<br> +org.eclipse.update.configurator<br> +</code> +</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 infocenter 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> diff --git a/org.eclipse.ua.tests/data/help/performance/search/ua_help_setup_nav.htm b/org.eclipse.ua.tests/data/help/performance/search/ua_help_setup_nav.htm new file mode 100644 index 000000000..403a88821 --- /dev/null +++ b/org.eclipse.ua.tests/data/help/performance/search/ua_help_setup_nav.htm @@ -0,0 +1,42 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> +<html> +<head><meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> +<title>Generated navigation topics</title> +<link rel="stylesheet" href="../book.css" charset="utf-8" type="text/css"> +</head> +<body> + +<h1>Generated navigation topics</h1> + +<p> +If a topic in the table of contents does not specify an <code>href</code> attribute, or a toc +element does not specify a <code>topic</code> element, Help will automatically generate a topic +containing the topic's title, a heading to denote the start of the list of subtopics, and an +unordered list of subtopic links (direct subtopics only). +</p> + +<p> +Products may customize the appearance of these generated topics using CSS. Help will look for +a <code>book.css</code> file at the root of the currently running product's plug-in, and will use +this stylesheet to style the generated document. You may rely on the elements with the following +classes to be present in the generated document, and use these to style it: +</p> + +<ul> +<li><code>NavTitle</code>: The class of the heading containing the topic's title.</li> +<li><code>NavListTitle</code>: The class of the heading before the list of topic links.</li> +<li><code>NavList</code>: The class of the list containing the links to the direct subtopics.</li> +</ul> + +<p> +For example, to hide the list bullets, you would use the following CSS rule: +</p> + +<pre> +UL.NavList { + list-style-type: none; +} +</pre> + +</body> +</html> diff --git a/org.eclipse.ua.tests/data/help/performance/search/ua_help_setup_preferences.htm b/org.eclipse.ua.tests/data/help/performance/search/ua_help_setup_preferences.htm new file mode 100644 index 000000000..080eee7d8 --- /dev/null +++ b/org.eclipse.ua.tests/data/help/performance/search/ua_help_setup_preferences.htm @@ -0,0 +1,496 @@ +<!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 language="JavaScript" src="PLUGINS_ROOT/org.eclipse.help/livehelp.js"></script> +<title>Help system customization</title> + +<style type="text/css"> + .deprecated { + color: #444444; + } + .warning { + color: red; + } +</style> + +</head> +<body> + +<h2>Help system customization</h2> + +<p>The Eclipse help system can be configured and branded to suit your +product by +specifying custom defaults for number of help preferences.<br> +</p> +<p>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. +</p> + +<h3>org.eclipse.help plug-in:</h3> + +<table border="1"> + <tbody> + <tr> + <td style="font-weight: bold;">Preference key</td> + <td style="font-weight: bold;">Usage<br> + </td> + <td style="font-weight: bold;">Default</td> + </tr> + <tr> + <td><code>HELP_DATA</code></td> + <td>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, + "<code>helpData.xml</code>" or "PLUGINS_ROOT/org.eclipse.platform/helpData.xml". Consult the + <a href="ua_help_setup_help_data.htm">schema documentation</a> for details.</td> + <td><br></td> + </tr> + <tr> + <td><code class="deprecated">baseTOCS</code> <span class="warning">(deprecated; use <code>HELP_DATA</code> instead)</span></td> + <td><span class="deprecated">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.</span></td> + <td><br></td> + </tr> + <tr> + <td><code class="deprecated">ignoredTOCS</code> <span class="warning">(deprecated; use <code>HELP_DATA</code> instead)</span></td> + <td><span class="deprecated">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.</span></td> + <td><br> + </td> + </tr> + <tr> + <td><code class="deprecated">ignoredIndexes</code> <span class="warning">(deprecated; use <code>HELP_DATA</code> instead)</span></td> + <td><span class="deprecated">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.</span></td> + <td><br> + </td> + </tr> + </tbody> +</table> + +<h3>org.eclipse.help.base plug-in:</h3> + +<table border="1"> + <tbody> + <tr> + <td style="font-weight: bold;">Preference key</td> + <td style="font-weight: bold;">Usage<br> + </td> + <td style="font-weight: bold;">Default</td> + </tr> + <tr> + <td><code>banner</code></td> + <td>Location of the banner page to display in the top frame<br> +Example: <code>banner=/org.eclipse.help.webapp/advanced/banner.html</code></td> + <td><br> + </td> + </tr> + <tr> + <td><code>banner_height</code></td> + <td>Height of the banner frame<br> +Example: <code>banner_height=60</code></td> + <td><br> + </td> + </tr> + <tr> + <td><code>help_home</code></td> + <td>The page to show in the content area when opening help. +Specify your html page as <code>/pluginId/path/to/home.html</code>.</td> + <td><code>/org.eclipse.help.base/doc/help_home.html</code></td> + </tr> + <tr> + <td><code>page_not_found</code></td> + <td>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.</td> + <td><code>/org.eclipse.help.base/doc/page_not_found.html</code></td> + </tr> + <tr> + <td><code>showBreadcrumbs</code></td> + <td>Set to <code>true</code> or <code>false</code> to control the + visibility of breadcrumbs.</td> + <td><code>true</code></td> + </tr> + <tr> + <td><code>bookmarksView</code></td> + <td>Set to <code>true</code> or <code>false</code> to control the + visibility of the bookmarks view.<br> + Note: this option has no effect in the infocenter.</td> + <td><code>true</code></td> + </tr> + <tr> + <td><code>indexView</code></td> + <td>Set to <code>true</code> or <code>false</code> to control the + visibility of the index view.</td> + <td><code>true</code></td> + </tr> + <tr> + <td><code>windowTitlePrefix</code></td> + <td>Set to <code>true</code> or <code>false</code> to control the title of +the browser +window. If <code>true</code>, the +title will have a form "Help - <code><PRODUCT_NAME></code>", +otherwise the title will be +"<code><PRODUCT_NAME></code>", +where <code><PRODUCT_NAME></code> +is the name of +Eclipse product set in the primary feature.</td> + <td><code>true</code></td> + </tr> + <tr> + <td><code>imagesDirectory</code></td> + <td>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 <code>/pluginID/directory</code> +format.</td> + <td><code>images</code></td> + </tr> + <tr> + <td><code>advanced.toolbarBackground</code></td> + <td>CSS background for toolbars. Value is used in browsers +that display advanced help UI.</td> + <td><code>ButtonFace</code></td> + </tr> + <tr> + <td><code>advanced.viewBackground</code></td> + <td>CSS background for navigation views. Value is used in +browsers that display advanced help UI. May be the empty string.</td> + <td><br></td> + </tr> + <tr> + <td><code>advanced.toolbarFont</code></td> + <td>CSS font for toolbars. Value is used in browsers that +display advanced help UI.</td> + <td><code>icon</code></td> + </tr> + <tr> + <td><code>advanced.viewFont</code></td> + <td>CSS font for navigation views. Value is used in browsers +that display advanced help UI.</td> + <td><code>icon</code></td> + </tr> + <tr> + <td><code>advanced.syncDefault</code></td> + <td>The default boolean value for whether the toc should automatically + be synchronized with the contents.</td> + <td><code>true</code></td> + </tr> + <tr> + <td><code>basic.toolbarBackground</code></td> + <td>Background color for toolbars. Value is used in browsers +displaying basic help UI.</td> + <td><code>#D4D0C8</code></td> + </tr> + <tr> + <td><code>basic.viewBackground</code></td> + <td>Background color for navigation views. Value is used in +browsers displaying basic help UI.</td> + <td><code>#FFFFFF</code></td> + </tr> + <tr> + <td><code>locales</code></td> + <td>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 <code>-nl</code> +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.<br> +Example: <code>locales=en ja zh_CN +zh_TW</code></td> + <td><br> + </td> + </tr> + <tr> + <td><code>productIndex</code></td> + <td>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.</td> + <td><br> + </td> + </tr> + <tr> + <td><code>always_external_browser</code></td> + <td style="vertical-align: top;">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.<br> + </td> + <td><code>false</code></td> + </tr> + <tr> + <td><code>default_browser</code></td> + <td><p>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 <code>available()</code> + method must return true on the current system.</p> + <p>This preference controls external browsers in stand-alone help mode. + In the workbench mode, help uses browsers provided by workbench browser + support.</p></td> + <td>default dynamically set based on the browser available on a +given system<br> + </td> + </tr> + <tr> + <td><code>custom_browser_path</code></td> + <td><p>Executable path for custom browser</p> + <p>This preference controls external browsers in stand-alone help mode. + In the workbench mode, help uses browsers provided by workbench browser + support.</p></td> + <td><code>C:\Program Files\Internet Explorer\IEXPLORE.EXE" %1</code> - on +Windows,<br> + <code>"konqueror %1"</code> - on +Linux<br> + <code>"mozilla %1"</code> - on +other platforms + </td> + </tr> + <tr> + <td><code>showDisabledActivityTopics</code></td> + <td>Help system filters topics from disabled +capabilities. This option controls this behavior and existence +of Show All Topics button.<br> +Accepted values: <code>never</code>, <code>off</code>, <code>on</code>, <code>always</code><br> + <code>never</code> - topic from +disabled capabilities are not shown<br> + <code>off</code> - user can +choose to show all topics, disabled topics +initially hidden<br> + <code>on</code> - user can choose +to show all topics, all topics initially +shown<br> + <code>always</code> - topic from +disabled capabilities are shown (filtering +disabled)</td> + <td><code>off</code></td> + </tr> + <tr> + <td><code>activeHelp</code></td> + <td>Allows enabling and disabling execution of active help. +The option has no effect in the infocenter setup, where active help is +disabled.<br> +Accepted values:<br> + <code>true</code> - default +active help actions enabled<br> + <code>false</code> - active help +framework disabled</td> + <td><code>true</code></td> + </tr> + <tr> + <td><code>restrictTopicParameter</code></td> + <td>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.</td> + <td><code>true</code></td> + </tr> + <tr> + <td><code>window_infopop</code></td> + <td>Allows enabling the old-style infopops when help key is pressed in + workbench windows. If false, the new dynamic help view will open + instead.</td> + <td><code>false</code></td> + </tr> + <tr> + <td><code>dialog_infopop</code><br> + </td> + <td>Allows enabling the old-style infopops + when help key is pressed in dialogs. If false, the new dynamic help + window will open instead.<br> + </td> + <td><code>false</code><br> + </td> + </tr> + <tr> + <td>help_view_open_mode</td> + <td>Controls where links in the help view are opened. <br> +Accepted values:<br> + <code>in_place</code> + - open documents in the help view<br> + <code>in_editor</code> - open document in an editor<br> + <code>in_browser</code> - open document in a browser</td> + <td>in_place</td> + </tr> + <tr> + <td><a name="remoteHelp"></a> + <code>remoteHelpOn</code><br> + </td> + <td>Controls whether or not remote help is enabled.<br> +Accepted values:<br> + <code>true</code> - remote help enabled<br> + <code>false</code> - remote help disabled</td> + <td><code>false</code><br></td> + </tr> + <tr> + <td colspan="3">The 5 remote help preferences below can each have multiple + comma separated values if there is more than one infocenter contributing + remote content. </td> + </tr> + <tr> + <td>remoteHostName</td> + <td>Specifies a name for this remote host which will appear in the table + on the preference page</td> + <td> </td> + </tr> + <tr> + <td><code>remoteHelpHost</code><br></td> + <td>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://").</td> + <td><br></td> + </tr> + <tr> + <td><code>remoteHelpPath</code><br> + </td> + <td>Specifies the context root of the Infocenter application running on the + specified host.</td> + <td> </td> + </tr> + <tr> + <td><code>remoteHelpPort</code><br> + </td> + <td>Specifies the port to use to access remote help content.</td> + <td> </td> + </tr> + <tr> + <td>remoteHelpICEnabled</td> + <td>Specifies that the infocenter will contribute remote content</td> + <td> </td> + </tr> + <tr> + <td colspan="3">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.<br> + 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.</td> + </tr> + <tr> + <td><code>topic_css</code></td> + <td>A list of css file(s) to include in every non navigation page served by + help system.</td> + <td > </td> + </tr> + <tr> + <td><code>nav_css</code></td> + <td>A list of css file(s) to include in every navigation page served by + help system</td> + <td ><code>/PRODUCT_PLUGIN/book.css</code></td> + </tr> + <tr> + <td><code>narrow_css</code></td> + <td>A list of css file(s) to include in every page + displayed in the help view or help tray .</td> + <td><code>/PRODUCT_PLUGIN/narrow_book.css,/PRODUCT_PLUGIN/${os}_narrow_book.css</code></td> + </tr> + <tr> + <td><code>disabled_css</code></td> + <td>A list of css file(s) to include in every page + served by help system from a capability that is not enabled..</td> + <td><code>/PRODUCT_PLUGIN/disabled_book.css</code></td> + </tr> + </tbody> +</table> + +<h3 class="deprecated">org.eclipse.help.appserver plug-in:</h3> +<span class="warning">Deprecated: This plug-in is no longer used by help. See table for alternative usage.</span> + +<table border="1"> + <tbody> + <tr> + <td style="font-weight: bold;"><span class="deprecated">Preference key</span></td> + <td style="font-weight: bold;"><span class="deprecated">Usage</span></td> + <td style="font-weight: bold;"><span class="deprecated">Default</span></td> + </tr> + <tr> + <td><code class="deprecated">port</code> <span class="warning">(deprecated)</span></td> + <td><p class="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.</p> +<p class="warning">Start Eclipse with "-vmargs -Dserver_port=<port>" instead</p></td> + <td> </td> + </tr> + <tr> + <td><code class="deprecated">host</code> <span class="warning">(deprecated)</span><br> + </td> + <td><p class="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.</p> + <p class="deprecated">Products using help in local mode (workbench or stand-alone, not infocenter), + can set this preference to "<code>127.0.0.1</code>" to + ensure help server is not exposed to other users on the network.<br> + </p> + <p class="warning">Start Eclipse with "-vmargs -Dserver_host=<host>" instead</p></td> + <td> </td> + </tr> + </tbody> +</table> + +<h3 class="deprecated">org.eclipse.tomcat plug-in:</h3> +<span class="warning">Deprecated: This plug-in is no longer used by help. No alternative commands available.</span> + +<table border="1"> + <tbody> + <tr> + <td style="font-weight: bold;"><span class="deprecated">Preference key</span></td> + <td style="font-weight: bold;"><span class="deprecated">Usage</span></td> + <td style="font-weight: bold;"><span class="deprecated">Default</span></td> + </tr> + <tr> + <td><code class="deprecated">acceptCount</code> <span class="warning">(deprecated)</span></td> + <td><span class="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.</span></td> + <td><code class="deprecated">100</code></td> + </tr> + <tr> + <td><code class="deprecated">maxProcessors</code> <span class="warning">(deprecated)</span><br> + </td> + <td><span class="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.</span> + </td> + <td><code class="deprecated">75</code><br> + </td> + </tr> + <tr> + <td><code class="deprecated">minProcessors</code> <span class="warning">(deprecated)</span><br> + </td> + <td><span class="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.</span> + </td> + <td><code class="deprecated">5</code><br> + </td> + </tr> + </tbody> +</table> +<br> + +</body> +</html>
\ No newline at end of file diff --git a/org.eclipse.ua.tests/data/help/performance/search/ua_help_setup_preindex.htm b/org.eclipse.ua.tests/data/help/performance/search/ua_help_setup_preindex.htm new file mode 100644 index 000000000..185c8476e --- /dev/null +++ b/org.eclipse.ua.tests/data/help/performance/search/ua_help_setup_preindex.htm @@ -0,0 +1,106 @@ +<!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 language="JavaScript" src="PLUGINS_ROOT/org.eclipse.help/livehelp.js"></script> +<title>Pre-indexing documentation</title> +</head> +<body> + +<h2>Pre-indexing documentation</h2> + +<p>When user searches help contents of a product, the search is performed +within a documentation index. By default, this index is created +on the first invocation of help search, but can be pre-built and delivered +to the user with each plug-in, since 3.1, or as a complete index for a product. This +prevents +indexing +from +occurring +on +the user machine and lets the user obtain first search results faster.</p> + +<h3>Building a documentation index for a plug-in.</h3> + +<p>To build an index follow the steps:</p> +<ul> + <li>add an <code>index</code> element to the <code>org.eclipse.help.toc + extension</code> in a documentation plug-in, to specify directory where + index will exist, for example + <pre><extension + point="org.eclipse.help.toc"> + <index + path="index"> + </index> +</extension></pre> + </li> + <li>Add the <code>help.buildHelpIndex</code> ANT task to the build.xml file in + the plugin project by adding the lines below. A build.xml file can be created + by right clinking on MANIFEST.MF in the package explorer and selecting the + menu item PDE Tools/Create Ant Build File. This example build the index for + the default locale and also for "nl/fr". This should be modified to match the + locales which you are using.<pre><target name="build.index" description="Builds search index for the plug-in: org.eclipse.platform.doc.user." if="eclipse.running"> + <help.buildHelpIndex manifest="plugin.xml" destination="."/> + <help.buildHelpIndex manifest="plugin.xml" destination="nl/fr"/> +</target></pre> +</li> + <li>create an index by building the target "build.index". The ant task must be + run in the same JRE as the workspace. To do this right click on build.xml, + select the menu item Run As/Ant build... the ant dialog will appear. On the + targets tab check only "build.index" and on the JRE tab select the radio + button "Run in the same JRE as the workspace". When you hit the + "Run" button the indexes will be built.<br> +</li> +</ul> + +<h3>Building an index for a product</h3> + +<p>Per-product index is a one aggregate index of all documentation in the product. + It should be used in scenarios in which the set of documentation plug-ins is + not changing. For example an info-center installation will benefit + from per-product + index.</p> +<p>To build an index follow the steps:<br> +</p> +<ul> + <li>build a product, including all documentation plug-ins,</li> + <li>create an index for a desired locale by running this command: + + <pre>eclipse -nosplash -application org.eclipse.help.base.indexTool -vmargs -DindexOutput=<i>outputDirectory</i> -DindexLocale=<i>locale</i></pre> +from the directory containing the product. The following arguments +need to be set :<br> + <b>outputDirectory</b> - specifies path of the directory where the index +is to be saved<br> + <b>locale</b> - specifies locale for which the index will be built<br> + </li> +</ul> +<p>For example, running<br> +</p> +<pre>eclipse -nosplash -application org.eclipse.help.base.indexTool -vmargs -DindexOutput=d:/build/com.my.plugin -DindexLocale=en</pre> +<p>will result in file <b>doc_index.zip</b> being saved in the <b>nl/en</b> +directory that will be created under <b>d:/build/com.my.plugin</b>. The +zip will contain index of contents of documents that are available to users +when they run the product in the <b>en</b> locale.<br> +</p> + +<h3>Packaging and Installation of the product's pre-built index</h3> + +Pre-built indices, the <b>doc_index.zip</b> files, need to be packaged as +a plug-in. You can choose to use a plug-in associated with the primary +feature, or choose to package the index for each language into separate fragments.<br> +<br> +For example, if product's documentation is available in three languages, say +English, German and Simplified Chinese, a plug-in com.my.plugin can have the following structure:<br> +<pre>com.my.plugin/<br> plugin.xml<br> nl/<br> de/<br> doc_index.zip<br> en/<br> doc_index.zip<br> zh/<br> CN/<br> doc_index.zip<br> other files of this plugin</pre> +<br> + The ID of the plug-in needs to be specified as a <b>productIndex</b> preference +for org.eclipse.help.base plug-in. For plug-in in the above example, the +plugin_customization.ini +file needs to contain the entry<br> +<pre>org.eclipse.help.base/productIndex=com.my.plugin<br></pre> + +</body> +</html>
\ No newline at end of file diff --git a/org.eclipse.ua.tests/data/help/performance/search/ua_help_setup_rcp.htm b/org.eclipse.ua.tests/data/help/performance/search/ua_help_setup_rcp.htm new file mode 100644 index 000000000..965c06fa9 --- /dev/null +++ b/org.eclipse.ua.tests/data/help/performance/search/ua_help_setup_rcp.htm @@ -0,0 +1,34 @@ +<!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 language="JavaScript" src="PLUGINS_ROOT/org.eclipse.help/livehelp.js"></script> +<title>Rich Client Platform (RCP) help</title> +</head> +<body> + +<h2>Rich Client Platform (RCP) help</h2> + +<p> +The Help system is an <em>optional</em> Rich Client Platform (RCP) component. That +is, it is <em>not</em> part of the minimal RCP, but can be added to it. The following +plug-ins and all of their dependencies, including optional dependencies must be added to the RCP base in order to run the Help system: +</p> + +<p> +<br> +org.eclipse.help.ui<br> +org.eclipse.help.webapp<br> +</p> + +<p> +<em>Note</em>: Help contents will only be made available to the user if there is +content available. If there are no topics in the table of contents, the help will +not be available. +</p> + +</body> +</html>
\ No newline at end of file diff --git a/org.eclipse.ua.tests/data/help/performance/search/ua_help_setup_standalone.htm b/org.eclipse.ua.tests/data/help/performance/search/ua_help_setup_standalone.htm new file mode 100644 index 000000000..8115360af --- /dev/null +++ b/org.eclipse.ua.tests/data/help/performance/search/ua_help_setup_standalone.htm @@ -0,0 +1,154 @@ +<!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 language="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>
\ No newline at end of file diff --git a/org.eclipse.ua.tests/data/help/performance/search/ua_help_war.htm b/org.eclipse.ua.tests/data/help/performance/search/ua_help_war.htm new file mode 100644 index 000000000..376c30d42 --- /dev/null +++ b/org.eclipse.ua.tests/data/help/performance/search/ua_help_war.htm @@ -0,0 +1,59 @@ +<!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 language="JavaScript" src="PLUGINS_ROOT/org.eclipse.help/livehelp.js"></script> +<title>Deploying the infocenter as a Web Archive</title> +</head> +<body> + +<h2>Deploying the infocenter as a Web Archive</h2> + +<p>Using Eclipse 3.4 or later it is possible to configure the help plugins to be deployed +as a web archive (war file) which will act as a fully <br> +functioning infocenter. The instructions below assume a Tomcat server has been +installed, but with minor modifications <br> +these steps should work for any full featured server. <br> +<br> +In your Eclipse installation locate the plugin org.eclipse.help.webapp.<version>.jar +and copy it to a temporary directory, <br> +unzip the copy into that folder.</p> + +<ol> + <li>In the webapp plugin locate the web-archive directory and underneath that +there will be two directories titled "help" and <br> +"org.eclipse.help.infocenter-feature".</li> + <li>Import the org.eclipse.help.infocenter-feature using File->Import->Existing +Project.</li> + <li>Export org.eclipse.help.infocenter-feature as a deployable feature and set +the destination to be +web-archive/help/WEB-INF/eclipse in the area where org.eclipse.help.webapp.<version>.jar +was unzipped.</li> + <li>Add some documentation plugins to the webapps/help/WEB-INF/eclipse/plugins +directory.</li> + <li>Download org.eclipse.equinox.http.servletbridge_<version>.jar and + org.eclipse.equinox.servletbridge_<version>.jar from the + <a href="http://download.eclipse.org/eclipse/equinox/">equinox download site</a>. + Select a version of Equinox that matches the version of Eclipse you are + running to take you to the downloads page.</li> + <li>Extract servletbridge.jar from org.eclipse.equinox.servletbridge_<version>.jar.</li> + <li>Add the file servletbridge.jar to the help/WEB-INF/lib directory. You may +need to create this directory.</li> + <li>Add the file org.eclipse.equinox.http.servletbridge_<version>.jar to the +help/WEB-INFeclipse/plugins directory</li> + <li>At this stage you can create a war file from the help directory or you can +copy the directory and its contents to the webapps +folder of your Tomcat installation.</li> + <li>Start Tomcat and see the help system start up.</li> +</ol>Notes: If you look in the config.ini in the help.war file under directory help/WEB_INF/eclipse/configuration +you will notice the <br> +line eclipse.product=org.eclipse.productname. If your product has help system +customizations in a product plugin you can <br> +activate these by changing this line to point to your product plugin.<br> + + +</body> +</html>
\ No newline at end of file |