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

PV Help DemoPolyVision HelpV1.0.0  OFeaturesã' Technical NotesÁWelcome and Thanksþ'Ä Creating the WordPerfect FileüÂPage Procedure#¾Extended Characters£
BÔCompiling the Help Filer,w!Testing Your Help File¡é'Placing Help in Your ProgramOtŠ*Licensing Agreement**Ù:[ENTER]—@Colors”š@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
middle button - goes to page 0 (zero)

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

See: Welcome and Thanks 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 stadard text format
setup.hlp - this file in help format for
demo purposes
pvhctry.c - c file to demo a simple test

Maximum number of characters 20,000 per page
Maximum number of help pages 2,001 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 can 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 which
text page 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.

(C) 1994 PolyVision SoftWare
All Rights Reserved.

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.

Technical Notes
Creating the WordPerfect File
Page Procedure
Extended Characters
Compiling the Help File
Testing Your Help File
Features
Placing Help in Your Program
Licensing Agreement 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 ([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.

See: Page Procedure next. 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 ([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. There should be no
problems using hyphenation as the PVH compiler
recognizes such WordPerfect code. There is no need to
insert hard returns after a hyphenation.

Use hard returns for ending paragraphs and when you
wish to use indent spacing on the next line.

Should you ever need to use a backslash followed by
either a dollar or pound sign, use two backslashes in
a row to indicate it as text.

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.

See also: Extended Characters

Creating the WordPerfect File  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 refer-
ences. 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 differ-
ence 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
begin Compiling the Help File.

NOTE: Please avoid using any WordPerfect codes other
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.
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 refer-
ence 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 with 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. 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 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 main-
taining 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);/* pg 3 in 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 pg 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 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.
(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. 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.

GOOD PROGRAMMING!

Thanks,

PolyVision SoftWare Refers to hitting the enter key on your keyboard.

Hitting [ENTER] in WordPerfect causes a Hard Return
(HRt) code to be inserted into you text file. HelpWindClr - text window color
HelpBordClr - border color
HelpRefClr - reference color
HelpGlosClr - glossary color
HelpBoldClr - bold text color