COSMOS Design 213635

SML-IF editor help not available from F1

This is the design document for bugzilla 213635.

Change History

Name:	Date:	Revised Sections:
David Whiteman	February 26, 2009	Initial version
David Whiteman	March 4, 2009	Purpose and design
David Whiteman	March 5, 2009	Reworked per Ruth Lee feedback to provide view-level help instead of field-level help

Workload Estimation

Rough workload estimate in person weeks

Process	Sizing	Names of people doing the work
Design	0.1	David Whiteman
Code	0.3
Test	0.1
Documentation	0
Build and infrastructure	0.1	Saurabh Dravid
Code review, etc.*	0
TOTAL	0.6

'* - includes other committer work (e.g. check-in, contribution tracking)

Purpose

The purpose of this enhancement is to provide contextual help for the UI in the SML Tooling. The user, when accessing one of the views, will be able to press F1 to display help for that view, taken from the COSMOS User Guide. The implementation will leverage Eclipse functionality for help integration.[1]

Design

A new plug-in will need to be created: org.eclipse.cosmos.rm.smlif.help. This plug-in will hold a contexts.xml file that contains a context for each view; that context will contain a single topic that references the page in the User Guide where that view is described. The plug-in will also hold the necessary parts of the HTML from the User Guide so that the help can be displayed; these can be copied from the HTML documentation source found in CVS into the new plug-in.

Here's an example context declaration:

<context id="smlImportView">
	<topic label="Importing an SML-IF File" href="html/importingsmliffiles.html" />
</context>

Important note: be sure to omit the <description> element from the context, as Eclipse 3.4 has a feature that automatically redirects the help view to the topic when there is no description provided.

The new plug-in will need to be added to the COSMOS RM feature by the RE team, so that it will be included in the download.

The code for building the various UIs in the SML tooling will need to be updated to hook in the help facility. For example (this does not represent actual existing code):

static String CONTEXT_ID_SMLIF_IMPORT_VIEW = "org.eclipse.cosmos.rm.smlif.smlImportView";
 
...
 
PlatformUI.getWorkbench().getHelpSystem().setHelp(composite, CONTEXT_ID_SMLIF_IMPORT_VIEW);

The following packages contain views that require contextual help:

• org.eclipse.cosmos.rm.internal.smlif.dialogs
• org.eclipse.cosmos.rm.internal.smlif.editor
• org.eclipse.cosmos.rm.internal.smlif.export.ui
• org.eclipse.cosmos.rm.internal.smlif.importing.ui
• org.eclipse.cosmos.rm.internal.smlif.newfile.ui

Any future views added to the SML tooling UI will likewise also require updating the new help plug-in.

Resources

1. Eclipse documentation on implementing contextual help