platform-help-home/v2overview.html

Parent Directory Parent Directory | Revision Log Revision Log

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