platform-help-home/v2overview.html

Parent Directory Parent Directory | Revision Log Revision Log

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