[platform-help-dev] Notes from 10/30 help review

[klicnik@xxxxxxxxxx]

Attached are my notes from the review at OTI.

10/30/2001 Eclipse Help component review

Attendees:

• Dave Thomson (Eclipse project PMC)
• Greg Adams (Eclipse project PMC)
• John Duimovich (Eclipse Tools project PMC)
• Dorian Birsan (Eclipse Help component)
• Vlad Klicnik (Eclipse Help component)

Scenarios to be addressed by Eclipse help:

• [A] Eclipse workbench is the client
• [B] Standalone client - help function integrated into other non-Eclipse-based product. Command-line and in-process invocation
• [C] InfoCenter - help content accessible from browser. No Eclipse function installed on client. All content/ function supplied by server

Design outline:

• adopt a common server-based approach for all 3 scenarios
• use servlets/ jsps/ frames to reender help UI (navigation, content, selected "controls" (see below))
• full web server for scenario [C], Eclipse runtime + Tomcat for scenario [B] and [A]
• abandon current approach of using browser control embedded in workbench in favor of using external browser on ALL platforms. The design rationale is
• embedded browser controls not available on all platforms, ones available are not written to SWT (exception is SWT support for ActiveX)
• open source Java browsers not available at required function/ "quality", not written to SWT
• full function 3rd party Java implementations not open, not written to SWT
• SWT port required for scenario [B] using embedded approach
• Standalone workbench required for scenario [B] using embedded approach (even for IE on Win)
• Modality problems need to be solved for scenario [A] using embedded approach (even for IE on Win)
• define a general framework for controlling external browsers
• intended to become API, but in 2.0 is only used for help only
• need to investigate how much control will be possible
• display URLs (basic capability supported by all)
• window size
• window location
• "kiosk" mode (control over showing menus, toolbars, URL entry, etc)
• ability to open and control multiple windows
• pluggable adaptors for different browsers
• locate configured browser
• map to browser native functions (via args, scripts, etc)
• enable support for "eclipse servlets"
• intended to become API, but in 2.0 is used only for help (incl. "live" help/ "doit" support)
• ability to write servlets as Eclipse extensions
• using in-process Tomcat
• UI team (via Greg) becomes responsible for driving help integration
• calling API to control browser in response to user interactions
• pick up ownership of infopops
• details of control function integration vary by scenario (discussed/ agreed to with Greg only)

Control Function	Scenario [A]	Scenario [B]	Scenario [C]
Help Launch	off Help menu (as today)	depends on product integrating the Eclipse help support	launch browser with URL
F1	F1 as today, incl. infopop support	depends on product integrating the Eclipse help support. The product handles the F1 trigger in its own way and then drives the browser to display the target URL	not applicable (no F1 context)
Search	request: same as scenario [B] *plus* help tab in Eclipse search dialog (because Eclipse users tend to click on Eclipse search button) NOTE: clicking search in browser could just cause the Eclipse search dialog to be displayed at the help tab result: same as scenario [B]	request: dialog window, similar look as Eclipse search dialog tab for help response: links in navigation frame	same as scenario [B]
Bookmarks	using browser function. Expose control in browser to add, view, select bookmark	same as scenario [A]	same as scenario [A]
History (not in 2.0)	not in 2.0	not in 2.0	not in 2.0
Live Help/ "doit" support	using Eclipse-supplied "doit" servlet. Request syntax similar to welcome.xml (href="")	generates "Not supported" response	same as scenario [B]
"Show me" help (animated) (not in 2.0)	same as live help (but the "doit" uses UI robot animation)	generates "Not supported" response	same as scenario [B]
Dynamic Update (new books installed)	restart Eclipse workbench	restart standalone support	recycle servlet using server administration console. Also can be done via URL request to the Eclipse servlet to terminate (next request starts new Eclipse)

• new simplified help contribution mechanism for 2.0 (discussed with Greg only)
• simple <topic> navigation tree
• self-contained navigation, ability to link-up (attach to referenced anchor) and link-down (include referenced topic tree), conditional contributions
• computed books (root nodes), currently no views
• ISSUE: need to consider support for explicitly declared <book> and <view> in addition/ instead of computed books