platform-help-home/v2overview.html
Parent Directory
| 
Revision Log
Revision 1.7 - (view) (download) (as text)
| 1 : | kkolosow | 1.6 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> |
| 2 : | <html> | ||
| 3 : | <head><title>Eclipse V2 Help System</title> | ||
| 4 : | <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> | ||
| 5 : | |||
| 6 : | <style> | ||
| 7 : | <!-- | ||
| 8 : | a:link { color: #0033CC; text-decoration: none } | ||
| 9 : | a:hover { color: #0033CC; text-decoration: underline } | ||
| 10 : | a:visited { color: #0033CC; text-decoration: none } | ||
| 11 : | li { line-height: 125%; font-size: 10pt } | ||
| 12 : | p { line-height: 125%; font-size: 10pt } | ||
| 13 : | th { font-size: 10pt } | ||
| 14 : | td { font-size: 10pt } | ||
| 15 : | --> | ||
| 16 : | </style> | ||
| 17 : | |||
| 18 : | <link rel="stylesheet" href="http://dev.eclipse.org/default_style.css" type="text/css"> | ||
| 19 : | |||
| 20 : | </head> | ||
| 21 : | |||
| 22 : | <body> | ||
| 23 : | |||
| 24 : | <h3><a name="top"></a>Eclipse V2 Help System - Support and Functionality | ||
| 25 : | Overview</font></h3> | ||
| 26 : | <p>The Eclipse help system is a component of the | ||
| 27 : | Eclipse Platform. It is used for displaying, browsing, searching, and printing | ||
| 28 : | online documentation. It also interacts with the Eclipse-based UIs through | ||
| 29 : | context-sensitive help (launching the help system from the user interface) and | ||
| 30 : | active help (launching a UI action from the help system content).</font></p> | ||
| 31 : | <p>The help system not only presents online | ||
| 32 : | documentation about the Eclipse SDK and tooling, but also lets developers add | ||
| 33 : | their own documentation to it. Also, it can be used apart from the rest of | ||
| 34 : | Eclipse as a help system for non-Eclipse based applications or other projects. | ||
| 35 : | It can be installed either locally or on a web server.</font></p> | ||
| 36 : | <ul> | ||
| 37 : | <li><a href="#scenarios">Scenarios</a></font></li> | ||
| 38 : | <li><a href="#nav">Navigation features</a></font></li> | ||
| 39 : | <li><a href="#content">Content features</a></font></li> | ||
| 40 : | <li><a href="#search">Search features</a></font></li> | ||
| 41 : | <li><a href="#infopop">Context-sensitive help features</a></font></li> | ||
| 42 : | <li><a href="#activehelp">Active help features</a></font></li> | ||
| 43 : | <li><a href="#platform">Platform support</a></font></li> | ||
| 44 : | <li><a href="#browser">Browser support</a></li> | ||
| 45 : | <li><a href="#language">Language support</a></font></li> | ||
| 46 : | <li><a href="#access">Accessibility support</a></font></li> | ||
| 47 : | <li><a href="#compatibility">Compatibility with previous releases</a></font></li> | ||
| 48 : | </ul> | ||
| 49 : | <h4><a name="scenarios"></a>Scenarios</font></h4> | ||
| 50 : | <p>The V2 help system supports the following product | ||
| 51 : | scenarios:</font></p> | ||
| 52 : | <ol> | ||
| 53 : | <li><p><b>Integrated</font> </b>- If you are creating an Eclipse-based product, | ||
| 54 : | the help system is automatically provided. You can launch the help browser from the <b>Help</b> menu in the | ||
| 55 : | workbench, or through infopop links.<br> | ||
| 56 : | </p></li> | ||
| 57 : | <li><p><b>Stand-alone (local)</font></b> - If you are creating an application | ||
| 58 : | that is not based on the Eclipse framework, you can still use the Eclipse help | ||
| 59 : | system. Your application can package and install the <i>stand-alone help | ||
| 60 : | system</i>, a very small version of Eclipse that has had everything except the | ||
| 61 : | help system stripped out of it. Then, your application can make API calls from | ||
| 62 : | its <b>Help</b> menu, or from UI objects, to launch the help browser. The | ||
| 63 : | stand-alone help system has all the features of the integrated help system, as | ||
| 64 : | described in the following sections. However, it interacts with the | ||
| 65 : | application UI for features such as context-sensitive help or active help will | ||
| 66 : | vary. All features except infopops and active help are supported.<br> | ||
| 67 : | </p></li> | ||
| 68 : | <li><p><b>Infocenter (served)</font></b> - You can also allow your users to | ||
| 69 : | access the help system over the Internet or their intranet, by installing the | ||
| 70 : | dbirsan | 1.7 | stand-alone help system and the documentation plug-ins on a server. The |
| 71 : | kkolosow | 1.6 | application accesses the documentation |
| 72 : | by calling a URL, and the help system is shown in their web browser. The | ||
| 73 : | infocenter help system can be used both for client applications and for web | ||
| 74 : | applications, either of which can have their help accessed remotely. All | ||
| 75 : | dbirsan | 1.7 | 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> |
| 76 : | kkolosow | 1.6 | </ol> |
| 77 : | <p>Plug-ins that contribute documentation content | ||
| 78 : | ("doc plug-ins") created for one of these scenarios will work in any of the | ||
| 79 : | scenarios, without any revision (although infopops and active help may not be | ||
| 80 : | supported by your UI).</p> | ||
| 81 : | <p><a href="#top"><font size="1">Top</font></a></p> | ||
| 82 : | <h4><a name="nav"></a>Navigation features</font></h4> | ||
| 83 : | <p>The help browser displays the navigation for the documentation in a frame on | ||
| 84 : | the left-hand side of the window.</p> | ||
| 85 : | <ul> | ||
| 86 : | dbirsan | 1.7 | <li><b>Bookshelf</b> - The first view, called the Contents, contains links to |
| 87 : | kkolosow | 1.6 | collections of online documentation. Clicking one of the links takes you to |
| 88 : | the navigation tree for that collection. </li> | ||
| 89 : | <li><b>Expand/collapse</b> - Browse by clicking the nodes to expand and | ||
| 90 : | collapse the tree, and to display topic content in the right-hand frame.</li> | ||
| 91 : | dbirsan | 1.7 | <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> |
| 92 : | kkolosow | 1.6 | <li><b>Synchronize</b> - Another button allows you to synchronize the |
| 93 : | navigation up with the current topic; this is useful when you have followed a | ||
| 94 : | link in the topic and want to see where the new topic falls within the | ||
| 95 : | navigation tree.</li> | ||
| 96 : | dbirsan | 1.7 | <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> |
| 97 : | kkolosow | 1.6 | </ul> |
| 98 : | <p>The navigation trees are created with XML, following the help system's TOC | ||
| 99 : | DTD which is available in drivers. The XML trees are essentially nested lists of | ||
| 100 : | topic elements, each with an associated label and an optional href (a relative | ||
| 101 : | link to a content file). To form the whole navigation tree, merge together trees | ||
| 102 : | from individual plug-ins or XML files. You can build the tree in either a | ||
| 103 : | bottom-up or a top-down fashion:</p> | ||
| 104 : | <ul> | ||
| 105 : | <li><b>Bottom up</b> - Sub-trees indicate where they want to link to in the | ||
| 106 : | parent tree; the parent tree provides anchor points for sub-trees to link to.</li> | ||
| 107 : | <li><b>Top-down</b> - Parent trees pull in sub-trees by linking to them from | ||
| 108 : | the desired point in the tree.</li> | ||
| 109 : | </ul> | ||
| 110 : | <p><a href="#top"><font size="1">Top</font></a></p> | ||
| 111 : | <h4><a name="content"></a>Content features</font></h4> | ||
| 112 : | <ul> | ||
| 113 : | <li><b>Supported formats</b> - The content frame of the help browser will | ||
| 114 : | display any content format supported by the base browser (see | ||
| 115 : | <a href="#browser">Browser Support</a>). We recommend using HTML, since search | ||
| 116 : | supports it. However, you can display PDF, XML (provided correct style sheets, | ||
| 117 : | XSL, plug-ins, or other client rendering technology is present), and so on.</li> | ||
| 118 : | <li><b>Printing</b> - A toolbar button lets you print the selected topic to a | ||
| 119 : | printer of your choice.</li> | ||
| 120 : | <li><b>Packaging</b> - In a documentation plug-in content can be packaged in a | ||
| 121 : | compressed zip file called doc.zip (with subdirectories, if desired). The help | ||
| 122 : | system treats any file in doc.zip as though it were unzipped in the plug-in | ||
| 123 : | directory.</li> | ||
| 124 : | </ul> | ||
| 125 : | <p><a href="#top"><font size="1">Top</font></a></p> | ||
| 126 : | <h4><a name="search"></a>Search features</h4> | ||
| 127 : | <p>The Eclipse help system provides search functionality via the Lucene search | ||
| 128 : | engine and a front end that is specific to the Eclipse help system. Information | ||
| 129 : | about the engine is available at <a | ||
| 130 : | href="http://www.lucene.com/">http://www.lucene.com/</a>. Eclipse makes no | ||
| 131 : | modifications to the Lucene code, but provides a front end and other | ||
| 132 : | functionality.</P> | ||
| 133 : | <ul> | ||
| 134 : | <li><b>Integration with the workbench</b> - You can search help from within | ||
| 135 : | the workbench. Click the flashlight toolbar button, or <b>Edit > | ||
| 136 : | Search</b>; then select the <b>Help Search</b> tab. Results are shown in the | ||
| 137 : | Search view. Double-click one of the results to open the help browsers to the | ||
| 138 : | Search Results view and the topic. | ||
| 139 : | <li><b>In the help system browser</b> - The basic search field is placed in | ||
| 140 : | the banner, so it is always visible. | ||
| 141 : | dbirsan | 1.7 | <li><b>Advanced options</b> - Advanced search |
| 142 : | kkolosow | 1.6 | functionality includes: |
| 143 : | <ul> | ||
| 144 : | <li><b>Boolean searches </b>- use AND, OR, and binary NOT | ||
| 145 : | <li><b>Phrase searches</b> - use double-quotation marks | ||
| 146 : | <li><b>Wildcards</b> - use * for any string or ? for any character | ||
| 147 : | dbirsan | 1.7 | <li><b>Search scoping</b> - select which documentation collections you want to search in </li></ul> |
| 148 : | kkolosow | 1.6 | <li><b>Results </b>- The results view lists the title tags from the HTML files |
| 149 : | that contain the first 500 hits. | ||
| 150 : | <li><b>Ranking </b>- the search engine determines the relative ranking of the | ||
| 151 : | hits by using a complex algorithm based on number of hits, the length of the | ||
| 152 : | file, and whether there are hits in the title tag. The ranking is shown in the | ||
| 153 : | results list in terms of a percentage. | ||
| 154 : | <li><b>Highlighting</b> - For straightforward queries, search term hits are | ||
| 155 : | highlighted in the topic contents. </li></ul> | ||
| 156 : | |||
| 157 : | <p>Some aspects of search can be controlled by language analyzers that can be | ||
| 158 : | provided through extension for every language. English and German analyzers are | ||
| 159 : | provided. They offer very high quality searches by performing the following: | ||
| 160 : | |||
| 161 : | <ul> | ||
| 162 : | <li><b>Lower-case conversion </b>- results in case-insensitive search. | ||
| 163 : | <li><b>Stemming</b> - For example, | ||
| 164 : | if you enter "compile", the search finds "compiling". | ||
| 165 : | dbirsan | 1.7 | Stemming is not applied to queries enclosed by double quotes.<li><b>Stop word removal</b> - For example, search ignores words like "a" and |
| 166 : | kkolosow | 1.6 | "the" in your query. |
| 167 : | </ul> | ||
| 168 : | <p>If no analyzer is provided for a particular language, a simple default | ||
| 169 : | analyzer will be used. Words composed of English characters or digits can still | ||
| 170 : | be found.</p> | ||
| 171 : | <p>From an exploiting product's standpoint, there is no effort involved in | ||
| 172 : | getting search to work. The search engine and UI are packaged as plug-ins. | ||
| 173 : | Indexes are generated the first time the user runs a search. You also have the | ||
| 174 : | option of pre-generating indexes so that they are available the first time | ||
| 175 : | search is used (this is particularly useful in the infocenter scenario). Indexes | ||
| 176 : | are re-generated each time a documentation plug-in is added or removed. | ||
| 177 : | First-use generation performance is satisfactory for several hundred topics. You | ||
| 178 : | may want to test if you will be using many more topics.</p> | ||
| 179 : | <p>The search engine currently searches only HTML. Also, only those topics which | ||
| 180 : | appear in the navigation tree will be indexed.</p> | ||
| 181 : | <p><a href="#top"><font size=1>Top</font></a></p> | ||
| 182 : | <h4><a name="infopop"></a>Context-sensitive help features</font></h4> | ||
| 183 : | <ol> | ||
| 184 : | <li><b>Infopops (integrated scenario only)</b><p>An infopop is a small, | ||
| 185 : | light-weight box that contains a description of a UI widget, and links to | ||
| 186 : | related topics. To launch an infopop, put focus on the widget (either by | ||
| 187 : | clicking on it, putting the cursor in it, or pressing Tab until the focus | ||
| 188 : | indicator is on it), and press F1. If you want more information than what is | ||
| 189 : | provided in the description, click one of the links. This will open the help | ||
| 190 : | browser to the Links view and the topic you clicked; the other links from the | ||
| 191 : | infopop will be listed. </p> | ||
| 192 : | <p>The UI developer must assign a context ID to each widget that needs an | ||
| 193 : | infopop. This context ID associates the widget with its infopop content. You | ||
| 194 : | can register the following kinds of objects for infopops:<ul> | ||
| 195 : | <li>Control objects, and those that inherit from Control</li> | ||
| 196 : | <li>IAction </li> | ||
| 197 : | <li>Menu and MenuItem</li> | ||
| 198 : | </ul> | ||
| 199 : | <p>Infopop content is written in XML, following the Contexts DTD, which is | ||
| 200 : | available in drivers. For each context ID there is a description and | ||
| 201 : | optionally one or more links. The XML files containing infopop content can be | ||
| 202 : | packaged in the code plug-in that also contains the UI objects it describes, | ||
| 203 : | or it can be packaged in another plug-in.</p> | ||
| 204 : | <p>You can define infopop content for a particular context ID in more than one | ||
| 205 : | XML file, in more than one plug-in. When an infopop is displayed, content | ||
| 206 : | defined in the code plug-in itself is listed first; additional descriptions | ||
| 207 : | and links, if any, are appended to the first set.<br> | ||
| 208 : | </li> | ||
| 209 : | <li><b>Launching the help system (integrated, stand-alone, and | ||
| 210 : | infocenter)</b><p>Any user interface can launch the help browser by calling a | ||
| 211 : | help system API. This API can take a topic href as an attribute and thus open | ||
| 212 : | the browser to that topic. <p>Also, it may be launched by running an | ||
| 213 : | executable, which can also take a URL as a parameter; this lets you set up | ||
| 214 : | launch points from the desktop or the Windows Start menu, and so on.</li> | ||
| 215 : | </ol> | ||
| 216 : | <p><a href="#top"><font size="1">Top</font></a></p> | ||
| 217 : | <h4><a name="activehelp"></a>Active help features</font></h4> | ||
| 218 : | <p>In the integrated scenario, a documentation topic can contain a special link | ||
| 219 : | that calls a class from the workbench. Using this, the user can launch workbench | ||
| 220 : | actions from the documentation. For example, consider a topic called "Importing | ||
| 221 : | external plug-ins". Instead of telling the user to go to the workbench and | ||
| 222 : | select <b>File > Import</b>, and then select <b>External Plug-ins and Fragments | ||
| 223 : | </b>and click <b>Next</b>, the topic could simply say "Click here to open the <b> | ||
| 224 : | Import External Fragments</b> wizard." The link would call a class you have | ||
| 225 : | defined, which in turn would open that wizard to that page.</p> | ||
| 226 : | <p><a href="#top"><font size="1">Top</font></a></p> | ||
| 227 : | <h4><a name="platform"></a>Platform support</font></h4> | ||
| 228 : | <p>The help system will be available on:</font></p> | ||
| 229 : | <ul> | ||
| 230 : | <li>Windows XP, Windows 2000, Windows 98SE*, | ||
| 231 : | Windows NT*, Windows ME*</font></li> | ||
| 232 : | dbirsan | 1.7 | <li>Redhat Linux 8.0on x86, SuSE Linux 8.1 on x86</font></li> |
| 233 : | kkolosow | 1.6 | <li>Sun Solaris 8 on SPARC</font></li> |
| 234 : | <li>HP-UX 11i on hp9000</font></li> | ||
| 235 : | <li>IBM AIX 5.1 on PowerPC</font></li> | ||
| 236 : | </ul> | ||
| 237 : | <p>*secondary testing status</font></p> | ||
| 238 : | <p><a href="#top"><font size="1">Top</font></a></p> | ||
| 239 : | <h4><a name="browser"></a>Browser support</h4> | ||
| 240 : | <p>The help system displays online documentation inside an HTML viewer provided | ||
| 241 : | by a Web browser. The standard browsers, such as Internet Explorer, Mozilla, | ||
| 242 : | Netscape, are pluggable into the help system, but require an adapter. The | ||
| 243 : | Eclipse help system provides one adapter for each platform, as shown below. | ||
| 244 : | These adapters are for the system browsers shipped with the OS, except for | ||
| 245 : | Windows NT where IE must be upgraded to at least v5. </p> | ||
| 246 : | <table border="1" cellpadding="0" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" width="300"> | ||
| 247 : | <tr> | ||
| 248 : | <th width="50%">Platform</th> | ||
| 249 : | <th width="50%">Browser adapter supplied</th> | ||
| 250 : | </tr> | ||
| 251 : | <tr> | ||
| 252 : | <td width="50%">Windows XP</td> | ||
| 253 : | <td width="50%">Internet Explorer 6</td> | ||
| 254 : | </tr> | ||
| 255 : | <tr> | ||
| 256 : | <td width="50%">Windows 2000</td> | ||
| 257 : | dbirsan | 1.7 | <td width="50%">Internet Explorer 5.5 or 6</td> |
| 258 : | kkolosow | 1.6 | </tr> |
| 259 : | <tr> | ||
| 260 : | <td width="50%">Windows 98SE</td> | ||
| 261 : | dbirsan | 1.7 | <td width="50%">Internet Explorer 5.5 or 6</td> |
| 262 : | kkolosow | 1.6 | </tr> |
| 263 : | <tr> | ||
| 264 : | <td width="50%">Windows NT</td> | ||
| 265 : | dbirsan | 1.7 | <td width="50%">Internet Explorer 5.5 or 6</td> |
| 266 : | kkolosow | 1.6 | </tr> |
| 267 : | <tr> | ||
| 268 : | <td width="50%">Windows ME</td> | ||
| 269 : | dbirsan | 1.7 | <td width="50%">Internet Explorer 5.5 or 6</td> |
| 270 : | kkolosow | 1.6 | </tr> |
| 271 : | <tr> | ||
| 272 : | dbirsan | 1.7 | <td width="50%">Redhat Linux 8.0</td> |
| 273 : | <td width="50%">Mozilla 1.0 or greater</td> | ||
| 274 : | kkolosow | 1.6 | </tr> |
| 275 : | <tr> | ||
| 276 : | dbirsan | 1.7 | <td width="50%">SuSE Linux 8.1</td> |
| 277 : | <td width="50%">Mozilla 1.0 or greater</td> | ||
| 278 : | kkolosow | 1.6 | </tr> |
| 279 : | <tr> | ||
| 280 : | <td width="50%">Sun Solaris 8</td> | ||
| 281 : | dbirsan | 1.7 | <td width="50%">Netscape 7 or 4.7</td> |
| 282 : | kkolosow | 1.6 | </tr> |
| 283 : | <tr> | ||
| 284 : | <td width="50%">HP-UX 11i</td> | ||
| 285 : | dbirsan | 1.7 | <td width="50%">Netscape 7 or 4.7</td> |
| 286 : | kkolosow | 1.6 | </tr> |
| 287 : | <tr> | ||
| 288 : | <td width="50%">AIX 5.1</td> | ||
| 289 : | dbirsan | 1.7 | <td width="50%">Netscape 7 or 4.7</td> |
| 290 : | kkolosow | 1.6 | </tr> |
| 291 : | </table> | ||
| 292 : | <p>For additional information about plans and restrictions, see | ||
| 293 : | <a href="http://dev.eclipse.org/viewcvs/index.cgi/~checkout~/platform-help-home/eclipse_project_plan_2_0_supported_browsers.html"> | ||
| 294 : | Supported Browsers in Eclipse V2</a>.</p> | ||
| 295 : | <p>The help system displays better in Mozilla, and best in Internet Explorer. | ||
| 296 : | </p> | ||
| 297 : | <p>We recommend you work with and require the browsers listed above. If you want | ||
| 298 : | your users to use a browser other than the ones listed above, you must ensure | ||
| 299 : | that it is available on their platform (i.e., you may have to get them to | ||
| 300 : | install a browser that didn't come with their OS), and you must supply your own | ||
| 301 : | adapter.</p> | ||
| 302 : | <p><b>Integrated scenario</b></p> | ||
| 303 : | <p>There is a Help preferences page that lets the user choose from the available | ||
| 304 : | browser adapters to select which browser they prefer to view help in.</p> | ||
| 305 : | <p><b>Stand-alone scenario</b></p> | ||
| 306 : | <p>If you want to allow users to select among browsers (if more than one adapter | ||
| 307 : | is available), you must provide your own UI for doing this.</p> | ||
| 308 : | <p><b>Infocenter scenario</b></p> | ||
| 309 : | <p>In this scenario, the Web browser <i>is</i> the help browser. It's | ||
| 310 : | recommended that you use one of the supported browsers (listed above).</p> | ||
| 311 : | <p><a href="#top"><font size="1">Top</font></a></p> | ||
| 312 : | <h4><a name="language"></a>Language support</font></h4> | ||
| 313 : | <p>The help system fully supports Latin-1 locales | ||
| 314 : | and, on Windows platforms, DBCS locales. The help system will also display BiDi | ||
| 315 : | navigation and content.</font></p> | ||
| 316 : | <p><a href="#top"><font size="1">Top</font></a></p> | ||
| 317 : | <h4><a name="access"></a>Accessibility support</font></h4> | ||
| 318 : | <ul> | ||
| 319 : | <li>uses system colors</li> | ||
| 320 : | <li>uses browser's accessibility support</li> | ||
| 321 : | <li>can navigate using only the keyboard</li> | ||
| 322 : | </ul> | ||
| 323 : | <p><a href="#top"><font size="1">Top</font></a></p> | ||
| 324 : | <h4><a name="compatibility"></a>Compatibility with previous release</font></h4> | ||
| 325 : | <p>The design for help content (doc.zip) and infopop | ||
| 326 : | content has not changed since V1. However, the name of the extension point for help | ||
| 327 : | contributions has changed, and the XML for creating and merging navigation | ||
| 328 : | TOC trees has been simplified. This means that plugin.xml and all navigation XML files will need | ||
| 329 : | a moderate amount of re-writing.</font> V1-level navigation is not supported.</p> | ||
| 330 : | <p>Also, support for nested contexts and context | ||
| 331 : | computers for infopops has been removed, meaning that code that registers UI | ||
| 332 : | objects via arrays or context computers will have to be changed.</font></p> | ||
| 333 : | <p>Also, support has been removed for putting | ||
| 334 : | translatable strings from the XML into doc.properties and context.properties. | ||
| 335 : | Translatable strings must remain in the XML.</font></p> | ||
| 336 : | |||
| 337 : | <p><a href="#top"><font size="1">Top</font></a></p> | ||
| 338 : | |||
| 339 : | </body> | ||
| 340 : | |||
| 341 : | dbirsan | 1.4 | </html> |
| help@eclipse.org | ViewVC Help |
| Powered by ViewVC 1.0.3 |