Simtel MSDOS 1992 June

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

/ Simtel MSDOS 1992 June / SIMTEL_0692.cdr / msdos / info / qhelp.arc / QHELP.DOC < prev next >

Wrap

Text File | 1988-04-30 | 17.3 KB | 372 lines

QHELP - PopUp Help Program Users Guide Written by Mark VanKekerix 2035 J Apt 6 Lincoln NE 68510 (402) 475-0601 QHELP and QHCOMPIL software Copyright 1988 by Mark VanKekerix TABLE OF CONTENTS License Introduction What is QHELP? The Story Behind QHELP System Requirements Using QHELP What Are Keywords? Installing QHELP Popping Up the Help Screen Moving Through the Help File Changing Help Files Removing QHELP from Memory Notes for Floppy Disk Users Acknowledgments NOTE: In this document, QHELP refers to the resident program QHELP.EXE, and QHCOMPIL refers to the help file compiler program QHCOMPIL.EXE. Although QHCOMPIL is referred to in this guide, information on creating help files with QHCOMPIL is contained in a separate document. QHCOMPIL and the QHCOMPIL documentation may not have been included with your copy of QHELP. LICENSE Users of the QHELP system are granted a limited license for personal use. No part of the QHELP system can be distributed for profit without a specific written agreement (this includes distribution within a company or corporation, "bundling" with other software, etc.). These limitations apply to QHELP, QHCOMPIL (the help file compiler), and any help files created with QHCOMPIL. What this means is you are free to use QHELP and any help files you have created yourself or obtained from bulletin boards, etc., but if you want to package QHELP with another program you are selling for profit, contact me for written permission to do so (I will ask for a small fee for such a license). The limitation on "bundling" QHELP with other programs applies only if the program is being sold for profit. If you have developed a public domain program and would like to use QHELP and a help file you have written as the program's help system, please feel free to do so. If you have written a help file for any program (public domain or otherwise) that you think other people would find helpful, I encourage you to make it part of the public domain (along with a copy of QHELP). I also encourage you to upload QHELP to all of your favorite bulletin boards, copy it for your friends, etc., as long as you don't violate the above restrictions. QHELP may be distributed by itself (without QHCOMPIL) subject to the above restrictions. If you are going to distribute QHELP in such a manner, please make sure this document and at least one compiled help file is included. INTRODUCTION What is QHELP? QHELP is a memory resident help system that can pop up in most any text- based application program. The file containing the available help information is called the "help file", and is fully user-definable. Anyone that has an ordinary text editor and a copy of QHCOMPIL (the help file compiler) can create his/her own help files. The help files can be very large, but QHELP will always use the same small amount of memory regardless of the size of the help file. QHELP does this by only holding a list of topic names (called "keywords") in memory; For the actual help information it returns to the file. The Story Behind QHELP A long time ago on a PC far, far away, I was a lowly Pascal language programmer who desperately wanted to learn a new language called "C" and write hot new programs that would take the world by storm... Actually it wasn't all that long ago and "C" isn't such a new language, but I decided it was about time I learned to use it, so I started writing simple programs and such using Borland International's TurboC compiler. Before too long I thought I was ready to start a major program, but I couldn't decide what to write. I wanted to write something for the public domain, but most of the really useful ideas I had had already been written by someone else. Then I came up with the idea for QHELP. TurboC has a really nice help system. It can give information on any topic relating to the use of its integrated development environment, including menu options, use of the editor, and "C" reserved words and standard library functions. The problem was that I didn't use the integrated environment very often; I have another editor that is more powerful than TurboC's (it allows editing of multiple files, definition of macros, etc.) but when I used it I couldn't access TurboC's help system. So I decided to write a "pop up" help program that could give me the help information I wanted from within any editor I chose to use. Since I wanted to be able to add to or change the help information, I made QHELP general enough that it could give help on any topic that someone had written a help file for. QHELP is very much patterned after TurboC's help system. I really liked the way Borland set it up; When popped up, the help system tried to find information on whatever word happened to be at the cursor, but if it couldn't find anything it would present a menu of topics. Also, if there were topics relating to the topic you were looking at it allowed you to go to those topics by simply pointing at the topic name. I decided to incorporate these features, plus a few of my own, into QHELP. System Requirements QHELP will run on IBM PC, XT, or AT (or compatible) computers using MS- DOS 2.0 or later. It takes up about 35K of memory when resident. QHELP doesn't care what display card you are using, but it will only pop up in text modes (not in graphics modes). Using QHELP What Are Keywords? Keywords are the basis for retrieval of help information. A help file for QHELP is simply a list of "key words" that identify the topics available in the help file, along with a description for each topic (the actual help information) and the names of topics that are related. For example, if the help file contained information on MS-DOS system commands, the word "chdir" would be a keyword (since it is the DOS command for changing directories). "chdir" would be listed in the help file as a keyword, along with a description of what the command does. Along with the description would be a list of related keywords, such as "mkdir","rmdir", and "dir" (the commands for creating, removing, and listing directories). When QHELP is "popped up", it looks at the word on the screen next to the cursor and tries to find that word in its list of keywords. If it finds a keyword, the description for that keyword is put on the screen, along with any related keywords. You are then allowed to select one of the related keywords (in which case the description for the selected keyword replaces the original one) or return to the application you are using. If QHELP can't find a keyword that matches the word at the cursor, it pops up a "default screen", usually a menu of available keywords. Installing QHELP Installing QHELP is fairly simple. At the DOS prompt, give the following command: QHELP <filename> where <filename> is replaced by the name of the help file you want to use. The help file name should not contain an extension; An extension of ".QHP" is assumed. For example, the command "QHELP TESTFILE" would install QHELP with the keyword list from the file "TESTFILE.QHP". "TESTFILE.QHP" would have to be in the current directory, or QHELP will not install and will instead report that it can't find the specified help file. Another way to install QHELP is to specify the full path and filename for the help file, as in "QHELP C:\QHFILES\TESTFILE", which would install QHELP with the keyword list from the file "TESTFILE.QHP", located in the QHFILES subdirectory of drive C:. If the specified help file is in the current directory when QHELP is installed, or if you have specified the full pathname for the help file, then QHELP will always be able remember where the help file is so it can properly retrieve help information. If a partial pathname is specified, as in "QHELP ..\TESTFILE" (which specifies the file "TESTFILE.QHP" in the directory above the current one), then QHELP will not be able to locate the file properly if you change directories (since "TESTFILE.QHP" will not always be located in the directory "above" the current one). If QHELP can find the help file you specified, it will print a message telling you that it is installing, and list for you the "hot key" combination that will cause it to pop up. Popping Up the Help Screen To obtain help information while running an application program, press the "hot key" combination that QHELP gave to you when it installed. For example, if the hot key was "[Alt][Ctrl]-H", then press and hold the "Alt" key, press and hold the "Ctrl" key, and tap the "H" key. The QHELP window will then appear in the middle of your screen, and you can release all the keys you're holding down. As it is popping up, QHELP will look at the word under the cursor and attempt to find that word in its list of keywords. The cursor MUST be positioned properly (on some part of the word) for QHELP to find that word. If it finds the word in its keyword list, then QHELP will display in its window the description for that keyword. If it can't find the word, then QHELP will display the "default screen" for the help file, which is usually a list available keywords. If QHELP detects that your system is capable of displaying colors, the QHELP window will appear in the colors defined by the author of the help file. If your system appears to be monochrome, the window will be displayed in QHELP's default black and white color scheme. When using a monochrome-type display with a color display adapter (like the composite display and CGA adapter of older Compaq portable computers) you may want to give the command "MODE BW80" at the DOS prompt to change your system to a video mode that QHELP will recognize as black and white. Moving Through the Help File The help information for a keyword may be longer than the window that QHELP displays it in. If this is the case, the word "PgDn" will appear in the lower right corner of the QHELP window, indicating that there is more information than will fit in the window and that you can use the <PgDn> key on the numeric keypad to display the next "page" of information. When you press <PgDn>, the next page will be displayed, and the word "PgUp" will appear in the upper right corner of the window, indicating that there are page(s) of information "above" the page currently in the window. If there are several pages of information, the "PgUp" and "PgDn" indicators may both be displayed at the same time. The help information text will be displayed in an appropriate color. If there are keywords related to the information you are currently looking at, these related keywords will be displayed in a different color. One of these related keywords will also be displayed in a "highlight" color, indicating that it is the "selected" related keyword. By using the arrow keys on the numeric keypad, you can change the selected keyword to any one of the related keywords being displayed. The right arrow key moves the "highlighter" to the next keyword to the right, the left arrow moves left, the up arrow moves up, and the down arrow moves down (pretty much as you would expect). Pressing the <Enter> key will cause the text in the window to be replaced with the information on the currently highlighted keyword. In this way, you can go directly to related topics. Pressing the <F1> key at any time will display the "default screen" for the help file (this is usually a list of available keywords). This is the same screen that would appear if QHELP was unable to find a keyword at the cursor when popped up. Pressing the [Alt]-F1 key combination will "back up" to the information on the keyword you last examined. For example, if you were looking at a description of the DOS "chdir" command, selected the related topic "mkdir", then pressed [Alt]-F1, you would be returned to the description of "chdir". QHELP remembers the last ten keywords you examined, and so allows you to back up ten times. If you have reached the limit of what QHELP remembers, no action is taken when you press [Alt]-F1. Pressing the <ESC> key will return you to your application program. Changing Help Files If you have popped QHELP up and realize that the information you seek is in a different help file than the one you installed, you must change help files. To do this, press the <F2> key. QHELP will prompt you for the name of the help file you wish to load. When entering the help file name, don't give an extension (".QHP" is assumed). It is usually best to specify the complete pathname for the file (including the drive letter). If QHELP is unable to locate the help file, it will tell you so, then return you to the keyword description that was in use when you pressed the <F2> key. If QHELP finds the help file, it will tell you the "hot key" associated with that file (which may be different from the original one). This is now the key combination that will pop QHELP up. The default screen for the new file will then be displayed. Removing QHELP from Memory If you wish to remove QHELP from memory, issue the following command at the DOS prompt: QHELP /U QHELP will check to see if it is resident in memory, and attempt to unload the resident portion if it is. If QHELP is not resident, it will tell you so. It is always a good idea to release all resident programs from memory in the reverse of the order in which they were installed, i.e., the last resident program should be released first, the next to last program second, etc. If you don't do this, you might end up with "holes" in memory, or worse yet, interrupt vector chains corrupted (this can cause your system to lock up among other things). QHELP will try to determine if other resident programs are loaded above it, and will refuse to release itself if it finds any, but it isn't always accurate. The best defense against such problems is to release all resident programs above QHELP before releasing QHELP itself. Notes to Floppy Disk Users If you are running QHELP from floppy disks, the floppy disk containing the help file must be in the same disk drive that it was in when QHELP was installed, or QHELP will be unable to locate its help information. You can remove the disk when QHELP is inactive, but the disk MUST be present when QHELP is popped up. If you inadvertently pop QHELP up without the disk in its proper drive, QHELP will give an error message, and you will have to press <ESC> (to exit QHELP), put the disk in the correct drive, and pop QHELP up again. Acknowledgments I would like to thank Borland International both for its outstanding "C" compiler, TurboC, and for the excellent help system in TurboC's integrated development environment which inspired me to write QHELP. I would also like to thank Al Stevens for his article "Writing Terminate-and- Stay-Resident Programs (Part 1: TSRs in TurboC)" in Computer Language magazine (February 1988 issue). In that article Mr. Stevens gave complete listings for the shell of a resident program, and these are the residency routines that QHELP uses (with some minor modifications). Anyone interested in trying his/her hand at writing resident programs (in "C" or otherwise) would do well to read Mr. Stevens' article. Also, special thanks go out to my roommate, Dave Steiner. Since he is an experienced "C" programmer and has also written many resident programs (in several languages), I pestered him with endless questions and he somehow managed to answer them all.