Getting ready for on-line documentation

This tip is the first in a series of tips dealing with on-line documentation in the Comet98 environment. In this tip, we discuss the MTB documentation and its integration with the Comet Editor (CED). In future tips, we'll discuss other documentation from Signature Systems and offer some ideas for your applications documentation.

Here's a little background about MTB documentation and CED. Back in Comet 503, we added an on-line MTB manual to the CED program. At the time, this was breakthrough technology. In fact, it was one of the first major applications of the Comet Help System (and the ENTER/EXIT approach to MTB programming).

When we updated the MTB documentation at the 504 level, we changed its format to hypertext documentation (we used the hypertext engine from the CVIEW program). We also added context sensitivity to CED -- you can type an MTB command, press the help key (F1), and CED will lookup the documentation for the MTB statement on the current source line.

Last year, when we updated the MTB documentation to the Comet98 level, we changed its format once again. This time, we used HyperText Markup Language (HTML) for all of the MTB documentation. Our reasoning was simple: HTML is the worldwide standard for on-line hypertext.

Until recently, these HTML files were available only one way: you had to run a web browser and link to the technical documentation section of Signature's web site.

The latest release of CED (version 99.02), when running under Comet98, provides the following ways to access the MTB documentation:

• CED can launch your web browser and automatically link to the MTB documentation at Signature's web site via an on-line connection

• CED can launch your web browser and link to a locally-installed version of the MTB documentation files

Note: Both of these options take advantage of the recently-released (Launch) mnemonic (included in REL release 99.01).

To enable the first option, use the INSTALL command in CED. At the "Enable HTML Help?" prompt, choose the "I" option, as shown below.

Subsequently, when you press the F1 key, CED will launch your web browser (and connect to the Internet if you're not already connected) and display the table of contents page for the on-line MTB manual.

To enable the locally-installed version of the MTB documentation, follow these steps:

• Create a unique directory on your system for the MTB documentation files. We suggest a path name of \techdoc\mtb directly under your Comet directory.

• Using your web browser, jump to the following web page: www.signature.net/signature/techdoc/mtb/index.html

• You'll find a link to a file named MTBDOC.ZIP. Download this file.

  This file contains all of the MTB documentation and graphics files. The zipped size is approximately 515KB. The unzipped size is approximately 1.3MB.

• Use the WinZip utility to unzip the MTB documentation to the \techdoc\mtb directory. Please note: the zip file contains long file names and an imbedded subdirectory named \images. Therefore, make sure to use WinZip, not PKUNZIP, to unzip this file.

• Use the INSTALL option in CED. At the "Enable HTML Help?" prompt, choose the "L" option, as shown below.
  

• At the CED HTML Setup Screen, enter the DOS path name for the HTML documentation files. Make sure to include intro.htm in the path -- this is the opening page of the MTB documentation.

  Hint: CED attempts to open this file (using a DOS OPEN) as a way of verifying that the path/file exists. If you get a CED error at this point, it's probably because you typed an incorrect path name.

  

• At the "Enter Browser program name" prompt, you have two options:
  1. Enter nothing and CED will use your default web browser to display the MTB documentation files.

  2. If you want to use a specific browser program, other than your default web browser, enter the program name (and DOS path) here. For example, we've been testing an off-line browser program named NavRoad. We're in the process of licensing this program and plan to make it available in the near future. NavRoad offers a big advantage over traditional web browsers: it's a smaller program and loads much faster than Netscape and Explorer.

Subsequently, when you press the F1 key, CED will launch your browser and display the intro page for the locally-installed MTB manual.

Here are a couple of final comments:

• This is the first release of CED that includes the HTML version of the MTB documentation. At this point, CED is not context-sensitive. We plan to add that feature in a future release. If you need context-sensitive MTB documentation, don't use the HTML files yet. Instead, use the 504 help feature in CED.

• As mentioned above, CED now uses the "launch" feature in Comet98. As of this writing, the "launch" feature is available in MTB, QMONITOR, and CED. However, in a forthcoming release, we plan to make this feature available in the Comet Help System, Nova, and SuperNova. This will offer you many new options for your applications documentation, and we'll discuss those options in a future Comet Tip.

Back to the Comet Tips page.