Simtel MSDOS 1992 September

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

/ Simtel MSDOS 1992 September / Simtel20_Sept92.cdr / msdos / info / quikhelp.arc / QHCOMPIL.DOC < prev next >

Wrap

Text File | 1988-06-08 | 33KB | 674 lines

QHCOMPIL - The Help File Compiler for QHELP Help File Programmer's 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 Writing Help Files for QHELP Overview Reserved Characters (and How to Use Them) Defining a Default Screen General Guidelines and Restrictions Using QHCOMPIL (the Help File Compiler) Overview Changing the Hot Key Changing the Display Attributes Changing Case Sensitivity Changing the Description Indentation Setting the Identifier Characters Updating Header Information (on an Existing File) Reading Header Information (from an Existing File) Compiling a Help File Uncompiling a Help File Compiler Errors and Warnings Acknowledgements NOTE: It is assumed in this manual that you are reasonably familiar with the use of QHELP. If you have never used QHELP before, read the QHELP Users Guide and try running QHELP to familiarize yourself with it before writing any help files. There should be a sample help file distributed with QHELP that is already compiled and ready for you to use. 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 and QHCOMPIL 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 the QHELP Users Guide and at least one compiled help file are included. If you are going to distribute the full QHELP system, please make sure that ALL the files you recieved (including the Users Guide and this document) are included in your distribution. INTRODUCTION This manual is going to assume that you are already familiar with the use of QHELP, and that you would now like to write some of your own help files. Before reading further you should know a couple of terms that this manual will use. A "source file" is the file you will create with your text editor. It will contain all the help information you want in your help file, organized in a such a way that QHCOMPIL understands how you want the information displayed by QHELP. Creating source files is discussed in the section "Writing Help Files". A "help file" is the file created by QHCOMPIL from your source file. It consists of several parts. First, a header record that defines the hot key, text colors, and several other things. Second, a list of the keywords defined in your source file along with pointers to where the keyword descriptions are located in the file (this allows QHELP to access help information quickly even if the help file is very large). Last, and most important, the actual descriptions for the keywords along with some information on how to properly display it in the QHELP window. You don't really need to fully understand the help file structure because QHCOMPIL takes care of all the messy details of creating it. "Reserved characters" are characters that you will use in your source file to tell QHCOMPIL how to define the keywords and how you want descriptions for the keywords displayed. The reserved characters that QHCOMPIL uses are described in the section on "Writing Help Files". A "default screen" is the display that appears when QHELP can't find a keyword at the cursor position, or when you press the <F1> key while QHELP is popped up. This is often a simple list of the available keywords, but it can be more complex (and more useful) if you define it properly. "Related keywords" are simply other keywords that relate to a given keyword. Related keywords are displayed in a highlighted color in keyword descriptions, and the user is allowed to select a related keyword while viewing the keyword description. Any text editor can be used to create source files, as long as the file created is a simple text file (so it doesn't contain any sort of "formatting" characters, such as tabs, etc.). Most word processors have either a "non- document" mode (that results in the same sort of simple text file) or a utility to convert a document to a simple text, or ASCII, file. To obtain a sample source file, try using the "Uncompile" option of QHCOMPIL on the sample help file included with QHELP. WRITING HELP FILES Overview There are two types of reserved characters: Those that are recognized only when they appear at the begining of a line, and those that are recognized anywhere within a line. If a reserved character that is only recognized at the beginning of a line appears anywhere else, it is simply treated as part of the text describing a keyword. If you must have a reserved character as part of your text in a position where it would be used by the compiler, simply put two such characters in that place. Any pair of reserved characters signals QHCOMPIL that the character must appear there as text, and QHCOMPIL will place ONE of the characters correctly. The following are the reserved characters: Name Character Position Define Keyword : Beginning of line Page End ! Beginning of line Comment @ Beginning of line Define Title # Beginning of line Reference Keyword ~ Anywhere The format of the source file is fairly simple. You simply define a keyword on a line starting with the Define Keyword character ':', and any lines that follow (up to the next Define Keyword line or the end of the source file) will be the description for that keyword. Reserved Characters (and How to Use Them) The Define Keyword character ':' must appear at the beginning of a line, and the keyword to define MUST immediately follow (no spaces between the ':' and the keyword). Null keywords (a ':' with no keyword behind it) are not allowed. All text on the lines following a keyword definition up to the next keyword definition or the end of the file comprise the description for that keyword. If the description is longer than the QHELP window size, QHCOMPIL will break the description into pages that will fit in QHELP's window. If you have a long description that you know will be paged and you want to define the page endings yourself, use the Page End character '!'. This character must appear at the beginning of a line, and all text behind the '!' on that line is completely ignored (not included in the description). When QHCOMPIL reaches the end of a description (the next keyword definition or end of file) it automatically ends the current page, so don't add a Page End character at the end of your description or you will be rewarded with a blank page. If your source file is very long, it might be wise to add some comments to it to help you remember its organization when you later try to change it. Comments are simply lines that begin with the Comment character '@'. This character must appear at the beginning of the line, and all text behind it is ignored. Comments can appear anywhere in the source file. The Define Title character '#' defines a title for the help file that appears on the top line of the QHELP window when popped up. The first 20 characters following the Define Title character are used to form the title. The Define Title character also defines the default screen; The next keyword definition following a Define Title line is taken as the "default keyword" for the file. This means that the display defined for the "default keyword" is the one that appears when QHELP can't find a keyword at the cursor, or when the <F1> key is pressed while QHELP is popped up. For more information on defining a default screen, see the subsection "Defining a Default Screen" later in this section. Only the first occurence of a Define Title line is valid; further occurences are ignored and treated as comments. The Reference Keyword character '~' is perhaps the most useful reserved character. This character can appear anywhere in a keyword description. Immediately following this character should be a word that is or will be defined as a keyword. When QHCOMPIL sees this character, it assumes that the word following it is a keyword related to the keyword being described, and QHCOMPIL will insert into the help file the proper information for QHELP to display this word in a highlighted color and allow it to be selected. The word following the Reference Keyword character MUST be defined as a keyword at some point in the source file, or errors will result when the file is compiled. However, the referenced keyword does not have to be defined before it is referenced (its definition may appear later in the source file). Defining a Default Screen When the first occurence of a Define Title line is found, the NEXT keyword definition is taken as the "default keyword" for the help file, and the keyword description for it becomes the default screen. The default screen appears when QHELP can't find a keyword at the cursor or when the <F1> key is pressed while QHELP is popped up. The default screen is defined the same way any other keyword description is defined, however you should make sure that the user will know that this is the default screen. One possibility for a default screen is a simple message that no keyword was found at the cursor, and that the user should press <ESC>. A better idea is a complete list of keywords, with each keyword in the list defined as a referenced keyword. This presents a list of highlighted and selectable keywords to the user when no keyword is found at the cursor. For example: #Title For File :KEYWORDLIST Available keywords ~KEY1 ~KEY2 ~KEY3 ~KEY4 Placing these lines at the top of your source file will create a default screen consisting of a list of four keywords that the user can select from. Note that "~KEYWORDLIST" does not appear in the list; While this is a valid reference (there is nothing preventing a keyword description from referencing itself) it is pointless, since selecting this keyword will simply cause the list to reappear. If the list of keywords is very long, QHCOMPIL will break it into pages that will fit in the QHELP window (or you can create the pages yourself with the Page End character). Another idea for a default screen is to create a "menu" structure by defining keywords that contain (as their description) sub-lists of the complete list of keywords. In this way, you can break down the list of keywords into logical groups. For example: #Title For File :MAINMENUKEY Select a Group ~GROUP1 ~GROUP2 ~GROUP3 :GROUP1 Select a Keyword ~KEY1 ~KEY2 :GROUP2 Select a Keyword ~KEY3 ~KEY4 ~KEY5 :GROUP3 Select a Keyword ~KEY6 ~KEY7 Placing these lines at the top of your source file will define a simple menu structure that breaks down the list of keywords into three groups. By selecting a group from the default screen, the user is presented with a list of keywords from that group, and can then select the keyword he/she was after. There is no limit to how "deep" such a menu structure can go. Notice that the group names are also defined as keywords, so you should choose as your group names words that are not likely to be found at the cursor. General Guidelines and Restrictions All keywords that are referenced with the Reference Keyword character '~' MUST be defined at some point in the source file. Failure to define a keyword that is referenced will result in a compiler error. Keywords can't be defined more that once; If your source file "redefines" a keyword, QHCOMPIL will generate a error. No more than ten pages of text are allowed for any keyword description. If a description has too many pages, QHCOMPIL will generate an error. Each page can be up to fifteen lines long. No more than 100 keywords can be referenced by any keyword description. Having too many references results in a compiler error. Note that the 100 references can appear on any page of the description or be split among the pages, but there can't be more than 100 in the entire description. No more than 500 keywords can be defined in a single help file. Defining too many keywords generates a compiler error. USING QHCOMPIL (THE HELP FILE COMPILER) Overview Once you have created your source file, you will need to compile it with QHCOMPIL. QHCOMPIL allows you to define the header information for the help file, compile and "un"-compile help files, and update the header of a help file without re-compiling it. The header information consists of several parts: 1) The "hot key" for popping up QHELP 2) The colors, or "attributes", of the text in the QHELP window 3) Whether the search for keywords at the cursor is case- sensitive 4) The indentation for displaying description lines 5) Which characters (if any) besides letters and numbers can be considered a part of a "word". To run the help file compiler give the following command at the DOS prompt: QHCOMPIL The QHCOMPIL menu will appear at the left side of the screen, and on the right side will be the current settings for the header and an example of the current attributes. To make selections from the menu, use the up and down arrow keys on the numeric keypad to move a highlight bar to the option you want, then press <ENTER>. To exit QHCOMPIL, simply select the "Exit to Operating System" option from the menu. Changing the Hot Key To change the "hot key" that will pop QHELP up, select the "Change Hot Key" option from the QHCOMPIL menu. The hot key is defined in two parts: The shift status and the scan code. The shift status is the state that the four shift keys must be in (the four shift keys are the <Alt> key, the <Ctrl> key, the left <Shift> key, and the right <Shift> key). The scan code identifies the key (other than the shift keys) that must be pressed when the shift status matches what QHELP is looking for. When the "Change Hot Key" option is selected, a small window will appear at the bottom of the screen that allows you to set the shift status. The four shift keys and their status for the current hot key will be shown. To change settings, move the highlight bar (with the arrow keys) to the shift key whose status you want to change, and press <Enter>. When you are finished setting the shift status, press <ESC>. After setting the shift status, a window will appear that lists the "names" of the keys on the keyboard that generate scan codes that QHELP can use (these names are laid out to match the 84-key AT keyboard layout). At the bottom of the window you will be asked for the name of the key. You can enter the name of any key listed, or "NONE" if want to pop up QHELP with a combination of only shift keys. After entering the name of the key you will be returned to the QHCOMPIL menu and the window at the upper right of the screen will be updated to show the hot key combination that you just entered. Note that in order for QHELP to pop up, the hot key combination must be pressed EXACTLY. For example, if the hot key is [Alt]-F1, then the user must press and hold ONLY the <Alt> key, then tap the <F1> key. If the user were to press the [Alt]-F1 combination while holding down the <Ctrl> key, QHELP would not pop up. The advantage to making the hot key match exactly is that you have many more unique key combinations to choose your hot key from. Note also that by choosing "NONE" for a scan code you can pop QHELP up with a combination of just shift keys. For example, you can set your hot key to be [Alt][Ctrl][LShft], and QHELP will pop up whenever these three keys (and no others) are pressed at the same time. Changing the Display Attributes When the "Change Attributes" option is selected, a small menu will appear at the lower right of your screen listing the QHELP window attributes that you can change. Select the option whose attribute you want to change (using the arrow keys to move the highlight bar) and press <Enter>. A large window will appear at the left side of your screen that has a table of x's in it, each one displayed in a different attribute combination. One of the x's will have a box around it. This is the current attribute for the option you selected. Using the arrow keys you can move the box around the window, and as you move the box, the attribute example window on the right side of your screen will change to show the option you selected in the attribute combination given by the box. Pressing the <Enter> key selects the attribute in the box for the given option and returns you to the list of options. If you have moved the box but decided you don't want to change anything, press the <ESC> key and the original attribute will be restored and you will be returned to the list of options. Note that the attributes you define for a help file apply only when QHELP detects that the system is running in a color mode. If the system is running in a black and white mode or is not capable of displaying colors, QHELP's default black and white color scheme is used for displaying the QHELP window. When you are finished changing attributes, press the <ESC> key and you will be returned to the QHCOMPIL menu. Changing Case Sensitivity Case sensitivity affects how QHELP compares the word it finds at the cursor to keywords in the help file. For example, with case sensitivity on, the words "Define" and "define" are considered DIFFERENT words. If case sensitivity is off, "Define" and "define" are considered the same word. The current state of case sensitivity is shown in the current settings window at the upper right of your screen. Selecting the "Change Case Sensitivity" option of the QHCOMPIL menu will "toggle" the case sensitivity on and off. Changing the Description Indentation The description indentation is the number of spaces inserted at the beginning of each line of a description when it is displayed in the QHELP window. Selecting the "Change Indentation" option from the QHCOMPIL menu will cause a small window to appear on your screen that asks you for the indentation. Enter the number of spaces to indent and press <ENTER>. An indentation of 2 or 3 is usually good enough (this is just enough to move the text away from the edge of the window). After entering the indentation, you will be returned to the QHCOMPIL menu. Setting the Identifier Characters Identifier characters are characters other than letters and numbers that QHELP considers part of words. For example, it is common in some computer programming languages to use the underline character as part of identifier names, as in "_status" (which might be a variable name). To change the list of characters that QHELP will use in determining what is and isn't a word, select the "Set Identifier Characters" option from the QHCOMPIL menu. A small window will appear that asks for a list of identifier characters. Type in ALL the characters you want in this list (if you simply want to add to the list that already appears in the current settings window, you must retype all the characters that are there in addition to the one you want to add). When entering these characters do NOT put spaces between them (if you do, the space character will be added to the list also). When the list is complete, press <Enter> and you will be returned to the QHCOMPIL menu with the current settings window updated to reflect the new list. Up to 10 additional identifier characters may be defined. Updating Header Information (on an Existing File) If your goal is simply to change the header information on an existing help file, you don't need to recompile the source file. Change the header information in the current settings window to match what you want for the help file using the first five options on the QHCOMPIL menu, then choose the "Update Help File Header" option. A small window will appear that asks you for the help file to update. Enter the help file name without an extension (".QHP" is assumed) and press <Enter>. If QHCOMPIL can't find the help file, a message to that effect will appear. If the help file exists, you will be warned that updating the header will permanently change the help file, and you will be asked to confirm that you want this done. Press 'Y' to confirm, 'N' to abort the operation. You will then be returned to the QHCOMPIL menu. Reading Header Information (from an Existing File) This option is useful if you are making a single change to the header information of a help file and don't want to re-enter all the other header information or if you are developing a large help file and will be compiling it several times and you don't want to re-enter all the header information every time. What this option does is loads the header information from an existing help file and changes all the settings in the current settings window to match that header information. Select the "Read Help File Header" option from the QHCOMPIL menu. A small window will appear that asks for the name of the help file from which to get the header information. Enter the help file name without extension (".QHP" is assumed) and press <Enter>. If QHCOMPIL can't find the help file, a message to that effect will appear, otherwise you will be returned to the QHCOMPIL menu with the current settings changed to match the specifed help file header. Compiling a Help File This option is the heart of QHCOMPIL. When the "Compile Help File" option is selected, a large window appears on your screen. You are first prompted for the name of the source file. When entering the source file name, you must include the extension (no extension is assumed for source files). If QHCOMPIL can find the source file, it asks for the name of the help file to create. When entering the help file name, do NOT include the extension (".QHP" is assumed). After both filenames are entered, QHCOMPIL will begin compiling the source file. As the compiler works, you will see messages in the window that tell you what it is doing. If an error occurs, compilation will halt and an error message will appear in the window, along with some information on where in the source file the error occured. You may also see some warnings, but these will not halt the compilation process. When compilation is complete or when an error occurs you will be asked to press <ESC>. This will return you to the QHCOMPIL menu. Uncompiling a Help File Uncompiling a help file is the reverse of compiling a source file; it takes a help file and creates a source file from it. When the "Uncompile Help File" option is selected, you will be asked for the name of the help file to uncompile. Enter this name without an extension (".QHP" is assumed). You are then asked for the name of the source file to uncompile to. Enter this file name WITH an extension (no extension is assumed for source files). After both filenames have been entered, QHCOMPIL will begin uncompiling the help file. When the process is complete, you will be returned to the QHCOMPIL menu. The source files that result from uncompiling a help file will not exactly match the original source file, since the help files don't store things like comments, etc. However, the resulting source file can be recompiled to obtain exactly the same help file. Also, the uncompile option will place several comments at the beginning of the resulting source file that indicate the settings of the header information for the help file. Compiler Errors and Warnings When compiling a help file QHCOMPIL may generate warning messages. These warnings do not stop compilation, but you should be aware of them. QHCOMPIL will generate a warning for every keyword that is defined but not used as a reference by some other keyword (that is, the keyword description is only available by popping QHELP up with that word under the cursor, and it will never appear as a highlighted word in another keyword description or a keyword list). This is perfectly legal, but it isn't always a good idea. If you have created a list of keywords as your default keyword description, you should take note of these warnings (note that the default keyword itself will appear in this list of warnings, but it can be safely ignored since it is not intended to be referenced). QHCOMPIL may also encounter errors in the source file. Any error will halt the compilation process, and a message will be printed describing the error, along with some information to help you locate the error in your source file. QHCOMPIL will only "see" the first error in a source file; If other errors exist, you will need to fix the current error and recompile the source file to find the next one. The following is a list of QHCOMPIL error messages. Most of these messages are self-explanatory, but where appropriate some additional information is given. The number at the left is the internal QHCOMPIL error number, so the numbering may have gaps but this list is complete. 2) Error writing output file. 3) Unable to resolve keyword reference. This error occurs when you have referenced a keyword with the Reference Keyword character '~' but have not defined the keyword being referenced anywhere else in the source file. 4) Unable to open input file. This error may occur if the source file exists but has been locked by some other program. 5) No title screen defined. QHCOMPIL didn't find a Define Title line anywhere in the source file, and therefore can't define a default screen. 12) Keyword too long in line XX The keyword being defined exceeds the maximum keyword length of 15 characters. 13) Maximum keywords exceeded in line XX You have tried to define more than 500 keywords in the source file. 14) Not enough available memory in line XX 15) Line too long in line XX The description line is too long to fit in the QHELP window. Note that the indentation defined as part of the header is added to the beginning of each line as it is compiled, so the line may LOOK like it will fit, but adding the indentation makes it too long. 16) Too many keyword references in line XX You have tried to reference more than 100 keywords in a keyword description. 17) Too many pages for description in line XX The keyword description exceeds 10 pages. 18) Text not associated with keyword in line XX This error will occur at the beginning of a source file if QHCOMPIL sees what appears to be part of a description but no keyword has been defined yet. 19) Null keywords not allowed here in line XX A Define Keyword character appears with no keyword behind it. 20) Keyword redefinition in line XX This error occurs when QHCOMPIL sees a keyword definition for a keyword that was defined earlier in the source file. XX) Unknown error XX in line XX This error occurs when an internal QHCOMPIL error is generated that QHCOMPIL doesn't recognize. 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. Oh, and I used a "C" library written by Dave for all the menus and windows in QHCOMPIL.