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

Workload Estimation

Rough workload estimate in person weeks

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

'* - 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 brief description for each field. It will also hold the necessary parts of the HTML from the User Guide so they can be linked from the field-specific help; 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="smlImportDestinationDirectory">
	<description>Enter the directory of the SML repository where you want to import the SML-IF file.  See also:</description>
	<topic label="Importing an SML-IF File" href="html/importingsmliffiles.html" />
</context>

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_DESTINATION_DIR = "org.eclipse.cosmos.rm.smlif.smlImportDestinationDirectory";
 
...
 
this.destinationDirTextField = Utilities.createLabelTextPair(composite, getDestinationDirLabel(), destinationDirInitialContents, false);
PlatformUI.getWorkbench().getHelpSystem().setHelp(this.destinationDirTextField, CONTEXT_ID_DESTINATION_DIR);

The following packages contain views with input fields 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 fields added to the SML tooling UI will likewise also require updating the new help plug-in.

Resources

1. Eclipse documentation on implementing contextual help