platform-help-home/v2overview.html

Parent Directory Parent Directory | Revision Log Revision Log

Revision 1.2 - (download) (as text) (annotate)
Wed Mar 27 18:20:36 2002 UTC (7 years, 8 months ago) by dbirsan
Branch: MAIN
Changes since 1.1: +2 -4 lines 
update with overview document

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML><HEAD><TITLE>Eclipse V2 Help System</TITLE>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">

<STYLE>A:link {
	COLOR: #0033cc; TEXT-DECORATION: none
}
A:hover {
	COLOR: #0033cc; TEXT-DECORATION: underline
}
A:visited {
	COLOR: #0033cc; TEXT-DECORATION: none
}
LI {
	FONT-SIZE: 10pt; LINE-HEIGHT: 125%
}
P {
	FONT-SIZE: 10pt; LINE-HEIGHT: 125%
}
TH {
	FONT-SIZE: 10pt
}
TD {
	FONT-SIZE: 10pt
}
</STYLE>
</HEAD>
<BODY>
<H3><A name=top></A>Eclipse V2 Help System - Support and Functionality 
Overview</FONT></H3>
<P>The Eclipse help system is a component of the Eclipse Platform. It is used 
for displaying, browsing, searching, and printing online documentation. It also 
interacts with the Eclipse-based UIs through context-sensitive help (launching 
the help system from the user interface) and active help (launching a UI action 
from the help system content).</FONT></P>
<P>The help system not only presents online documentation about the Eclipse SDK 
and tooling, but also lets developers add their own documentation to it. Also, 
it can be used apart from the rest of Eclipse as a help system for non-Eclipse 
based applications or other projects. It can be installed either locally or on a 
web server.</FONT></P>
<UL>
  <LI><A 
  href="file:///C:/temp/C.Notes.Data/v2overview.htm#scenarios">Scenarios</A></FONT> 

  <LI><A href="file:///C:/temp/C.Notes.Data/v2overview.htm#nav">Navigation 
  features</A></FONT> 
  <LI><A href="file:///C:/temp/C.Notes.Data/v2overview.htm#content">Content 
  features</A></FONT> 
  <LI><A href="file:///C:/temp/C.Notes.Data/v2overview.htm#search">Search 
  features</A></FONT> 
  <LI><A 
  href="file:///C:/temp/C.Notes.Data/v2overview.htm#infopop">Context-sensitive 
  help features</A></FONT> 
  <LI><A href="file:///C:/temp/C.Notes.Data/v2overview.htm#activehelp">Active 
  help features</A></FONT> 
  <LI><A href="file:///C:/temp/C.Notes.Data/v2overview.htm#platform">Platform 
  support</A></FONT> 
  <LI><A href="file:///C:/temp/C.Notes.Data/v2overview.htm#browser">Browser 
  support</A> 
  <LI><A href="file:///C:/temp/C.Notes.Data/v2overview.htm#language">Language 
  support</A></FONT> 
  <LI><A href="file:///C:/temp/C.Notes.Data/v2overview.htm#access">Accessibility 
  support</A></FONT> 
  <LI><A 
  href="file:///C:/temp/C.Notes.Data/v2overview.htm#compatibility">Compatibility 
  with previous releases</A></FONT> </LI></UL>
<H4><A name=scenarios></A>Scenarios</FONT></H4>
<P>The V2 help system supports the following product scenarios:</FONT></P>
<OL>
  <LI>
  <P><B>Integrated</FONT> </B>- If you are creating an Eclipse-based product, 
  the help system is automatically provided. You can launch the help browser 
  from the <B>Help</B> menu in the workbench, or through infopop 
  links.<BR>&nbsp;</P>
  <LI>
  <P><B>Stand-alone (local)</FONT></B> - If you are creating an application that 
  is not based on the Eclipse framework, you can still use the Eclipse help 
  system. Your application can package and install the <I>stand-alone help 
  system</I>, a very small version of Eclipse that has had everything except the 
  help system stripped out of it. Then, your application can make API calls from 
  its <B>Help</B> menu, or from UI objects, to launch the help browser. The 
  stand-alone help system has all the features of the integrated help system, as 
  described in the following sections. However, it interacts with the 
  application UI for features such as context-sensitive help or active help will 
  vary. All features except infopops and active help are 
supported.<BR>&nbsp;</P>
  <LI>
  <P><B>Infocenter (served)</FONT></B> - You can also allow your users to access 
  the help system over the Internet or their intranet, by installing the 
  stand-alone help system and the documentation plug-ins on a web server. The 
  application accesses the documentation by calling a URL, and the help system 
  is shown in their web browser. The infocenter help system can be used both for 
  client applications and for web applications, either of which can have their 
  help accessed remotely. All features except infopops and active help are 
  supported.</P></LI></OL>
<P>Plug-ins that contribute documentation content ("doc plug-ins") created for 
one of these scenarios will work in any of the scenarios, without any revision 
(although infopops and active help may not be supported by your UI).</P>
<P><A href="file:///C:/temp/C.Notes.Data/v2overview.htm#top"><FONT 
size=1>Top</FONT></A></P>
<H4><A name=nav></A>Navigation features</FONT></H4>
<P>The help browser displays the navigation for the documentation in a frame on 
the left-hand side of the window.</P>
<UL>
  <LI><B>Bookshelf</B> - The first view, called the bookshelf, contains links to 
  collections of online documentation. Clicking one of the links takes you to 
  the navigation tree for that collection. 
  <LI><B>Expand/collapse</B> - Browse by clicking the nodes to expand and 
  collapse the tree, and to display topic content in the right-hand frame. 
  <LI><B>Toggle navigation - </B>A toolbar button allows you to hide or show the 
  navigation frame. 
  <LI><B>Synchronize</B> - Another button allows you to synchronize the 
  navigation up with the current topic; this is useful when you have followed a 
  link in the topic and want to see where the new topic falls within the 
  navigation tree. </LI></UL>
<P>The navigation trees are created with XML, following the help system's TOC 
DTD which is available in drivers. The XML trees are essentially nested lists of 
topic elements, each with an associated label and an optional href (a relative 
link to a content file). To form the whole navigation tree, merge together trees 
from individual plug-ins or XML files. You can build the tree in either a 
bottom-up or a top-down fashion:</P>
<UL>
  <LI><B>Bottom up</B> - Sub-trees indicate where they want to link to in the 
  parent tree; the parent tree provides anchor points for sub-trees to link to. 
  <LI><B>Top-down</B> - Parent trees pull in sub-trees by linking to them from 
  the desired point in the tree. </LI></UL>
<P><A href="file:///C:/temp/C.Notes.Data/v2overview.htm#top"><FONT 
size=1>Top</FONT></A></P>
<H4><A name=content></A>Content features</FONT></H4>
<UL>
  <LI><B>Supported formats</B> - The content frame of the help browser will 
  display any content format supported by the base browser (see <A 
  href="file:///C:/temp/C.Notes.Data/v2overview.htm#browser">Browser 
  Support</A>). We recommend using HTML, since search supports it. However, you 
  can display PDF, XML (provided correct style sheets, XSL, plug-ins, or other 
  client rendering technology is present), and so on. 
  <LI><B>Printing</B> - A toolbar button lets you print the selected topic to a 
  printer of your choice. 
  <LI><B>Packaging</B> - In a documentation plug-in content can be packaged in a 
  compressed zip file called doc.zip (with subdirectories, if desired). The help 
  system treats any file in doc.zip as though it were unzipped in the plug-in 
  directory. </LI></UL>
<P><A href="file:///C:/temp/C.Notes.Data/v2overview.htm#top"><FONT 
size=1>Top</FONT></A></P>
<H4><A name=search></A>Search features</FONT></H4>
<P>The Eclipse help system provides search functionality via the Lucene search 
engine and a front end that is specific to the Eclipse help system. Information 
about the engine is available at <A 
href="http://www.lucene.com/">http://www.lucene.com/</A>. Eclipse makes no 
modifications to the Lucene code, but provides a front end and other 
functionality though extensions.</P>
<UL>
  <LI><B>Integration with the workbench</B> - You can search help from within 
  the workbench. Click the flashlight toolbar button, or <B>Edit &gt; 
  Search</B>; then select the <B>Help Search</B> tab. Results are shown in the 
  Search view. Double-click one of the results to open the help browsers to the 
  Search Results view and the topic. 
  <LI><B>In the help system browser</B> - The basic search field is placed in 
  the banner, so it is always visible. 
  <LI><B>Advanced options</B> - Advanced searching options are available by 
  clicking the Advanced link near the search field. In the workbench search, the 
  options are available right on the Help Search page. Advanced search 
  functionality includes:
  <UL>
    <LI><B>Boolean searches </B>- use AND, OR, and binary NOT 
    <LI><B>Exact string searches</B> - use double-quotation marks 
    <LI><B>Wildcards</B> - use * for any string or ? for any character 
    <LI><B>Filtering by book</B> - select which documentation collections (as 
    shown on the bookshelf) you want to search in </LI></UL>
  <LI><B>Case-insensitive </B>- can be changed by providing a case sensitive 
  extension point. 
  <LI><B>Stemming </B>- For example, finds "compiling" if you enter "compile". 
  Stemming is provided for English and German, with the ability to add it for 
  more languages via extension points. 
  <LI><B>Stop words</B> - For example, ignores words like "a" and "the" in your 
  query. Stop words are provided for English and German, with the ability to add 
  it for more languages via extension points. 
  <LI><B>Results </B>- The results view lists the title tags from the HTML files 
  that contain the first 500 hits. 
  <LI><B>Ranking </B>- the search engine determines the relative ranking of the 
  hits by using a complex algorithm based on number of hits, the length of the 
  file, and whether there are hits in the title tag. The ranking is shown in the 
  results list in terms of a percentage. 
  <LI><B>Highlighting</B> - For straightforward queries, search term hits are 
  highlighted in the topic contents. </LI></UL>
<P>From an exploiting product's standpoint, there is no effort involved in 
getting search to work. The search engine and UI are packaged as plug-ins. 
Indexes are generated the first time the user runs a search. You also have the 
option of pre-generating indexes so that they are available the first time 
search is used (this is particularly useful in the infocenter scenario). Indexes 
are re-generated each time a documentation plug-in is added or removed. 
First-use generation performance is satisfactory for several hundred topics. You 
may want to test if you will be using many more topics.</P>
<P>The search engine currently searches only HTML. Also, only those topics which 
appear in the navigation tree will be indexed.</P>
<P><A href="file:///C:/temp/C.Notes.Data/v2overview.htm#top"><FONT 
size=1>Top</FONT></A></P>
<H4><A name=infopop></A>Context-sensitive help features</FONT></H4>
<OL>
  <LI><B>Infopops (integrated scenario only)</B>
  <P>An infopop is a small, light-weight box that contains a description of a UI 
  widget, and links to related topics. To launch an infopop, put focus on the 
  widget (either by clicking on it, putting the cursor in it, or pressing Tab 
  until the focus indicator is on it), and press F1. If you want more 
  information than what is provided in the description, click one of the links. 
  This will open the help browser to the Links view and the topic you clicked; 
  the other links from the infopop will be listed. </P>
  <P>The UI developer must assign a context ID to each widget that needs an 
  infopop. This context ID associates the widget with its infopop content. You 
  can register the following kinds of objects for infopops:
  <UL>
    <LI>Control objects, and those that inherit from Control 
    <LI>IAction 
    <LI>Menu and MenuItem </LI></UL>
  <P>Infopop content is written in XML, following the Contexts DTD, which is 
  available in drivers. For each context ID there is a description and 
  optionally one or more links. The XML files containing infopop content can be 
  packaged in the code plug-in that also contains the UI objects it describes, 
  or it can be packaged in another plug-in.</P>
  <P>You can define infopop content for a particular context ID in more than one 
  XML file, in more than one plug-in. When an infopop is displayed, content 
  defined in the code plug-in itself is listed first; additional descriptions 
  and links, if any, are appended to the first set.<BR>&nbsp; </P>
  <LI><B>Launching the help system (integrated, stand-alone, and infocenter)</B>
  <P>Any user interface can launch the help browser by calling a help system 
  API. This API can take a topic href as an attribute and thus open the browser 
  to that topic. 
  <P>Also, it may be launched by running an executable, which can also take a 
  URL as a parameter; this lets you set up launch points from the desktop or the 
  Windows Start menu, and so on. </P></LI></OL>
<P><A href="file:///C:/temp/C.Notes.Data/v2overview.htm#top"><FONT 
size=1>Top</FONT></A></P>
<H4><A name=activehelp></A>Active help features</FONT></H4>
<P>In the integrated scenario, a documentation topic can contain a special link 
that calls a class from the workbench. Using this, the user can launch workbench 
actions from the documentation. For example, consider a topic called "Importing 
external plug-ins". Instead of telling the user to go to the workbench and 
select <B>File &gt; Import</B>, and then select <B>External Plug-ins and 
Fragments </B>and click <B>Next</B>, the topic could simply say "Click here to 
open the <B>Import External Fragments</B> wizard." The link would call a class 
you have defined, which in turn would open that wizard to that page.</P>
<P><A href="file:///C:/temp/C.Notes.Data/v2overview.htm#top"><FONT 
size=1>Top</FONT></A></P>
<H4><A name=platform></A>Platform support</FONT></H4>
<P>The help system will be available on:</FONT></P>
<UL>
  <LI>Windows XP, Windows 2000, Windows 98SE*, Windows NT*, Windows ME*</FONT> 
  <LI>Redhat Linux 7.2 on x86, SuSE Linux 7.3 on x86</FONT> 
  <LI>Sun Solaris 8 on SPARC</FONT> 
  <LI>HP-UX 11i on hp9000</FONT> 
  <LI>IBM AIX 5.1 on PowerPC</FONT> </LI></UL>
<P>*secondary testing status</FONT></P>
<P><A href="file:///C:/temp/C.Notes.Data/v2overview.htm#top"><FONT 
size=1>Top</FONT></A></P>
<H4><A name=browser></A>Browser support</H4>
<P>The help system displays online documentation inside an HTML viewer provided 
by a Web browser. The standard browsers, such as Internet Explorer, Mozilla, 
Netscape, are pluggable into the help system, but require an adapter. The 
Eclipse help system provides one adapter for each platform, as shown below. 
These adapters are for the system browsers shipped with the OS, except for 
Windows NT where IE must be upgraded to at least v5. </P>
<TABLE style="BORDER-COLLAPSE: collapse" borderColor=#111111 cellSpacing=0 
cellPadding=0 width=300 border=1>
  <TBODY>
  <TR>
    <TH width="50%">Platform</TH>
    <TH width="50%">Browser adapter supplied</TH></TR>
  <TR>
    <TD width="50%">Windows XP</TD>
    <TD width="50%">Internet Explorer 6</TD></TR>
  <TR>
    <TD width="50%">Windows 2000</TD>
    <TD width="50%">Internet Explorer 5</TD></TR>
  <TR>
    <TD width="50%">Windows 98SE</TD>
    <TD width="50%">Internet Explorer 5</TD></TR>
  <TR>
    <TD width="50%">Windows NT</TD>
    <TD width="50%">Internet Explorer 5+</TD></TR>
  <TR>
    <TD width="50%">Windows ME</TD>
    <TD width="50%">Internet Explorer 5.5</TD></TR>
  <TR>
    <TD width="50%">Redhat Linux 7.2</TD>
    <TD width="50%">Mozilla 0.9 or greater</TD></TR>
  <TR>
    <TD width="50%">SuSE Linux 7.3</TD>
    <TD width="50%">Mozilla 0.9 or greater</TD></TR>
  <TR>
    <TD width="50%">Sun Solaris 8</TD>
    <TD width="50%">Netscape 4.7</TD></TR>
  <TR>
    <TD width="50%">HP-UX 11i</TD>
    <TD width="50%">Netscape 4.x</TD></TR>
  <TR>
    <TD width="50%">AIX 5.1</TD>
    <TD width="50%">Netscape 4.x</TD></TR></TBODY></TABLE>
<P>For additional information about plans and restrictions, see <A 
href="http://dev.eclipse.org/viewcvs/index.cgi/~checkout~/platform-help-home/eclipse_project_plan_2_0_supported_browsers.html">Supported 
Browsers in Eclipse V2</A>.</P>
<P>The help system displays better in Mozilla, and best in Internet Explorer. 
</P>
<P>We recommend you work with and require the browsers listed above. If you want 
your users to use a browser other than the ones listed above, you must ensure 
that it is available on their platform (i.e., you may have to get them to 
install a browser that didn't come with their OS), and you must supply your own 
adapter.</P>
<P><B>Integrated scenario</B></P>
<P>There is a Help preferences page that lets the user choose from the available 
browser adapters to select which browser they prefer to view help in.</P>
<P><B>Stand-alone scenario</B></P>
<P>If you want to allow users to select among browsers (if more than one adapter 
is available), you must provide your own UI for doing this.</P>
<P><B>Infocenter scenario</B></P>
<P>In this scenario, the Web browser <I>is</I> the help browser. It's 
recommended that you use one of the supported browsers (listed above).</P>
<P><A href="file:///C:/temp/C.Notes.Data/v2overview.htm#top"><FONT 
size=1>Top</FONT></A></P>
<H4><A name=language></A>Language support</FONT></H4>
<P>The help system fully supports Latin-1 locales and, on Windows platforms, 
DBCS locales. The help system will also display BiDi navigation and 
content.</FONT></P>
<P><A href="file:///C:/temp/C.Notes.Data/v2overview.htm#top"><FONT 
size=1>Top</FONT></A></P>
<H4><A name=access></A>Accessibility support</FONT></H4>
<UL>
  <LI>uses system colors 
  <LI>uses browser's accessibility support 
  <LI>can navigate using only the keyboard </LI></UL>
<P><A href="file:///C:/temp/C.Notes.Data/v2overview.htm#top"><FONT 
size=1>Top</FONT></A></P>
<H4><A name=compatibility></A>Compatibility with previous release</FONT></H4>
<P>The design for help content (doc.zip) and infopop content has not changed 
since V1. However, the name of the extension point for help contributions has 
changed, and the XML for creating and merging navigation TOC trees has been 
simplified. This means that plugin.xml and all navigation XML files will need a 
moderate amount of re-writing.</FONT> V1-level navigation is not supported.</P>
<P>Also, support for nested contexts and context computers for infopops has been 
removed, meaning that code that registers UI objects via arrays or context 
computers will have to be changed.</FONT></P>
<P>Also, support has been removed for putting translatable strings from the XML 
into doc.properties and context.properties. Translatable strings must remain in 
the XML.</FONT></P>
<P><A href="file:///C:/temp/C.Notes.Data/v2overview.htm#top"><FONT 
size=1>Top</FONT></A></P></BODY></HTML>