******************
Welcome to SHAZAM!
******************

Documentation for SHAZAM is both "online" and "offline":

[X] ONLINE - The context-sensitive portion is cross-referenced with
the manual, most of which is also in HyperText format.

[X] OFFLINE - The PRINTDOC program is about to be generated and
compiled. It will print the Technical Manual and demonstration
programs with your choice of formats and margins. The "Test
print" option is a 2-page report, so you can make adjustments and
try different settings.

All source for units and example programs is included. You can
re-use dialogs, hints and help text files as "plug n' play"
elements of your own programs.


CONTENTS
--------
1 - Getting started
2 - Notes
3 - Installation
4 - Units
5 - Examples
6 - Overview
7 - Acknowledgements
8 - Technical Support



1 - GETTING STARTED
===================
If you are upgrading from version 1.x, you MUST read UPGRADE.DOC.

To give you an idea of what SHAZAM can do, the following...

KEYWORDS & ITEMS HINTS
| |
V V
----------------------------------------------
[ submenu ] file ;;hint for file stuff
open f3 ;;open a file
save f2 ;;save window

[ status ]
f1 Help ;;call HyperText help
alt-x exit cmQuit ;;return to DOS
----------------------------------------------

...creates a ready-to-run EXE with Help Text & Hints, using overlays
and resources, recovers overlay heap for EXEC, and runs under DOS 2.x
or higher. By default, SHAZAM allows for use of ExecSWAP, so the
application is unitized (encapsulated) and you get Swap-To-Disk/EMS
capability too, with minimum overhead, less than <6k.

No kidding.

Type the above into a file with an *.DEF extension & press Ctrl-F9.

Don't want overlays? Use the "/O-" switch, from the DOS prompt or
SETUP|Code dialog. No ExecSwap? Use "/X-". Code, instead of
resources? Use "/1". And so on...

Now, for an actual "Exec", you would have to add custom code, BUT
there's a routine in GENERAL.PAS called "VisionExec" (just like
DOS.Exec) which takes care of Turbo Vision housekeeping for you.

There's also pre-done events called "hdLittleDOS", "hdMediumDOS" and
"hdBigDOS" for shelling to the DOS prompt. Run the ED*.DEF examples
and see the help text for details.

The basic idea of using SHAZAM is: It codes the "FrameWork" for you,
so you can concentrate on "fleshing out" custom code and Help Text.
This gives you the freedom to experiment with interface design, since
you can re-generate & re-compile anytime with one keystroke (Ctrl-F9).


To accelerate your learning curve
---------------------------------
Start with the ADEMO*.DEF series, in IDE mode. Type "C:>shazam", use
"File|OPEN" to select a file, then press Ctrl-F9, which will
generate, compile & run a program.


An alternative
--------------
Print the ADEMO*.DEF series, then generate all programs using
command-line mode. Type "C:>shazam ademo*/m" to generate, compile &
run the whole series at once.


Note on HELP
------------
SHAZAM generated programs will automatically support ALT-F1 (to view
previous help screens) if you patch HELPFILE.PAS with ALTF1.PAT



2 - NOTES
=========
[X] Copyrights

Please respect any and all copyright notices.

All parts of this software are copyrighted, including but not
limited to programs, documentation, source-code and examples.

As a licensed user, you may use the example programs. However,
they may not be sold, given away or otherwise distributed without
written permission.

Also, as a licensed user, you are free to incorporate examples
(definitions, help text, etc.) and source code into your programs.


[X] Documentation

You should view, or print, all *.DOC files. Do AINTRO.DOC first,
before starting on the ADEMO*.DEF series. You may also want to
print the ADEMO*.DEF files as you go along. Since SHAZAM
automatically loads support files along with definitions, you can
use "File|Print all" or Ctrl-F4 to print all editor windows
currently loaded into the Desktop.


[X] Interactive and Command-Line modes

Both are supported in the same program. Type "C:\>shazam /?" at
the command-line for a list of switches, or "C:\shazam" and
select the SETUP|Code dialog.


[X] PATCHES

A number of tested patches have been included. Browse the *.PAT
files for details.

APP.PAT - DesqView patch for APP.PAS
------------------------------------
If you want all your Turbo Vision programs to run under DesqView,
APP.PAT contains a simple modification to accomplish this. If
you make this patch, activate the "define" in the "COMPILER.PAS"
file by adding a dollar sign:

{DEFINE desqview} --> {$DEFINE desqview}


This is so the "UserScreen" and "CopyScreen" routines in
GENERAL.PAS will recognize the DesqView patch.


EDLOAD.PAT - for original EDITORS
---------------------------------
An improved version of EDITORS comes with SHAZAM. If you want to
use the original, you must correct this bug in the load/store
methods, or your program will hang during Desktop load/store.


[X] ONLINE HELP

SHAZAM comes with its own help file, but if you need Online Help
for Turbo Vision, don't forget THELP.COM (shipped with Turbo
Pascal). It provides memory resident help/reference on both
Turbo Pascal & Turbo Vision at a relatively low cost in memory
overhead (about 30k).



3 - INSTALLATION
================
If you need to restore the example code, you can re-run INSTALL. All
existing files will be over-written.


Programs
--------
INSTALL.EXE - Installation program
INSTALL.DAT - Installation data

Archives
--------
BABEL - Multiple Language Editor
DEF - Commonly used Definitions
DLG - Commonly used Dialogs
EXAMPLES - Sample definitions and source code
EXSWAP - Source code for EXECSWAP & EXECPROC
GENERAL - General purpose code for Turbo Vision
PATCH - Turbo Vision patches
SHAZAM - Program, Help and Help Compiler
TXT - Commonly used Help Text


Instant INSTALL
---------------
Installation was done using "Instant INSTALL", a generic INSTALL
program which supports multiple diskettes using ARC/LZH/ZIP formats
and de-archive programs. For more information, use the "/?" switch at
the DOS prompt:

C:\>a:install/?


SHAZAM program installation creates the following directory structure:

?:\SHAZAM2\
\DEF\
\DLG\
\TXT\

You are free to re-arrange things to suit you. Use the SETUP |
Directory dialog to let SHAZAM know where things are. The most
likely change is to move the program files -- SHAZAM.EXE, SHAZAM.HLP
and SZHC.EXE -- to a directory on your system PATH.


DISK SPACE
----------
Although three megabytes of disk space are needed to install SHAZAM
and run the PRINTDOC program, you can erase the examples and keep
only the program files.

To free up disk space (ie: before a backup), run CLEAN.BAT. This
erases only generated files, which you can easily re-create.


PORTABLE SHAZAM
---------------
If you must work "on-site" to develop an interface, it is possible to
fit SHAZAM, the compiler (TPC.EXE) and the Turbo Vision units on a
high-density diskette of either size.

The bare essentials are:

[X] SHAZAM.EXE - main program. (SHAZAM.HLP is optional)
[X] SZHC.EXE - new Help Compiler (old TVHC.EXE may be used)

...plus the compiler and TV units, of course.



4 - UNITS
=========
Only the Turbo Vision units are needed to compile a generated
application. However, a number of utility & workhorse units are
included, as used by SHAZAM itself and many of the examples:


GENERAL.PAS Standard events, dialog handling, strings, conversion
and so on. Routines such as "hdSaveDesktop",
"hdLoadDesktop", "VisionExec", etc. may be called
within any Turbo Vision application.


PRINT.PAS Report & print capability for Turbo Vision or DOS, with
support for Generic, Dot-Matrix, LaserJet and
DaisyWheel printers.

Interruptible dialogs are easy to use, can print to
disk or LPT ports, and are ready for use with
EditWindows, printing from disk files, from the
FileViewer or other PCollections (see PPRINT.INT).

For user control of printing, the library directories
contain re-usable dialogs, hints and help text for page
& printer setup (PAGE.DLG & PRINT.DLG, HINTPRN.DEF,
PRNSETUP.TXT).


EDITORS.PAS An enhancement of the original EDITORS, providing the
following features via direct keystrokes and/or from a
menu:

* Centering * Right-margin
* Go to line number * TAB stops
* Place markers (10 per window) * Word wrap

Several *.DEF, *.DLG and *.TXT files were created to
enhance this unit. Actually, you have everything used
by this version of SHAZAM.

See ED*.DEF for examples, EDITORS.DOC for unit details.


EXECSWAP.PAS
&
EXECPROC.PAS These provide swap-to-disk/EMS for EXEC calls. Note
that using "VisionExec" in place of "DOS.Exec" takes
care of TV house-keeping as well. See the EXEC*.DOC
files for details, ADEMO9.DEF for example.


LISTREZ.PAS Program to list contents of resource files (*.REZ).



5 - EXAMPLES
============
The example definitions will generate as either code or resource
based programs. For those examples which switch MenuBars/Boxes and
StatusLines, compiler symbols are used in program logic.

If ALL framework/interface elements are either code OR resources (but
not a mix), SHAZAM automatically defines the compiler symbols "code"
or "resource", respectively. If you use mixed options, be forewarned
that this may affect the program logic in the examples.



6 - OVERVIEW
============
SHAZAM generates complete TApplications, including Help Text and
Hints, so you can test the look & feel of your visual shell.

You can generate, compile and run directly from SHAZAM. The Help
Compiler and Code Compiler are called as needed.

The Turbo Vision objects provide you with a set of "bones", around
which you add the "meat" of your application. With SHAZAM, you
change the skeleton to make different animals. This lets you
concentrate on "fleshing out" your program, rather than writing and
debugging user-interface code. (OK, OK, enough with the analogies
already...)


COMPOSING AN INTERFACE

MenuBars, MenuBoxes, StatusLines and Hints are composed one line at a
time, in a definition (*.DEF) file. In most cases, you need only two
or three of SHAZAM's keywords. In addition, you can design dialogs
interactively using the built-in Dialog Editor (Alt-D).

There aren't many limits to what you can do. As you work through the
examples, bear in mind that SHAZAM was used to design itself; as well
as compile, overlay, execswap, etc. It's just a tad easier than
hand-coding...and you can re-use what you create in other programs.
Especially since include files can be nested for both definitions and
help text.

The ADEMO*.DEF series shows how to travel the road from interface to
working program. It might be handy to use the PRINTDOC program
to extract a Table of Contents and/or just the documentation from all
example *.DEF files.


MAKE IT A PROGRAM

One use of SHAZAM is to create, revise and experiment with user
interfaces. But you can maintain software with it, too.

With SHAZAM's "scanning" ability and the [ EXTERNAL ] keyword, you
can easily add methods and events from include files and units.

You can quickly develop and change interfaces, using just code and no
online help. Or you can maintain fully resourced, overlaid programs
with HyperText Help and Hint Text, using switchable MenuBars/Boxes,
StatusLines and Hint sets.

Foreign translations are also made easier: See the BABEL example.

One thing to keep in mind: SHAZAM maintains and regenerates itself,
and it was built from the Turbo Vision and GENERAL units.


DESIGN PHILOSOPHY

Although some of the examples use code from the GENERAL, PRINT and
EXEC*.PAS units, code generated by SHAZAM requires only the standard
Turbo Vision units. No dependencies are introduced, with the
exception of ExecSWAP, and that can be turned off ("/x-" switch).



7 - ACKNOWLEDGEMENTS
====================


EXECSWAP
--------
This source-code is by Turbo Power Software and is included by
permission. The company has a forum library on CompuServe (PCVENB)
and has other programming products. They may be contacted by:

Kim Kokkonen Information 719.260.6641
TURBO POWER SOFTWARE Orders 800.333.4160
Post Office Box 49009 Fax 719.260.7151
Colorado Springs, CO 80949-9009 CompuServe 76004.2611
USA INTERNET [email protected]


DIALOG EDITOR
-------------
The built-in Dialog Editor was derived by permission from L. David
Baldwin's original DLGDSN (Dialogbox Design). It will read and
export the *.DLG file format.


EDITORS
-------
This unit is adapted from Al Andersen's original NEWEDIT package, by
permission.


BABEL Multi-Language Editor
---------------------------
The translations for the definitions (*.DEF) and help text (*.TXT)
were done by:


Thomas Davidson
PASO del NORTE LENGUAJE Voice 915.564.0990
2713 Hamilton Ave Fax 915.564.5293
El Paso, TX 79930-3639 CompuServe 75540.1022
USA INTERNET [email protected]

Note - Work was done via CompuServe EMAIL.



8 - TECHNICAL SUPPORT
=====================
If you have any problems, you can get the best Technical Support by
Electronic Mail or telephone. For subjects of a more leisurely
nature, you can send postal mail.

Johnathan J. Stein
STEIN RESEARCH & ENGINEERING Voice 419.666.7103
Post Office Box 346 Fax 419.874.4922
Perrysburg, OH 43552 CompuServe 76576.470
USA INTERNET [email protected]



{///////////////////////////////////////////////////////////////////
// THE END //
////////////////////////////////////////////////////////////////////
// //
// First, there was SHAZAM I: "To TAME TApplication!" //
// Then came SHAZAM II: "The WRATH of RESOURCES!" //
//- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - //
// Next, our Hero returns in: //
//- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - //
// //
// SHAZAM III //
// ---------- //
// "The SEARCH for SERENDIPITY!" //
// //
////////////////////////////////////////////////////////////////////
// Advance tickets sent to Licensed Users //
///////////////////////////////////////////////////////////////////}