GUIDE 1.

0
A Popup Reference Engine
------------------------
Copyright (C) 1989, TurboPower Software
All Rights Reserved
GUIDE displays help text while other programs are active. It waits in
the background until a hot key is pressed and then displays the
requested information. GUIDE uses advanced software techniques to
minimize the system RAM that it uses while at the same time providing
good response time.
GUIDE can be installed in several ways:
- as a normal TSR using 70-120K of RAM
- as a TSR that swaps itself to EMS (expanded) memory, leaving only
a 6K kernel behind in normal RAM
- as a TSR that swaps itself to disk, leaving a 6K kernel in RAM
- as a shell that execs another program and then automatically
removes itself from memory.
You can select among these options by using GUIDE command line
parameters.
The help information displayed by GUIDE is generated by the Turbo
Professional TPHELP/MAKEHELP facilities. Hence, you can use it to
manage help files for your own projects.
Supplied with this version of GUIDE is a help file for Turbo
Professional. This help file contains information about all
interfaced constants, types, variables, procedures, and functions in
the latest version of Turbo Professional. In addition, it provides
useful tables of information about scan codes and line drawing
characters. The Turbo Professional help file is supplied in source
format so that you can add to it as you see fit. The process of
compiling it is a simple one-step operation.
Getting Started with GUIDE
---------------------------------------------------------------------
Due to the size and number of files needed to build the Turbo
Professional help file, we've supplied it in archived format, using a
self-dearchiving EXE file generated by LHARC. To dearchive it, simply
copy BLDGUIDE.EXE to a drive and directory with at least 1 megabyte
free. Then enter
BLDGUIDE COMPILE
This starts the build process, which dearchives the help text files as
well as GUIDE.EXE itself and a copy of MAKEHELP.EXE. Then it
automatically runs MAKEHELP to compile the help text files into a
compressed, indexed image. The result in this case is TPRO.HLP.
If instead you type
BLDGUIDE
at the DOS command line, the files will be extracted but the final
step of running MAKEHELP will not be performed. You may want to use
this option if you are short of disk space. See "Modifying the Turbo
Professional Help File" below for more information on running MAKEHELP
manually.
When this process is done, you can manually delete BLDGUIDE.EXE. If
you've run MAKEHELP already and you don't plan on modifying the Turbo
Professional help files, you can also delete TPRO.TX* and
MAKEHELP.EXE. This will leave you with
GUIDE.EXE the popup reference engine
TPRO.HLP the Turbo Professional help file
These two files consume about 350K of disk space.
Installing GUIDE
---------------------------------------------------------------------
The version of GUIDE provided has been set up to load the TPRO.HLP
file by default. Hence, in the simplest case, you can make GUIDE
memory resident by entering
GUIDE
at the DOS command line while TPRO.HLP is in the current directory.
This will install GUIDE in swapping mode; it will use EMS memory
(about 115K) or disk space (two files, each about 102K) for swapping.
GUIDE will allocate only about 6K of your DOS RAM.
GUIDE provides a number of options to control how it goes resident. It
uses the following DOS command line syntax:
GUIDE [HelpFile] [Options]
HelpFile is an optional pathname to a help file. This version of GUIDE
will automatically load the TPRO.HLP file by searching in the current
directory and on the DOS path. Specify a different directory or a
different help file by putting it on the GUIDE command line. A default
extension of HLP is appended.
The following options may be specified on the command line:
/B Force use of black and white video attributes.
/D Force swapping to disk even if EMS is available.
/E ProgToExec CommandLine
Execute a program instead of going resident. No
swapping. This option must be the last one on the
command line.
/H Height Specify help window height other than 12 rows.
/I HotKey Specify alternate hot key for help index.
/L HotKey Specify alternate hot key for screen lookup.
/M Disable message appearing while TSR swaps to or from
disk.
/N Force entire TSR to remain in memory (no swapping).
/P HotKey Specify alternate hot key for previous topic.
/S Path Specify drive and directory for disk swapping.
/U Unload TSR from memory.
/? Display a help screen.
Examples:
GUIDE C:\TPRO5\TPRO.HLP
Load TPRO.HLP from the specified directory.
GUIDE MYHELP /H 15
Load MYHELP.HLP using a help window height of 15 rows.
GUIDE /D /M /S F:\
Force GUIDE to swap to disk, using the root directory of drive F:
for the swap files. Disable swap messages.
GUIDE /E TURBO MYPROG.PAS
Load GUIDE temporarily and run the TURBO integrated environment.
GUIDE /N
Make GUIDE resident without swapping.
GUIDE /U
Unload the resident copy of GUIDE.
When the /E option is used, GUIDE is resident only for the time the
specified program is running. When the program halts, GUIDE removes
itself from memory automatically. GUIDE uses COMMAND.COM to run
ProgToExec, so the program can be anywhere on the DOS PATH. You can
also specify any command line parameters normally used by the program,
with the exception that redirection of input or output is not allowed.
If you have extended memory, the best way to let GUIDE take advantage
of it is with a RAM disk. Use the /S option to give GUIDE the drive
letter of the RAM disk, and it will swap to and from that area. For a
help file the size of TPRO.HLP, you'll need about 230K free space on
the RAM disk.
While GUIDE swaps to and from disk, it normally puts a status message
on the top line of the screen. If you're swapping to a RAM disk, this
status line may be an annoyance. If so, specify the /M option to
disable the status.
The TPRO.HLP file is optimized to display in a 12 line help window.
Other help files may be optimized for different window heights. You
can change this parameter only when GUIDE goes resident by using the
/H option.
GUIDE uses three different hot keys. By default, the hot keys are:
<Left Shift><F1> Look up help topic based on word at cursor
<Left Shift><F2> Redisplay previous help topic
<Left Shift><F3> Display help index
The following options control the hot keys:
/L Look up help topic
/P Redisplay previous help topic
/I Display help index
You can specify alternate hot keys at the time GUIDE is installed. On
the command line, a hot key is specified as a hexadecimal word. The
top byte specifies the shift key(s) to be pressed and must be
non-zero. The bottom byte specifies the scan code for the hot key.
The shift key codes are:
Right Shift - 01
Left Shift - 02
Ctrl - 04
Alt - 08
Valid scan codes (in hexadecimal) are:
A - 1E N - 31 0 - 0B F1 - 3B [ - 1A
B - 30 O - 18 1 - 02 F2 - 3C ; - 27
C - 2E P - 19 2 - 03 F3 - 3D , - 33
D - 20 Q - 10 3 - 04 F4 - 3E / - 35
E - 12 R - 13 4 - 05 F5 - 3F \ - 2B
F - 21 S - 1F 5 - 06 F6 - 40 ] - 1B
G - 22 T - 14 6 - 07 F7 - 41 ' - 28
H - 23 U - 16 7 - 08 F8 - 42 . - 34
I - 17 V - 2F 8 - 09 F9 - 43 ` - 29
J - 24 W - 11 9 - 0A F10- 44
K - 25 X - 2D F11- 57
L - 26 Y - 15 F12- 58
M - 32 Z - 2C
For example:
/L 0244 performs lookup when <Left Shift><F10> is pressed
/P 0819 shows previous topic when <Alt><P> is pressed
/I 0517 displays help index when <Ctrl><Right Shift><I> is
pressed
Two hot keys may not be based on the same scan code, even if the shift
keys differ. For example, you cannot use <Alt><F1> for one hot key and
<Ctrl><F1> for another. You must also specify at least one of the
shift keys for each hot key, i.e., the top byte of the specified word
must not be zero.
Keep in mind one important restriction when installing GUIDE in
swapping mode. When GUIDE pops up, it disables any TSR's that have
been loaded after it. This is necessary because it is overwriting
their memory while it swaps in. Some TSR's, especially network shells
and communication programs, won't accept being disabled in this way:
the network will disconnect a station that doesn't respond after a
time, or a communication program will lose incoming characters. It's
possible to avoid these problems by loading GUIDE after such TSR's. To
avoid one common problem, GUIDE automatically detects when it is
loaded before the Novell NetWare shell and refuses to pop up in this
situation.
Using GUIDE
---------------------------------------------------------------------
Once GUIDE is installed you can go about your business. The most
likely place for you to start using it is within your text editor or
within the TURBO integrated environment.
If you want to call a particular Turbo Professional routine and you
can remember its name but not its parameters, position the editor
cursor at the end of the procedure name you've typed in. Then press
the Lookup hot key, <Left Shift><F1> by default. GUIDE searches the
list of topics looking for an exact match (disregarding case). If that
fails, it looks for a topic whose name starts with the search string.
If GUIDE can find a matching topic with one of these two search
strategies, it will pop up a help window showing you the details about
that routine. If it can't, it will instead pop up a window with the
names of all the Turbo Professional units.
If you're not sure of the name of a routine, but you remember which
unit it's in, press the Index hot key, <Left Shift><F3> by default,
and you'll get a pick list showing all the Turbo Professional units.
Select the unit you want and a list of topics within that unit will
appear.
Within a help window you can use the cursor keys to move a highlight
bar which indicates links to other topics. Once the highlight bar is
positioned over a topic you want, press <Enter> to bring up that
topic. In this way you can browse around the help database at will.
Once you've seen the information you want, you can return to the
underlying application by pressing <Esc>.
If you want to see the same help topic again, press the Previous Topic
hot key, <Left Shift><F2> by default.
While the GUIDE help window is active, there are several other
commands available:
<F1>
displays the main topic index again.
<Alt><F1>
displays the topic that was displayed prior to the current one.
<F3>
prompts for a new help file. A default extension of HLP is
appended. GUIDE will read any help file built using the Turbo
Professional MAKEHELP utility. Note that GUIDE reserves a
certain amount of memory when it goes resident, and it cannot
increase that amount later. Therefore, if you expect to load
multiple help files during one GUIDE session, you should load the
largest of them when GUIDE is made resident.
GUIDE is also configured with certain limits: a maximum of 20
pages per help topic, and a maximum of 150 cross-references per
topic. These limits are large enough to handle the TPRO.HLP file,
but may not be adequate for other help files. GUIDE simply ignores
items in excess of the limits.
<F5>
allows repositioning the help window using the cursor keys. Press
<Enter> or <Esc> to finalize the position.
<PgUp>, <PgDn>
moves to the next or previous page of the current help topic.
<Left>, <Right>, <Up>, <Down>
moves the highlight bar to the next corresponding cross-reference
link. For example, the help topic for the TPDIR unit lists all of
the procedures and functions within that unit as cross-reference
links. Moving the highlight bar to one of these procedure or
function names and pressing <Enter> will cause GUIDE to display
more information about that particular routine.
<Enter>
selects the currently highlighted cross-reference topic.
<Esc>
Exits GUIDE. The current topic and page are retained and may be
redisplayed by pressing the Previous Topic hot key, <Left
Shift><F2> by default.
We're sure you will find GUIDE so intuitive that you won't need to
come back to this DOC file again. If you need a reminder, just bring
up the Help on Help topic within GUIDE itself.
Modifying the Turbo Professional Help File
---------------------------------------------------------------------
We've supplied the source text for the Turbo Professional help file in
case you want to make additional notes in it or you want to document
routines of your own.
TPRO.HLP is built from 10 source files: TPRO.TXT and
TPRO.TX1..TPRO.TX9. The numbered files are include files within the
main file. The main file documents which units are to be found in
which include file. The main file also documents many of the
conventions used in designing the help file.
You can modify the source files using any text editor. See the Turbo
Professional documentation of TPHELP and MAKEHELP for more
information.
To recompile TPRO.HLP, just enter the following at the DOS command
line:
MAKEHELP TPRO
This will replace any existing copy of TPRO.HLP.
Copyright Information
---------------------------------------------------------------------
GUIDE.EXE, MAKEHELP.EXE, and the Turbo Professional help files are
copyrighted property of TurboPower Software. The Turbo Professional
help files and MAKEHELP.EXE are intended for the sole use of the
licensed owner of a copy of Turbo Professional. However, TurboPower
Software grants you the right to distribute GUIDE.EXE along with help
files of your own design.
The source code for GUIDE.EXE is not available for distribution at
this time because it depends in part on the unreleased product Object
Professional. GUIDE source code will be distributed with Object
Professional, which is scheduled for shipment in November 1989. (GUIDE
was renamed to POPHELP, whose source code is now distributed with
Object Professional.)
Version History
---------------------------------------------------------------------
1.00 - initial release
1.01 - 8/29/89
add /B option to force B&W video
fix swapping message problem on VGA, some CGA
recompile with latest version of OPSWAP
1.02 - 10/6/89
preallocate prompt window buffer to minimize heap fragmentation
increase maximum xrefs per topic to 150 to accommodate TURBO.HLP
allow screenwidths other than 80
recompile with latest version of OPSWAP
1.03 - 10/30/89
use filemode $00 to open help file for DOS 2.x systems (instead of
$20, read-only, deny write under DOS 3.0 and later) fix
cursor-reading routine to work on non-default video pages
1.04 - 12/4/89
recompile with latest version of OPSWAP (fixes swapping to file
server)
1.05 - 12/4/89
change /B option to use only attributes $07, $0F, and $70
1.06 - 10/5/90
recompile with opswap 1.03
allow no-shift-key hotkeys
1.07 - 11/27/91
recompile with opswap 1.12
recompile with tpro 5.12
update for TP6 compilation
1.08 - 11/5/92
recompile with opswap 1.20
recompile with tpro 5.20
update for BP compilation
1.09 - 2/26/93
recompile with opswap 1.21
recompile with tpro 5.21
increase stack space to 4000 bytes