Viewing Helpsets

A helpset viewer is provided with the release to enable you to view your helpsets. If the path to the java executable file is in your PATH variable, you can enter the following command in your operating system's command-line shell to run the helpset viewer (where JavaHelp_home is the JavaHelp system installation directory): 

java -jar JavaHelp_home/demos/bin/hsviewer.jar
On a Windows system, you can configure a shortcut to run the viewer. For example, if your J2SE installation is in C:\j2sdk1.4.1 and your JavaHelp system installation is in C:\JavaHelp, you can configure the shortcut as follows:
 
  1. If necessary, create a shortcut on your desktop.
    1. Open the file Explorer and navigate to a folder containing an executable file (for example, c:\j2sdk1.4.1\bin\java.exe). 
    2. Right-click the file and choose Create Shortcut.
    3. Drag the newly created shortcut to your desktop.
  2. Right-click the shortcut and choose Properties.
  3. In the Shortcut dialog, type the following command in the Target field:

    c:\j2sdk1.4.1\bin\java -jar c://JavaHelp//demos//bin//hsviewer.jar

  4. Save the shortcut.
  5. You can then double-click the shortcut to open the viewer in the Java virtual machine.

All helpsets are displayed in the JavaHelp system help viewer—the same viewer used to provide help in applications.

note blue ball image  If you want the viewer to find the default helpset, add its path to the CLASSPATH system variable.
  blue ball image  For the purpose of running the examples, the JRE you use to run hsviewer does not have to be the same version as the JRE on which your application is deployed. For example, you can use J2SE 1.4.1 to run the demo programs (including hsviewer) even if your application is deployed on J2SE 1.3.1.
  blue ball image  For a list of limitations, bugs, and "idiosyncrasies" that pertain to the JavaHelp system HTML viewer, see Limitations and Bugs.
  blue ball image  The viewer toolbar does not include a reload button. The easiest way to reload a file after you change it is to click the viewer's "previous" and "next" buttons.

Displaying a Helpset with hsviewer.jar

To display a specific helpset, start the helpset viewer hsviewer.jar as described above. When the viewer opens, either click the Browse button to navigate to a helpset or, in the URL field, type the full path to the helpset file. When the helpset has loaded, click Display to view the helpset in the viewer.

Alternatively, you can specify the helpset by using a command-line switch with hsviewer.jar. You can do this on the command line itself, in a batch file, in a script file, in a JAR file, or in a shortcut. The command-line syntax of the hsviewer.jar command-line interface is:

   java -jar hsviewer.jar [-helpset hs_name]

-helpset Specifies the helpset name:
hs_name The full path to a helpset file. For example (on a Windows system):
C:\> java -jar c:\JavaHelp\demos\bin\hsviewer.jar
     -helpset c:\JavaHelp\demos\hs\newmerge\MergeHelp.hs

Displaying a Helpset in Windows by Clicking the .hs File

In Windows, you can open a file in a program by double-clicking the file in the Explorer. For example, if you double-click an HTML file, it opens in your default web browser. This technique works because Windows can associate a file extension (like .html) with a program that displays the file. You can use this technique to open a helpset file in the helpset viewer (hsviewer.jar). Here is how to do it.

  1. Create a batch file that runs hsviewer.jar and accepts a command-line parameter.

    For example, if the JavaHelp system is installed in c:\JavaHelp and java.exe is in your PATH, you would put the following line in the file:

    java -jar c://JavaHelp//demos//bin//hsviewer.jar -helpset %1
  2. Save the file as hsviewer.bat.

  3. Open Windows Explorer, navigate to a directory containing a helpset (.hs) file, and double-click the file.

    Windows displays the Open With dialog, which enables you to associate the helpset file with a program that opens the file.

  4. Click the Other button, navigate to the directory where you saved the hsviewer.bat file, and choose that file as the one that will open .hs files.

  5. Click OK in the Open With dialog.

  6. The helpset opens in the helpset viewer.

    In the future, when you double-click a helpset file in the Explorer, it will open in the helpset viewer.

Displaying a Helpset by Using an Executable JAR File

You can display a specific helpset in a standalone environment by using the sunw.demo.jhdemo.Runner class available in hsviewer.jar, specifying that class and some other information in a manifest file, and creating an executable JAR file from the manifest file.

To create a JAR file that can display a single helpset:

  1. Create a manifest file for the helpset.

    For example, shown below is the manifest file that displays the JavaHelp System User's Guide. (See the UserGuide.jar file in the JavaHelp-Home/demos/bin directory.)

      Main-Class: sunw.demo.jhdemo.Runner
      Run-Class: sunw.demo.jhdemo.JHLauncher
      Class-Path: ../../javahelp/lib/jh.jar hsviewer.jar ../../doc/jhug/
      Arguments: -helpset jhug.hs

    The syntax of the manifest file is as follows:

      Main-Class: sunw.demo.jhdemo.Runner
      Run-Class: sunw.demo.jhdemo.JHLauncher
      Class-Path:     jar-file | directory
      Arguments: -javahelp     helpset-filename

    Main-Class: The main class to execute when running this JAR file. This class is a standard argument for executable JAR files, and in this case it must always be sunw.demo.jhdemo.Runner. For example:

       Main-Class: sunw.demo.jhdemo.Runner
    Run-Class: The class that the sunw.demo.jhdemo.Runner executes. This class is usually sunw.demo.jhdemo.JHLauncher, but it could be another class that launches a JavaHelp viewer. The following code is the typical Run-Class entry:

       Run-Class: sunw.demo.jhdemo.JHLauncher
    Class-Path: Files to use with the Run-Class. Specify them as a series of space-separated JAR files or directories to be added to existing CLASSPATH environment variable.

    Note: The files must be relative to the location of the executable JAR file. For example, if the JAR file is in the demos/bin directory of the JavaHelp installation directory, this entry would be::

      Class-Path: ../../javahelp/lib/jh.jar hsviewer.jar ../../doc/jhug/

    Arguments: Arguments to be passed to the Run-Class when Run-Class is executed. These arguments are specific to the Run-Class. For example:

    -helpset jhug.hs

  2. Create an executable JAR file by using the jar command. The JAR file contains only one file, the manifest file. Other files are specified in the Class-Path argument and must be relative to the JAR file. The command to create the manifest file is:

       jar cmf manifest_file jar_file

    For example:

       jar cmf manifest.mf UsersGuide.jar

  3. Run the JAR file by opening it in java.exe or executing it from the Windows Explorer (if you have set up java.exe as the application that executes JAR files). For example: