Power-Programmierung

home *** CD-ROM | disk | FTP | other *** search

/ Power-Programmierung / CD2.mdf / tools / help / pvhc / setup.txt < prev

Wrap

Text File | 1994-04-19 | 16.4 KB | 412 lines

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.