wiki:GROUP_APP_HELP_R0
Last modified 16 years ago Last modified on 05/15/09 15:13:31

Error: Macro BackLinksMenu(None) failed
compressed data is corrupt

Error: Macro TicketQuery(summary=GROUP_APP_HELP_R0, format=table, col=summary|owner|status|type|component|priority|effort|importance, rows=description|analysis_owners|analysis_reviewers|analysis_score|design_owners|design_reviewers|design_score|implementation_owners|implementation_reviewers|implementation_score|test_owners|test_reviewers|test_score|) failed
current transaction is aborted, commands ignored until end of transaction block

Analysis

Overview

The goal of this task is to provide the ability for Sophie 2 to display help information for the end user. The actual writing of the help content is for another tasks.

Note: if you are writing analysis of a next revision of this task, please read carefully all proposals in this page.

Task requirements

  • The help information should be in HTML format and available both offline and online.
  • Some help content is already available at ITERATION_06/Release/UserDocumentation.
  • For next revisions: Select a better place for the help files in the official website for Sophie 2.
  • Since we'll have different versions of Sophie, for example 2.0, 2.01, 2.1, 2.2, etc., we should support different help content for each of them.
    • In the root directory of the online help information create subdirectory named "2.0".
    • When a new version is released, create a subdirectory, named according to that new version.
    • Each subdirectory should contain the whole HTML content (and only the HTML content, because images can be shared). It is error prone to have only the new pages, because HTML pages from a previous version may have links to pages from that old version, instead of the new. (example: 2.0/a.htm, 2.0/b.htm with link to a.htm; 2.1/a.htm, if we use 2.0/b.htm, there is a link to 2.0/a.htm instead of 2.1/a.htm).
    • If the changes are minor, for example a menu item is renamed, then there is no need to copy the whole content; instead, use the previous version, with updated help page, for example: "The MegaTetris menu (Tetris menu in version 2.0)..." or something similar.
  • There are several ways to display the help content. Some of their pros and cons are listed too.
    • User's default web browser:
      • Pros: displays all kind of rich content - HTML with JavaScript, flash, CSS, etc.
      • Impediments: platform dependency
    • Another option is to use JavaHelp which uses JEditorPane.
      • Pros: platform independent
      • Cons: limited HTML support, so the help content on the web site has to be compatible with it
    • In future revisions we can use Sophie book.
    • For this revision it's appropriate to use JavaHelp.
  • The Help menu in Sophie 2 should contain the following items:
    • &Help Contents - displays the start page of the help information. See the Extensibility section.
    • (in next revisions) &Web site - opens the official website of Sophie 2 in the default web browser.
    • (in next revisions) As&k for Help... - opens a web page (web form, forum, wiki, etc.) where the user can ask anything about the program or propose enhancements. This is related with the next section - the bug report form.
    • Send an &Error Report... - opens the bug report form (see APP_BUG_REPORT_FORM_R0).
    • (separator)
    • &About - displays the about dialog window.
    • in next revisions: Check for &Updates.
    • ("&" means that the following letter will be underlined and used as a keyboard shortcut).
  • For next revisions it will be good to have a Help tab similar to the Search tab - search box and list of results.
  • Extensibility
    • Modules should be able to attach help entries.
    • Each Sophie module can provide (if appropriate) an extension with help information.
    • The extension should contain the relative path of the HelpSet file.
    • The HelpSets are dynamically merged into a single HelpSet.
  • (in next revisions) About dialog
    • Currently there is existing simple about dialog (OldAboutDialog), which displays textual information about the product.
    • Current about dialog should be refactored in order to match the new design of the application.
    • Add the official Sophie 2 logo to the about dialog.
    • It should show the license used in Sophie 2.
    • The dialog should be extensible, at least because there are two products - Author and Reader and each of them has different about information.
    • It's good to have a changelog (for the next revisions).
    • In next revisions may be it is good to display the version of each installed plug-in.
    • The dialog does not have a button to close. Clicking elsewhere hides the dialog.
    • source:/trunk/sophie2-platform/doc/spec-diagrams/AboutDialog.png
    • Discuss each change with Nick first.
  • Tooltips - we already have them, just check for inconsistency.
  • Author and Reader
    • They need different help information.
    • Currently there is no Reader, only an idea.

Task result

  • source code
  • partial help information in html pages

Implementation idea

  • Create a module org.sophie2.main.func.help.
    • Create the menu items.
  • (in next revisions) For the about dialog:
    • Ask for the official logo of Sophie 2.
    • Create an extension point in the help module, to allow the Author and the Reader to display different information.
    • Currently AboutDialog just calls OldAboutDialog.
    • Use setUndecorated(true) in JFrame to remove the about dialog window border.
    • Handle the mouse clicking in R3 style (OperationDef) so the window can be closed with a mouse click.

How to demo

  • Start Sophie 2
  • Show the Help menu
  • Open the contents
  • Close them, then show the About dialog

Design

  • Create a module org.sophie2.main.func.help.
    • Create an extension point for help entries (see below).
    • Create menu item Help Contents.
    • Move all about dialog functionality to the new module.
  • Create a class HelpEntry that represents the JavaHelp's HelpSet that a module can provide.
    • The class should have two fields:
      • helpSetPath - relative path to the corresponding HelpSet file.
      • sortKey - string value which determines the order of this entry in the help contents tree.
  • Create an enum HelpLogic with field DISPLAY_HELP.
    • Construct a HelpSet by merging all HelpSets that are provided by Sophie modules.
    • Create a HelpBroker and display the main help ID.
  • Create a folder help in src/main/resources/distrib.
    • Place all HTML files and images from the user documentation in trac.
      • All links have to be converted to relative
      • All images should be in images subdirectory
      • Create a CSS file that defines appearance similar to that in trac
    • Create JavaHelp files using JHelpDev:
      • HelpSet - SophieHelp.hs (defines the title of the help window, declare what tabs will be available - TOC and Search)
      • Table of contents - SophieHelpTOC.xml (maps titles with IDs, defines the tree structure of the TOC)
      • Map - Map.jhm (maps IDs with URLs)
      • Search index - JavaHelpSearch subdirectory

Implementation

Testing

(Place the testing results here.)

Comments

(Write comments for this or later revisions here.)