Ashley J.S Mills

ashley@ashleymills.com

2005 The University Of Birmingham JavaHelp is a standard extension to the J2SE programming environment available from Sun. It provides the developer with a help interface written entirely in Java. The help interface looks like this: The JavaHelp interface showing table of contents The left pane contains three tabs, the first, as shown above, contains the table of contents, the second contains the index and is shown below: The JavaHelp interface showing index The third tab contains an interface to a search engine that allows one to search the help documentation: The JavaHelp interface showing search capability In order to illustrate an overview of the system, a real, but very simple example will be used. There are six core components to the JavaHelp system: The first is the documentation itself which is written in HTML 3.2, this usually spans over many different files and contains certain special elements that are used by the JavaHelp system, checkout the files index.html and ar01s02.html, these were automatically generated using an XSLT tool from an XML DocBook document. The second component is the HelpSet file, this contains information about the whole help system and is the file read by the HelpViewer when the help system is loaded by an application. The HelpSet file that corresponds to the HTML pages linked to above is shown below: <?xml version="1.0" encoding="ISO-8859-1" standalone="no"?> <!DOCTYPE helpset PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp HelpSet Version 1.0//EN" "http://java.sun.com/products/javahelp/helpset_1_0.dtd"> <helpset version="1.0"> <title>Title</title> <maps> <homeID>top</homeID> <mapref location="jhelpmap.jhm"/> </maps> <view> <name>TOC</name> <label>Table Of Contents</label> <type>javax.help.TOCView</type> <data>jhelptoc.xml</data> </view> <view> <name>Index</name> <label>Index</label> <type>javax.help.IndexView</type> <data>jhelpidx.xml</data> </view> <view> <name>Search</name> <label>Search</label> <type>javax.help.SearchView</type> <data engine="com.sun.java.help.search.DefaultSearchEngine">JavaHelpSearch</data> </view> </helpset> It contains information like the location of the map file, explained next, and view information which specifies information about the types of view that the Help viewer should display and how it should display them. The third component of the JavaHelp system is the JavaHelp map file. The map file for the project under discussion is shown below: <?xml version="1.0" encoding="ISO-8859-1" standalone="no"?> <!DOCTYPE map PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp Map Version 1.0//EN" "http://java.sun.com/products/javahelp/map_1_0.dtd"> <map version="1.0"> <mapID target="Simple" url="index.html"/> <mapID target="Simple.Introduction" url="index.html"/> <mapID target="Simple.Explanation" url="ar01s02.html"/> <mapID target="Simple.Explanation.Files" url="ar01s02.html"/> <mapID target="Simple.Explanation.Cheater" url="ar01s02.html"/> <mapID target="id328078" url="ar01s02.html#cheating"/> </map> The map file "map"s the id's used in the documentation to the HTML page or position in a HTML page they correspond to. The fourth component of the JavaHelp system is the JavaHelp table of contents file, the TOC file for the project under discussion is shown below: <?xml version="1.0" encoding="ISO-8859-1" standalone="no"?> <!DOCTYPE toc PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp TOC Version 1.0//EN" "http://java.sun.com/products/javahelp/toc_1_0.dtd"> <toc version="1.0"> <tocitem target="Simple" text="Title"> <tocitem target="Simple.Introduction" text="Introduction"/> <tocitem target="Simple.Explanation" text="Explanation"> <tocitem target="Simple.Explanation.Files" text="Lots of files"/> <tocitem target="Simple.Explanation.Cheater" text="Cheating"/> </tocitem> </tocitem> </toc> The toc element specifies the titles that should be used for each of the sections in the documentation as indicated by the id's which were mapped to the HTML files by the map file. The fifth component of the JavaHelp system is the index file. The index file for the project under discussion is shown below: <?xml version="1.0" encoding="ISO-8859-1" standalone="no"?> <!DOCTYPE index PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp Index Version 1.0//EN" "http://java.sun.com/products/javahelp/index_1_0.dtd"> <index version="1.0"> <indexitem text="cheater" target="id328078"/> </index> This maps any index terms to particular IDs which are in turn mapped to HTML pages via the map file. The sixth component of the JavaHelp system is the search data, generated like this: jhindexer *.html Which generates the directory JavaHelpSearch which is referenced in jhelpset.hs. Note that the reference in jhelpset.hs refers to the JavaHelpSearch directory directly because it is in the same directory but that this could theoretically be placed anywhere on the local system as long as the reference reflected the location. The example below uses the search data to create its search engine. The various components of the JavaHelp system have been shown, not all of them are compulsory, one may choose whether or not to include index information for example. The JavaHelp documentation illustrated in the past few paragraphs is shown in the JavaHelp viewer below: JavaHelp system discussed showing initial state. JavaHelp system discussed showing index term. This can be instantiated very easily from within Java, the program used to instantiate the JavaHelp viewer shown above is shown below: // Import the javahelp files. import javax.help.*; import java.net.URL; import javax.swing.*; public class JavaHelpTest { public static void main(String args[]) { JHelp helpViewer = null; try { // Get the classloader of this class. ClassLoader cl = JavaHelpTest.class.getClassLoader(); // Use the findHelpSet method of HelpSet to create a URL referencing the helpset file. // Note that in this example the location of the helpset is implied as being in the same // directory as the program by specifying "jhelpset.hs" without any directory prefix, // this should be adjusted to suit the implementation. URL url = HelpSet.findHelpSet(cl, "jhelpset.hs"); // Create a new JHelp object with a new HelpSet. helpViewer = new JHelp(new HelpSet(cl, url)); // Set the initial entry point in the table of contents. helpViewer.setCurrentID("Simple.Introduction"); } catch (Exception e) { System.err.println("API Help Set not found"); } // Create a new frame. JFrame frame = new JFrame(); // Set it's size. frame.setSize(500,500); // Add the created helpViewer to it. frame.getContentPane().add(helpViewer); // Set a default close operation. frame.setDefaultCloseOperation(JFrame.DISPOSE_ON_CLOSE); // Make the frame visible. frame.setVisible(true); } } The JHelp object extends javax.swing.JComponent, this is why it can be added directly to a frame. The JavaHelp API comes with JavaHelp and can be viewed online at: This is as far as this tutorial is going to go, I have provided enough information for a normal person to be able to get going with JavaHelp and links to find out more information. Download the zipped archive of the JavaHelp software from http://java.sun.com/products/javahelp/download_binary.html#download. Extract the zipped archive to some suitable location. Set the JAVAHELP_HOME environment variable to point to the directory the archive was extracted to. Append (where you extracted the javahelp archive)/javahelp/lib/jh.jar to the CLASSPATH environment variable. Append (where you extracted the javahelp archive)/javahelp/bin to the PATH environment variable. JavaHelp is now installed, the classes may be imported into Java programs and the tools that came with the distribution may be used. The API is in the doc sub directory. http://java.sun.com/products/javahelp/ The JavaHelp homepage http://java.sun.com/products/javahelp/ The JavaHelp FAQ http://www.javaworld.com/javaworld/javaone98/j1-98-help.html A short article called Java Apps Get Help! about JavaHelp from javaworld.