| Prev | Next | Start of Chapter | Next Chapter | Contents | Glossary | Index | Comments | (12 out of 12)

Using GOLD to Access Online Documentation

G2 OnLine Documentation (GOLD) is a utility that enables you to develop, distribute, and access online documentation within your G2 application. GOLD also provides the basic infrastructure to:

Obtain context-sensitive help
Perform keyword searches in the documentation

A separate KB module, GOLDUI, provides a user interface for configuring and using GOLD in your application.

The Online Documentation

The online documentation is a collection of document files formatted in HyperText Markup Language (HTML), a standard markup language that describes text formats. Angle bracketed tags containing HTML definitions are imbedded throughout the document to describe the formatting characteristics of text elements, such as headings, paragraphs, bulleted lists, numbered steps, and tables. These tags tell the HTML browser how to display the document.

For example, the following excerpt is from the HTML version of the G2 OnLine Documentation User's Guide:

<html><head><title>Getting Started</title></head>

<body bgcolor="#ffffff">

<h5><a href="get_st13.htm">| Prev </a>

  <a href="get_st15.htm">| Next </a>

 <a href="get_star.htm">| Start of Chapter </a>

 <a href="get_st17.htm">| End of Chapter </a>
          .
          .
          .

<a name="1023396">

<h1> Setting Up Gold Machine Configurations</h1>

<p><a name="1055381">
          .
          .
          .

You can preconfigure the machines running G2 and Telewindows
at your site for GOLD before users access online help by
creating and configuring one or more Gold machine
configurations.<p>

</a><a name="1020833">

You create a machine configuration by cloning the object from
the GOLD top-level workspace. The workspace on which you place
the machine configuration should be assigned to a module that
requires GOLD.<p>

Within an HTML file there are a number <a name="n"> tags, each marking a specific entry point within the file.

Gold Books

To support online documentation, a KB module must have one or more GOLD book objects, each containing the information necessary to locate a particular HTML fileset of online documentation. There is a one-to-one correspondence between a set of files that constitute an online book and a book object.

URLs

A Web browser reads a given Universal Resource Locator, or URL, to locate the desired documentation. The URL that defines the location of a document is a text string concatenation of the:

Protocol over which the document is served
Network address of the machine providing the service
Path name location of the document on the machine providing the service

For example:

http://www.gensym.com/helpdesk-doc/hd_work5.htm

where

http is the protocol
www.gensym.com is the network address
helpdesk-doc/hd_work5.htm is the location of the document

Optionally, the URL can conclude with a pound sign (#) followed by a text string that indexes a particular location within a document. For example:

http://www.gensym.com/helpdesk-doc/hd_work5.htm#4035

Every entry point into the documentation must have an associated URL.

Cross-Reference Hotlinks

Cross references within the documentation appear as "hot" text in any HTML browser. These hotlinks point to URLs. Clicking on a hotlink repoints the browser to the new location.

How GOLD Uses URLs

GOLD manages the display of online documentation by:

Spawning a process that launches a Web browser
Providing the URL associated with the online documentation

The browser reads the given URL to locate and display the related documentation, for example:

Out of all the URLs embedded in the document, a subset known to GOLD constitutes external entry points into the documentation. GOLD uses these entry points two ways:

To implement context sensitive help
To provide a mechanism for keyword searches

Context-Sensitive Help

In response to a user request for context-sensitive help, GOLD calls a procedure that determines the possible entry points and adds them to a list. To encapsulate the software from direct knowledge of the URLs (which might change due to updates to the documentation), GOLD uses a system of logical entry points that are specified as unique symbols. These symbolic keys are referred to as HelpIDs.

During initialization, GOLD reads the HelpIDs corresponding to a particular book from a file into a key table. Each entry in this table contains:

A HelpID
The URL of the associated entry point
A text string description of this entry point, which can be presented to the user

Keyword Searches

GOLD provides a system to search for specific keywords as text strings in the documentation, based on the index entries of a book. During initialization, GOLD reads the list of keywords and their corresponding URLs from a file into a search table.

Application Programmer's Interface to GOLDUI

All programmatic interactions with GOLD take place through a small set of public procedures, classes, and attributes. Collectively, these items are referred to as the application programmer's interface (API).

Note: The GOLD API procedures are currently under development and are expected to change to take advantage of the G2 Version 5.0 Rev. 0 features. The full application programmer's interface to GOLD will be made public in a later release of the G2 utilities.

| Prev | Next | Start of Chapter | Next Chapter | Contents | Glossary | Index | Comments | (12 out of 12)

Using GOLD to Access Online Documentation

The Online Documentation

Gold Books

URLs

Cross-Reference Hotlinks

How GOLD Uses URLs

Context-Sensitive Help

Keyword Searches

Application Programmer's Interface to GOLDUI

| Prev | Next | Start of Chapter | Next Chapter | Contents | Glossary | Index | Comments | (12 out of 12)

Copyright © 1997 Gensym Corporation, Inc.