Generating a User Manual From JavaHelp

I'm working on an application that needs to have the user documentation accessible when you click the big, bright, friendly 'help' button, and also as a printed manual. We're using JavaHelp, which has its moments but seems to do the job, and was quite painless to get going.

JavaHelp needs pages to be in html 3.2 (why? why?) - this means you need to be careful when writing / editing help with a wysiwyg editor. On my system, I get strange-looking pages when editing with nvu, but openoffice works fine.

JhelpDev is a JavaHelp generator. It’s easy to use - create your html pages then use the TOC editor to organise them into a table of contents. Then, export the helpset and related files. The methods to create and display the help from java are:

 /*
  * This method creates the help frame
  *
  */

 private void createHelp() {
  try {
   ClassLoader cl = Welcome.class.getClassLoader();
   URL url = new URL((new File(".")).toURL(), "doc" + File.separator
     + "help.hs");
   JHelp helpViewer = null;
   // Create a new JHelp object with a new HelpSet.
   helpViewer = new JHelp(new HelpSet(cl, url));
   helpViewer.setCurrentID("top");

   frame.setSize(800, 600);
   frame.setTitle("iDART Help System");

   frame.getContentPane().add(helpViewer);
   frame.setDefaultCloseOperation(JFrame.DISPOSE_ON_CLOSE);

  } catch (Exception e) {
   System.err.println("API Help Set not found");
   e.printStackTrace();
  }
 }

 /*
  * This method displays the help
  *
  */
 private void showHelp() {
  frame.setVisible(true);

 }

Once you’ve got the help working fine from the application, you can turn it into a user manual by:

1. Generating an ordered list of the files you want to concatenate into the help. Since this order is probably the same as the order of the TOC entries for JavaHelp, it’s easiest to just extract the file names from the xml TOC file.
2. Use the ordered list as input to htmlcat, a perl script for concatenating html files. This should give you one long html file, in the correct order
3. Open the html file in your word processor and save it as a document. Insert page breaks as necessary.