## 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.

|  | If you want the viewer to find the default helpset, add its path to the `CLASSPATH` system variable.
|  | 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.
|  | For a list of limitations, bugs, and "idiosyncrasies" that pertain to the JavaHelp system HTML viewer, see Limitations and Bugs.
|  | 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:
   - In the command shell, change to the JavaHelp-home`/demos/bin` directory and enter the following command:

     `java -jar UserGuide.jar`

   - In Windows Explorer, navigate to the directory containing the JAR file and double-click it to display the help file.

     Note: If double-clicking the file opens it in WinZip or some other zip utility, right-click the file, choose Open, and then navigate to the `java.exe` program in your J2SE installation's bin directory.