platform-help-home/v2overview.html

Parent Directory Parent Directory | Revision Log Revision Log

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