| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> |
| <html> |
| <head><title>Eclipse V2 Help System</title> |
| <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> |
| |
| <style> |
| <!-- |
| a:link { color: #0033CC; text-decoration: none } |
| a:hover { color: #0033CC; text-decoration: underline } |
| a:visited { color: #0033CC; text-decoration: none } |
| li { line-height: 125%; font-size: 10pt } |
| p { line-height: 125%; font-size: 10pt } |
| th { font-size: 10pt } |
| td { font-size: 10pt } |
| --> |
| </style> |
| |
| <link rel="stylesheet" href="http://dev.eclipse.org/default_style.css" type="text/css"> |
| |
| </head> |
| |
| <body> |
| |
| <h3><a name="top"></a>Eclipse V2 Help System - Support and Functionality |
| Overview</font></h3> |
| <p>The Eclipse help system is a component of the |
| Eclipse Platform. It is used for displaying, browsing, searching, and printing |
| online documentation. It also interacts with the Eclipse-based UIs through |
| context-sensitive help (launching the help system from the user interface) and |
| active help (launching a UI action from the help system content).</font></p> |
| <p>The help system not only presents online |
| documentation about the Eclipse SDK and tooling, but also lets developers add |
| their own documentation to it. Also, it can be used apart from the rest of |
| Eclipse as a help system for non-Eclipse based applications or other projects. |
| It can be installed either locally or on a web server.</font></p> |
| <ul> |
| <li><a href="#scenarios">Scenarios</a></font></li> |
| <li><a href="#nav">Navigation features</a></font></li> |
| <li><a href="#content">Content features</a></font></li> |
| <li><a href="#search">Search features</a></font></li> |
| <li><a href="#infopop">Context-sensitive help features</a></font></li> |
| <li><a href="#activehelp">Active help features</a></font></li> |
| <li><a href="#platform">Platform support</a></font></li> |
| <li><a href="#browser">Browser support</a></li> |
| <li><a href="#language">Language support</a></font></li> |
| <li><a href="#access">Accessibility support</a></font></li> |
| <li><a href="#compatibility">Compatibility with previous releases</a></font></li> |
| </ul> |
| <h4><a name="scenarios"></a>Scenarios</font></h4> |
| <p>The V2 help system supports the following product |
| scenarios:</font></p> |
| <ol> |
| <li><p><b>Integrated</font> </b>- If you are creating an Eclipse-based product, |
| the help system is automatically provided. You can launch the help browser from the <b>Help</b> menu in the |
| workbench, or through infopop links.<br> |
| </p></li> |
| <li><p><b>Stand-alone (local)</font></b> - 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 <i>stand-alone help |
| system</i>, a very small version of Eclipse that has had everything except the |
| help system stripped out of it. Then, your application can make API calls from |
| its <b>Help</b> menu, or from UI objects, to launch the help browser. The |
| stand-alone help system has all the features of the integrated help system, as |
| described in the following sections. However, it interacts with the |
| application UI for features such as context-sensitive help or active help will |
| vary. All features except infopops and active help are supported.<br> |
| </p></li> |
| <li><p><b>Infocenter (served)</font></b> - You can also allow your users to |
| access the help system over the Internet or their intranet, by installing the |
| stand-alone help system and the documentation plug-ins on a server. The |
| application accesses the documentation |
| by calling a URL, and the help system is shown in their web browser. The |
| infocenter help system can be used both for client applications and for web |
| applications, either of which can have their help accessed remotely. All |
| features except infopops and active help are supported. Search scoping is done with the Advanced options, not with working sets as in the Integrated and Standalone modes.</p></li> |
| </ol> |
| <p>Plug-ins that contribute documentation content |
| ("doc plug-ins") created for one of these scenarios will work in any of the |
| scenarios, without any revision (although infopops and active help may not be |
| supported by your UI).</p> |
| <p><a href="#top"><font size="1">Top</font></a></p> |
| <h4><a name="nav"></a>Navigation features</font></h4> |
| <p>The help browser displays the navigation for the documentation in a frame on |
| the left-hand side of the window.</p> |
| <ul> |
| <li><b>Bookshelf</b> - The first view, called the Contents, contains links to |
| collections of online documentation. Clicking one of the links takes you to |
| the navigation tree for that collection. </li> |
| <li><b>Expand/collapse</b> - Browse by clicking the nodes to expand and |
| collapse the tree, and to display topic content in the right-hand frame.</li> |
| <li><b>Toggle navigation - </b>Double clicking on the toolbar of the help system frames maximizes the pane or restores it if is already maximized. </li> |
| <li><b>Synchronize</b> - Another button allows you to synchronize the |
| navigation up with the current topic; this is useful when you have followed a |
| link in the topic and want to see where the new topic falls within the |
| navigation tree.</li> |
| <LI><B>Bookmarks</B> - In the Integrated and Standalone scenarios one can bookmark topics using the button available on the toolbar. In infocenter mode, right clicking on a document brings up the browser context menu and the bookmark can be added that way.</LI> |
| </ul> |
| <p>The navigation trees are created with XML, following the help system's TOC |
| DTD which is available in drivers. The XML trees are essentially nested lists of |
| topic elements, each with an associated label and an optional href (a relative |
| link to a content file). To form the whole navigation tree, merge together trees |
| from individual plug-ins or XML files. You can build the tree in either a |
| bottom-up or a top-down fashion:</p> |
| <ul> |
| <li><b>Bottom up</b> - Sub-trees indicate where they want to link to in the |
| parent tree; the parent tree provides anchor points for sub-trees to link to.</li> |
| <li><b>Top-down</b> - Parent trees pull in sub-trees by linking to them from |
| the desired point in the tree.</li> |
| </ul> |
| <p><a href="#top"><font size="1">Top</font></a></p> |
| <h4><a name="content"></a>Content features</font></h4> |
| <ul> |
| <li><b>Supported formats</b> - The content frame of the help browser will |
| display any content format supported by the base browser (see |
| <a href="#browser">Browser Support</a>). We recommend using HTML, since search |
| supports it. However, you can display PDF, XML (provided correct style sheets, |
| XSL, plug-ins, or other client rendering technology is present), and so on.</li> |
| <li><b>Printing</b> - A toolbar button lets you print the selected topic to a |
| printer of your choice.</li> |
| <li><b>Packaging</b> - In a documentation plug-in content can be packaged in a |
| compressed zip file called doc.zip (with subdirectories, if desired). The help |
| system treats any file in doc.zip as though it were unzipped in the plug-in |
| directory.</li> |
| </ul> |
| <p><a href="#top"><font size="1">Top</font></a></p> |
| <h4><a name="search"></a>Search features</h4> |
| <p>The Eclipse help system provides search functionality via the Lucene search |
| engine and a front end that is specific to the Eclipse help system. Information |
| about the engine is available at <a |
| href="http://www.lucene.com/">http://www.lucene.com/</a>. Eclipse makes no |
| modifications to the Lucene code, but provides a front end and other |
| functionality.</P> |
| <ul> |
| <li><b>Integration with the workbench</b> - You can search help from within |
| the workbench. Click the flashlight toolbar button, or <b>Edit > |
| Search</b>; then select the <b>Help Search</b> tab. Results are shown in the |
| Search view. Double-click one of the results to open the help browsers to the |
| Search Results view and the topic. |
| <li><b>In the help system browser</b> - The basic search field is placed in |
| the banner, so it is always visible. |
| <li><b>Advanced options</b> - Advanced search |
| functionality includes: |
| <ul> |
| <li><b>Boolean searches </b>- use AND, OR, and binary NOT |
| <li><b>Phrase searches</b> - use double-quotation marks |
| <li><b>Wildcards</b> - use * for any string or ? for any character |
| <li><b>Search scoping</b> - select which documentation collections you want to search in </li></ul> |
| <li><b>Results </b>- The results view lists the title tags from the HTML files |
| that contain the first 500 hits. |
| <li><b>Ranking </b>- the search engine determines the relative ranking of the |
| hits by using a complex algorithm based on number of hits, the length of the |
| file, and whether there are hits in the title tag. The ranking is shown in the |
| results list in terms of a percentage. |
| <li><b>Highlighting</b> - For straightforward queries, search term hits are |
| highlighted in the topic contents. </li></ul> |
| |
| <p>Some aspects of search can be controlled by language analyzers that can be |
| provided through extension for every language. English and German analyzers are |
| provided. They offer very high quality searches by performing the following: |
| |
| <ul> |
| <li><b>Lower-case conversion </b>- results in case-insensitive search. |
| <li><b>Stemming</b> - For example, |
| if you enter "compile", the search finds "compiling". |
| Stemming is not applied to queries enclosed by double quotes.<li><b>Stop word removal</b> - For example, search ignores words like "a" and |
| "the" in your query. |
| </ul> |
| <p>If no analyzer is provided for a particular language, a simple default |
| analyzer will be used. Words composed of English characters or digits can still |
| be found.</p> |
| <p>From an exploiting product's standpoint, there is no effort involved in |
| getting search to work. The search engine and UI are packaged as plug-ins. |
| Indexes are generated the first time the user runs a search. You also have the |
| option of pre-generating indexes so that they are available the first time |
| search is used (this is particularly useful in the infocenter scenario). Indexes |
| are re-generated each time a documentation plug-in is added or removed. |
| First-use generation performance is satisfactory for several hundred topics. You |
| may want to test if you will be using many more topics.</p> |
| <p>The search engine currently searches only HTML. Also, only those topics which |
| appear in the navigation tree will be indexed.</p> |
| <p><a href="#top"><font size=1>Top</font></a></p> |
| <h4><a name="infopop"></a>Context-sensitive help features</font></h4> |
| <ol> |
| <li><b>Infopops (integrated scenario only)</b><p>An infopop is a small, |
| light-weight box that contains a description of a UI widget, and links to |
| related topics. To launch an infopop, put focus on the widget (either by |
| clicking on it, putting the cursor in it, or pressing Tab until the focus |
| indicator is on it), and press F1. If you want more information than what is |
| provided in the description, click one of the links. This will open the help |
| browser to the Links view and the topic you clicked; the other links from the |
| infopop will be listed. </p> |
| <p>The UI developer must assign a context ID to each widget that needs an |
| infopop. This context ID associates the widget with its infopop content. You |
| can register the following kinds of objects for infopops:<ul> |
| <li>Control objects, and those that inherit from Control</li> |
| <li>IAction </li> |
| <li>Menu and MenuItem</li> |
| </ul> |
| <p>Infopop content is written in XML, following the Contexts DTD, which is |
| available in drivers. For each context ID there is a description and |
| optionally one or more links. The XML files containing infopop content can be |
| packaged in the code plug-in that also contains the UI objects it describes, |
| or it can be packaged in another plug-in.</p> |
| <p>You can define infopop content for a particular context ID in more than one |
| XML file, in more than one plug-in. When an infopop is displayed, content |
| defined in the code plug-in itself is listed first; additional descriptions |
| and links, if any, are appended to the first set.<br> |
| </li> |
| <li><b>Launching the help system (integrated, stand-alone, and |
| infocenter)</b><p>Any user interface can launch the help browser by calling a |
| help system API. This API can take a topic href as an attribute and thus open |
| the browser to that topic. <p>Also, it may be launched by running an |
| executable, which can also take a URL as a parameter; this lets you set up |
| launch points from the desktop or the Windows Start menu, and so on.</li> |
| </ol> |
| <p><a href="#top"><font size="1">Top</font></a></p> |
| <h4><a name="activehelp"></a>Active help features</font></h4> |
| <p>In the integrated scenario, a documentation topic can contain a special link |
| that calls a class from the workbench. Using this, the user can launch workbench |
| actions from the documentation. For example, consider a topic called "Importing |
| external plug-ins". Instead of telling the user to go to the workbench and |
| select <b>File > Import</b>, and then select <b>External Plug-ins and Fragments |
| </b>and click <b>Next</b>, the topic could simply say "Click here to open the <b> |
| Import External Fragments</b> wizard." The link would call a class you have |
| defined, which in turn would open that wizard to that page.</p> |
| <p><a href="#top"><font size="1">Top</font></a></p> |
| <h4><a name="platform"></a>Platform support</font></h4> |
| <p>The help system will be available on:</font></p> |
| <ul> |
| <li>Windows XP, Windows 2000, Windows 98SE*, |
| Windows NT*, Windows ME*</font></li> |
| <li>Redhat Linux 8.0on x86, SuSE Linux 8.1 on x86</font></li> |
| <li>Sun Solaris 8 on SPARC</font></li> |
| <li>HP-UX 11i on hp9000</font></li> |
| <li>IBM AIX 5.1 on PowerPC</font></li> |
| </ul> |
| <p>*secondary testing status</font></p> |
| <p><a href="#top"><font size="1">Top</font></a></p> |
| <h4><a name="browser"></a>Browser support</h4> |
| <p>The help system displays online documentation inside an HTML viewer provided |
| by a Web browser. The standard browsers, such as Internet Explorer, Mozilla, |
| Netscape, are pluggable into the help system, but require an adapter. The |
| Eclipse help system provides one adapter for each platform, as shown below. |
| These adapters are for the system browsers shipped with the OS, except for |
| Windows NT where IE must be upgraded to at least v5. </p> |
| <table border="1" cellpadding="0" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" width="300"> |
| <tr> |
| <th width="50%">Platform</th> |
| <th width="50%">Browser adapter supplied</th> |
| </tr> |
| <tr> |
| <td width="50%">Windows XP</td> |
| <td width="50%">Internet Explorer 6</td> |
| </tr> |
| <tr> |
| <td width="50%">Windows 2000</td> |
| <td width="50%">Internet Explorer 5.5 or 6</td> |
| </tr> |
| <tr> |
| <td width="50%">Windows 98SE</td> |
| <td width="50%">Internet Explorer 5.5 or 6</td> |
| </tr> |
| <tr> |
| <td width="50%">Windows NT</td> |
| <td width="50%">Internet Explorer 5.5 or 6</td> |
| </tr> |
| <tr> |
| <td width="50%">Windows ME</td> |
| <td width="50%">Internet Explorer 5.5 or 6</td> |
| </tr> |
| <tr> |
| <td width="50%">Redhat Linux 8.0</td> |
| <td width="50%">Mozilla 1.0 or greater</td> |
| </tr> |
| <tr> |
| <td width="50%">SuSE Linux 8.1</td> |
| <td width="50%">Mozilla 1.0 or greater</td> |
| </tr> |
| <tr> |
| <td width="50%">Sun Solaris 8</td> |
| <td width="50%">Netscape 7 or 4.7</td> |
| </tr> |
| <tr> |
| <td width="50%">HP-UX 11i</td> |
| <td width="50%">Netscape 7 or 4.7</td> |
| </tr> |
| <tr> |
| <td width="50%">AIX 5.1</td> |
| <td width="50%">Netscape 7 or 4.7</td> |
| </tr> |
| </table> |
| <p>For additional information about plans and restrictions, see |
| <a href="http://dev.eclipse.org/viewcvs/index.cgi/~checkout~/platform-help-home/eclipse_project_plan_2_0_supported_browsers.html"> |
| Supported Browsers in Eclipse V2</a>.</p> |
| <p>The help system displays better in Mozilla, and best in Internet Explorer. |
| </p> |
| <p>We recommend you work with and require the browsers listed above. If you want |
| your users to use a browser other than the ones listed above, you must ensure |
| that it is available on their platform (i.e., you may have to get them to |
| install a browser that didn't come with their OS), and you must supply your own |
| adapter.</p> |
| <p><b>Integrated scenario</b></p> |
| <p>There is a Help preferences page that lets the user choose from the available |
| browser adapters to select which browser they prefer to view help in.</p> |
| <p><b>Stand-alone scenario</b></p> |
| <p>If you want to allow users to select among browsers (if more than one adapter |
| is available), you must provide your own UI for doing this.</p> |
| <p><b>Infocenter scenario</b></p> |
| <p>In this scenario, the Web browser <i>is</i> the help browser. It's |
| recommended that you use one of the supported browsers (listed above).</p> |
| <p><a href="#top"><font size="1">Top</font></a></p> |
| <h4><a name="language"></a>Language support</font></h4> |
| <p>The help system fully supports Latin-1 locales |
| and, on Windows platforms, DBCS locales. The help system will also display BiDi |
| navigation and content.</font></p> |
| <p><a href="#top"><font size="1">Top</font></a></p> |
| <h4><a name="access"></a>Accessibility support</font></h4> |
| <ul> |
| <li>uses system colors</li> |
| <li>uses browser's accessibility support</li> |
| <li>can navigate using only the keyboard</li> |
| </ul> |
| <p><a href="#top"><font size="1">Top</font></a></p> |
| <h4><a name="compatibility"></a>Compatibility with previous release</font></h4> |
| <p>The design for help content (doc.zip) and infopop |
| content has not changed since V1. However, the name of the extension point for help |
| contributions has changed, and the XML for creating and merging navigation |
| TOC trees has been simplified. This means that plugin.xml and all navigation XML files will need |
| a moderate amount of re-writing.</font> V1-level navigation is not supported.</p> |
| <p>Also, support for nested contexts and context |
| computers for infopops has been removed, meaning that code that registers UI |
| objects via arrays or context computers will have to be changed.</font></p> |
| <p>Also, support has been removed for putting |
| translatable strings from the XML into doc.properties and context.properties. |
| Translatable strings must remain in the XML.</font></p> |
| |
| <p><a href="#top"><font size="1">Top</font></a></p> |
| |
| </body> |
| |
| </html> |
