platform-help-home/v2overview.html

Parent Directory Parent Directory | Revision Log Revision Log

Revision 1.4 - (view) (download) (as text)

1 : dbirsan 1.1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
2 : dbirsan 1.4 <html>
3 :     <head><title>Eclipse V2 Help System</title>
4 : dbirsan 1.2 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
5 :    
6 : dbirsan 1.4 <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 : dbirsan 1.3
18 :     <link rel="stylesheet" href="http://dev.eclipse.org/default_style.css" type="text/css">
19 :    
20 : dbirsan 1.4 </head>
21 : dbirsan 1.1
22 : dbirsan 1.4 <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 :     &nbsp;</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 : dbirsan 1.1 help system stripped out of it. Then, your application can make API calls from
62 : dbirsan 1.4 its <b>Help</b> menu, or from UI objects, to launch the help browser. The
63 : dbirsan 1.1 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 : dbirsan 1.4 vary. All features except infopops and active help are supported.<br>
67 :     &nbsp;</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 :     stand-alone help system and the documentation plug-ins on a web server. The
71 :     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 :     features except infopops and active help are supported.</p></li>
76 :     </ol>
77 :     <p>Plug-ins that contribute documentation content
78 :     (&quot;doc plug-ins&quot;) 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 :     <li><b>Bookshelf</b> - The first view, called the bookshelf, contains links to
87 : dbirsan 1.1 collections of online documentation. Clicking one of the links takes you to
88 : dbirsan 1.4 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 :     <li><b>Toggle navigation - </b>A toolbar button allows you to hide or show the
92 :     navigation frame. </li>
93 :     <li><b>Synchronize</b> - Another button allows you to synchronize the
94 : dbirsan 1.1 navigation up with the current topic; this is useful when you have followed a
95 :     link in the topic and want to see where the new topic falls within the
96 : dbirsan 1.4 navigation tree.</li>
97 :     </ul>
98 :     <p>The navigation trees are created with XML, following the help system's TOC
99 : dbirsan 1.1 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 : dbirsan 1.4 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 : dbirsan 1.1 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 : dbirsan 1.4 directory.</li>
124 :     </ul>
125 :     <p><a href="#top"><font size="1">Top</font></a></p>
126 :     <h4><a name="search"></a>Search features</font></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 about the
129 :     engine is available at <a href="http://www.lucene.com">www.lucene.com</a>.
130 :     Eclipse makes no modifications to the Lucene code, but provides a front end and
131 :     other functionality though extensions.</p>
132 :     <ul>
133 :     <li><b>Integration with the workbench</b> - You can search help from within
134 :     the workbench. Click the flashlight toolbar button, or <b>Edit &gt; Search</b>;
135 :     then select the <b>Help Search</b> tab. Results are shown in the Search view.
136 :     Double-click one of the results to open the help browsers to the Search
137 :     Results view and the topic.</li>
138 :     <li><b>In the help system browser</b> - The basic search field is placed in
139 :     the banner, so it is always visible.</li>
140 :     <li><b>Advanced options</b> - Advanced searching options are available by
141 : dbirsan 1.1 clicking the Advanced link near the search field. In the workbench search, the
142 :     options are available right on the Help Search page. Advanced search
143 : dbirsan 1.4 functionality includes:<ul>
144 :     <li><b>Boolean searches </b>- use AND, OR, and binary NOT</li>
145 :     <li><b>Exact string searches</b> - use double-quotation marks</li>
146 :     <li><b>Wildcards</b> - use * for any string or ? for any character</li>
147 :     <li><b>Filtering by book</b> - select which documentation collections (as
148 :     shown on the bookshelf) you want to search in</li>
149 :     </ul>
150 :     </li>
151 :     <li><b>Case-insensitive </b>- can be changed by providing a case sensitive
152 :     extension point.</li>
153 :     <li><b>Stemming </b>- For example, finds &quot;compiling&quot; if you enter &quot;compile&quot;.
154 : dbirsan 1.1 Stemming is provided for English and German, with the ability to add it for
155 : dbirsan 1.4 more languages via extension points.</li>
156 :     <li><b>Stop words</b> - For example, ignores words like &quot;a&quot; and &quot;the&quot; in your
157 : dbirsan 1.1 query. Stop words are provided for English and German, with the ability to add
158 : dbirsan 1.4 it for more languages via extension points.</li>
159 :     <li><b>Results </b>- The results view lists the title tags from the HTML files
160 :     that contain the first 500 hits.</li>
161 :     <li><b>Ranking </b>- the search engine determines the relative ranking of the
162 : dbirsan 1.1 hits by using a complex algorithm based on number of hits, the length of the
163 :     file, and whether there are hits in the title tag. The ranking is shown in the
164 : dbirsan 1.4 results list in terms of a percentage.</li>
165 :     <li><b>Highlighting</b> - For straightforward queries, search term hits are
166 :     highlighted in the topic contents.</li>
167 :     </ul>
168 :     <p>From an exploiting product's standpoint, there is no effort involved in
169 : dbirsan 1.1 getting search to work. The search engine and UI are packaged as plug-ins.
170 :     Indexes are generated the first time the user runs a search. You also have the
171 :     option of pre-generating indexes so that they are available the first time
172 :     search is used (this is particularly useful in the infocenter scenario). Indexes
173 :     are re-generated each time a documentation plug-in is added or removed.
174 :     First-use generation performance is satisfactory for several hundred topics. You
175 : dbirsan 1.4 may want to test if you will be using many more topics.</p>
176 :     <p>The search engine currently searches only HTML. Also, only those topics which
177 :     appear in the navigation tree will be indexed.</p>
178 :     <p><a href="#top"><font size="1">Top</font></a></p>
179 :     <h4><a name="infopop"></a>Context-sensitive help features</font></h4>
180 :     <ol>
181 :     <li><b>Infopops (integrated scenario only)</b><p>An infopop is a small,
182 :     light-weight box that contains a description of a UI widget, and links to
183 :     related topics. To launch an infopop, put focus on the widget (either by
184 :     clicking on it, putting the cursor in it, or pressing Tab until the focus
185 :     indicator is on it), and press F1. If you want more information than what is
186 :     provided in the description, click one of the links. This will open the help
187 :     browser to the Links view and the topic you clicked; the other links from the
188 :     infopop will be listed. </p>
189 :     <p>The UI developer must assign a context ID to each widget that needs an
190 : dbirsan 1.1 infopop. This context ID associates the widget with its infopop content. You
191 : dbirsan 1.4 can register the following kinds of objects for infopops:<ul>
192 :     <li>Control objects, and those that inherit from Control</li>
193 :     <li>IAction </li>
194 :     <li>Menu and MenuItem</li>
195 :     </ul>
196 :     <p>Infopop content is written in XML, following the Contexts DTD, which is
197 : dbirsan 1.1 available in drivers. For each context ID there is a description and
198 :     optionally one or more links. The XML files containing infopop content can be
199 :     packaged in the code plug-in that also contains the UI objects it describes,
200 : dbirsan 1.4 or it can be packaged in another plug-in.</p>
201 :     <p>You can define infopop content for a particular context ID in more than one
202 : dbirsan 1.1 XML file, in more than one plug-in. When an infopop is displayed, content
203 :     defined in the code plug-in itself is listed first; additional descriptions
204 : dbirsan 1.4 and links, if any, are appended to the first set.<br>
205 :     &nbsp;</li>
206 :     <li><b>Launching the help system (integrated, stand-alone, and
207 :     infocenter)</b><p>Any user interface can launch the help browser by calling a
208 :     help system API. This API can take a topic href as an attribute and thus open
209 :     the browser to that topic. <p>Also, it may be launched by running an
210 :     executable, which can also take a URL as a parameter; this lets you set up
211 :     launch points from the desktop or the Windows Start menu, and so on.</li>
212 :     </ol>
213 :     <p><a href="#top"><font size="1">Top</font></a></p>
214 :     <h4><a name="activehelp"></a>Active help features</font></h4>
215 :     <p>In the integrated scenario, a documentation topic can contain a special link
216 : dbirsan 1.1 that calls a class from the workbench. Using this, the user can launch workbench
217 : dbirsan 1.4 actions from the documentation. For example, consider a topic called &quot;Importing
218 :     external plug-ins&quot;. Instead of telling the user to go to the workbench and
219 :     select <b>File &gt; Import</b>, and then select <b>External Plug-ins and Fragments
220 :     </b>and click <b>Next</b>, the topic could simply say &quot;Click here to open the <b>
221 :     Import External Fragments</b> wizard.&quot; The link would call a class you have
222 :     defined, which in turn would open that wizard to that page.</p>
223 :     <p><a href="#top"><font size="1">Top</font></a></p>
224 :     <h4><a name="platform"></a>Platform support</font></h4>
225 :     <p>The help system will be available on:</font></p>
226 :     <ul>
227 :     <li>Windows XP, Windows 2000, Windows 98SE*,
228 :     Windows NT*, Windows ME*</font></li>
229 :     <li>Redhat Linux 7.2 on x86, SuSE Linux 7.3 on x86</font></li>
230 :     <li>Sun Solaris 8 on SPARC</font></li>
231 :     <li>HP-UX 11i on hp9000</font></li>
232 :     <li>IBM AIX 5.1 on PowerPC</font></li>
233 :     </ul>
234 :     <p>*secondary testing status</font></p>
235 :     <p><a href="#top"><font size="1">Top</font></a></p>
236 :     <h4><a name="browser"></a>Browser support</h4>
237 :     <p>The help system displays online documentation inside an HTML viewer provided
238 : dbirsan 1.1 by a Web browser. The standard browsers, such as Internet Explorer, Mozilla,
239 :     Netscape, are pluggable into the help system, but require an adapter. The
240 :     Eclipse help system provides one adapter for each platform, as shown below.
241 :     These adapters are for the system browsers shipped with the OS, except for
242 : dbirsan 1.4 Windows NT where IE must be upgraded to at least v5. </p>
243 :     <table border="1" cellpadding="0" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" width="300">
244 :     <tr>
245 :     <th width="50%">Platform</th>
246 :     <th width="50%">Browser adapter supplied</th>
247 :     </tr>
248 :     <tr>
249 :     <td width="50%">Windows XP</td>
250 :     <td width="50%">Internet Explorer 6</td>
251 :     </tr>
252 :     <tr>
253 :     <td width="50%">Windows 2000</td>
254 :     <td width="50%">Internet Explorer 5</td>
255 :     </tr>
256 :     <tr>
257 :     <td width="50%">Windows 98SE</td>
258 :     <td width="50%">Internet Explorer 5</td>
259 :     </tr>
260 :     <tr>
261 :     <td width="50%">Windows NT</td>
262 :     <td width="50%">Internet Explorer 5+</td>
263 :     </tr>
264 :     <tr>
265 :     <td width="50%">Windows ME</td>
266 :     <td width="50%">Internet Explorer 5.5</td>
267 :     </tr>
268 :     <tr>
269 :     <td width="50%">Redhat Linux 7.2</td>
270 :     <td width="50%">Mozilla 0.9 or greater</td>
271 :     </tr>
272 :     <tr>
273 :     <td width="50%">SuSE Linux 7.3</td>
274 :     <td width="50%">Mozilla 0.9 or greater</td>
275 :     </tr>
276 :     <tr>
277 :     <td width="50%">Sun Solaris 8</td>
278 :     <td width="50%">Netscape 4.7</td>
279 :     </tr>
280 :     <tr>
281 :     <td width="50%">HP-UX 11i</td>
282 :     <td width="50%">Netscape 4.x</td>
283 :     </tr>
284 :     <tr>
285 :     <td width="50%">AIX 5.1</td>
286 :     <td width="50%">Netscape 4.x</td>
287 :     </tr>
288 :     </table>
289 :     <p>For additional information about plans and restrictions, see
290 :     <a href="http://dev.eclipse.org/viewcvs/index.cgi/~checkout~/platform-help-home/eclipse_project_plan_2_0_supported_browsers.html">
291 :     Supported Browsers in Eclipse V2</a>.</p>
292 :     <p>The help system displays better in Mozilla, and best in Internet Explorer.
293 :     </p>
294 :     <p>We recommend you work with and require the browsers listed above. If you want
295 : dbirsan 1.1 your users to use a browser other than the ones listed above, you must ensure
296 :     that it is available on their platform (i.e., you may have to get them to
297 :     install a browser that didn't come with their OS), and you must supply your own
298 : dbirsan 1.4 adapter.</p>
299 :     <p><b>Integrated scenario</b></p>
300 :     <p>There is a Help preferences page that lets the user choose from the available
301 :     browser adapters to select which browser they prefer to view help in.</p>
302 :     <p><b>Stand-alone scenario</b></p>
303 :     <p>If you want to allow users to select among browsers (if more than one adapter
304 :     is available), you must provide your own UI for doing this.</p>
305 :     <p><b>Infocenter scenario</b></p>
306 :     <p>In this scenario, the Web browser <i>is</i> the help browser. It's
307 :     recommended that you use one of the supported browsers (listed above).</p>
308 :     <p><a href="#top"><font size="1">Top</font></a></p>
309 :     <h4><a name="language"></a>Language support</font></h4>
310 :     <p>The help system fully supports Latin-1 locales
311 :     and, on Windows platforms, DBCS locales. The help system will also display BiDi
312 :     navigation and content.</font></p>
313 :     <p><a href="#top"><font size="1">Top</font></a></p>
314 :     <h4><a name="access"></a>Accessibility support</font></h4>
315 :     <ul>
316 :     <li>uses system colors</li>
317 :     <li>uses browser's accessibility support</li>
318 :     <li>can navigate using only the keyboard</li>
319 :     </ul>
320 :     <p><a href="#top"><font size="1">Top</font></a></p>
321 :     <h4><a name="compatibility"></a>Compatibility with previous release</font></h4>
322 :     <p>The design for help content (doc.zip) and infopop
323 :     content has not changed since V1. However, the name of the extension point for help
324 :     contributions has changed, and the XML for creating and merging navigation
325 :     TOC trees has been simplified. This means that plugin.xml and all navigation XML files will need
326 :     a moderate amount of re-writing.</font> V1-level navigation is not supported.</p>
327 :     <p>Also, support for nested contexts and context
328 :     computers for infopops has been removed, meaning that code that registers UI
329 :     objects via arrays or context computers will have to be changed.</font></p>
330 :     <p>Also, support has been removed for putting
331 :     translatable strings from the XML into doc.properties and context.properties.
332 :     Translatable strings must remain in the XML.</font></p>
333 :    
334 :     <p><a href="#top"><font size="1">Top</font></a></p>
335 :    
336 :     </body>
337 :    
338 :     </html>