Common Desktop Environment: Help System Author's and Programmer's Guide

Chapter 4 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.

Overview

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

Graphic

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.

HelpTag Software

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

Helptag does two significant tasks:

  1. The HelpTag 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.err.

  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 HelpTag, 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.

Graphic

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 HelpTag, it reads your volume.htg or volume.ctg file and any additional source files that are included using entities. Also, graphics file names are validated.

Be sure the /usr/dt/bin/dthelptag 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.htg file is located.

    Graphic
  2. Select the file icon.

  3. Choose Compile from the File Manager Selected menu.

    The volume.htg file is processed and creates a volume.sdl file and volume.err file.

HelpTag Output

The output from HelpTag is a run-time help volume, named volume.sdl. If any errors occurred during processing, they are reported in an error file (volume.err). If no errors were encountered, the volume.err file contains copyright information and several status lines.

Setting the onerror=go option in your helptag.opt file allows the parser to continue processing (if possible) after encountering an error. Without the onerror=go option, the parser halts when the first error is detected. 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.htg file. For example, if your volume.htg is named Librarian.htg, then the help volume name is Librarian.sdl.


Caution - Caution -

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


To Run the dthelptag Command Manually

    Run the dthelptag command as follows:

dthelptag  command-options  volume  parser-options

Where command-options are options entered before the volume name and parser-options are options entered after the volume name. "Processing HelpTag Files (dthelptag)" lists all available options.

Example: Commands

The following command processes a help volume named MyVolume:

dthelptag MyVolume

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

dthelptag -verbose MyVolume

Adding a search path enables HelpTag to find files stored in a subdirectory (of the current directory) named graphics:

dthelptag -verbose MyVolume search=graphics

Example: A helptag.opt File

Here's a sample helptag.opt file showing that each option is on a separate line. It would be appropriate for creating a draft version of the volume.

memo
onerror=go 
search=graphics/
search=entityFiles/

Before producing the final version of the help volume, you would remove the memo and onerror=go lines.

See Also

To Review and Correct Parser Errors

    Look at the contents of the volume.err file after running HelpTag (where volume is the base name of your volume.htg file).

Each error listed in the volume.err file begins with a string of asterisks (*****). For example, the following error was detected at line 54 of the file actions:

*****
Line 54 of actions,
Missing end tag for LIST:
...the execution host becomes the current working directory.

<s2 id=EverythingYouNeedToKnow> E...
Current element is LIST begun on Line 28 of actions.

A few lines of the file are shown to give you some context for the error. Also, there is a hint that the current element is a LIST started on line 28 of the same file. An <s2> is not allowed within a list, so it appears that the author forgot to enter the <\list> end tag.

It's possible for a single, simple error to produce several error messages. This is because the first 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 for an element is a common mistake. When creating elements, such as a list, figure, note, caution, or warning, be sure to include the end tag. Check your markup carefully especially if you have nested one 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.

Similarly, changing the ID assigned to an element affects any cross-reference or link to that topic.

Viewing a Help Volume

The Help Viewer can be used to display any help volume. It supports all types of hyperlinks except 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 just edited your help volume. First, process it with the HelpTag software:

dthelptag MyVolume

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

dthelpview -h MyVolume.sdl

See Also

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 HelpTag 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 

Adding Your Help to the Browser Volume

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

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

Figure 4-1 Browser help volume displaying help families

Graphic

To make your help volume available in the browser 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 browser volume.

Browser Volume

A desktop utility creates and updates the browser 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 browser.hv in the user's HomeDirectory/.dt/help/$DTUSERSESSION directory. After initial creation, the volume is updated only if changes have occurred.

To manually update the browser volume, refer to "Generating a Browser Help Volume (dthelpgen)".

Any help volume listed in the browser volume can be viewed by selecting the volume title. Because you can display and navigate through different volumes, the browser help window includes an additional button, called Top Level. You can use this button to return to the browser 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 browser volume. Figure 4-1 shows two help families, Common Desktop Environment and Overview and Basic Desktop Skills, listed in the browser 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 CDE 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. See "Understanding Font Schemes" for a list of supported character sets. The family title and family abstract should not contain any HelpTag markup; this file is not processed with the HelpTag 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 CDE Advanced User's and System Administrator's Guide describes how to run the dtappintegrate script.

Example

Here's a family file for the desktop's online help. Comments at the top of the file identify the family and release version.

!##############################################
 !#                                            #
 !#          Desktop  Help Family              #
 !#                                            #
 !#                 Version 1.0                #
 !#                                            #
 !##############################################
 *.charSet:      ISO-8859-1
 *.title:        Desktop Version 1.0
 *.bitmap:       /usr/dt/appconfig/help/C/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

To Display the Browser Volume

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

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


    Note -

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


To Display the browser Volume Manually

    Run the dthelpview command as follows:

dthelpview -helpVolume browser

See Also

Printing Help Topics

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

Figure 4-2 Help print dialog box

Graphic

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

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:

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

Checking for Parser Errors

When developing a help volume, it is often convenient to set the onerror=go option in the helptag.opt file. If you have done this, you should remove the option and process your source files a final time to ensure that no errors are encountered.

See Also