# Processing and Displaying a Help Volume

This chapter shows you how to process your marked-up help files to create an online format that you view using the Help System. It also describes how to make your help volume accessible from the desktop Front Panel Help Viewer.

HRDC.CrHV.mkr.2
HRDC.CrHV.mkr.3
HRDC.CrHV.mkr.6
HRDC.CrHV.mkr.7
HRDC.CrHV.mkr.8
HRDC.CrHV.mkr.13
HRDC.CrHV.mkr.15

## Overview

Before a help volume can be displayed, you must create a run-time help file by processing your files with the DocBook software. Run-time files use an online presentation format called Semantic Delivery Language (SDL). An`.sdl` file extension identifies a run-time help file.

The utility `dtdocbook` takes documents conforming to the DocBook 2.2.1 DTD subelement Part and produces documents conforming to the SDL 1.2 DTD, which can serve as input to the DtHelp viewer.

During translation, several items are precomputed to speed run-time display of the document. These items include: the table of contents, the keyword index, resolution of cross-references, and labeling of ordered lists. The SDL conforming document produced by the translation is compressed by default.

The Help System defines desktop actions and data types for help-specific files. This lets you easily process and view a run-time help file from the desktop.

### DocBook Software

The DocBook software can be invoked automatically by double-clicking a help source file in File Manager or by running the `dtdocbook` command manually in a terminal window.

`dtdocbook` does two significant tasks:

1. The DocBook parser converts your marked-up files into an internal format (Semantic Delivery Language) understood by the Help System. If you've made any markup errors, the errors are reported in a file named volume`.log`.

2. If there are no parser errors, the master help volume file (volume`.sdl`) is created.

### Viewing Your Volume

After processing your source files with DocBook, your help volume is ready to be displayed. You can display it by double-clicking the volume`.sdl` file icon in File Manager, or use the `dthelpview` command in a terminal window.

If you have written help for an application and the application is ready to use, you can display your help by running the application and asking for help.

## Creating Run-Time Help Files

When you run `dtdocbook`, it reads your volume`.sgm` file and any additional source files that are included using entities. It also validates graphics file names.

Be sure the `/usr/dt/bin/dtdocbook` command is in your search path. (If you're not sure how to do this, ask your system administrator.)

### To Create a Run-Time Help Volume

1. Open File Manager and change to the directory where your volume`.sgm` file is located.

2. Select the file icon.

3. Choose Compile from the File Manager Selected menu.

   The volume`.sgm` file is processed and creates a volume`.sdl` file and a volume`.log` file.

### DocBook Output

DocBook takes the file volume`.sgm` as its input and outputs several files:

- Most importantly, the final output file, a run-time help volume, named volume`.sdl`.

- If any errors occurred during processing, they are reported in an error file named volume`.log`, typically removed after use.

The volume`.sdl` file is not created until the source file is without errors.

The volume`.sdl`, file, plus your graphics files, are read by the Help System to display help topics.

The run-time help file has the same base name as your volume`.sgm` file. For example, if your source file is named `Librarian.sgm`, then the help volume name is `Librarian.sdl`.

The `dtdocbook` utility accepts a single file as an argument. If the file name ends in the characters “`.sgm`”, those characters are assumed to be the file name extension and are removed to create the file base names for all intermediate files and for the final output file.

When the `dtdocbook -c` or the `dtdocbook -d` option is specified to request compression or decompression of an existing SDL file, the input file name will end in the characters “`.sdl`”. Again, those characters are assumed to be the file name extension and are removed to create the file base names for all intermediate files and for the final output file.

If the `-c` option is specified and the file is already compressed, the file will be decompressed and recompressed. This action is useful as a means to verify the integrity of a compressed SDL file.

If the `-d` is specified and the file is already decompressed, the file will be re-parsed, all precomputations will be performed, and the file will be re-written. This action is useful as a means to verify the integrity of an SDL file. It is also useful for forcing a recomputation of the table of contents, including byte offsets to individual help topics, when such recomputation is made necessary, for example, by editing the SDL file directly.

The final output file name extension will always be “`.sdl`”, unless the `dtdocbook -o` option is specified, in which case the filename argument to `dtdocbook -o` will be used as given as the output file name.

Never rename a run-time help file or graphics file after running `dtdocbook`. The information stored in the volume`.sdl` file depends on the original names. If you rename your volume`.sgm` file or any of your graphic files, be sure to rerun `dtdocbook`.

### To Run the dtdocbook Command Manually

- Run the `dtdocbook` command as follows:

  `dtdocbook` options volume

  Observe that options are entered before the volume name. HRDC.CmdS.mkr.2 lists all available options.

#### Examples of Command Options.sgm

The following command processes a help volume named `MyVolume`:

    dtdocbook MyVolume

Using the `-r` option removes all files previously generated by processing a source file of `MyVolume.sgm`:

    dtdocbook -r MyVolume.sgm

The following command processes the source file named `MyVolume.sgm` and leaves the result in the file named `Other_File.sdl`::

    dtdocbook -o Other_File.sdl MyVolume.sgm

Using the `-v` option causes the progress of the processing to be displayed on your screen:

    dtdocbook -v MyVolume

#### See Also

- HRDC.Inst.mkr.1 explains which help files are included in your application installation package.

### To Review and Correct Parser Errors

The primary source of error messages will be the SGML parser. Most of them will be SGML syntax error messages, and a few will be of the "file not found" variety.

The two passes of the translation process that takes the source file from SGML to SDL will also generate syntax error messages and "file not found" messages, but to a lesser degree. The second of the two passes will issue error messages rarely, since all the syntax and context will have been checked by then.

After running `dtdocbook`, look at the contents of the volume`.log` file (where volume is the base name of your volume`.sgm` file).

It is quite possible for a single, simple error to produce several error messages, because the error may cause the parser to lose track of the intended context, making it impossible to interpret subsequent markup properly.

#### Common Errors

Most processing errors result from these common mistakes:

- Omitting an end tag

- Using an incorrect entity name

- Referring to an invalid element ID

Omitting an end tag for an element is a common mistake. Virtually all DocBook elements require end tags. Check your markup when you have nested one structurally complex element within another, such as a figure within a list.

Errors can also be introduced by using an incorrect entity name. In most instances, it is simply a misspelled word. In other cases, an entity name may have been changed, but cross-references to the original name were overlooked. When you change an entity name, remember to search your source file (or files) for all instances of the entity name.

Errors can also be introduced by changing the ID assigned to an element, since this affects any cross-reference or link to that topic. When you change an ID, remember to search your source file (or files) for all instances of that ID.

## Viewing a Help Volume

The Help Viewer can be used to display any help volume. It supports all DocBook hyperlinks but not application-defined links (because it cannot know how your links are to be interpreted).

If you are writing application help and your application is ready to use, you can also view your help by running your application, then requesting help just as a user would.

### To Display a Help Volume

1. Open File Manager and change to the directory where the volume`.sdl` file is located.

2. Double-click its icon.

   The default action displays the file using the Help Viewer.

#### To Run the dthelpview Command Manually

- If the volume`.sdl` file for the volume you want to display is either in the current directory or has been registered, execute this command:

  `dthelpview -helpVolume volume`.sdl``

  Or, if the volume`.sdl` is in another directory (and hasn't been registered), execute this command:

  `dthelpview -helpVolume /full-path/ volume.sdl`

The `-helpVolume` parameter can be shortened to `-h` in any of these commands.

#### Example

Suppose you have just edited your help volume. First, process it with the DocBook software:

    dtdocbook MyVolume.sgm

If no errors occurred, you could then display it with this command:

    dthelpview -h MyVolume.sdl

#### See Also

- HRDC.Inst.mkr.9

#### Example: A Personal Help Directory

During a project, you may want to access the help volume you are developing, but not expose it to all users on your system. For example, suppose your working directory is `/projects/help` and your help volume is named `Myvolume`.

First, create the personal help directory in your home directory where you can register the volume:

    mkdir -p $HOME/.dt/help/C

Now create a symbolic link to the `Myvolume.sdl` file (which is created by the DocBook software):

    ln -s /projects/help/Myvolume.sdl $HOME/.dt/help/C/Myvolume.sdl

You can now display the volume with the following command (regardless of your current directory) because the`.dt/help/C` directory within your home directory is one of the first places the Help System looks for help volumes.

    dthelpview -helpVolume Myvolume.sdl

## Adding Your Help to the Index Volume

The desktop provides a special help volume called the index volume that lists help volumes available on your system. The index volume is displayed by clicking the Help Viewer control in the Front Panel.

You can view assorted help volumes directly from the index volume. This allows access to application-specific help without starting the application. If you are writing standalone help, this is the only way for users to get to your help.

### Index help volume displaying help families

To make your help volume available in the index volume, you create a help family file. When your application is registered on the desktop, the presence of a family file causes the help volume to be included in the index volume.

### Index Volume

A desktop utility creates and updates the index volume. When a user clicks on the Front Panel Help Viewer for the first time, the utility is automatically run. It identifies help volumes and help family files that are located in the help search path directories. It creates a file called `index.hv` in the user's `HomeDirectory/.dt/help/$DTUSERSESSION` directory. After its initial creation, the volume is updated only if changes have occurred.

To manually update the index volume, refer to HRDC.CmdS.mkr.5.

Any help volume listed in the index volume can be viewed by selecting the volume title. Because you can display and navigate through different volumes, the index help window includes an additional button, called Top Level.You can use this button to return to the index list after displaying one or more volumes.

### Help Family File

The desktop utility examines help family files to identify which help volumes are gathered into the index volume. HRDC.CrHV.mkr.9 on HRDC.CrHV.mkr.9 shows two help families, Common Desktop Environment and Overview and Basic Desktop Skills, listed in the index volume. Each family file consists of one or more related help volumes. For example, the Common Desktop Environment family includes different volumes that describe the desktop.

Refer to the Advanced User's and System Administrator's Guide for a detailed explanation of how an application and its help files are installed on the desktop.

### To Create a Help Family

1. Pick a file name that is unique to your product. Use the`.hf` extension to identify the file as a help family.

   `family.hf`

2. Enter the following lines into the file:

       *.charSet:           character-set
       *.title:        family title
       *.bitmap:       icon file
       *.abstract:     family abstract
       *.volumes:      volume volume volume ...

   Where character-set specifies the character set used by the family title and family abstract strings. HRDC.Lang.mkr.11 for a list of supported character sets. The family title and family abstract should not contain any DocBook markup; this file is not processed with the DocBook software.

   The icon file is optional. If you provide one, the path you use to specify the location of the file should be a complete path name. If you do not provide an icon, do not include the `*.bitmap` resource in your family file.

   The list of volume names identifies which volumes belong to the family. The volumes will be listed in the order they appear on this line. A volume may be listed in more than one family.

   If any of the values occupy more than one line, end each line — except the last — with a backslash (`\`).

   Any line in the file that begins with an `!` (exclamation mark) is a comment line and is ignored.

3. When you prepare your final product, you should install your family`.hf` file with the rest of your help files. When the desktop integration script, (`dtappintegrate`) is run, it creates the symbolic links to your family file.

   The Advanced User's and System Administrator's Guide describes how to run the `dtappintegrate` script.

#### Example

Here's an example of a family file for the desktop's online help.

    *.charSet:      ISO-8859-1
    *.title:        Common Desktop Environment
    *.bitmap:       /usr/dt/appconfig/help/C/graphics/cdelogo.pm
    *.abstract:     Overview and Basic Desktop Skills \
                    * File Manager and the Desktop \
                    * Front Panel \
                    * Application Manager \
                    * Style Manager \
                    * Text Editor \
                    * Mailer
    *.volumes: Intromgr.sdl Filemgr.sdl FPanel.sdl
               Appmanager.sdl Stylemgr.sdl
               Textedit.sdl Mailer.sdl

The help family file actually included with the desktop software may not exactly match this example.

#### See Also

- HRDC.Lang.mkr.5 for a list of supported character set names

### To Display the Index Volume

1. Choose the Help Viewer control from the desktop's Front Panel.

2. Scroll the help window to view the help families available on your system.

3. If desired, display a volume by selecting the help family title.

To view help information about the Help System, choose the title Common Desktop Environment and then Desktop Help System.

#### To Display the Index Volume Manually

- Run the `dthelpview` command as follows:

      dthelpview -helpVolume index

#### See Also

- hrdc.cmds.mkr.4 lists `dthelpview` command line.

- `dthelpgen`(1) man page

## Printing Help Topics

After displaying your help volume, you can print help topics. Using the Print dialog box shown in HRDC.CrHV.mkr.14 you can print an individual topic, a table of contents and index information, or the entire help volume. Printed output omits graphics.

### Help print dialog box

## Testing Your Help

Testing your help volume is as important as testing any software product. Here are some tips to help you plan your testing.

### Validating Hyperlinks

- Display your help volume and try every hyperlink. Any underlined text (solid or dashed underlines) is a hyperlink. Also, test any graphics that are hyperlinks. Graphic hyperlinks use an open-cornered border (dashed or solid) around the image as a hyperlink cue.

- If you are writing application-specific help and you have included any `JumpNewView`, `Man`, or `AppDefined` links, you must test these links from your application. Testing such links using `dthelpview` does not ensure that the links will operate correctly from within your application.

### Verifying Entry Points

If you are writing application-specific help that uses IDs to access particular help topics, there are two ways to verify that the IDs have been properly established within the help volume:

- Run your application and request help just as a user will, trying each of the entry points. This also verifies that the application is using the correct IDs.

- If your application is not ready to use (still under development), you can test each ID by running `dthelpview` for each ID:

      dthelpview -helpVolume volume.sdl -locationId id

  Where id is the location ID that you want to test. If `dthelpview` displays the correct topic, then the ID is okay.

### Checking Index Entries

Users search or browse a help volume index to find help topics. Examine your index entries carefully to eliminate any vague terms or duplicate entries. Also select each index entry to verify that the topic displayed is the most appropriate information.

### Testing Graphics

- Physically run your application on various displays to verify that the graphics are acceptable on color, grayscale, and monochrome displays.

- You can also simulate other displays by changing the number of colors used by the desktop. To do so, open Style Manager, choose Number Of Colors, and select a different color option.

#### See Also

- HRDC.CmdS.mkr.5