Context Sensitive Help Terminology
The following terms are used in discussing Context Sensitive Help.
Application Context A string, defined by the application programmer,
that is used as a key to find a help page.
Document Tag A help file specific tag that points to a specific
page in a help document. There is a one-to-one correspondence between an
application context and a document tag.
NX Translation Table Translation table used by NX to associate
the Application Context to the Document Tag.
HTML file Hyper Text Markup Language version of a help file that
can be viewed using a standard browser. HTML is a non-proprietary format,
based upon SGML, and is widely used for publishing hypertext on the World
Wide Web (WWW). HTML uses tags to structure text into headings, paragraphs,
lists, hypertext links and more.
Interleaf A desktop publishing system.
WorldView file A read-only version of a help file that can be
viewed or printed with Interleaf's WorldView product. WorldView files have
a ".pl" file extension and are some times referred to as printerleaf/WordView
files.
WorldView A tool that displays a collection of WorldView files.
WorldView climap.cli A map file created by WorldView used to
determine the proper location in the documentation given the locator name.
WorldView Press A tool for converting Interleaf documents into
WorldView collections.
The Context Sensitive Help Mechanism
The context sensitive help mechanism begins with calls made by the Open C
developer to push application contexts onto a stack before entering a dialog.
These application contexts are tracked by the help mechanism and capture
the path the user has taken through the application. When the user requests
context sensitive help, the help mechanism uses the application contexts
to initiate the display of help.
The current application context from the stack is looked up in a translation
table to find the display method and the actual document tag. The display
method specifies a format type for the help, either HTML, plain text or
WorldView. The document tag specifies the directory of the help files,
and in the case of HTML and WorldView, a specific location within the document.
The following are the basic steps required for implementing context
sensitive help.
1. Create help files. For HTML files you can include location anchors
and hyperlinks that branch to other help files. For WorldView collections,
you must include locators that reference specific pages in a collection.
2. Create a translation table that establishes mappings between application
contexts and the appropriate help files.
3. Insert calls in the application code to push application contexts.
Context Sensitive Help Preparation
The first thing to be done as an Open C developer who wants to hook
up with the Context Sensitive help mechanism is to decide which dialogs
require specific help pages in a document. The other items that require
consideration are:
- Unique naming conventions.
- Creation of help files. These can be HTML help files, with optionally
embedded positioning anchors, simple text help files, or an Interleaf WorldView
collection containing properly positioned locator tags.
- Creation of a translation table.
- Translation table syntax rules.
- WorldView Document Tags.
Naming Conventions
Application contexts should be unique across any translation tables
that might be loaded at the same time so that name conflicts do not occur.
We recommend that the application context and the WorldView document locator
be constructed with the vendor name along with the name of the function.
<Vendor_Name>_<Function_name>
For example, a vendor application with a DA1 could use the following
(assume the vendor name is "vnd"):
vnd_import
vnd_export
vnd_plot
vnd_fileUtilites
vnd_objectDisplay . .
For help based on text or HTML files the mappings consist of individual
document ids. For HTML mappings you can optionally include anchor locations.
For WorldView help, mappings refer to locations in a WorldView collection.
Each WorldView mapping specification includes the name of a locator tag
that identifies the correct site in the collection.
HTML Based Help
Context sensitive help supports the use of HTML help files. All you
need to do is create the HTML files containing your help text, and then
add entries to the translation table that maps them for NX.
When you request HTML based context sensitive help from NX,
the system checks the mapping specified for the application context in
the translation table, and then displays the help using the web browser
startup script specified by the UGII_CSHELP_BROWSER environment variable.
These are the details on the translation table.
These are the details on inserting HTML document
tags in the translation table.
Text File Based Help
Context sensitive help supports the use of help files composed of plain
text. As with HTML help files, all you need to do is create your help text
in plain text files, and then add entries to the translation table that
maps them to NX.
When you request text based context sensitive help from NX,
the system checks the mapping specified for the application context in
the translation table, and then displays the text in the Information window.
These are the details on the translation table.
These are the details on inserting text document
tags in the translation table.
WorldView Based Help
WorldView based context sensitive help requires more steps and a greater
effort to setup than its HTML and text based counterparts. A WorldView
help collection, however, supports full-text search capabilities not provided
by HTML and text based help. This section includes instructions on preparing
help files based on Interleaf WorldView collections.
These are the details on the translation table.
These are the details on inserting WorldView document
tags in the translation table.
Creating Locators in a World View Collection
Context sensitive help supports the use of help files based on Interleaf
WorldView collections. Help based on a WorldView collection is specified
by the translation table and locator tags embedded in the Interleaf text.
In preparation for creating locators, the Interleaf writer should open
Interleaf and:
- Select Tools-->Admin-->Tool Manager from the desktop.
Enable the Hyperleaf Toolkit 3.3 option.
- Execute File-->New-->Tools-->Hyperleaf-->HyperMap
to create a HyperMap file on the desktop.
- Create additional HyperMap files in each book that requires locators
by executing File-->New-->Tools-->Hyperleaf-->HyperMap.
Books within books should have a HyperMap at each book level. You can add
locators to paragraphs or graphics frames. Multiple locators can exist
per paragraph or frame.
To install a locator, open the Hyperleaf dialog, either from inside
a document (Tools-->HyperLeaf...) or from a container window
such as the Desktop (Tools-->HyperLeaf-->HyperLeaf...).
Once the HyperLeaf dialog is open, it can be left open for the session.
Open the document and find the paragraph or frame to receive the locator
that is to reference the appropriate DA1 help dialog. If you use a paragraph,
position the cursor inside the paragraph. If you use a frame, select the
frame (highlighted black).
To create a locator the choose the Locators... button on the
HyperLeaf dialog. This opens the Locators dialog.
The Locators dialog lets you add and delete locators. The procedure
is to type the name of the locator (such as vnd_fileUtil) in the entry
field and then press the Add button. Once you add the locator, then
press Apply.
Save the document when you have finished adding all locators.
Use the menu bar option, Edit-->Find Object-->HyperLeaf Locator,
to search for hidden locators in a document
Placing Locators in interleaf Documentation
Place a locator at a location in the documentation that provides immediate
help for a user seeking either general or specific information. The type
of information provided to the user should depend on what dialog is current.
Generally, writers should regard locators as landing points in the documentation
for one of two kinds of users: those seeking specific information and those
seeking general information. The type of user usually depends on the launch
point from the third party application within NX.
Landing points can be made for Interleaf frames containing figures of
NX dialogs overlaid with page reference links for options on the dialog,
each jumping to a different description.
An attempt should be made to:
- standardize the context sensitive landing points.
- provide as many page reference links as possible.
Creating The Translation Table
The translation table contains a mapping from the application context
to the actual document and page that contains the help information. The
translation table also contains information about the type of display program
to call in order to display the help file.
The translation table itself is a plain ascii text file that contains
some header information along with ordered pairs of application contexts
and document tags.
Translation Table Syntax Rules
The syntax for the translation table is as follows.
<app_context> = <display_method> <document_tag>
Where:
<app_context> is the context used with UF_HELP_push_context.
<display_method> is the display method string. You can
choose from one of three methods:
HTML for HTML format
text for plain text format
WorldView for WorldView format
<document_tag> is information necessary for the help display
method application to find the actual document to display.
For HTML this is the URL for the help file, and an optional anchor location.
For text this is the full pathname for the plain text help file.
For WorldView this is the path to the map (.cli) file and the WorldView
locator.
The following rules are used to parse the translation table.
1. Leading and trailing blanks are ignored.
2. If the first nonblank character is a # sign, the line is ignored.
3. Blanks before or after the "=" sign separator are ignored.
4. Multiple blanks for the document tag are compressed to a single blank.
5. Spaces with the braces for an environment variable are ignored.
6. The <app context> and <document_tag> fields are case sensitive.
7. The <display_method> field is case insensitive.
8. For the HTML display method, a pound sign with trailing text (e.g.,
#info1) appended at the end of a document tag specifies the name of a destination
anchor location.
An example of entries in a translation table using all three display
methods is shown below:
#
# Vendor Apps Translation Table
#
vnd_ugphoto=HTML http://www.vendor.com/helpfiles/ug_photo.html#info1 vnd_displaypref=HTML
http://www.vendor.com/helpfiles/displayprefs/disp.html vnd_viewopt=HTML
file:/helpfiles/viewoptions/viewopt.html#viewopt1
vnd_fileopen=text /proj/inter45/vnd_fopen.txt
vnd_partpolicy=text ${VND_HELP_LOCATION}/vnd_policy.txt
vnd_import=Worldview /vndhlp/ughelp/photo/map.cli import
vnd_export=WorldView /vndhlp/ughelp/climap.cli export
vnd_plot=WorldView ${vnd_HELP_LOCATION} vnd_plot
The entries on the left side of the translation table contain both the
application context for NX and the display method. The right side
specifies the document tag.
For the HTML display method the document tag consists of the
URL and any optional location anchors (e.g., #info1). For the text display
method the document tag consists of the full pathname for the help text
file. For the WorldView display method the document tag consists
of the WorldView map file (.cli) and the World View locator. For further
details on document tags for the three display methods, see HTML
Document Tags, Text Document Tags and WorldView
Document Tags.
With regard to WorldView, it is possible for a single NX translation
table to reference documents in different collections by specifying the
correct map file, as indicated by the use of two different map files, map.cli
and climap.cli, as shown in the above translation table.
The parser for the translation table uses the space between the map
file name and the locator name as the separator. The directory name must
not contain a space for proper parsing.
As shown above, you may use application contexts that differ from the
corresponding WorldView locators or HTML filenames, i.e. the application
contexts on the left hand side do not have to be the same as the locators
on the right hand side. We recommend, however, that for simplicity you
make them the same, as in the case of vnd_plot above.
The previous example also demonstrates the use of directory paths as
well as an environment variable for the specification of the WorldView
map file location.
To use environment variables on UNIX, begin the definition with a "$"
and enclose the environment variable in curly braces: "{" and
"}". For example:
vnd_label=WorldView ${ENVVAR}/climap.cli vnd_label
myAppHelp=HTML file:${UGII_CSHELP_DOCS}/myapp.html
For Windows NT this could be:
vnd_label=WorldView ${ENVVAR}\climap.cli vnd_label
HTML Document Tags
The HTML display method specifies HTML document tags that consist of
the full URL (Uniform Resource Locator), and which begin with "http://"
or "file:/". For example:
vnd_layer=HTML http://www.vendr.com/help/vnd_layer.html
In this example, vnd_layer is the application context, HTML
is the display method and http://www.vendor.com/help/vmd_layer.html
is the document tag.
You can add a specific anchor location to the HTML document tag by including
a pound sign (#) at the end, followed by the name of the desired anchor.
(The name will correspond with the NAME attribute for the anchor tag in
the HTML file.) For example:
vnd_layer=HTML http://www.vendr.com/help/vnd_layer.html#info1
To create a named anchor in an HTML document, use the NAME attribute
of the anchor description (<A NAME="info1">). Place this
anchor in the HTML document at the location you want to be the top of the
page.
Text Document Tags
The text display method contains the full pathname for the ASCII help
file. No positioning information is needed, because the whole file is always
displayed in the Information window. For example:
vnd_layer=text /directory/help/vnd_layer.txt
In this example, vnd_layer is the application context, text
is the display method and /direcotry/help/vnd_layer.txt is the
document tag.
WorldView Document Tags
In the case of WorldView, the program translates from a help string
in the program to a WorldView locator that becomes associated with a specific
WorldView map file. WorldView Press creates its own special mapping file
(climap.cli) along with the World View collection. The World view document
tag in the translation table consists of the WorldView climap.cli file
name along with the WorldView locator.
If no locators are added to a WorldView collection, the climap.cli file
is not generated. Document tags in the translation table contain the path
to the map file and the locators specified in the WorldView collection.
The following is an example climap.cli file:
;; <Date and time of file generation and user name appears here.>
(:version 1)
("vnd_import" "vndbook/3file.pl" 5)
("vnd_export" "vndbook/3file.pl" 20)
("vnd_plot" "vndbook/3file.pl" 49)
("vnd_fileUtilities" "vndbook/3file.pl" 56)
("vnd_objectDisplay" "vndbook/4object.pl" 3)
The climap file maps the locator names to the printerleaf (.pl) files
in a subdirectory (named after the WorldView collection name), which is
located in the collection. The directory path to the printerleaf file is
relative. This means that the map file must be in the same directory as
the subdirectory that contains the printerleaf files.
Assume that the collection shown above was in the directory /vnd/vnddoc,
and the map file name remained climap.cli. Entries in the NX translation
table for this World View collection would look something like what is
shown below:
vnd_import=WorldView /vnd/vnddoc/climap.cli vnd_import
vnd_export=WorldView /vnd/vnddoc/climap.cli vnd_export
vnd_plot=WorldView /vnd/vnddoc/climap.cli vnd_plot
Environment Variables
There are three environment variables that specify the directory paths
to the startup script for customer help, translation tables, and the WorldView
Press collection for NX documentation.
UGII_CSHELP - Points to the startup script for customer site
help. The default setting is as follows.
$UGII_CSHELP=${UGII_BASE_DIR}/ugdoc/cshelp.ksh
UGII_CSHELP_MAPS - Points to the directory containing the translation
table (i.e. "*.tbl") files. The default setting is as follows.
$UGII_CSHELP_MAPS=${UGII_BASE_DIR}/ugii/docmaps
UGII_CSHELP_DOCS - Points to the World View press collection
for the NX documentation set. The default setting is as follows.
$UGII_CSHELP_DOCS=${UGII_BASE_DIR}/ugdoc/pl_files
UGII_CSHELP_BROWSER - Sets the default web browser for the HTML
display method (HTML file format). The default setting is as follows.
$UGII_CSHELP_BROWSER=${UGII_BASE_DIR}/ughelp/cshelp_html.ksh
Programming Context Sensitive Help
For context sensitive help, the NX dialogs are broken down
into two categories, one for DA1 dialogs, and one for all other dialogs.
Load The Translation Table
The translation table is used to isolate the application code from changes,
to help locations or help mechanisms by providing one level of indirection
between the application context and the actual data needed to invoke the
help file.
The translation table needs to be loaded by the application prior to
using the application contexts. The translation table is loaded by calling:
UF_HELP_load_map_file( char *map_file_name);
The translation files can be specified either with a full path name,
or by just using the file name. If the file name is used, the program first
looks for the translation table in the working directory and then in a
directory specified by the environment variable, UGII_HELP_DIR.
Once a translation table has been loaded, subsequent calls to load the
same translation table are ignored. Translation tables can be unloaded
by calling UF_HELP_unload_map_file, or can be reloaded during debugging
of the translation table by calling the function UF_HELP_reload_map_file.
Add Application Contexts
The help mechanism uses a stack to keep track of the application contexts,
so that immediate help can be offered on the current context. The 3rd party
developer places a procedure call before the display of a dialog and after
the operation of the function in order to add and remove application contexts
from the context sensitive help system.
Add DA1 Dialog Contexts
For a DA1 dialog the programmer calls UF_HELP_push_primary_context to
place an application context on the help stack. Consider the following
example:
void fcn_DA1()
{
UF_HELP_push_primary_context("FCN1_MAIN");
while (!done)
{
switch( response )
{
case MATERIAL_ITEM:
do_materials(...);
break;
case TEXTURE_ITEM:
do_textures(...);
break;
case ...;
}
}
}
In the example above a call has been made to push a primary (DA1) context
onto the stack somewhere near the top of the function. This is the only
change required in this function.
Add Other Dialog Contexts
When adding application contexts to other dialogs you need to use the
calls UF_HELP_push_context and UF_HELP_pop_context. The push
call needs to be placed before the call to mtDialogExtended, and the pop
call needs to occur just before the function exits. There are two methods
that could be used to implement adding application contexts. For example:
void do_materials( ...)
{
UF_HELP_push_context( "FCN1_MATERIALS");
response=mtDialogExtended(...);
switch (response)
{
case ...;
break;
case BACK:
UF_HELP_pop_context();
return;
break;
}
...
UF_HELP_pop_context();
}
In the example above the DA1 dialog in section "Add DA1 Dialog
Contexts" invoked a second dialog in the function "do_materials".
Before the dialog in do_materials is started, the call to UF_HELP_push_context
has been added. This adds the context sensitive help context for this dialog
to the stack.
The UF_HELP_pop_context call needs to be placed such that it
is always invoked when the function which controls the dialog returns.
In the example function above, two calls to UF_HELP_pop_context have
been inserted. One call before the forced return in the "BACK"
case, and one just before the normal end of the function. In a "normal"
case, for functions with a single point of entry and exit, you would place
UF_HELP_push_context right at the start of the function and UF_HELP_pop_context
just before the end of the function.
Another method of adding help for a DA2 dialog is shown below.
void fcn_DA1()
{
UF_HELP_push_primary_context("FCN1_MAIN");
while (!done)
{
response = mtDialogExtended(...);
switch( response )
{
case MATERIAL_ITEM:
do_materials(...);
break;
case TEXTURE_ITEM:
UF_HELP_push_context("FCN1_TEXTURES");
do_textures(...);
UF_HELP_pop_context();
break;
case ...;
}
}
}
In the example above the push and pop of a context was placed directly
around the call to the function.
Error Handling
The UF_HELP Open C API routines all return zero (0) for success, and
a error return code (non zero) for failure. It is up to the user to display
any error messages to the user in the event of a nonzero return code.
A trace facility is available by calling UF_HELP_set_context_debug().
Activating the trace facility prints status and error messages to standard
out and can be useful in tracking down problems with context sensitive
help.
How To Display Help
Three routines are provided to assist you in displaying the context
sensitive help information. If this is an internal Open C API program
that can take advantage of the NX menu bar, you can display context sensitive
help via the menu bar "HELP->On Context" menu item. If that
function is not available then you need to implement your own function
to activate context sensitive help. The three display functions are:
- UF_HELP_display_current_context(void) display current app context
- UF_HELP_display_context( char *context); display specified context
- UF_HELP_display_wv( char *mapfile, char *locator); display specific
WorldView document at a particular locator
UF_HELP_display_current_context() is used to display the current application
context from the context stack. This is the normal routine used to implement
context sensitive help for applications using the UF_HELP_push_context
and UF_HELP_pop_context routines.
UF_HELP_display_context() is used to display a particular application
context. This routine does not use or change any of the data in the application
context stack. The context parameter is translated using the loaded translation
table in order to find the document to display for help.
UF_HELP_display_wv is used to directly display a page in a WorldView
collection. The first parameter is the path and name of the map file for
the collection, and the second parameter is the name of the WorldView locator
that specifies the page in the document. These two parameters would be
the same as the two data fields in the context sensitive help translation
table.