platform-help-home/v2overview.html
Parent Directory
| 
Revision Log
Revision 1.6 -
(download)
(as text)
(annotate)
Tue Mar 4 18:50:51 2003 UTC (6 years, 8 months ago) by kkolosow
Branch: MAIN
Changes since 1.5: +343 -343 lines
Tue Mar 4 18:50:51 2003 UTC (6 years, 8 months ago) by kkolosow
Branch: MAIN
Changes since 1.5: +343 -343 lines
ascii/binary property
<!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 { line-height: 125%; font-size: 10pt }
p { line-height: 125%; font-size: 10pt }
th { font-size: 10pt }
td { font-size: 10pt }
-->
</style>
<link rel="stylesheet" href="http://dev.eclipse.org/default_style.css" type="text/css">
</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="#scenarios">Scenarios</a></font></li>
<li><a href="#nav">Navigation features</a></font></li>
<li><a href="#content">Content features</a></font></li>
<li><a href="#search">Search features</a></font></li>
<li><a href="#infopop">Context-sensitive help features</a></font></li>
<li><a href="#activehelp">Active help features</a></font></li>
<li><a href="#platform">Platform support</a></font></li>
<li><a href="#browser">Browser support</a></li>
<li><a href="#language">Language support</a></font></li>
<li><a href="#access">Accessibility support</a></font></li>
<li><a href="#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>
</p></li>
<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>
</p></li>
<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="#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>
<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>
<li><b>Toggle navigation - </b>A toolbar button allows you to hide or show the
navigation frame. </li>
<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>
<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="#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="#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>
<li><b>Printing</b> - A toolbar button lets you print the selected topic to a
printer of your choice.</li>
<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="#top"><font size="1">Top</font></a></p>
<h4><a name="search"></a>Search features</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.</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 >
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>Phrase 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>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>Some aspects of search can be controlled by language analyzers that can be
provided through extension for every language. English and German analyzers are
provided. They offer very high quality searches by performing the following:
<ul>
<li><b>Lower-case conversion </b>- results in case-insensitive search.
<li><b>Stemming</b> - For example,
if you enter "compile", the search finds "compiling".
<li><b>Stop word removal</b> - For example, search ignores words like "a" and
"the" in your query.
</ul>
<p>If no analyzer is provided for a particular language, a simple default
analyzer will be used. Words composed of English characters or digits can still
be found.</p>
<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="#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>
<li>IAction </li>
<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>
</li>
<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.</li>
</ol>
<p><a href="#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 > 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="#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>
<li>Redhat Linux 7.2 on x86, SuSE Linux 7.3 on x86</font></li>
<li>Sun Solaris 8 on SPARC</font></li>
<li>HP-UX 11i on hp9000</font></li>
<li>IBM AIX 5.1 on PowerPC</font></li>
</ul>
<p>*secondary testing status</font></p>
<p><a href="#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 border="1" cellpadding="0" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" width="300">
<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>
</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="#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="#top"><font size="1">Top</font></a></p>
<h4><a name="access"></a>Accessibility support</font></h4>
<ul>
<li>uses system colors</li>
<li>uses browser's accessibility support</li>
<li>can navigate using only the keyboard</li>
</ul>
<p><a href="#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="#top"><font size="1">Top</font></a></p>
</body>
</html>| help@eclipse.org | ViewVC Help |
| Powered by ViewVC 1.0.3 |