How to add custom help index

Index


It is possible to maintain your own help index file. This is a powerful feature which lets you add and maintain your own help indices. As powerful as this feature is if not used properly can lead to excessive memory usage and poor help performance. It is important to be careful when adding indexes to the custom index file. Once the index is added to the help it will be treated like any other index. In other words pressing F1 on any custom help index keyword in the editor and more can search all custom indices. The order of search is JDK index first and User index next. This will safeguard against a big user index file.

Help/Search dialog now has 3 tabs: one for JDK keywords, one for Kawa help search and the other for user index or custom index. Selecting any keyword in either tab and double clicking on it will display all the topics available for that keyword. Double clicking on the topic again will display the topic content in the help window.

Custom indices can be built from any HTML file. However, the way it is designed it works very well with the format of AllNames.html file that is generated by Javadoc command. In fact, all the JDK indices under Kawa were generated this way. In order to add custom indices select Customize/User Index… and the dialog box as shown below is displayed.

In this dialog box it is possible to delete an existing custom index or modify the keyword for an existing custom index. It is not possible to modify the link for a keyword however. In order to add a new file select Add File… and in the ensuing dialog select a HTML file which has links to other topics. Kawa will scan the selected HTML file for all links to other topics and display another dialog where the link entries can be modified just like in the previous dialog. This dialog lists all the available links from the selected file only as shown below.

In the above dialog Jtree html file was selected from the JFC control documentation. Once all the indices are ready to be added from the new file to the custom indices select Add to add the indices to custom indices. The same step can be repeated for as many files as desired. Finally, when the index is ready to be saved to an index file select Save from the above User Index dialog to save the index into an user index file called USER.IPG which will be created in the Kawa directory. All the new indices are instantly available for searching just like the JDK indices that are prebuilt with Kawa. During the processing of building a new custom index Kawa performs several steps to optimize the help search. Please notice the status text in the bottom of the frame and also the new progress control in the bottom right corner of the mainframe window as shown below for the progress of different steps.

Some of the files can take a real long time to build a custom index like the AllName.html from JFC control. Please be patient during the entire build process.

All help files are now loaded in a background thread. Sometimes, when you press F1 to access help, Kawa will start loading the help indices if the background thread is still not complete. This is a normal behavior.