wiki:GROUP_APP_HELP_R0

Version 10 (modified by mitex, 16 years ago) (diff)

--

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.

Task requirements

  • The help information should be in HTML format and available online. This has the following advantages:
    • quick access from everywhere
    • easily updateable (fixed wrong help information, adding more information, etc.)
    • easy to create rich text content with text formatting, links, images, menus with JavaScript, etc.
    • searchable by google and other search engines (if we use a Sophie book for the help, this will be hard to achieve)
  • Select a place for the help files in the official website for Sophie 2.
  • Provide search functionality in the site.
  • Some help content is available at ITERATION_06/Release/UserDocumentation.
  • 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).
  • 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 JEditorPane instead of a browser.
      • Pros: platform independent
      • Cons: limited functionality, so the help content on the web site has to be compatible with it
    • In future revisions we can use embedded browser.
    • For this revision it's appropriate to use the user's default web browser.
  • 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.
    • &Search... - opens the search page in the website.
      • for next revisions it will be good to have a Help tab similar to the Search tab - search box and list of results.
    • &Web site - opens the official website of Sophie 2 in the default web browser.
    • 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).
  • Extensibility
    • Modules should be able to attach help entries.
    • Each Sophie module can provide (if appropriate) an extension with help information. This extension may contain:
      • URL of the help information of the module.
        • Can point to the sophie website
        • Third-party modules can use their vendor's website, or local directory with help files.
      • Help contents entries. For example, the org.sophie2.main.view.menus module can provide an entry with id="main.view.menus.file", title="File Menu" and parent="main.view.menus". The location of the HTML page should be something like <sophie_website>/<help>/main/view/menus/file.html.
    • When selecting "Help Contents" in the Help menu, a content page is generated.
      • The entries are gathered from each module's help extension.
      • The generated page is in HTML format
      • The page is created in the TEMP directory. Do not forget to delete it after closing the window.
      • The page can consist of a frameset with left frame - the generated menu, and right frame - the remote help page that is invoked by clicking on a menu entry.
      • We should use locally generated help contents menu instead of the website's help index page, because each Sophie installation may have different plugins installed.
  • 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
  • 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.help.
    • Create the menu and menu items.
  • For the browser:
    • browse(URI) in java.awt.Desktop can be used.
    • but the Desktop API is from Java 6.
  • For the content generator:
    • Create two HTML files:
      • Index page (index.html or similar) - frameset with two frames - actually it is the same every time, so you can use already created html file.
      • Contents page - the help contents, arranged in a tree. Each link should be open in the right frame.
        • Use CSS from the official website of Sophie 2.
  • 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.
    • Add mouse listener 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

(Describe your design here.)

Implementation

(Describe and link the implementation results here (from the wiki or the repository).)

Testing

(Place the testing results here.)

Comments

(Write comments for this or later revisions here.)