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

---

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

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

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().

#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", "." );
 
    /* ... */
}

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

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

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

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

#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 );

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);

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().

/* 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 );

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:

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

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.

/* 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);
}

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.

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);
          }
     }
}

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.

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 …]

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.

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:

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.

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:

To create the help document file for your application:

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.

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 spec file specifies:

To create these files, follow these steps:

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

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:

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.

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:

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.

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