platform-help-home/v2overview.html

Parent Directory Parent Directory | Revision Log Revision Log

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

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