Chapter 9. Providing Online Help With SGIHelp
Prev | Part I. Getting the Right Look and Feel | Next

## Chapter 9. Providing Online Help With SGIHelp

This chapter describes how to use the Silicon Graphics online help system, SGIHelp, to deliver the online help for your product. It describes how to prepare the help and integrate it into your application. It contains the following sections:

- “Overview of SGIHelp” provides an overview of the help system.

- “The SGIHelp Interface” describes the SGIHelp API.

- “Implementing Help in an Application” provides some examples of implementing online help in an application.

- “Application Helpmap Files” describes the format and use of application helpmap files.

- “Writing the Online Help” describes how to write the source files containing your application's online help.

- “Producing the Final Product” describes how to compile your help files into viewable form and package them for installation on your users' systems.

- “Bibliography of SGML References” list additional references.

The section “Online Help” in Chapter 4 of the IRIX Interactive User Interface Guidelines provides interface and content guidelines for adding online help to your application.

## Overview of SGIHelp

The SGIHelp system consists of a help viewer, a help library and include file, help document files, and optional application helpmap files. This section describes:

- “The Help Viewer”

- “The SGIHelp Library and Include File”

- “Help Document Files”

- “Application Helpmap Files”

  | Note: To develop online help for your application, you must install the insight_dev product, which contains the SGIHelp library and include file, help generation tools, examples, and templates.

### The Help Viewer

The SGIHelp viewer, `sgihelp`(1), also referred to as the help server, displays help text in easy-to-use browsing windows. Figure 9-1 shows an example of a help window.

Figure 9-1. The Help Viewer

`sgihelp` can also display an index of all help topics available in a help document and allow the user to select a particular topic from the list. Figure 9-2 shows an example of a help index.

Figure 9-2. The Help Index Window

`sgihelp` is a separate application that gets started automatically whenever an application makes a help request. Neither users nor your application should ever need to explicitly start `sgihelp`. After the user closes all help windows, `sgihelp` remains running in the background for a few minutes. If it receives no other help requests within that time, it automatically exits.

### The SGIHelp Library and Include File

The Silicon Graphics help library, `libhelpmsg`, handles communication with the help server. `libhelpmsg` depends on the `libX11` library. Be sure to specify `–lhelpmsg` before `–lX11` in the compilation or linking command.

For example, to compile a file `hellohelp.c++` to produce the executable hellohelp, you would enter:

    CC -o hellohelp hellohelp.c++ -lhelpmsg -lX11

You must include `<helpapi/HelpBroker.h>` in any source file that accesses online help. Both the library and include file were developed in C, and can be used with either the C or C++ programming languages.

### Help Document Files

Help document files contain the actual help text in Standard Generalized Markup Language (SGML) format. In addition to text, help documents can contain graphics and hypertext links to other help topics.

### Application Helpmap Files

Application helpmap files are optional; an application can request specific help topics directly. Applications helpmap files provide a level of indirection that allows you to structure your help presentation independently of your application code. The SGIHelp library also uses helpmaps to make it easier for you to implement context-sensitive help in your application.

| Note: You must provide a helpmap for your application if you want a help index.

## The SGIHelp Interface

This section describes the functions you use to access the help server from your application:

- “Initializing the Help Session”

- “Displaying a Help Topic”

- “Displaying the Help Index”

### Initializing the Help Session

Before calling any other help functions, your application must first call `SGIHelpInit()`:

    int SGIHelpInit (Display *display, char *appClass, char *separator);

display |  | The application's Display structure.
appClass |  | The application's class name. Use the same name as you provide to `XtAppInitialize()`.
separator |  | The separator character used by the application to separate the widget hierarchy when a context-sensitive help request is made. At this time, you must use the period ( . ).

`SGIHelpInit()` does not start or communicate with the help server process; it simply initializes data structures for the other SGIHelp functions. `SGIHelpInit()` returns 1 on success, and 0 on failure.

Example 9-1 shows an example of how to use `SGIHelpInit()`.

Example 9-1. Initializing a Help Session Using `SGIHelpInit()`

    #include <Xm/Xm.h>
    #include <helpapi/HelpBroker.h>

    void main ( int argc, char **argv )
    {
        Widget       mainWindow; /* Main window shell widget */
        XtAppContext app;        /* An application context,
                                  * needed by Xt
                                  */
        int          status;     /* Return status */

        /* ... */

        mainWindow = XtAppInitialize ( &app, "MyApp", NULL, 0,
                                       &argc, argv, NULL,
                                       NULL, 0 );

        /* Initialize the help session */

        status = SGIHelpInit( XtDisplay(mainWindow),
                              "MyApp", "." );

        /* ... */
    }

### Displaying a Help Topic

To request display of a help topic from within your application, call `SGIHelpMsg()`:

    int SGIHelpMsg (char *key, char *book, char *userData);

key |  | Specifies either 1) the ID of a particular help topic in a help document, or 2) a widget hierarchy. If you provide a help ID, the help server displays the help topic identified in the help document specified by the book argument. You must provide a help book name in this case. See “Writing the Online Help” for an explanation of help IDs. If you provide a widget hierarchy, the help server looks in the application's helpmap file to find a mapping. If it doesn't find an exact match, it uses a fallback algorithm to determine which is the “closest” hierarchy found. Typically you use this technique to provide context-sensitive help. See “Application Helpmap Files” for more information about the helpmap file.
book |  | Gives the short name of the help document containing the application's help information. See “Writing the Online Help” for a description of help document short names. If you set this to NULL or asterisk (*), the help server looks in the application's helpmap file for the book name. In this case, a helpmap file must exist. See “Application Helpmap Files” for more information about the helpmap file.
userData |  | Reserved for future use. You should always set this field to NULL.

If a copy of the help server is not already running, `SGIHelpMsg()` automatically starts the server. `SGIHelpMsg()` returns 1 on success, and 0 on failure.

Example 9-2 shows an example of using `SGIHelpMsg()` to display the help topic identified by the help ID “help_save_button” in the help document with the short name “MyAppHelp.”

Example 9-2. Requesting a Specific Help Topic Using `SGIHelpMsg()`

    #include <helpapi/HelpBroker.h>

    /* Assume initialization of help session is complete */

    /*
     * This call displays the help topic with a key of
     * "help_save_button" (found in the "HelpId=" field).
     * It will look for this section in the help document
     * "MyAppHelp".
     */

    status = SGIHelpMsg( "help_save_button", "MyAppHelp", NULL );

Example 9-3 shows an example of using `SGIHelpMsg()` to request help given a widget hierarchy. In this case, the application must have a helpmap file, and the help file must contain an entry mapping the given hierarchy to a help topic for this call to succeed.

Example 9-3. Requesting a Help Topic for a Widget Using `SGIHelpMsg()`

    #include <helpapi/HelpBroker.h>

    /* Assume initialization of help session is complete */

    /*
     * This call displays the help topic specified by the
     * mapping for the widget hierarchy
     * "MyApp.mainWindow.controlPane.searchButton"
     * as given in the application's helpmap file.
     */

    status = SGIHelpMsg( "MyApp.mainWindow.controlPane",
                         NULL, NULL );

### Displaying the Help Index

The `SGIHelpIndexMsg()` call causes the help server to look for the application's helpmap file and to display the Help Index window:

    int SGIHelpIndexMsg (char *key, char *book);

key |  | You should always set this field to NULL or “index.”
book |  | Reserved for future use. You should always set this field to NULL.

The index displays all the help topics in the helpmap file in the order they appear in the file. You must have a helpmap file for this call to work properly. See “Application Helpmap Files” for more information about the helpmap file. `SGIHelpIndexMsg()` returns 1 on success, and 0 on failure.

Example 9-4 shows an example of how to use `SGIHelpIndexMsg()`.

Example 9-4. Displaying a Help Index Using `SGIHelpIndexMsg()`

    /* Assume initialization of help session is complete */

    /*
     * This call will look in the application's helpmap
     * file for a list of topics to display to the user in
     * sgihelp's index window.
     */

    status = SGIHelpIndexMsg( "index", NULL );

## Implementing Help in an Application

The section “Types of Online Help” in Chapter 4 of the IRIX Interactive User Interface Guidelines describes the user interfaces to online help that your application should provide. In summary, these services are:

- Help menus in all application windows with menu bars

- Help buttons in all applications without menu bars

- Context-sensitive help available through both the help menus and the `<Shift+F1>` keyboard accelerator.

This section contains specific suggestions for implementing these help interfaces to your application:

- “Constructing a Help Menu”

- “Implementing a Help Button”

- “Providing Context-Sensitive Help”

### Constructing a Help Menu

For those windows in your application with a menu bar, you should provide a Help menu. “Providing Help through a Help Menu” in Chapter 4 of the IRIX Interactive User Interface Guidelines recommends that the following entries appear in the Help menu:

“Click for Help”
| Provides context-sensitive help. This option should also use the `<Shift+F1>` keyboard accelerator. When a user selects “Click for Help,” the cursor should turn into a question mark (?). The user can then move the cursor over an item or area of interest and click. Your application should then display a help topic describing the purpose of the item or area. “Providing Context-Sensitive Help” provides detailed instructions for implementing context-sensitive help.
“Overview”
| Displays overview information. The main primary window should provide an overview of the application. For other windows, this option should appear as “Overview for <window name>” and provide an overview of the current window only.
A list of topics and tasks
| This section should contain a list of topics and tasks that the user can perform in your application. When the user selects one of the options, your application should display a help topic for that item. To reduce the size of this section, you can move some of the tasks to submenus. You can hard code the entries in this section or, if you have a helpmap file for your application, you can parse the helpmap and dynamically create the task and subtask entries.
“Index”
| Displays Help Index window for the application. You must have an application helpmap file to support this option.
“Keys & Shortcuts”
| Displays the application's accelerator keys, keyboard shortcuts, and other actions in the application.
“Product Information”
| Displays a dialog box showing the name, version, and any copyright information or other related data for your application. Typically, you should present this information using an IRIS IM dialog rather than using online help.

Separators are added automatically. See the program listing in Example C-4 for an example of creating a Help menu.

### Implementing a Help Button

For those windows in your application that don't contain a menu bar, you should provide a Help button. Example 9-5 shows how you can use the SGIHelp API to communicate with the help server from a pushbutton within your application. “Providing Help Through a Help Button” in Chapter 4 of the IRIX Interactive User Interface Guidelines provides guidelines for when to implement a Help button.

Example 9-5. Providing a Help Button

    /* required include file for direct communication with help server */
    #include <helpapi/HelpBroker.h>
    #include <Xm/Xm.h>

    /* ... */

    /* initialize help server information */
    SGIHelpInit(display, "MyWindowApp", ".");

    ...

    /* create help pushbutton for your window */
    Widget helpB = XmCreatePushButton(parent, "helpB", NULL, 0);
    XtManageChild(helpB);

      XtAddCallback(helpB, XmNactivateCallback,
                    (XtCallbackProc)helpCB, (XtPointer)NULL);
    /* ... */

    /* help callback */
    void helpCB(Widget w, XtPointer clientData, XtPointer callData)
    {
                    /*
                     * communicate with the help server; developer
                     * may wish to pass the "key" in as part of the
                     * callback's callData parameter...
                     */
                    SGIHelpMsg("key", "book", NULL);
    }

### Providing Context-Sensitive Help

To provide context-sensitive help from within your application, you need to write code that tracks the cursor and interrogates the widget hierarchy. Additionally, you need to make a mapping between what the user has clicked, and the help card that's displayed.

The best way to provide the mapping is with the application helpmap file. The SGIHelp library provides a fallback algorithm for finding help topics that simplifies the process mapping widgets to topics. If the help system can't find an exact match to the widget string in the helpmap file, it drops the last widget from the string and tries again. The help system reiterates this process until it finds a match in the helpmap file. This eliminates the need to explicitly map a help topic for every widget in your application. Instead you can map a help topic to a higher-level manager widget and have that topic mapped to all of its descendent widgets as well.

For more information on the structure of application helpmap files, see “Application Helpmap Files”.

Example 9-6 shows the code used to implement context-sensitive help in the example program listed in Example C-4, which simply installs `clickForHelpCB()` as the callback function for the “Click for Help” option of the Help menu. As long as you create a helpmap file for your application, you can use this routine as listed in your application as well.

Example 9-6. Implementing Context-Sensitive Help

    void clickForHelpCB(Widget wid, XtPointer clientData, XtPointer callData)
    {
         static Cursor cursor = NULL;
         static char path[512], tmp[512];
         Widget shell, result, w;

         strcpy(path, "");
         strcpy(tmp,  "");

    /*
     * create a question-mark cursor
     */
         if(!cursor)
             cursor = XCreateFontCursor(XtDisplay(wid), XC_question_arrow);

         XmUpdateDisplay(_mainWindow);

    /*
     * get the top-level shell for the window
     */
         shell = _mainWindow;
         while (shell && !XtIsShell(shell)) {
                shell = XtParent(shell);
         }

    /*
     * modal interface for selection of a component;
     * returns the widget or gadget that contains the pointer
     */
         result = XmTrackingLocate(shell, cursor, FALSE);

         if( result ) {
             w = result;

    /*
     * get the widget hierarchy; separate with a '.';
     * this also puts them in top-down vs. bottom-up order.
     */
             do {
                  if( XtName(w) ) {
                      strcpy(path, XtName(w));

                      if( strlen(tmp) > 0 ) {
                          strcat(path, ".");
                          strcat(path, tmp);
                      }

                      strcpy(tmp, path);
                  }

                  w = XtParent(w);
             } while (w != NULL && w != shell);

             /*
              * send msg to the help server-widget hierarchy;
              *      OR
              * provide a mapping to produce the key to be used
              *
              * In this case, we'll let the sgihelp process do
              * the mapping for us, with the use of a helpmap file
              *
              * Note that parameter 2, the book name, can be found
              * from the helpmap file as well. The developer need
              * not hard-code it, if a helpmap file is present for
              * the application.
              *
              */
              if( strlen(path) > 0 ) {
                    SGIHelpMsg(path, NULL, NULL);
              }
         }
    }

## Application Helpmap Files

Application helpmap files provide a level of indirection that allows you to structure your help presentation independently of your application code.

- “Helpmap File Conventions”

- “Helpmap File Format”

- “Widget Hierarchies in the Helpmap File”

You don't have to create a helpmap for your application, but doing so gives you the following benefits:

- Your application can display a Help Index window, allowing users to select a particular topic directly from the list.

- You can write the code that generates your application's Help menu to create the “list of topics and tasks” options dynamically from the helpmap. You can then add and restructure your task help without recompiling your application. See “Constructing a Help Menu” for details on the Help menu's list of topics.

- Your application's Help menu can launch a browser and access a URL on the World Wide Web. See “Example of Helpmap Entry to Access a Web Browser” for more information.

- You can provide context-sensitive without hard-coding in your source code a help topic to each widget. The SGIHelp library provides a fallback algorithm for finding help topics that simplifies the process mapping widgets to topics. If the help system can't find an exact match to the widget string in the helpmap file, it drops the last widget from the string and tries again. The help system reiterates this process until it finds a match in the helpmap file. This eliminates the need to explicitly map a help topic for every widget in your application. Instead you can map a help topic to a higher-level manager widget and have that topic mapped to all of its descendent widgets as well. See “Providing Context-Sensitive Help” for information on implementing context-sensitive help in your application.

### Helpmap File Conventions

Helpmap files are ASCII text files. The name of your application helpmap file must be “appClass.helpmap”, where appClass is your application's class name as provided in your application's call to `SGIHelpInit()`. See “Initializing the Help Session” for more information on `SGIHelpInit()`.

If you create a helpmap file for your application, you must create a subdirectory named `help` in the directory containing your help document and put all of your document's figures in that subdirectory. See “Preparing to Build the Online Help” for more information.

### Helpmap File Format

Each entry, or help topic, in a helpmap consists of a single line containing at least six fields, each field separated by semicolons:

    type;book;title;level;helpID;widget-hierarchy[;widget-hierarchy …]

#### Helpmap Fields

All fields are required for each entry. Their purpose is as follows:

type |  | The type of help topic. Its value can be:
0 | A context-sensitive topic.
1 | The overview topic.
2 | A task-oriented entry that could show up in the “list of topics and tasks” area of the Help menu. See “Constructing a Help Menu” for details on the Help menu's list of topics.
3 | The Keys and Shortcuts topic.
book |  | The name of the help document that contains this help topic. Help topics can reside in different books. Each individual help topic can point to only one help book.
title |  | The title of the help topic. This appears in the Help Index window. If your application parses the helpmap file to generate the “list of topics and tasks” area of the Help menu, you can use this as the label for the menu option.
level |  | A number determining the topic level. A value of 0 indicates a main topic, a value of 1 a sub-topic, a value of 2 a sub-sub-topic, and so forth. This produces an expandable/collapsible outline of topics for the Help Index window. If your application parses the helpmap file to generate the “list of topics and tasks” area of the Help menu, you can also use these values to construct “roll-over” submenus as part of a Help menu.
helpID |  | The unique ID, as specified by the “HelpID” attribute, of the specific help topic in the help document.
widget-hierarchy |  | One or more fully-qualified widget specifications for use with context-sensitive help. You can provide multiple specifications, delimited by semicolons, to associate different areas with the same topics.

#### Examples of Helpmap Entries

For example, the following entry in `Swpkg.helpmap` specifies the overview topic:

    1;IndigoMagic_IG;Overview;0;Overview;Swpkg.swpkg.overview

The following entries from `Swpkg.helpmap` specify several context-sensitive help topics. In this case, the first entry appears as a main topic in the Help Index window and the next three appear as sub-topics:

    0;Swpkg_UG;Using the swpkg Menus;0;menu.bar;Swpkg.swpkg.menuBar
    0;Swpkg_UG;The File Menu;1;menu.bar.file;Swpkg.swpkg.menuBar.File
    0;Swpkg_UG;The View menu;1;menu.bar.view;Swpkg.swpkg.menuBar.View
    0;Swpkg_UG;The Help menu;1;menu.bar.help;Swpkg.swpkg.menuBar.helpMenu

The following shows a more complex hierarchy from `Swpkg.helpmap`:

    2;Swpkg_UG;Tagging Files;0;tag.files.worksheet;Swpkg.swpkg
    2;Swpkg_UG;Selecting Product Files;1;file.browser;Swpkg.swpkg.view.viewPanedWindow.viewForm.\
     leftForm.filesBody.addBody.FileListAdd.selectionGrid
    0;Swpkg_UG;Setting the Browsing Directory;2;file.browser.dirfield;Swpkg.swpkg.view.\
     viewPanedWindow.viewForm.leftForm.filesBody.addBody.FileListAdd.directoryLabel;Swpkg.swpkg.\
     view.viewPanedWindow.viewForm.leftForm.filesBody.addBody.FileListAdd.directoryTextField
    0;Swpkg_UG;Selecting Files From the File List;2;file.browser.filelist;Swpkg.swpkg.view.\
     viewPanedWindow.viewForm.leftForm.filesBody.addBody.FileListAdd.scrolledWindow.filesList;\
     Swpkg.swpkg.view.viewPanedWindow.viewForm.leftForm.filesBody.addBody.FileListAdd.\
     scrolledWindow.VertScrollBar

| Note: The backslashes (\) indicate linewraps; they do not actually appear in the helpmap file. Each helpmap entry must be a single line.

In the example above, the first entry is a task-oriented topic (2 in the type field). `swpkg` parses the helpmap file to create its Help menu, so “Tagging Files” appears as a selection. The second entry is also a task-oriented topic. It's a sub-topic of the first entry and appears in a submenu off the “Tagging Files” selection. The last two entries are marked as context-sensitive only (0 in the type field). These entries don't appear anywhere in the application's Help menu, but they do appear as sub-sub-topics in the Help Index window. Also note that the last two entries have two widget specifications, providing context-sensitive help for two different widgets.

| Note: The order of the entries in the application helpmap file determines the order in which help topics appear in the Help Index window.

#### Example of Helpmap Entry to Access a Web Browser

You can put an entry into a helpmap file to launch a Web browser and access a URL. An example entry in the showcase `helpmap` file looks like this:

    2;HREF=http://www.sgi.com/Products/SGIHelp_Hub/Showcase_3.3.2.html;\
    Showcase Web Page;0;showcase_web;Showcase3D.showcase2;ShowcaseUG;\
    About Gizmos;0;about_gizmo;Showcase3D.showcase

| Note: The backslashes (\) indicate linewraps; do not actually enter them in the helpmap file. Each helpmap entry must be a single line.

When SGIhelp encounters this type of entry, it uses a Web browser such as Netscape (or $WEBBROWSER) to show the URL specified by the entry.

### Widget Hierarchies in the Helpmap File

At least one widget hierarchy must accompany every point in the application helpmap file. That one (default) point should be set to “application_classname.top-level_shell”.

Note that the application class name must always be the first component of a widget hierarchy string. All widget ID's within the string must be delimited by a period ( . ).

Widget hierarchies can be as fine-grained as you wish to make them. A fall-back algorithm is in place (to go to the closest available entry) when the user clicks a widget in context-sensitive help mode. For example, suppose your application includes a row or set of buttons. When the user asks for help on a button, you pass that widget string to SGIHelp. If the widget string is not found in the mappings, the last widget is dropped off the string (in this case, the widget ID for the button itself). The new string is compared to all available mappings. This loop continues until something is found. At the very least, you should fall back to an “Overview” card.

To get a sample widget hierarchy (help message) from an application, you can run the SGIHelp help server process in debug mode. Before doing this, you need to add the SGIHelp API call, `SGIHelpMsg()`, to your application and implement context-sensitive help. Make sure that you send a widget hierarchy string for the “key” parameter in the `SGIHelpMsg()` call. (See “Providing Context-Sensitive Help within an Application” and “Understanding Available Calls” for details on this call.)

To get a sample widget hierarchy from an application that implements context-sensitive help, follow these steps:

1. Bring up a shell.

2. Make sure the help server process isn't running. Type:

       % /etc/killall sgihelp

3. Type the following to make the help server process run in the foreground in debug mode:

       % /usr/sbin/sgihelp -f -debug

4. Run your application, and then choose “Click for Help” from the help menu. The cursor should change into a question mark (?), or whatever cursor you've implemented for context sensitive help.

5. Click a widget or an area of the application.

6. Check the shell from which SGIHelp is being run. You should see a line such as:

       REQUEST= client="Overview" command="view" book=""
          keyvalue="DesksOverview.MainView.Frame.viewport.Bboard"
          separator="." user_data=""

   The “keyvalue” field contains the widget hierarchy that you can add to the helpmap file. Remember to add the application class name to the front of the string. For the example above, the full widget hierarchy string would be:

       Overview.DesksOverview.MainView.Frame.viewport.Bboard

## Writing the Online Help

This section describes how you prepare the online help document. It provides an explanation of the standard format you must use, as well as the steps you take to actually prepare the file. Topics include:

- “Overview of Help Document Files”

- “Viewing the Sample Help Document Files”

- “Creating a Help Document File”

- “Preparing to Build the Online Help”

- “Building the Online Help”

- “Finding and Correcting Build Errors”

For guidelines on structuring and writing your online help text, see “Writing Online Help Content for SGIHelp” in Chapter 4 of the IRIX Interactive User Interface Guidelines.

### Overview of Help Document Files

Help document files contain the actual help text in Standard Generalized Markup Language (SGML) format. When you write the online help for your product, you need to embed SGML tags to describe the structure of your document.

The file `/usr/share/Insight/XHELP/samples/sampleDoc/sample.sgm` is an example of a file with embedded SGML tags. (Example C-1 also lists this file.) Notice the tags surrounded by angle brackets (<>). These tags describe how each item fits into the structure of the overall document. For example, a paragraph might be tagged as a list item, and a word within that paragraph may be tagged as a command.

The Document Type Definition (DTD) outlines the tagging rules for your online documentation. In other words, it specifies which SGML tags are allowed, and in what combination or sequence. The file `/usr/share/Insight/XHELP/dtd/XHELP.dtd` lists the legal structure for your online help.

A DTD can be difficult to read, so you might instead want to look at the file `/usr/share/Insight/XHELP/samples/XHELP_elements/XHELP_elements.sgm`, which lists the legal elements in a help document and describes when to use them in your documents. (Example C-2 also lists this file.)

For a more complete understanding of SGML, refer to the bibliography in “Bibliography of SGML References”. It lists several of the many books on SGML.

### Viewing the Sample Help Document Files

Before beginning to write your own help documents, you might find it helpful to examine the source of the sample help documents and then view resulting online versions. You can compile and view the help documents in Insight. To do so, follow these steps:

1. Go to a directory in which you want to build the sample help book.

2. Copy the necessary directories and files by entering:

       % cp -r /usr/share/Insight/XHELP/samples .

3. Enter:

       % cd samples/sampleDoc

4. Build the file `sample.sgm` by entering:

       % make help

5. To view this file, enter:

       % iiv -b . -v sample

6. Change to the `exampleApp` directory by entering:

       % cd ../exampleApp

7. Build the file `exampleAppXmHelp.sgm` by entering:

       % make help

8. To view this file, enter:

       % iiv -b . -v exampleAppXmHelp

### Creating a Help Document File

To create the help document file for your application:

1. Create a new directory for the online help, then go to this directory.

2. Create a text file and name the file “`title`.sgm”, where title is one word that identifies the online help.

3. Write the online help.

You can include figures as described in the example help documents. If your document contains figures, create a subdirectory named either `figures` or `online` in your help document directory and put all of your document's figures in that subdirectory.

### Preparing to Build the Online Help

After writing your online help you must build it, similarly to the way you compile a program. When you build the online help, you transform the raw SGML file into a viewable, online document. To get started, you need to create two files: a Makefile and a spec file.

The Makefile specifies:

- the name of file that contains the online help

- the name you want to assign to the help book

- the version number of the product

The spec file specifies:

- the title of your product

- the official release and version numbers

- other information that is used when you create the final, installable images

To create these files, follow these steps:

1. Go to the directory that contains the online help file.

2. Copy `/usr/share/Insight/XHELP/templates/Makefile_xhelp` by typing:

       cp /usr/share/Insight/XHELP/templates/Makefile_xhelp Makefile

3. Copy `/usr/share/Insight/XHELP/templates/spec_xhelp` by typing:

       cp /usr/share/Insight/XHELP/templates/spec_xhelp spec

4. Edit the Makefile:

   - Next to the label TITLE, type the name of the file that contains the online help.

   - Next to the label FULL_TITLE, type the name you want to assign to the help book. This name can contain several words, and is used only if you decide to display the help as a “book” on the Insight bookshelf.

   - Next to the label VERSION, type the version number for the product.

   - Next to the label HIDDEN, remove the comment character (#) if you want the online help to appear as a book on an Insight bookshelf. Change this if you want users to be able to browse the help information using Insight, and not just from within your application.

5. Edit the spec file:

   - Replace the string ${RELEASE} with the release number for the product. This should match what you've entered in the Makefile for the VERSION.

   - Replace the string <ProductName> with a one-word name for the product.

   - Replace the string <Shortname> with the TITLE you specified in the Makefile.

   - Replace the string <SHORTNAME> with the TITLE you specified in the Makefile. Capitalize all letters.

   - Replace the string <SHORTNAME_HELP> with the TITLE followed by “_HELP”.

   - Replace the string <Book title> with the FULL_TITLE you specified in the Makefile.

Once you have edited these files, the directory containing your help document should contain:

- your help document

- the `Makefile`

- the `spec` file

- if you included figures in your help document, a subdirectory named either `figures` or `online` containing all of the figures

- if you created a helpmap file for you application, a subdirectory named `help` containing the helpmap file

### Building the Online Help

Once you have written the online help and done the preparation described in “Preparing to Build the Online Help”, you can build and view the online help. To do so, follow these steps:

1. Go to the directory that contains the online help files.

2. Enter:

       % make help

   If the help is formatted properly, the online help will build. You should see a file called `booklist.txt` and a directory called `books`.

   If the SGML file contains errors, you will see them displayed in the shell window. See “Finding and Correcting Build Errors” for details.

3. View the book by typing

       % iiv -b . -v title

   Where title is the value of TITLE from the Makefile.

### Finding and Correcting Build Errors

The SGML tags come in pairs. Each pair contains an opening tag and a closing tag, and the tag applies to everything between the opening tag and the closing tag. If you use these tags incorrectly, you'll get error messages when you build the help file. The most common errors are the result of misspelled tag names, mismatched end tags, or tags used out of sequence.

Some examples of common error messages are:

    mkhelperror: not authorized to add tag 'PAR', ignoring content.

This error appears if you specify an invalid tag. In this case, the invalid tag is “PAR.” The valid tag name is “PARA.”

    mkhelperror: Start-tag for 'HELPLABEL' is not valid in this context.
    mkhelp  Location:  Line       37 of entity '#DOCUMENT'
    Context:   'hor point for the link
    syntax.</>&#RS;</HelpTopic>&#RS;&#RS;<Helplabel>'...
                 '<Anchor Id="AI003">Using Notes, Warnings or Tips Within a P'
         FQGI:      DOCHELP

This error message occurs when the parser sees a tag it isn't expecting. In this case it found a HELPLABEL that was not preceded by a HELPTOPIC start tag. The error message specifies the line number of the error (37), the context in the file, and the Fully Qualified Generic Identifier (FQGI) of the context. You can probably ignore the FQGI; it describes where the error occurs within the SGML structure.

    mkhelperror: No 'WARNING' is open, so an end-tag for it is not valid.
    The last one was closed at line 46.
    mkhelp  Location:  Line       46 of entity '#DOCUMENT'
    Context:   '<warning>Missing open para. This is a
    warning.</></warning>'...
                 '&#RS;<note><para>For your information, this is a note.</></note'
       FQGI:      DOCHELP,DESCRIPTION,PARA,PARA

This message can occur if you close items with the generic end tag, </>. In this case, the </> closes the <warning> because the start tag for <para> is missing. This may occur if you leave out a start tag or accidentally spell it incorrectly.

If you want additional information about the errors, use the command `make verify`. It produces a more detailed error log.

## Producing the Final Product

This section describes how to package your online help as a subsystem that users can install using Software Manager (`swmgr`), the Silicon Graphics software installation utility. Topics include:

- “Creating the Installable Subsystem”

- “Incorporating the Help Subsystem into a Product With a Custom Installation Script”

- “Incorporating the Help Subsystem into an Installable Product”

### Creating the Installable Subsystem

After you've finished writing and building your online help, you need to package it so that users can install it with the rest of your product. To do so:

1. Go to the directory that contains the online help.

2. Enter:

       % make images

   This produces a directory called `images`. This directory contains all of the files you need to let users install the online help using Software Manager.

### Incorporating the Help Subsystem into an Installable Product

If you use the Software Packager utility (`swpkg`) to package your product so that users can install it using Software Manager, you need to merge the online help subsystem with the rest of your product. Consult the Software Packager User's Guide for detailed instructions for using `swpkg`.

You don't need to use `swpkg` to create spec or IDB files for your online help subsystem. By following the instructions in “Preparing to Build the Online Help”, you created the spec file. The process of building your online help, described in “Building the Online Help” automatically created an IDB file and tagged the files; set the permissions and destinations; and assigned the necessary attributes. The online help build tools use “/” as the Source and Destination Tree Root directories when generating the IDB file. (The Software Packager User's Guide defines all of these terms.)

If you've not already created the spec and IDB files for the rest of your product using `swpkg`, you can use `swpkg` to open the existing help subsystem spec and IDB files, and expand them as needed to handle the rest of your product. Consult the Software Packager User's Guide for instructions.

If you've already created the spec and IDB files for your product, you can merge the help subsystem with the existing files as described in “Combining Existing Products Into a Single Product” in Chapter 7 of the Software Packager User's Guide.

### Incorporating the Help Subsystem into a Product With a Custom Installation Script

If you don't use `swpkg` to package your product for installation with Software Manager, do one of the following.

- If users install your product using the `tar` command, have them use `tar` to copy the online help images as well. After copying the images, the user needs to type:

      # inst -af <inst_product>

  where inst_product is the location of the images.

- If you've created a script, enhance the script so that it extracts all of the help images onto disk, and then invokes the command:

      # inst -af <inst_product>

  where inst_product is the location of the images.

## Bibliography of SGML References

1. *SoftQuad, Inc. The SGML Primer. SoftQuad's Quick Reference Guide to the Essentials of the Standard: The SGML Needed for Reading a DTD and Marked-Up Documents and Discussing Them Reasonably. Version 2.0. Toronto: SoftQuad Inc., May 1991. 36 pages. Available from SoftQuad Inc.; 56 Aberfoyle Crescent, Suite 810; Toronto, Ontario; Canada M8X 2W4; TEL: +1 (416) 239-4801; FAX: +1 (416) 239-7105.

2. Bryan, Martin. SGML: An Author's Guide to the Standard Generalized Markup Language. Wokingham/Reading/New York: Addison-Wesley, 1988. ISBN: 0-201-17535-5 (pbk); LC CALL NO: QA76.73.S44 B79 1988. 380 pages. A highly detailed and useful manual explaining and illustrating features of ISO 8879. The book: (1) shows how to analyze the inherent structure of a document; (2) illustrates a wide variety of markup tags; (3) shows how to design your own tag set; (4) is copiously illustrated with practical examples; (5) covers the full range of SGML features. Technical and non-technical authors, publishers, typesetters and users of desktop publishing systems will find this book a valuable tutorial on the use of SGML and a comprehensive reference to the standard. It assumes no prior knowledge of computing or typography on the part of its readers.

3. Goldfarb, Charles F. The SGML Handbook. Edited and with a foreword by Yuri Rubinsky. Oxford: Oxford University Press, 1990. ISBN: 0-19-853737-1. 688 pages. This volume contains the full annotated text of ISO 8879 (with amendments), authored by IBM Senior Systems Analyst and acknowledged “father of SGML,” Charles Goldfarb. The book was itself produced from SGML input using a DTD which is a variation of the “ISO.general” sample DTD included in the annexes to ISO 8879. The SGML Handbook includes: (1) the up-to-date amended full text of ISO 8879, extensively annotated, cross-referenced, and indexed; (2) a detailed structured overview of SGML, covering every concept; (3) additional tutorial and reference material; and (4) a unique “push- button access system” that provides paper hypertext links between the standard, annotations, overview, and tutorials.

4. Herwijnen, Eric van. Practical SGML. Dordrecht/Hingham, MA: Wolters Kluwer Academic Publishers. 200 pages. ISBN: 0-7923- 0635-X. The book is designed as a “practical SGML survival-kit for SGML users (especially authors) rather than developers,” and itself constitutes an experiment in SGML publishing. The book provides a practical and painless introduction to the essentials of SGML, and an overview of some SGML applications. See the reviews by (1) Carol Van Ess-Dykema in Computational Linguistics 17/1 (March 1991) 110-116, and (2) Deborah A. Lapeyre in <TAG> 16 (October 1990) 12-14.

5. Smith, Joan M.; Stutely, Robert S. SGML: The Users' Guide to ISO 8879. Chichester/New York: Ellis Horwood/Halsted, 1988. 173 pages. ISBN: 0-7458-0221-4 (Ellis Horwood) and ISBN: 0-470-21126-1 (Halsted). LC CALL NO: QA76.73.S44 S44 1988. The book (1) supplies a list of some 200 syntax productions, in numerical and alphabetical sequence; (2) gives a combined abbreviation list; (3) includes highly useful subject indices to ISO 8879 and its annexes; (4) supplies graphic representations for the ISO 8879 character entities; and (5) lists SGML keywords and reserved names. An overview of the book may be found in the SGML Users' Group Newsletter 9 (August 1988).

6. ISO 8879:1986. Information Processing—Text and Office System—Standard Generalized Markup Language (SGML). International Organization for Standardization. Ref. No. ISO 8879:1986 (E). Geneva/New York, 1986. A subset of SGML became a US FIPS (Federal Information Processing Standard) in 1988. The British Standards Institution adopted SGML as a national standard (BS 6868) in 1987, and in 1989 SGML was adopted by the CEN/CENELEC Standards Committees as a European standard, #28879. Australia has dual numbered versions of ISO 8879 SGML and ISO 9069 SDIF (AS 3514—SGML 1987; AS 3649—1990 SDIF).

7. ISO 8879:1986 / A1:1988 (E). Information Processing—Text and Office Systems—Standard Generalized Markup Language (SGML), Amendment 1. Published 1988-07-01. Geneva: International Organization for Standardization, 1988.

Prev | Table of Contents | Next
Chapter 8. Monitoring Changes to Files and Directories |  | Chapter 10. Handling Users' System Preferences