Make your own online help. (help files) (Programming Power) (Column)
by Tom Campbell

This month we'll start off with a bang by transforming some Turbo Pascal example code from an interesting demo into a commercial-quality application. And it's all free for the downloading.

One of my favorite additions to Turbo Pascal 6.0 is the EDITORS unit; it lets you add a multiwindow text editor with search and replace to your applications by adding just a few lines of code.

It suffers a couple of limitations; namely, there's no online help, and word-wrap isn't supported. This month on COMPUTE/NET you'll find solutions to both problems and an example of adding help to your application.

The executable file size of the multiwindow editor TVED2 is 111K--not bad for an editor with state-of-the-art menus, snappy dialogs, multiple windows, hypertext help, search and replace, support for any wacky text mode you can throw at it, and word-wrap. (The self-extracting archive file TVED.EXE is quite large, as it also includes the source, help files, and documentation.)

It all began as a communal project on CompuServe's BPROGA (Borland's Pascal forum) late last year. Al Anderson (ID 71610,3214) modified the EDITORS.PAS example file so that it supported word-wrap, and he requested volunteers for testing and assembly language optimization. I dispatched the latter in record time because it didn't need optimization: Al's code was so efficient that it didn't even show up on the profiler.

I then foolishly offered to implement a help system based on the help engine provided as one of the example files. In three hours, I had the code up and running; I wrote the text for the help system in another day and a half. I had the easy part; Al pulled yeoman duty and made his code available free, a remarkable gift deserving special praise.

Borland's documentation on both the editor and the help system is hard to come by. You have to scrape it out of obscurely named files in at least three directories, and depending on the manual's edition, you'll find little or no mention of it in print. That's because Borland terms this "example" code.

This column details the construction of an editor employing online help and its help files. TVED.EXE repackages all the relevant information in one place; refer to the files TVED2.PAS and HELP.DOC while reading. Even if you don't need a text editor, all of the lessons apply to any Turbo Vision application using online help.

Following is an overview of the processes used to add hypertext help to your application; they're detailed step by step in README.1 (the theory) and TVED2.PAS (the implementation).

First, you must write a help source file to run through TVHC.PAS, the help compiler. TVHC eats your source and spits out an indexed HLP file for your application to use at runtime and a PAS file you'll need at compile time. Here's a tiny help source file: .topic NoContext=0.h. To quit, hold down ALT and press X.

The line .topic Save File-Save Save writes the document to a file on disk. See also @obSave as....SaveAS@cb.

The line .topic SaveAs File-Save as ... lets you write the document to a different file-name, thus preserving the current document and automatically replacing it with the newly created one.

The topic whose value is 0 will be displayed whenever help is requested in a context for which no help has been defined.

Later topics will be given values that increment by 1 each time, so Save will be 1 and Save as ... will be 2.

Lines starting with a period are used to generate values for the help system, and commands embedded within the text are set off by curly braces to indicate hypertext links. The source file above would create this PAS file:

unit edhelp; interface const hcNoContext = 0; hcSave = 1; hcSaveAs = 2; implementation end.

It took the .topic links, inserted hc in front of each, and wrapped up these constant values in public unit declarations. Add that file to your USES clause and mix well. TVHC is surely a no-frills program, but it makes online help a cakewalk.

After creating the help file, you need to add a couple of methods to your TApplication descendant, add a help command to the status line, and assign help constants to any menu or TView-descended object for which you need help, like this: HelpCtx := hcSaveAs;.

HelpCtx is a field in all TView descendants; it provides a hook for help systems like the one that comes with Turbo Vision. If you can't remember which objects are descended from TView, the compiler willingly reminds you: An Unknown identifier message when you try to write to HelpCtx means it isn't!

Don't settle for less. Just download TVED.ZIP and follow these steps; you'll end up with a help system rivaling that of any commercial product. All for free.