Generating Help for Eclipse Plugins

1
Generating Help for Eclipse Plugins

• WritersUA Peer Showcase 2005

2
Overview

• Background Standalone Agitator
• Moving to Eclipse
• The Challenge
• The Solution Expediency over Elegance
• Resources

3
Background What is Agitator?

• Software development tool
• Helps Java programmers test their own code
• Initial releases standalone product, worked with
  IDEs

4
Single-Sourcing Help for Agitator 1.0

• Target formats
• PDF manuals (tutorial and user guides)
• JavaHelp with context-sensitive topics
• Chosen tools FrameMaker WWP
• Separate book files for PDF manuals
• Text insets for material shared across books
• Combined help book file, to simulate merged help
• Book-specific condition tags for each part of
  help book

5
Moving to Eclipse Agitator 2.0

• Eclipse is its own world
• Need to look like we live there
• Eclipse platform has its own help format
• HTML pages, displayed by Eclipse engine
• TOC defined in XML
• Context-sensitive help popups, also defined in
  XML
• No explicit support for back-of-the-book index
• Packaged as Eclipse plugin

6
The Challenge

• Modify docs to use Eclipse terminology
• Integrate help with Eclipse help engine
• During transition, support both standalone
  version and Eclipse prototype
• Continue using single-source process
• No existing WWP templates support Eclipse help
  format directly

7
The Solution Expediency over Elegance

• Start with WWP Dynamic HTML template
• Generates plain HTML pages
• Includes HTML-based index, linked to each
  generated page
• TOC
• FrameMaker no changes
• WWP piggyback on existing TOC macros
• Infopops (context-sensitive topics)
• Write lines of XML directly, rather than
  buffering entries
• New FrameMaker tags and markers
• Corresponding WWP macros

8
Generating the TOC

• The easy part
• Eclipse TOC format
• XML, similar to format for JavaHelp toc.xml
• WWP changes
• Change generated file name to toc.xml
• Modify TOC macros based on JavaHelp template

9
Generating Infopops

• Popup topics for views and dialog boxes
• Press F1 (Windows) or CtrlF1 (Linux)
• Describes specified context
• Provides links into help system

10
Infopops What Eclipse Expects

• ltcontextsgt
• ltcontext id"dialog_addExpression"gt
• ltdescriptiongtThe Add Expression dialog box
  lets you define a new assertion or
  observable expression.lt/descriptiongt
• lttopic href"file_link1.html" label"Add
  Expression Dialog Box"/gt
• lttopic href"file_link2.html"
  label"Observations and Assertions"/gt
• lttopic href"file_link3.html" label"Defining
  and Managing Expressions"/gt lttopic
  href"file_link4.html" label"Agitator Expression
  Syntax"/gtlt/contextgt
• . . .
• lt/contextsgt

11
Defining it in FrameMaker

• New markers and paragraph tags
• All in same file, bounded by markers

EclipseContextsStart
EclipseContext
EclipseTopic
EclipseLink
EclipseLink
EclipseLink
EclipseLinkLast
EclipseContextsEnd
12
WebWorks Processing

• Marker macros delineate entries
• Paragraph macros define contents
• Use WWP _at_WRITE macro to generate XML

ltcontextsgt ltcontext id"dialog_addExpression"gt
ltdescriptiongt The Add Expression dialog box
lets you define a new assertion or
observable expression.lt/descriptiongt lttopic
href"file_link1.html" label "Add
Expression Dialog Box"/gt lttopic
href"file_link2.html" label"Observations
and Assertions"/gt lttopic href"file_link3.ht
ml" label"Agitator Expression Syntax"/gt
lt/contextgt . . . lt/contextsgt
EclipseContextsStart
EclipseContext
EclipseTopic
EclipseLink
EclipseLink
EclipseLinkLast
EclipseContextsEnd
13
Packaging the Help

• Add processing to WWP building block
  BZOnConvertAllEnd
• Collect generated HTML and XML in Zip file
• Copy doc.zip, toc.xml, and contexts.xml to
  separate plugin directory
• Write plugin.xml by hand (one-time task)
• Identifies contents of plugin
• Connects with Eclipse extension points for help
• Integrated with build process
• Place in eclipse/plugins directory and there it
  is

14
The Result
15
Resources

• Eclipses own help search for help
• most of the returned topics are useful
• Eclipse.org Contributing a Little Help
• www.eclipse.org/articles/Article-Online20Help20f
  or202_0/help1.htm
• IBM DeveloperWorks
• www-106.ibm.com/developerworks/opensource/library/
  os-echelp/
• Yahoo Groups
• groups.yahoo.com/group/eclipse_tw
• groups.yahoo.com/group/wwp-users
• For a PDF describing my changes, go to the Files
  sections of both groups
• Generating Help for Eclipse Plugins
• by Martha Kolman-Davidson
  (martha_at_agitar.com)