The Java Analysis Studio Help System

General notes

Currently, JAS uses Oracle Help For Java to implement the help system.  Every attempt was made to encapsulate all help details in jas.util.Application so that the expected switch to Sun's JavaHelp will be simple.

The help system is fundamentally implemented by the following file types:

• .oht - links context-sensitive areas of the application to help pages (one per book)
• .hhc - table of contents (for one book)
• .hhk - index (not search index, but list of key words you see on the navigator) of key words for one book
• .htm, .html - content files
• .jpg, .gif - images

Notes on the file formats

• The .oht files follow a format prescribed by the Oracle Help For Java File Format Reference.  They map an arbitrary keyword to the URL for a help page.  This allows the programmers to hard-code keywords for each of the context-sensitive help topics and change the actual URLs that they reference without recompiling the classes or re-releasing the application.  For example, a link on the OptionsDialog uses the keyword "TimedBackup" for a help page on timed backups and specifies that the topic is described is in the "jobs" book (by returning the value jas.util.Application.JOBS_BOOK when asked for a book index).  The .oht file for the jobs book (called jobs.oht) maps that keyword to a URL by following the OHT file format.  As far as I can tell, only Oracle Help For Java uses this format.   It's easiest to edit these files by hand, but be warned: The parser is very picky so follow the format exactly.  Your only clue that an error is found is that the book and its contents are absent from the help viewer.
• The .hhc and .hhk files are generated by Microsoft's HTML Help Workshop, which provides a simple GUI that allows you to edit the index and contents files. Each book has a project file (.hhp) which the help workshop uses to keep track of the files for that book.  These formats are considered universal (they were proposed by Microsoft at the World Wide Web Consortium), and should be portable to Sun's JavaHelp.  It's best not to edit these formats by hand.
• The .htm and .jpg files are created in or handled by in Microsoft Front Page 98.  The .html files are created by the javadoc tool, and it uses a set of .gif files on the pages it creates.

Therefore, if you create a new HTML file and add it to the help system completely, you must

• Select a book to add it to.  This will depend entirely on which topic set it belongs with.
• Open the .hhp file (but not from FrontPage, open from My Computer instead) for that book. For example, the project file for the jobs book is jobs.hhp.   The help files are all in \\sldnt17\users\inetpub\wwwroot\jas\help\%jas_version%\, where jas_version is the an envoronment variable that contains the directory name for the version you're interested in.
• Add the new HTML file to the project by clicking on the second tool bar button ("Add/Remove topic files") on the "Project" tab in the help workshop window.  This just tells the Help Workshop that this file is a part of that project, so it should be included in a list of files that can easily be indexed and added to the contents page.
• Add the new file to the table of contents by clicking on the "Insert a page" button on the tool bar on the "Contents" tab.
• Add some keywords from the new file to the index file by using the buttons on the tool bar on the "Index" tab. Be sure to alphabetize the index file before saving. Do this by clicking on the the button with the "AZ" image on it.  If you don't do this, the help system gets confused because it expects the keywords to be alphabetized.
• Save the project and exit from the workshop.
• The changes should also be reflected in the search index file (.idx). There is typically one .idx file for each book, but it is simpler for us just to have one for all of the books. I have a batch file (\\sldnt17\users\jgifford\help\index.bat) that creates an index file like this:

md temp\
set java_compiler=
copy \\sldnt17\users\inetpub\wwwroot\jas\help\%jas_version%\*.htm temp\
rem copy \\sldnt17\users\inetpub\wwwroot\jas\help\%jas_version%\api\jas\*.html temp\
rem copy \\sldnt17\users\inetpub\wwwroot\jas\help\%jas_version%\api\hep\*.html temp\
del temp\relnotes.htm
del temp\contents.htm
\\sldnt21\ohelp\tools\indexer-win\index temp\ \\sldnt17\users\inetpub\wwwroot\jas\help\%jas_version%\jobs.idx
rmdir temp\ /q/s
    

Support for Local Help Files

Java Analysis Studio allows users to have the help files dowloaded on their machines and allows them to access those files from the application. This is accomplished by creating a .jar file that includes all of the help files, and by adding that file to the classpath for the JAS application.

By default, the application uses local help files if they are available (i.e., in the classpath). If the .jar file is not in the classpath or if the property ReadHelpFromDisk is set to false, the application tries instead to read the files from the server.  To set application properties, add or change entries in the file jas.properties which is stored in the directory specified by System.getProperty("user.home").

The actual .jar file is created by a batch file at \\sldnt17\users\jgifford\help\jarhelp.bat. The file looks like this:

set java_compiler=
md jas\help\
md jas\help\api\jas
md jas\help\api\hep
md jas\help\api\jas\images
md jas\help\api\hep\images
javac -d .\ JASHelp.java
copy \\sldnt17\users\inetpub\wwwroot\jas\help\%jas_version%\*.htm jas\help\
copy \\sldnt17\users\inetpub\wwwroot\jas\help\%jas_version%\*.hhc jas\help\
copy \\sldnt17\users\inetpub\wwwroot\jas\help\%jas_version%\*.hhk jas\help\
copy \\sldnt17\users\inetpub\wwwroot\jas\help\%jas_version%\*.idx jas\help\
copy \\sldnt17\users\inetpub\wwwroot\jas\help\%jas_version%\*.jpg jas\help\
copy \\sldnt17\users\inetpub\wwwroot\jas\help\%jas_version%\api\jas\*.html jas\help\api\jas\
copy \\sldnt17\users\inetpub\wwwroot\jas\help\%jas_version%\api\hep\*.html jas\help\api\hep\
copy \\sldnt17\users\inetpub\wwwroot\jas\help\%jas_version%\api\jas\images\*.gif
jas\help\api\jas\images\
copy \\sldnt17\users\inetpub\wwwroot\jas\help\%jas_version%\api\hep\images\*.gif
jas\help\api\hep\images\
del jas\help\relnotes.htm
del jas\help\contents.htm
del standalonehelp.jar
jar -c jas\help\*.* > standalonehelp.jar
del jas\help\*.class
javac -d .\ HelpRef.java
del builtinhelp.jar
copy \\sldnt17\users\inetpub\wwwroot\jas\help\%jas_version%\*.oht jas\help\
jar -c jas\help\*.* > builtinhelp.jar
rmdir jas\help\ /s/q

The batch file actually creates two .jar files.

• The first, standalonehelp.jar, is used by a stand-alone application. This allows the user to run help totally separately from the JAS application. I invoke this stand-alone application using a batch file (\\sldnt17\users\jgifford\help\jashelp.bat) that simply has

set java_compiler=
java -classpath standalonehelp.jar;%classpath% jas.help.JASHelp

• The second, builtinhelp.jar, is used by the JAS application. Add this file to the classpath of the application to allow the application access to all of the help files locally. Like the first file, it contains all of the HTML files, images, and index and table of contents files. It also contains the .oht files to enable context-sensitive help, and a very simple class, jas.help.HelpRef, which allows the application to
• know whether the .jar file with all the help files has been added to the classpath
• know the location of the help files by using a path relative to the location of that class

The source files for the classes mentioned above are \\sldnt17\users\jgifford\help\HelpRef.java and \\sldnt17\users\jgifford\help\JASHelp.java.

Therefore, changes to the help system contents should be reflected in

• the .idx file, and
• the .jar files,

as well as the in the .hhc, .hhk, .hhp, and .oht files for the book(s) that the changes were made to.  The batch files that create these files should be run after any changes have been made to the help pages.  Of course, the .idx file should be created before the .jar files because both the .jar files use the .idx file and they should have the latest version available.

Implementing Context-Sensitive Help

Ultimately, you must invoke the method showHelpTopic(int, String) on the instance of java.util.Application.   This takes two arguments:

1. The integer index for the help book where the topic you want can be found.  Every book is denoted by unique integer.  The indexes for built-in books are defined by public static constants in the jas.util.Application class.  For example, the index for the jobs book is jas.util.Application.JOBS_BOOK.  The correct index for a user-added help book will be returned by the addHelpBook methods.
2. The string for the topic you want to show.  The help system will open the URL that the .oht file for the selected book maps to the string given as the second argument.

Convenience help access is coded in for

• JASWizardPage
  If your page implements jas.util.HasHelpPage, the 'Help' button will enable.  You must implement methods that return the two parameters listed above.
• JASDialog
  If you call the methods setHelpTopic and setHelpBook before the dialog is shown, and you include the flag HELP_BUTTON among the button flags then an enabled help button will appear on the dialog.
• ErrorBox
  If you provide a help book and topic to the ErrorBox constructor then an enabled help button will show on the error dialog.

Adding Help Books

You can add as many books as you want by calling the addHelpBook methods on the application object (access by typing jas.util.Application.getApplication()).  These methods will invoke corresponding methods on the help object and return the integer index you must use to refer to the newly created book.   The documentation below is modified from the Oracle Help For Java documentation.  It explains the parameters for the two methods.

public int addHelpBook(String baseURL, String baseName, String bookTitle)

Creates a Book object for the specified book information.

Parameters:

baseURL - Base URL string of the documentation. This is where all the documentation actually resides. Applications are advised to use paths relative to getCodeBase() of the applet.

baseName - baseName is the basename for TableOfContents (HHC), KeyWords (HHK), Topics (OHT) and Search (IDX) files. For example, if baseName is "sqlplus", then the names of these files are assumed to be sqlplus.hhc, sqlplus.hhk, sqlplus.oht and sqlplus.idx.

Applications are not required to provide all the four files with the documentation. For example, Topics (OHT) file is only used for context-sensitive help. If OHT file is missing for a product, it simply means that the application does not support context-sensitive help.

bookTitle - bookTitle is the string displayed in the navigator window for this book.

Returns:

the integer index for the newly created book

public int addHelpBook(Class baseClass, String dirName, String baseName, String bookTitle)

Creates a Book object for the specified book information.

Most of the times applications/applets do not know the absolute location of the documentation at run time but do know the location relative to some known class. This constructor takes a class and a directory name as arguments, and builds the baseURL of the book using ClassLoader.getResource() mechanism. Applications have to make sure that the directory they pass in is locatable using getResource() mechanism.

Parameters:

baseClass - Class relative to which documentation is located.

dirName - Name of the documentation directory

baseName - baseName of the book.

bookTitle - bookTitle is the string displayed in the navigator window for this book.

Returns:

the integer index for the newly created book

Creating javadoc

I use the following batch file (which is \\sldnt17\users\jgifford\help\docjas.bat) to create the javadoc pages (note that the environment variable jas_root is the directory where all JAS source code is. For example, the source file for jas.util.Application would be %jas_root%\jas\util\Application.java):

set java_compiler=
cd %jas_root%
copy jas\histjp\*.java jas\hist\
java -mx40m -ms40m sun.tools.javadoc.Main -d \\sldnt17\users\inetpub\wwwroot\jas\help\%jas_version%\api\jas jas.swingstudio jas.hist jas.hist.test jas.util jas.jds.module jas.jds.module.pawserver jas.jds.module.flatfileserver jas.jds.module.hepevt jas.jds.module.hippo jas.jds.module.jdbc jas.jds.module.sld
del jas\hist\*.java /q
javadoc -d \\sldnt17\users\inetpub\wwwroot\jas\help\%jas_version%\api\hep hep.analysis hep.analysis.peer

Jonas Gifford, January 14, 2004