Adding online help

Once an application is started by the user it is most convenient to provide information and help directly out of that application. With JavaHelp technology the Java language has an extension for online help which any application can use to seamlessly incorporate documentation.

JavaHelp extension

JavaHelp extends the Java Runtime Environment in the way that it provides a specification and platform to display any kind of documentation. All Information presented in JavaHelp is stored in HTML files. Table of contents, index and map are XML files all wrapped together with the HTML topic files into a framework of classes to view and query the information through a common user interface.

Unfortunately the JavaHelp extension is not a part of the core Java Runtime Environment (JRE) so the extension has to be applied manually by coping the extension file for JavaHelp into the extensions directory of the JRE.

How to use JavaHelp in an application

Once a JavaHelp documentation is set up by creating HTML documents, table of contents, index and map files and the JavaHelp extension is available to the JRE, displaying JavaHelp documentation simply is done by creating a HelpSet object for the corresponding help set and display it with an instance of HelpBroker.

More about the JavaHelp specification and technology is available at

http://java.sun.com/products/javahelp

How help is created for SimplyHTML

All documentation is stored in a single JavaHelp help set in directory help of the SimplyHTML class path ( source/com/lightdev/app/shtm/help). The help set is the one you are currently reading. It was produced entirely with the Java application HelpExpert. HelpExpert is created by the author of SimplyHTML (hey, that's me again!) and is available at

http://www.calcom.de/eng/product/hlpex.htm

How help is implemented in SimplyHTML

A common practice is to deliver documentation through menu 'Help'. Consequently SimplyHTML has an item 'Help Topics' in the 'Help' menu linking to this help set. In stage 1 the link was performed by SHTMLHelpShowContentsAction. This has been refined to now being handled in method initJavaHelp of class FrmMain.

Method initJavaHelp

In method initJavaHelp an instance of a HelpBroker is created pointing to the JavaHelp version of this tutorial (included in the Java archive (JAR) file of SimplyHTML). A reference to this HelpBroker is kept for later use. Then class FrmMain's instance of class DynamicResource is used to get the menu item meant for displaying the application's online help topics overview.

Class CSH (for context sensitive help) of the JavaHelp API is used to create an ActionListener responsible to display context sensitive help on occurrence of a given action (selecting the 'Help contents' menu item in this case). This ActionListener is registered with the menu item.

Important: A 'readme' document should always be distributed with an application as plain text file. The readme file should contain essential information to properly set up and run the application. If all other tools fail, at least the user can be referred to this file to start with.