Introduction

Sun WorkShop Visual provides extensive on-line help which can be accessed from many different points in the application. This chapter describes the support that Sun WorkShop Visual provides for building help into your application.

The Help Model

The model used to support help in your application is very simple. You can either use the help callback, available with all Motif widgets, or an activation callback on a help button. Therefore, to provide context-sensitive help, all you need is a generic callback that takes as its client data the help (or a path to the help) to be displayed when the callback is invoked. In Sun WorkShop Visual this help specification is defined as a document path and a marker that denotes some reference in that document. We supply a callback that can be used with one of the help system interfaces provided with Sun WorkShop Visual. See "Help Viewers" on page 604 for more information on which systems are provided to display your help.

Obviously you are free to re-implement the callback that you use in your application to make it interface with the help system of your choice. Likewise, you can achieve the same effect simply by using the ordinary callback mechanisms, or you can decide not to give your users any on-line help at all.

Internally, Sun WorkShop Visual uses two systems when displaying help:

Sun WorkShop Visual Help. This is the help viewer with built-in navigation commands and links to related help topics.

Netscape. This is used as a HTML browser.

In order to try out your help within Sun WorkShop Visual you will have to use one of these.

Motif's Help Callback

By default in Motif the Help callback is invoked by the Help action which is specified for every widget. This action is bound to the <osfHelp> key using a default translation in every Motif class.

Help Viewers

Sun WorkShop Visual provides interfaces to the following viewers:

Sun WorkShop Visual Help

Netscape

FrameMaker

You can use these to display help in your application. They are explained in more detail in the following sections.

You set up help for your application in the same way, regardless of which viewer you intend to use. You then link your application with the appropriate supplied library, as described in "Help Implementation" on page 617.

Sun WorkShop Visual Help

Sun WorkShop Visual Help is the help viewer used by Sun WorkShop Visual and is shown in Figure 21-1.

FIGURE  21-1 Sun WorkShop Visual Help Viewer

The Sun WorkShop Visual Help help viewer contains a menubar with "File", "Edit", "Navigation" and "Help" menus containing file, editing and navigation commands respectively. The "Help" menu contains version information and help on using Sun WorkShop Visual Help. A toolbar is also provided with buttons for quick access to most of the menu items. As you pass the mouse pointer over the toolbar buttons, information about the function of the button is displayed in the status line at the bottom of the viewer window.

There are two text areas in the help viewer. The topmost text area displays help about the currently selected topic. The bottom area contains links to other related topics. Double clicking over one of the links displays help on that topic.

The files used by Sun WorkShop Visual Help are in HTML (HyperText Markup Language). This is a public domain format which uses only printable characters and can, therefore, be created in any text editor. It is also a standard used by many applications.

Sun WorkShop Visual Help does not claim to be a full HTML interpreter; it recognizes a subset of HTML and interprets them in a simple way. "HTML Tags" on page 607 describes the HTML keywords recognized by Sun WorkShop Visual Help and the way they are interpreted.

See Appendix E, "Further Reading" for suggested books on HTML.

Netscape

Netscape is a browser which takes HTML (HyperText Markup Language) files and displays them complete with any hypertext links or special formatting you have specified.

Netscape also provides file operations and navigation commands allowing the user to browse around the help files you provide.

FrameMaker

FrameMaker is a desktop publishing package which uses its own internal format. FrameMaker also provides a means of viewing and browsing around read-only documents. For information on using FrameMaker as your help viewer, see "Using FrameMaker" on page 611.

Using HTML in Help Documents

Both Sun WorkShop Visual Help and Netscape read HTML files. You will need to write the files so that you have specified HTML anchors at points which will be the source and destination of a link. You should remember the names of these anchors as they are used to specify the help action for individual widgets.

These anchor points are the "markers" in Sun WorkShop Visual which are specified in the Help callback. Setting up Help callback markers is explained in "Setting up Help in Sun WorkShop Visual" on page 612.

To use either Sun WorkShop Visual Help or Netscape as the help system in your application you will need to do the following:

HTML Tags

This section gives a brief description of the major HTML keywords, known as tags. The tags listed here are all those interpreted by Sun WorkShop Visual Help. The description given offers an indication of the way the tags are interpreted by most full HTML interpreters (such as Netscape) and the way they are interpreted by Sun WorkShop Visual Help, if different.

In HTML tags are enclosed within angle brackets (< and >). You must use these brackets in your text files. See "Example HTML document" on page 610 for an illustration of the way you should use HTML tags in your documents.

The tags have been divided into categories according to their usage. Note that the tags are listed here in uppercase. HTML, however, is not a case sensitive language. You can, therefore, use either case.

Starting and Ending

<HTML> All HTML documents start with this tag.

</HTML> HTML documents end with this.

Anchors and Links

<A NAME="anchorname">text</A> This is an anchor which will be used as the destination of a link. anchorname is your internal name for the anchor. text is the text you want people to click on to go to the link destination.

<A NAME="#anchorname">text</A> This is the source of a link to another part of the same document. anchorname is the internal name given to the anchor.

You can have links to other files using relative or absolute pathnames. An external file can even reside on another server. For external links anchorname is the filename and you should omit the `#' sign at the beginning.

Paragraph

<P> This tag is used to indicate the start of a paragraph. Paragraphs are separated by a blank line.

</P> This tag is used to indicate the end of a paragraph.

Break

<BR> This tag indicates a hard line break. If there is no line break, the text will flow to fit the width of the browser window.

Lists

Sun WorkShop Visual Help does not handle the different types of list in the way most HTML interpreters do. Lists are interpreted for compatibility so that existing HTML documents can be used.

<OL> Indicates that the following lines are an ordered list. Most HTML implementations would put a number in front of the list items but Sun WorkShop Visual Help simply prints a `-' (dash).

</OL> Indicates the end of an ordered list.

<UL> Indicates that the following lines are an unordered list. Most HTML implementations would put a bullet mark in front of the list items but Sun WorkShop Visual Help simply prints a `-' (dash).

</UL> Indicates the end of an unordered list.

<DL> Indicates that the following lines are a definition list. Most HTML implementations would expect a "term" and a "definition" as in a glossary - Sun WorkShop Visual Help simply prints a `-' (dash) in front of each item in the list.

</DL> Indicates the end of a definition list.

<LI> Indicates a list item. A `-' (dash) is printed at the beginning of the line.

<DT> Indicates a "term" in a definition list. Sun WorkShop Visual Help treats these as plain list items.

<DD> Indicates a "definition" in a definition list. Sun WorkShop Visual Help treats these as indented list items with no `-' (dash).

Character Formats

<EM> Indicates the following text should be emphasized. Some HTML interpreters use italic and some use bold. Sun WorkShop Visual Help prints a `*' (asterisk) before and after the text.

</EM> The end of the text to be emphasized.

<B> Indicates the following text should be printed in bold. Sun WorkShop Visual Help prints a `*' (asterisk) before and after the text.

</B> The end of the text to be printed in bold.

<I> Indicates the following text should be printed in italic. Sun WorkShop Visual Help prints a `*' (asterisk) before and after the text.

</I> The end of the text to be printed in italic.

Headings

HTML defines a range of headings from "H1" to "H6" which, according to most HTML interpreters, start large and bold and gradually lessen in size and weight. Sun WorkShop Visual Help simply prints two blank lines before a heading. The heading tags indicate the beginning and end of the text of the heading:

<H1>First Level Heading</H1>

<H2>Second Level Heading</H2>

<H3>Third Level Heading</H3>

<H4>Fourth Level Heading</H4>

<H5>Fifth Level Heading</H5>

<H6>Sixth Level Heading</H6>

Preformatted Text

<PRE> Most HTML interpreters format the text in a HTML document ignoring any extra spaces, tabs or line returns. The "preformatted" tag causes the interpreter to print the text as you typed it and uses a monospaced font, such as Courier. Sun WorkShop Visual Help only prevents the output function from stripping white space.

</PRE> End of preformatted text.

Example HTML document

Below is an example of a help document written for Sun WorkShop Visual Help in HTML:

<html>

<head>

About Sun WorkShop Visual

</head>

<h1>About Sun WorkShop Visual </h1>

<p>This is Sun WorkShop Visual, a tool to help you develop Motif

Graphical user Interfaces.

<p>

If you are new to Sun WorkShop Visual, select `Getting Started' in the

 list below, and then press the Follow link button.

<p>

A complete list of help topics is available, and can be viewed by 
similarly selecting the `Index of Help Topics' item.

See also:

<ul>

  <li><a href="get_started">Getting Started</a><br>

  <li><a href="dialogs">Resource Panels and other >Sun WorkShop Visual 

dialogs</a><br>

  <li><a href="widget_list">Widgets</a><br>

  <li><a href="code_gen">Code Generation</a><br>

  <li><a href="index">Index of Help Topics</a><br>

</ul>

</html>

This file is shown displayed in Sun WorkShop Visual Help in Figure 21-1.

Using FrameMaker

If you plan to use FrameMaker to build your help system, you must know how the FrameMaker hypertext system works. Complete documentation is provided in your FrameMaker manuals and a brief summary is given below.

FrameMaker lets you mark places in the text as either source or destination markers. Destination markers are places you can jump to in a help document. Source markers are places in a help document or your application that the user can select which cause an action, usually a jump to a destination marker. Source markers in a help document require a visual clue to tell the user he can click on them. The best way to do this is to specify a character format such as italics or underline to denote a source link.

When the user clicks in a document at a place where the special character format is in effect, FrameMaker checks for a source marker in that area. If it finds one, it highlights the whole graphical area or section of text and executes the action specified by the marker.

You can insert these special markers into your FrameMaker document by using the "Marker" command from the Special menu.

A tag can be specified either as <tag_name> for a tag in the current document, or as <document_name>:<tag_name> for a tag in a different document.

This command gives you the option of saving the document in its locked state.

Setting up Help in Sun WorkShop Visual

The term tag means the combination of a document and a marker. Help Tags are specified from the "Code generation" page of the Core resource panel. There are two Help tags that can be specified: one for the Help callback, which can be specified for any Motif widget, and one for the Activate callback, which can only be specified for PushButton and CascadeButton widgets.

---

Note - The Activate callback for a CascadeButton is only called if there is no pulldown menu associated with it.

---

To specify a tag, type the name of the document and the name of the marker, and press "Apply". You should now be able to display that document by invoking the callback in the dynamic display, which is done by clicking on the button for an Activate callback, or pressing <F1> for a Help callback.

When you specify tag information in the Core resource panel, Sun WorkShop Visual automatically adds the callback function XDhelp_link() to the appropriate callback list for the widget. You do not have to specify a callback in the Callbacks dialog for the widget.

Inherited Documents

You may be able to specify some of your help information by typing the marker only, without having to retype the name of the help file. If you specify a marker but no document name for the Help callback, Sun WorkShop Visual uses the Help callback document of the closest parent widget. If none of the widget's ancestors has a Help callback document, Sun WorkShop Visual uses the default document specified in the Module Help defaults panel, as described in the Module Defaults section below.

In the case of the Activate callback, if no document is explicitly set the document for the Help callback is used. If this is not set, the same Help document inheritance, described above, takes place.

Module Defaults

There are numerous help defaults that can be specified on a per module basis. To specify these defaults, pull down the Module Menu and select "Help defaults". The resulting dialog is shown in Figure 21-2.

FIGURE  21-2 Help defaults dialog

The Help Defaults Dialog lets you specify defaults for use both in building the help system in Sun WorkShop Visual and in the finished application.

TABLE  21-1  

Default document:	This field specifies the name of the default document for use if no other document is specified on an individual widget.
Default path:	All help tag document names are assumed to be relative paths unless they begin with "/". This field specifies a default path to be added to the beginning of any relative path document names. The Default path is also used to find documents when you test your help in Sun WorkShop Visual.
Path resource:	In the application, you can override the Default path setting by setting an application resource. This field specifies the name of the application resource.
Path environment variable:	You can also override the resource setting by setting an environment variable. This field specifies the name of the environment variable.
Default translation:	This field specifies an event to be added as a translation to every widget that has a marker specified for the Help callback. The translation calls the Help() action. This lets you designate a key combination as an application help key.
Preview Viewer	This option menu lets you specify which help viewer Sun WorkShop Visual should use when you ask to preview your help document(s). There are three options: Sun WorkShop Visual Help, Netscape and FrameMaker.
Always own window:	This toggle makes the FrameMaker integration callback display the document in its own window. If this toggle is off, an existing window is used to display the new page. You can designate the use of a new window for individual pages using the "Own window" toggle in the Help documents and markers dialog.

Finding Help Documents and Markers

The "Activate callback" and "Help callback" buttons in the "Code generation" page of the Core resource panel can be used to display a dialog showing all the documents and markers that are currently referenced by your design.

FIGURE  21-3 Help Documents and Markers Dialog

TABLE  21-2  

Add:	You can add a document or marker by typing the name in the appropriate selection field and pressing "Add".
Delete:	You can delete a document or marker by selecting its name from the list and pressing "Delete". You cannot delete documents or markers that are still referenced by a widget in the design.
Find:	This button pops up a file selection dialog to help you navigate in the file system. You can also display this dialog by selecting the "Default path" or "Default document" buttons in the Help defaults dialog.
Preview:	This button makes Sun WorkShop Visual try to connect to the selected help viewer and display the named document at the named marker. Select which help viewer you wish to use in the Module Help Defaults dialog - see "Module Defaults" on page 613.
Own window:	Each document has an "Own window" flag associated with it. This flag forces the system to display this document in its own window, not to share a common window with other documents. This toggle lets you designate the state of the flag for the selected document.
<Open>:	A special default marker that causes the document to be opened at the first page.
<Widget name>:	A special default marker that uses the widget name as a marker to jump to in the document.

Linking Help into your Application

To use Sun WorkShop Visual's default help callback function, you must link in the supplied object files which can be found in Sun WorkShop Visual's installation directory (referred to below as $VISUROOT).

There are three directories, one for each help viewer. For Sun WorkShop Visual Help and FrameMaker you will also need to link with additional files.

Sun WorkShop Visual Help

To use Sun WorkShop Visual Help you will need to link the file helplink.o in with your application. The source of this object file, helplink.c, is found in:

$VISUROOT/src/libhelplink/helplink

There is also a Makefile with instructions for building helplink.o and a file named README with information on linking in Sun WorkShop Visual Help.

In addition you will need to link in the library in:

$VISUROOT/src/help/client

There is a Makefile in that directory with instructions for building the library.

Netscape

To use Netscape you will need to link the file helplink.o in with your application. The source of this object file, helplink.c, is found in:

$VISUROOT/src/libhelplink/nshelplink

There is also a Makefile with instructions for building helplink.o and a file named README with information on linking in Netscape.

FrameMaker

To use FrameMaker you will need to link the file helplink.o in with your application. The source of this object file, helplink.c, is found in:

$VISUROOT/src/libhelplink/fmhelplink

There is also a Makefile with instructions for building helplink.o and a file named README with information on linking in FrameMaker.

In addition you will also need to build the files in

$VISUROOT/src/libhelplink/fmhelplink/libframe/fmclient

There is a Makefile in that directory with instructions for building the library.

Other

You can also supply your own Help callback function. This function should also be called XDhelp_link() and should follow the same form as Sun WorkShop Visual's function. See the Help Implementation section below for suggestions on how to customize the Help callback function.

Help Implementation

The preceding descriptions show how the help system works within Sun WorkShop Visual. If you use the default Help callback provided with Sun WorkShop Visual, the help in your application will work in the same way. However, you may want to customize your implementation of the Help callback. The following sections describe how to do so using the FrameMaker integration as a guide.

The Sun WorkShop Visual directory libhelplink/fmhelplink contains all the sources for the FrameMaker integration callback XDhelp_link. The subdirectory libframe contains various source files, adapted from the FrameMaker release. The original files are in $FMHOME/source/openmaker if you want to check them out.

XDhelp_link() receives a client_data parameter that is a pointer to an _XDHelpPair_t structure:

typedef struct _XDHelpPair_s {

_XDHelpDoc_p	 doc;

char	** tag; 

Bool	 open_doc;

} _XDHelpPair_t, *_XDHelpPair_p;

This contains a pointer to an _XDHelpDoc_t structure, a pointer to a marker (tag), and an open_doc flag. If tag is NULL the developer has specified one of the default markers: <Widget name> if open_doc is FALSE, <Open> if open_doc is TRUE. The document structure is:

typedefstruct_XDHelpDoc_s{

char	* doc;

char	** path;

int 	handle;

Bool 	new_window;

}_XDHelpDoc_t,*_XDHelpDoc_p;

The doc field is the name of the document. path is a pointer to the default path if one exists. This path is calculated as described above, taking account of the setting of the help path application resource and environment variable. handle is the document handle returned from FrameMaker, and new_window specifies whether the document is to have its own window.

The main code file contains static arrays of documents and markers, and an array of tag pairs that points into the other arrays. A pointer to an element in the tag pairs array is passed as the client data.

XDhelp_link() calls the appropriate routines to communicate with FrameMaker to display the document as requested. Other implementations of XDhelp_link() communicate with different help systems. There are libraries supplied for integrating with Netscape and with Sun WorkShop Visual Help.