|
HTMLHELP |
|
|
|
|
Introduction
The HTMLHELP program is part of the REL directory starting with version 01.03. With this program, every Comet98 and Comet2000 system can contain context-sensitive help based on a standard format (HTML) and displayed with a familiar tool (a web browser). Even though this program is intended to launch HTML documents, it’s possible to launch any type of document or Windows program via HTMLHELP. These advanced features are explained below.
HTMLHELP is a Comet subprogram that can be assigned to a function key (F1, F11, F12, or Shift-F1 through Shift-F12) or to a pop-up item, toolbar icon, or accelerator key. The function keys are assigned with the NOVAMNT program (#43 on the Comet Utility Programs menu), while the pop-up items, toolbar icons, and accelerator keys are defined with the CTMAINT program (also known as the SuperNova feature in Comet).
Whether you’re using NOVAMNT or CTMAINT, you’ll want to use the action code of “ENTER” and the program name “HTMLHELP.”
Please note that the HTMLHELP program does not replace the existing Comet Help System (i.e., the NOVA program). NOVA and HTMLHELP are independent programs. If you’re already using Nova for help messages and/or lookup programs, continue to do so. HTMLHELP provides an additional (optional) feature.
Once the key/toolbar assignment has been made, the user can invoke the HTMLHELP feature by pressing the appropriate key, clicking on the appropriate icon or pop-up menu item, or using the appropriate accelerator key combination.
For example, suppose that the HTMLHELP program is assigned to the F12 function key. When the user presses F12, Comet suspends the current program and enters the HTMLHELP subprogram. HTMLHELP then launches the document or program it has been told to (based on a user-defined control file) and then resumes processing the user’s original program.
You can control the level of context sensitivity in several ways. The easiest method is to create your HTML documents, create a control file that contains the path to these documents, and assign the HTMLHELP program to a function key or SuperNova toolbar. For greater control, you can use the HELPKEY$ system variable in your Internet Basic programs. The HTMLHELP program interrogates HELPKEY$ and launches the document or Windows program associated with it. The following sections describe all of the implementation options.
Basic Implementation
Follow these steps to implement the basic features in HTMLHELP:
1. Create a folder where you will be storing your HTML documents.
· This folder is not a Comet directory.
· On a single-user Comet system, this will be a directory on your local hard drive.
· On a network, this will be a directory on the file server.
Note: If you are running a web server, you can store and launch your HTML documents from it. See below for more information.
2. Create your HTML documents.
Choose one of the following options when you pick names for your HTML documents.
Option 1
Name the HTML files to correspond with the value of the HELPKEY$ system variable, if you are using HELPKEY$ in your program. The value of HELPKEY$ specifies the name of the HTML file that will be launched. The HTMLHELP program appends a “.HTM” suffix to the value of HELPKEY$ and launches this document:
Example
Internet Basic code: HELPKEY$
= “ABCD”
INPUT (0) DATA$
HTMLHELP launches: ABCD.HTM
The main advantage of this option is that you can provide any number of unique HTMLHELP links (to different HTML documents) simply by adding multiple HELPKEY$ assignments in your program.
Option 2
If you are not using the HELPKEY$ system variable in your Internet Basic program, be sure that the HTML file names correspond to your Internet Basic object program names. The HTMLHELP program appends “.HTM” suffix to the Comet object program name and launches this document.
Example
Object program name: CM
HTMLHELP launches: CM.HTM
The main advantage of this option is that the HTMLHELP program launches a document whose name corresponds to the name of the current Internet Basic object program. Thus, it’s very easy to add HTML documentation for each Comet application program.
3. Create a Comet sequential or text file named #HTMLDOC.
· This is a control file that will contain the pathname of the folder containing your HTML document files.
· This file can be stored in any accessed Comet directory. We recommend that you put it on one of your application directories. Do not create this file on REL, UTL, or any of the other directories released by Signature Systems.
4. Add a control record to #HTMLDOC.
This control record contains the pathname of the folder containing your HTML files (starting in the first position in the record).
When HTMLHELP is invoked, it reads the first record in #HTMLDOC. The data in this record becomes the first portion of a field that HTMLHELP launches.
As mentioned above, the second portion of the launch string is either the value of HELPKEY$ (if it is not null) or the name of the current Internet Basic program (if HELPKEY$ is null), and the third portion of the launch string is the “.HTM” suffix.
Example 1
Suppose your HTML documents are stored in a folder named C:\HTMLFILES. Write the following pathname as the first (and only) record in the #HTMLDOC file:
C:\HTMLFILES\
(Note: The final "\" is required.)
When you run an Internet Basic program where HELPKEY$ is set to “ABCD” and press the HTMLHELP key, Comet launches the following document:
C:\HTMLFILES\ABCD.HTM
If this document launches successfully, it is displayed in your web browser and the HTMLHELP program exists back to the user’s original Comet application program.
However, if the document does not launch successfully, HTMLHELP will reform the launch string using the user’s current object program name (see Example 2). Regardless of the success of this launch, HTMLHELP will then exit back to the user’s original program.
Example 2
Suppose your HTML documents are stored in a folder named C:\HTMLFILES. Write the following pathname as the first (and only) record in the #HTMLDOC file:
C:\HTMLFILES\
(Note: The final "\" is required.)
When you run an Internet Basic program, CM for example (and assuming that HELPKEY$ is null), and press the HTMLHELP key, Comet launches the following document:
C:\HTMLFILES\CM.HTM
If this document exists, it is displayed in your web browser and HTMLHELP will then exit back to the user’s original program.
Example3
Suppose your HTML documents are located on a web server. Here's how to specify the pathname in the #HTMLDOC file:
http://www.yourdomain.name.com/directory/directory/
(Notes: The final "/" is required. The above format includes the http:// protocol type, your domain name, and the specific path where your HTML files are stored.)
In this case, when you run CM and press the HTMLHELP key (assuming that HELPKEY$ is null), Comet launches the following document:
http://www.yourdomain.name.com/directory/directory/CM.HTM
If this document exists, it will be displayed in your web browser and HTMLHELP will then exit back to the user’s original program.
Note: If the CM program in this example contained a non-null value for HELPKEY$, that value would become part of the launch string, as show in Example 1 above.
4. A note about CometAnywhere
If a CometAnywhere user invokes HTMLHELP, the program will copy the HTML document to the remote system, placing it in the following folder:
$(CATOOLS)\DOC\
See the Directory Aliases Overview for more information on how files are transferred to a CometAnywhere remote system.
Once the document has been copied to the CometAnywhere system, HTMLHELP launches it.
Note: The Advanced Implementation provides an option to bypass this step.
Advanced Implementation
Note: This implementation
requires Comet98/Comet2000 Build 290 or higher.
The HTMLHELP program supports advanced features that give you more control over what is launched when the program is invoked. For example, HTMLHELP can launch any document or Windows application, and the launch value can be based on the value of HELPKEY$ or the object program name.
In order to accommodate these features, the #HTMLDOC file must be a keyed file and must contain certain control records and fields.
Follow these steps in order to implement the advanced features in HTMLHELP:
1. Create one or more folders where you will be storing your documents
2. Create your documents. Depending on which of the advanced methods you wish to use, your document names or specific launch instructions may be based on the value of HELPKEY$ or the name of the user’s object program. See the following step for more information.
3. Create a Comet keyed file named #HTMLDOC.
· The key size for this file must be 16 and the record size must be 274.
· This file must contain at least one record, keyed by “*”. This record must contain the pathname of the folder containing the HTML documents (starting in record position 21).
· There may be any number of additional records in this file. These records must be keyed either by the value of HELPKEY$ or by the name of a Comet object program (uppercase is required). Each record must contain the key, followed by 4 option bytes and a fully-qualified Windows launch instruction. This provides the flexibility to launch documents of any type (e.g., .DOC, .PDF, .HTM) or to launch any Windows application.
Here is the layout for the #HTMLDOC file:
Master key
*
Master record
Position Length Value
1 16 *
17 1 CometAnywhere file transfer flag:
Y
causes HTMLHELP program to attempt
to
transfer the file to a CometAnywhere
session;
other values skip the transfer
attempt.
18 3 Reserved for future use
21 254 Pathname of the folder containing the
HTML documents
Optional keys
HELPKEY$ value or Comet object program name
Optional records
Position Length Value
1 16 HELPKEY$ value or Comet object program
name
17 1 CometAnywhere file transfer flag:
Y
causes HTMLHELP program to attempt
to
transfer the file to a CometAnywhere
session;
other values skip the transfer
attempt.
18 3 Reserved for future use
21 254 Fully-qualified Windows launch
instruction
Note: The Utility Source Subset directory (XTL) contains a usefile for this data file. The usefile is named #HTMHELP.
Under the advanced implementation, the HTMLHELP program will attempt a series of launches until one is successful or the test case expires. Here is the order of the cases:
a. First, if the HELPKEY$ system variable has been set in the user’s original program, the HTMLHELP program reads the #HTMLDOC control file using the value of HELPKEY$ as the key. If this key exists, the program performs the launch using the fully-qualified Windows launch instruction (from position 21 in the data record).
b. Second (if the first rule fails), if HELPKEY$ has been set in the user’s program, the HTMLHELP program forms an HTML launch instruction using the pathname specified in the “*” record and the value of HELPKEY$ (this is the same as the Basic Implementation).
c. Third (if the first two rules fail), HTMLHELP reads #HTMLDOC using the current program name as the key. If this key exists, HTMLHELP performs the launch using the fully-qualified Windows launch instruction (from position 21 in the data record).
d. Fourth (if the first three rules fail), HTMLHELP forms an HTML launch instruction using the pathname specified in the “*” record and the name of the user’s current object program (this is the same as the Basic Implementation).
Here are some examples that demonstrate this process:
Example 1
Suppose that you have created a PDF file named F:\Comet\Documentation\INFO.PDF, and you want it to be launched whenever the user invokes HTMLHELP with one of your Internet Basic programs containing a HELPKEY$ value equal to “INFO.” Also suppose that you want the HTMLHELP program to attempt to send this file to a CometAnywhere session.
You’ll need to add a record to the #HTMLDOC file. The key will be “INFO” and the record will contain the following data:
Position Length Value
1 16 INFO
17
1 Y
18
3 (blank
spaces)
21 254 F:\Comet\Documentation\INFO.PDF
You’ll also have to add the following statement to the Internet Basic program(s) where you want this document to be available:
HELPKEY$ = "INFO"
When the user invokes HTMLHELP, the program follows the first rule and reads #HTMLDOC using the value of HELPKEY$ as the key. Finding a key of “INFO,” the program performs the launch instruction, which in this case is F:\Comet\Documentation\INFO.PDF. This launches the PDF document (which will be displayed by the Acrobat reader installed on your system).
If this step is successful, HTMLHELP will exit back to the user’s original program. If it is not successful, HTMLHELP will continue to the next processing rule.
Example 2
Suppose that you have created an HTML file named F:\Comet\Htmlfiles\MAIN.HTM, and you want that files to be launched whenever one of your Internet Basic programs contains a HELPKEY$ value equal to “MAIN.” Also suppose that you want the HTMLHELP program to attempt to send this file to a CometAnywhere session.
You’ll need to add a master record to the #HTMLDOC file. The key is “*” and the record will contain the following data:
Position Length Value
1 16 *
19
1 Y
20
3 (blank
spaces)
21 254 F:\Comet\Htmlfiles\
You’ll also have to add the following statement to the Internet Basic program(s) where you want this document to be available:
HELPKEY$ = "MAIN"
When the user invokes the HTMLHELP program, it will attempt to read #HTMLDOC using the value of HELPKEY$ (the first rule). However, this read will fail because there is no record keyed by “MAIN.” The program will move to the second rule. It will read the “*” key and form a launch instruction from the (1) the value found at position 21, (2) the value of HELPKEY$, and (3) the ”.HTM” suffix. In this case, the launch instruction will be:
F:\Comet\Htmlfiles\MAIN.HTM
The browser will launch and display the INFO.HTM file.
Example 3
Suppose you are not using HELPKEY$ in your Internet Basic programs, and that you want to launch a PDF file named F:\Comet\Documentation\OE_documentation.PDF when someone invokes HTMLHELP from within the OE program. Also suppose that you do not want the HTMLHELP program to attempt to send this file to a CometAnywhere session.
You’ll need to add a record to the #HTMLDOC file. The key will be “OE” (upper case is required) and the record will contain the following data:
Position Length Value
1 16 OE
21
1 N
22
3 (blank
spaces)
21 254 F:\Comet\Documentation\OE_documentation.PDF
When the user invokes the HTMLHELP program, it will try the first two rules without success, since HELPKEY$ is not set. Using the third rule, HTMLHELP will read #HTMLDOC using the program name as the key, and perform the launch instruction found in the data record. In this case, the launch instruction is:
F:\Comet\Documentation\OE_documentation.PDF
If a CometAnywhere user makes this request, HTMLHELP will not attempt to copy the file to the remote system. However, HTMLHELP will attempt to launch this document from the remote system.
Example 4
Suppose you are not using HELPKEY$ in your Internet Basic programs, and that you want to launch an HTML file from the F:\Comet\Htmlfiles\ folder when someone invokes HTMLHELP from within a Comet object program. Also suppose that you want the HTMLHELP program to attempt to send this file to a CometAnywhere session.
You’ll need to add a master record to the #HTMLDOC file. The key is “*” and the record will contain the following data:
Position Length Value
1 16 *
23
1 Y
24
3 (blank
spaces)
21 254 F:\Comet\Htmlfiles\
When a user invokes HTMLHELP, the first three rules are tried without success. Using the fourth (and final) rule, HTMLHELP reads the “*” key and forms a launch instruction from (1) the contents of the data record (starting at position 21), (2) the user’s program name, and (3) the “.HTM” suffix.
Summary
The HTMLHELP program provides many options. We recommend that you plan your implementation (basic or advanced) carefully before starting. If you simply want to add HTML documentation to your Comet applications, it’s best to use the basic implementation, not use HELPKEY$, and name all of your HTML documents to correspond with your object program names.
However, if you want more context sensitivity, you may want to consider using HELPKEY$ in your programs and naming your HTML documents after the values of HELPKEY$.
If you plan to use the advanced options, start by creating the #HTMLDOC file with just the master record (keyed by “*”). This implementation matches the basic one, and provides a mechanism for future growth.
While we have highlighted the on-line documentation features available with HTMLHELP, the program is not only for that purpose. The advanced implementation allows you to enter any Windows launch command in the control file. Thus, it’s possible to launch a spreadsheet program, word processor, e-mail application, etc. by invoking the HTMLHELP program. We’ll leave the potential applications of this feature to your imagination.
|
|