!WIDTH 66
;
!TOPIC 1 Initializing
TPHELP exports several data types and routines so that a client
program can easily integrate a help system. The main data type is:

type
HelpPtr = ^HelpDesc; {The user hook to the help system}

A variable of this type points to a data structure that lets TPHELP
manage the help system. The client program needs only to declare a
variable of this type (which uses 4 bytes of space in whatever segment
it's declared) and initialize it as described below, in order to
access the help system.
!PAGE
TPHELP offers the following two functions to initialize a help system.
One of these must be called prior to displaying help.

function OpenHelpFile(HelpFileName : string;
XLow, YLow, YHigh : Byte;
var Help : HelpPtr) : Word;
{-Find and open help file, returning 0 or error code, and
an initialized help descriptor if successful}

function OpenHelpMem(HPtr : Pointer;
XLow, YLow, YHigh : Byte;
var Help : HelpPtr) : Word;
{-Initialize help descriptor for a help structure
bound into code}

procedure SetHelpPos(Help : HelpPtr;
XLow, YLow, YHigh : Byte);
{-Change the position of a help window}
;
;
;---------------------------------------------------------------------
!TOPIC 2 Displaying
TPHELP offers three methods of displaying help. You can call one or
more of them at appropriate places in your program.

function ShowHelp(Help : HelpPtr; Item : Word) : Boolean;
{-Display help screen, returning true if successful}

function ShowHelpByName(Help : HelpPtr;
Name : string) : Boolean;
{-Display help screen for topic with pick name Name}

function PickHelp(Help : HelpPtr;
XLow, YLow,
YHigh, PickCols : byte) : word;
{-Display help pick list, returning Item number,
or 0 for none}
!PAGE
A bit of background: each help topic is referenced by an Item number
(which ranges from 1 to the maximum topic number) and optionally by a
topic Name. The Item number and Name for each topic are assigned by
you in the original text help file.
;
;
;---------------------------------------------------------------------
!TOPIC 3 Help Compiler
The text that will eventually be displayed by the help system starts
out as a text file that you must write. You put directives in that
text file to tell the help compiler how to format it. You then run the
help compiler, MAKEHELP, to create a formatted, indexed file that will
be used by the help system.

Directives are denoted by an exclamation point that appears as the
first non-blank character on a line, immediately followed by the
directive name, followed by various options separated by one or more
spaces. Here is a list of the directives accepted by the help
compiler.
;---------------
!PAGE

!WIDTH Width

Specifies the number of columns to be occupied by the
help window, including the frame. The help will eventually be
displayed with one blank column separating the text from each edge
of the frame. Thus, the actual width for text is (Width-4)
columns. If no !WIDTH directive is specified, MAKEHELP assumes
Width=40.

Because MAKEHELP word wraps the text, the width specification for
a help system is built into the help file. The width may not be
changed when the text is later displayed. By contrast, MAKEHELP
does not automatically paginate the help text, thus allowing help
screens that can automatically adjust between 25, 43, and 50 line
text modes.

The !WIDTH directive must appear before the first !TOPIC directive.

Example: !WIDTH 70
;---------------
!PAGE

!TOPIC Item [Name]

Each help topic must begin with a !TOPIC directive. Typically,
help topics will be entered in ascending numerical order, starting
with number 1. The !TOPIC directive may also specify an optional
topic name. The name may contain spaces, and it will later appear
on-screen exactly as entered in the !TOPIC directive. (The topic
name appears as the title of the help window, and as an entry in
the help pick list.)

Examples: !TOPIC 1 First Help Section
!TOPIC 22
;------------------
!PAGE

!LINE

This directive forces MAKEHELP to finish the current line of text,
inserting a line break. Since MAKEHELP automatically fills and
word-wraps the text in your original help file, the line breaks
in the final help screens are not necessarily the same as those in
the your text file. The !LINE command gives you appropriate control when
needed. MAKEHELP also inserts a line break whenever it encounters a
blank line or a line that begins with one or more spaces.
;---------------------
!PAGE

!PAGE

This directive forces MAKEHELP to finish the current page of text,
inserting a page break. Normally, page breaks are inserted when
the help text is displayed, only when the current window has
filled with help.
;---------------------
!PAGE

You may enter comments in the text file that will not appear in the
final help. Comments are indicated when a semicolon appears in the
first column of the text file. Example:

;ANY TEXT APPEARING AFTER THE SEMICOLON IS IGNORED.
;---------------------
!PAGE

To activate the special text attributes, you insert control characters
directly into your help text. ^A toggles SpAttr1 on and off, ^B
toggles SpAttr2, and ^C toggles SpAttr3. The actual control characters
will not appear in the final help screens. To enter such characters
using the Turbo Pascal editor, first press , then hold down the
control key and press the desired character.

When the special attributes are used in combination, they are applied
in priority order. SpAttr1 takes priority over SpAttr2, which takes
priority over SpAttr3.

SpAttr1 has a special purpose as well. The selected topic in the help
pick menu is displayed in attribute SpAttr1.
;
;
;---------------------------------------------------------------------
!TOPIC 4 Binding Help

TPHELP will directly read the binary file produced by MAKEHELP.
However, if the help file is relatively small (definitely less than
64K), you may want to link the help file directly into the application
so that no additional files are required.

You can do this with the aid of the BINOBJ.EXE utility that Borland
supplies with Turbo Pascal. BINOBJ converts the binary help file into
a linkable OBJ file that can be bound into your program.

Let's use an example to show how this works. Assume you have a help
text file named MYHELP.TXT. The first step would be to run
MAKEHELP.EXE to create the binary help file:

MAKEHELP MYHELP.TXT MYHELP.HLP
!PAGE
Then run BINOBJ to create the OBJ file:

BINOBJ MYHELP.HLP MYHELP.OBJ MYHELP

The third parameter to BINOBJ specifies the name of the public
identifier by which your program can refer to the contents of the OBJ
file.

Now, within your application program, insert the following lines of
source code:

{$L MYHELP.OBJ}
procedure MyHelp; external;

The $L compiler directive tells Turbo to link in MYHELP.OBJ. The fake
procedure MyHelp gives your program a way to refer to the contents of
that OBJ file.
!PAGE
Finally, to initialize the help system, make a call to OpenHelpMem as
follows:

Status := OpenHelpMem(@MyHelp, XLow, YLow, YHigh, Help);
if Status <> 0 then
{Error, help not available};

The notation @MyHelp passes the address of the binary structure to the
help system initialization procedure.

From then on, simply refer to the Help variable returned by
OpenHelpMem.