Category : Miscellaneous Language Source Code
Archive   : PVHC.ZIP
Filename : SETUP.TXT

Welcome and Thanks

Thank you for taking the time to try out the PolyVision Help
Compiler for DOS version 1.0. It is a unique and easily
integrated programming tool that allows you to create, compile
and incorporate customized context-sensitive, cross-referenced
help into you DOS text mode applications.

Working with your favorite word processor and saving your
document in WordPerfect 4.2 format, you use the compiler to
reformat the document into a form the help function understands.

Then using three standard C functions in your program, you then
(1)initialize the system, (2)request help text pages at different
times throughout the run of the program and then (3)close it down
when the program terminates.

No separate TSR. At the slim cost of 5-6K, the system is hard
coded to your program. We're sure you'll find it simple,
practical and most of all useful.

================================================================

The PVHC.ZIP file comes with 10 files:

phc.exe - the PolyVision Help Compiler
phctest.exe - a program to test your help files
printdoc.bat - prints setup file to printer
read1st.txt - features and requirements
pvhcl.lib - Large model library file for linking
functions (Borland C++ 3.1 version)
pvhcl4.lib - Large model library file for linking
functions (Borland C++ 4.0 Chicago version)
pvhc.h - include header file for C functions
setup.txt - this file in standard text format
setup.hlp - this file in help format for demo
purposes (see Testing Your Help File
below to find out how to view this
file using phctest.exe)
pvhctry.c - c file to demo a simple test

The following should allow you to beginning using this program in
a matter of minutes. Please note that [ENTER] refers to hitting
the enter key on your keyboard.

(1) Technical Notes
(2) Creating the WordPerfect File
(3) Page Procedure
(4) Extended Characters
(5) Compiling the Help File
(6) Testing Your Help File
(7) Features
(8) Placing Help in Your Program


LICENSING AGREEMENT

(C) 1994 PolyVision SoftWare
All Rights Reserved.
All trademarks and registered trademarks are property of their
respective owners.

Please note that this is a shareware program. Please register
with check or money order of $25 per copy in U.S. funds made
out to: Rigo Muniz

Mail to:
PolyVision SoftWare
P.O. Box 16074
West Palm Beach, FL 33416-6074

The registration fee is $25 per programmer's copy. Thank you for
your honesty! No guarantee is made or implied. The program is
provide "as is".

Once you have registered, you may incorporate the functions
provided in the pvhcl.lib in your programs in executable
form only - ROYALTY FREE. You may not distribute the support
programs phc.exe, phctest.exe as stand alone parts of your
program, but you may distribute copies of the achieved pvhc
files for shareware distribution.

We have done our best to ensure that the programs and code here
are error free. Still, PolyVision SoftWare and its agents
disclaim all warranties, expressed or implied, including but not
limited to any implied warranty as to the merchantability or
fitness for a particular purpose. In no event will PolyVision or
its agents be liable for any damages resulting from the use
of this software. The end user agrees to accept all risk by using
this software.

Thanks,

PolyVision SoftWare


TECHNICAL NOTE:

Maximum number of characters 20,000 per page
Maximum number of help pages 2,001


CREATING THE WordPerfect FILE

Once you've opened WordPerfect, set your margins to 1" in from the left
and your right margin to 6.5" so you have a total of 5.5" for text.
Use a fixed width font such as courier at 12 point or 10 cpi.

At the start of the file you should give the entire file a name of up
to 24 characters of your choosing. To do this type a backslash immediately
followed by a dollar sign then type your title and end the line with a hard
return (press [ENTER]).

Example:
\$MyProg V2.0 Help File[ENTER]

This should only be done ONCE at the beginning of the file. It will come
in handy if anyone should (at the DOS prompt) enter the command:

TYPE MyProg.hlp

Only your first line will be printed to the screen and then returned to the
prompt.


PAGE PROCEDURE:

Begin with the first page - page 0 (zero). Type a backslash immediately
followed by a pound sign. Type your title of up to 30 characters. End the
line with a hard return (press ENTER). Be careful of beginning and ending
spaces as this may generate matching errors.

Example
\#File Menu[ENTER]

Proceed to type your text. Allow WordPerfect to wrap your text as it
normally does. Use hard returns for ending paragraphs and spacing. If
you need to indent, do NOT use tabs. Instead use spaces. Any time there
are more than two spaces in a row, the PolyVision Help Compiler will
automatically insert a compression code for whatever the number of spaces.
This will help compact the final help file. It will not slow down the final
performance.

Page 0 is the page the user will get if F1 is pressed during a help
session. You will probably want to use this page for help on help.

EXTENDED CHARACTERS:

The WordPerfect 4.2 format uses the complete ASCII character set.
Therefore, you can use all characters from 1 through 254. To use
the extended characters (1 thru 32 and 127 thru 254) in versions
of WordPerfect 5.0 and above, you must find them in the WordPerfect
character sets (1 through 8). The PolyVision Help Compiler will accept
these as though they were single characters (not counting the code).
You may also use them in or as your titles. This will allow you to
draw boxes, arrows, symbols and other characters you may require.

When you come to the end of the WordPerfect page (but not the end of
your help page), allow WordPerfect to insert a soft-page return. There
are five color codes for your text. (See PLACING HELP IN YOUR PROGRAM
for more on setting colors.)

HelpWindClr - text window color
HelpBordClr - border color
HelpRefClr - reference color
HelpGlosClr - glossary color
HelpBoldClr - bold text color

While creating the help file you will not have to do anything to use the
HelpWindClr or the HelpBordClr these are used as the default text and
border colors. Your page title will become part of your border. For text
you wish to color in a "bold" color (i.e. a different color to separate it
apart from the regular text) select the text in WordPerfect and make it
bold.

To REFERENCE another page, type that page's title exactly as you named it
then select that text and make it underlined in WordPerfect. This will
later show up in the help file using the HelpRefClr you've selected. When
the user clicks on the text with the mouse or uses the arrow keys to move
the cursor to it and presses enter - it will automatically go to the page
it references. PHC matches the page name to the reference the page. No
other action is required on your part. Be careful with spaces before and
after titles.

For GLOSSARY references, use the same procedure as for REFERENCE except
after selecting the text use strikeout instead of underline in WordPerfect.
The only difference here is that it will use the HelpGlosClr and these
may be shorter than a full reference page - that is up to you.

When you finally reach the end of your help page, insert a hard-page return
(Control-Enter). The next page will be page 1 and so on. Repeat the page
procedure. Pages may be as long or a short as you need them to be.

Once you have finished the help file, simply save it as a WordPerfect 4.2
file. Exit WordPerfect and prepare to compile the file.

NOTE: Please avoid using any other codes than the ones explained above.
Although the PolyVision Help Compiler will usually ignore and discard
these, it is safer not to fit too many codes into your text file.


COMPILING THE HELP FILE:

Syntax: PHC [option] [input_file] [output_file]

option : -h make C header type file
input file : complete name
output file: if not specified uses input file's prefix tagging
on an .hlp suffix

The compiler does NOT destroy the form of the original file. It merely
uses the WordPerfect file as a reference and creates a new file in the
PolyVision Help File format. This way you can create the help file in
increments and also use the text for a printed manual.

First be sure that the help file is in the same path as the PolyVision Help
Compiler (PHC.EXE). On the command line you can use the -h switch which
will use your page names to create #defines that refer to your pages. For
instance if you named page 3 File Menu. A header file using your output
file name (such as MyProg.h) would have a reference such as

#define FILE_MENU 3

and so on. Notice that the name has been declared with all caps and the
space has been replaced the an underbar ( _ ). This is helpful, especially
if you're shifting your pages around as you create the help file. If you do
not wish to include this option, go directly to the input_file name.

The input file name is the only argument that MUST be on the command line.
You must type the complete file name such as MyProg.wp4 - both prefix and
suffix.

The output file can be specified if you wish, otherwise a .hlp suffix will
be appended to the original file's name.

NOTE: PHC automatically deletes a file of the same name as the help file
being created if it's on the path and replaces it with the new one.
Please be aware of this. Don't name the WordPerfect file with an
.hlp suffix.



TESTING YOUR HELP FILE:

Syntax: PHCTEST [help_file]

The compiled help file should be on the same path as phctest.exe or you
must provide the name in full

EXAMPLE:
same path
phctest MyProg.hlp[ENTER]

different directory
phctest c:\borland\MyProg.hlp[ENTER]

The program phctest.exe is provided so you can test your help file without
loading it into a program. The color attributes are preset as follows.

HelpWindClr = BLUECYAN - cyan background blue text
HelpBoldClr = HIWHITECYAN - cyan background white text
HelpBordClr = REDWHITE - gray background red text
HelpGlosClr = BLACKCYAN - cyan background black text
HelpRefClr = YELLOWCYAN - cyan background yellow text

FEATURES:

The features are the same as are provided when within your program. Press
F1 to start the help session.

KEYBOARD:
arrow keys - scroll cursor up, down, left, right
page up - scrolls text up one window's worth
page down - scrolls text page down one window's worth
end - goes to end of current line
home - goes to beginning of current line
control page up - scrolls forward to next help page (i.e. pg1 to pg2)
control page down - scrolls back one help page (i.e. pg2 to pg1)

F1 - goes to page zero
alternate+F1 - goes to previous help page (i.e. pg3 to pg7)
enter - cursor over a reference or glossary note; goes to that page
escape - ends help session

MOUSE:
left button - cursor over reference or glossary note; goes to that page
over ALT+F1 instruction at the bottom of the screen will
perform that function
RIGHT SIDE OF HELP SCREEN:
over up triangle will move up one line
over up arrow will page up
over down arrow will page down
over down triangle will move down one line

right button - escape

Using PHCTEST.EXE you can make sure everything is working properly.
Pressing the F10 function key will exit you from the phctest program.


PLACING HELP IN YOUR PROGRAM:

To use the help functions in your programs requires only a few simple
steps. In the Borland IDE (Integrated Development Environment - the
editor part) go to Option|Directories and be sure that there is a clear
reference to where you placed the pvhc.lib file in the libraries section
and the pvhc.h file in the include section. You should also go to
Options|Make and include Check auto-dependencies. On ALL modules that
refer to any of the functions or colors of the PolyVision Help system
be sure to include the line

#include "pvhc.h"

Within your main function you should set or call a function that first sets
the Help Window Colors such as follows:

HelpWindClr = 0x31; /* cyan background blue text */
HelpBoldClr = 0x3F; /* cyan background white text */
HelpBordClr = 0x74; /* gray background red text */
HelpGlosClr = 0x30; /* cyan background black text */
HelpRefClr = 0x3E; /* cyan background yellow text */

This is an 8-bit (one unsigned char) reference to the colors used. You
might consult your Borland C++ Library Reference manual under textattr
for further information on how to set these color schemes. You may change
these colors anytime during the run of your program. That way if your user
wishes to go to a color mode or a black and white mode - you can change
these colors to their needs and taste.

Next, before you call any other functions you have to call the initPVHelp
function. It requires a string with the full name of the help file. You may
also include the directory location also.

EXAMPLES:
initPVHelp("MyProg.hlp");

also
initPVHelp("C:\MyDir\MyProg.hlp");

This prepares the help function by opening and maintaining the help file,
and opens a buffer using farcalloc for the maximum size page in your file
(not the entire file). If for some reason this cannot happen initPVHelp
will return the following:

-1 - Could not open help file.
-2 - Help file not PVHC type.
-3 - Could not allocate help buffers.

otherwise it returns a 1 (one). You may wish to call it like this:

EXAMPLE:
if(initPVHelp("MyProg.hlp") != 1)
MessageWindow("Could not initiate help file.");

Once initPVHelp has been established you may call to your pages one at a
time from anywhere in you program. getHelpPage takes the argument of your
requested page number. For instance if in the File Menu part of your
program your user pressed F1 and you have help page 3 set for it you could
use a switch argument like this:

EXAMPLE:
int key; /* keyboard or mouse number */
:
switch(key)
:
case F1_KEY: getHelpPage(3); /* shows page 3 in the help file */
break;
:

That's all there is to it. getHelpPage retrieves that page from you help
file opens the help window and performs the same way as demonstrated above
in the PHCTEST.EXE section. When the user presses escape, he returns to
your program. If for some reason initPVHelp did not activate, getHelpPage
will simple return without doing anything. In other words if the user
pressed F1 in the example above, nothing would happen. On ALL modules that
refer to any of the functions or colors of the PolyVision Help system
be sure to include the line #include "pvhc.h".

When the help window closes, it defaults to hiding the cursor and
mouse cursor. If you wish to make the cursor visible just add a call
to showcursor(). This will return your cursor to its original size
and position. The showcursor and hidecursor routine is part of the
pvhcl.lib and is used by getHelpPage().

EXAMPLE:
case F1_KEY: getHelpPage(3); /* shows page 3 in the help file */
showcursor();
break;


Before your program exits you must make one final call which is to
DestroyPVHelp. It takes no arguments but safely closes the opened help
file and frees the allocated memory. If initPVHelp was not activated this
function does nothing.

EXAMPLE:
DestroyPVHelp(); /* closes down PVHelp system */

That's all there is to it! On ALL modules that refer to any of the
functions or colors of the PolyVision Help system be sure to include
the line #include "pvhc.h". You should also go to Options|Make and
include Check auto-dependencies. Be sure you are using the LARGE model.

GOOD PROGRAMMING!

PolyVision SoftWare

(C)1994 PolyVision SoftWare
All Rights Reserved.