Garbo/Garbo.cdr/pc/progrmng/qhcompil.lzh/QHCOMPIL.DOC

Text File | 1988-04-30 | 34KB | 676 lines

                  QHCOMPIL - The Help File Compiler for QHELP
                         Help File Programmer's Guide



                                  Written by

                                Mark VanKekerix
                                 2035 J Apt 6
                              Lincoln, NE  68510
                                [phone]



         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.