Hypertext Help

17

17.1 Introduction

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

17.2 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 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 WorkShop Visual. See the Help Viewers section on page 570 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, WorkShop Visual uses two systems when displaying help:

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 WorkShop Visual you will have to use one of these.

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

17.3 Help Viewers

WorkShop Visual provides interfaces to the following viewers:

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 the Help Implementation section on page 584.

See the Setting up Help in WorkShop Visual section on page 578 for information on adding help callbacks to widgets in your design. Note that you will need to follow the instructions in the Linking Help into your Application section on page 583 so that the help callback is defined in your application.

3. Link the generated code with the WorkShop Visual Help or Netscape libraries provided

See the Help Implementation section on page 584.

17.3.5 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 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 WorkShop Visual Help, if different.

In HTML tags are enclosed within angle brackets (< and >). You must use these brackets in your text files. See the Example HTML document section on page 576 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

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 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 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 - 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. WorkShop Visual Help treats these as plain list items.

<DD> Indicates a "definition" in a definition list. 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. 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. 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. 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. 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. WorkShop Visual Help only prevents the output function from stripping white space.

</PRE> End of preformatted text.

17.3.6 Example HTML document

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

<html>

About WorkShop Visual

<h1>About WorkShop Visual </h1>

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

Graphical user Interfaces. </p>

<p>

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

 list below, and then press the Follow link button.

</p>

<p>

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

</p>

See also:

<ul>

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

  <li><a href="dialogs">Resource Panels and other >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 WorkShop Visual Help in Figure 17-1.

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

: 1. Select "Hypertext" from the Marker Type list.

2. To specify a destination marker, type: newlink <tag_name> in the Marker Text field.

3. To specify a source marker, type: gotolink <tag_name>

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.

4. Hypertext markers are only effective in a locked document. To toggle the lock of a document on or off, type: <escape> <F> <l> <k>

5. To exit from a locked document, type: <escape> <f> <c>

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

17.4 Setting up Help in 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, 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.

17.4.1 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, WorkShop Visual uses the Help callback document of the closest parent widget. If none of the widget's ancestors has a Help callback document, 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.

17.5 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 17-2.

Figure 17-2 Help defaults dialog

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


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 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 WorkShop Visual should use when you ask to preview your help document(s). There are three options: 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.

17.6 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 17-3 Help Documents and Markers Dialog


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 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 the Module Defaults section on page 579.
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.

17.7 Linking Help into your Application

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

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

17.7.1 WorkShop Visual Help

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

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

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

17.7.4 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 WorkShop Visual's function. See the Help Implementation section below for suggestions on how to customize the Help callback function.

17.8 Help Implementation

The preceding descriptions show how the help system works within WorkShop Visual. If you use the default Help callback provided with 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 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 primary module 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. You are free to use a different implementation of XDhelp_link() to communicate with a different help system.