EZhelp Reference, EZcomp compiler
(C) Copyright 1990, Brain Child Systems.
All rights reserved.
--------------------------------------------------------------------------

{{ What's EZhelp?,  1,1,0 }}
  ........................................................................




                        I N T R O D U C T I O N

                                  T O

                    E Z h e l p   R e f e r e n c e
   
                              version 1.2

                       A ShareWare reference tool

                (C) Copyright Brain Child Systems, 1990

                          All rights reserved




  ........................................................................


                                Hello!


     EZhelp is a shareware package designed as a tool for writers or
  programmers who need a basic help system to use stand-alone or call
  from existing software, or to use as an on-line reference. You can
  easily create a window driven help system with new or existing texts,
  and registered users may distribute them with EZhelp free of charge.


     This reference guide is driven by EZhelp, and describes how to
  set up your own text files and for in-house use or distribution.
  Take a moment to read the help topics and move through the
  different menus.


     Any suggestions you have for the program are welcome. There are
  many possible features that could be added, and this will depend on
  what you ask for. If you try the program and have an opinion, drop
  us a line!


  EZhelp consists of three programs:

    EZcomp.EXE -  A text compiler program that creates
                  an index on help reference files. This index
                  file describes where topics begin and end
                  within the text.

    EZhelp.EXE  - The program that uses the help file and the index
                  created with the compiler to drive the windows
                  and text display.

    EZsetup.EXE - A utility program that creates a default options
                  file for use by EZhelp at runtime.


    You will need a text editor or word processor to create your text
    files with. There are a few issues to be aware of when using a word
    processor. For more information, select the "Entering text" menu.
    You will also be more successful with this package if you follow
    the hints on organizing your topics. More information can be found
    in the "Forming Outline" menu.



    EZhelp features:


          quick text compiler with optional topic sorting,
           reference report, error messages

          pop-up menus
          choice of line style
          choice of colors on five screen components
          manual/automatic text window sizing
          optional page number display
          choice of PageUp/PageDn/Escape messages
          display text at top or bottom of screen
          start at any menu level
          jump directly to any help topic

          1 free update

{{ 3 easy steps,    1,2,0 }}

     3 easy steps


      There are 3 steps to setting up your own help reference system:

      1) Writing the reference help text -

           Forming an outline, creating topic definitions,
           and entering the text

      2) Compiling text -

           Compiling the text using EZcomp to create the
           text index
           
      3) Using EZhelp -

           Calling the program with a choice of startup options and/or
           default data created by EZsetup.exe
{{ Writing text,    1,3,2 }}

   .... menu 2 is next ....

{{ Compiling text,  1,4,3 }}

   .... menu 3 is next ....

{{ Using EZhelp,    1,5,4 }}

   .... menu 4 is next ....

{{ Using EZsetup,   1,6,0 }}

     Using EZsetup

      EZsetup is a utility that creates a data file of startup options
   used by EZhelp Reference at runtime. The options that can be saved
   in the data file are:

       Title color         1st letter auto selection
       Letter color        Automatic window sizing
       Window color        Page number display
       Border color        Error display
       Hilite color        Customized page up string
       Border style        Customized page down string
                            Customized exit string
                            Help window anchor (top or bottom)

      Some of the startup data options can be overridden from the
   command line when EZhelp is started. For more information on
   command line parameters, see Using EZhelp, Command line.

{{ Registering,     1,7,0 }}

     Registering EZhelp

      EZhelp is a shareware product, and may be used for a reasonable
   trial period free of charge. What defines a reasonable trial period?
   You may evaluate the package for 30 days, which should be enough
   time to decide if you would like to continue using it.

      The basic registration fee is $25. This fee includes a diskette
   with all EZhelp executable files, including the compiler and setup
   utility, and a user's guide on the diskette. When an update becomes
   available, registered users will be notified. One free update will
   be provided, less media and postage costs.


      To register EZhelp, print out a copy of the file "order.frm" with
   this DOS command:

      COPY ORDER.FRM > PRN





   Ŀ
       R e g i s t r a t i o n   F o r m  /  U s e r   P r o f i l e   
   Ĵ
    Name             Computer __________________   Brain Child Systems 
    Company          Application to use            P.O. Box 3882       
    Address          EZhelp (if any) ___________   Austin, TX 78764    
    City State ZIP   EZhelp version ____________                       
   Ĵ
                                                                       
                                                                       
       Twenty percent of each registration fee will be donated to      
                 a non-profit, charitable organization.                
                                                                       
                                                                       
   Ĵ
    Basic Registration fee... 25.00     Laser printed guide... 10.00   
   
{{ ---------------, 1,8,0 }}

{{ Charityware?,    1,9,0 }}
  ........................................................................

                               Charityware
                          

       Twenty percent of each registration fee received for this
    package will be donated to charity. This pledge extends for the
    lifetime of this package and any subsequent versions.
       The concept of charityware is something that should be
    explored. This package is fundamentally a shareware package,
    with voluntary registration and trial use. No obligation on
    your part is implied with its use during a reasonable trial
    period. The basic trust embedded in the shareware concept can
    have a double benefit with the Charityware concept - not only
    have you done your part to promote shareware and shareware
    authors, you also have made a charitable contribution that
    counts.

       If you have any questions or comments on the Charityware
    concept, please contact us.  We have more information of
    interest available to shareware authors and corporate donors.

  ........................................................................
{{ Forming outline, 2,1,0 }}


     Forming an outline of the text

      Writing an outline is the essential first step to creating
   the reference. It will help to begin with the most general
   subjects, and narrow the subjects into sub-topics and further
   sub-topics. The outline itself should have no more than eight
   levels of sub-topics.

     A typical printed reference guide has a table of contents and
  body of text, and an optional index. An EZHelp text file contains
  the same elements. The items in the outline become topic definition
  lines in the text. The text can be entered first, and the EZhelp
  topic lines inserted later, or the topic lines can be entered first,
  and the text inserted between them.

     Topic lines include the name of the topic, the menu number,
  the order within the menu, and sub-topics to follow, if applicable.
  If there are no sub-topics to follow, the text following the topic
  line will be displayed.

{{ Creating topics, 2,2,0 }}

     Creating topics

      Working from your outline, you will create Topic Descriptions
   that will be displayed in the pop-up menus. The topic itself is
   a line of text that you will insert in your document, just above
   the point where the help text begins for that topic.

   The topic consists of:

   {{  topic name,    menu #,    menu order,     next menu  }}

        {{ - double brackets placed in the text will begin
         a topic definition. A topic definition is ended with
         another set of brackets }}.

        topic name - you may use up to fifteen characters for the
           topic, beginning with the first character at the left.

        menu # - this will identify the group of topics which
           are to be shown on the same menu. The outermost menu,
           or most general, should begin with 1 as a rule.


        menu order - this will specify the order of the topic
           among the other topics in the menu, from top to bottom.
           If you wish the menu topics to be sorted alphabetically,
           use 0 for the order number in each topic in the menu.

        next menu - if this topic leads to another topic
           sub-menu, use the sub-menu number. If this topic leads
           to the help text (the help text follows the topic in the
           document), use 0.


   The topic which defined the text you are now reading is:

    {{ Creating topics, 2,2,0 }}

      Note that each parameter in the topic should be followed with
   a comma. The spacing between the parameters is not critical,
   but only numbers should be used for the last three. Menu numbers
   may be 1 - 256, although the maximum number of menu layers is 16.
   The topic definition must contain a complete set of brackets,
   parameters, and commas, or unexpected results may occur.

                                                      
   Here is an example of a complete set of menu definitions for
   a help reference describing methods of transportation:

   {{ Land,          1,  1,  2     }}
   {{ Water,         1,  2,  3     }}   menu 1, 3 topics
   {{ Air,           1,  3,  4     }}   ____________________

   {{ Car,           2,  1,  0     }}
   {{ Bicycle,       2,  2,  0     }}   menu 2, 3 topics
   {{ Feet,          2,  3,  0     }}   ____________________

   {{ Speedboat,     3,  1,  0     }}
   {{ Yacht,         3,  2,  0     }}   menu 3, 3 topics
   {{ Jet ski,       3,  3,  0     }}   ____________________

   {{ Airlines,      4,  1,  0     }}
   {{ Hang glider,   4,  2,  0     }}   menu 4, 2 topics

   Note that menu in menu 1, topic "Land" defines a next menu, 2.
   Also in menu 1, topic "Water" defines next menu 3, and topic
   "Air" defines next menu 4.

{{ Entering text,   2,3,0 }}

     Entering text

      This is the basic layout of an EZhelp text file:
    Ŀ
     .beginning of file       
                              
        Comments (a)            (a) Optional comments may be placed
                                  at the beginning of the file, until
     Topic definition (b)         the first Topic definition.
                              
        Accompanying text (c)   (b) A topic definition line will
                                  always be followed with Accompanying
     Topic definition (b)         text unless another menu is to
                                   follow.
        Accompanying text (c) 
                                (c) The accompanying text will be
     Topic definition (b)         assumed to continue until the next
                                  topic definition is found, or the
        Accompanying text (c)     end of the file is reached.
                              
     .end of file             
    

    An EZhelp text file MUST conform to these three guidelines:

      Carriage return/line feed  (CR/LF):

          A carriage return/line feed pair must terminate every line in
       the file. What this means for text written with many commercial
       word processors (Microsoft Word, Wordperfect, others) is that it
       will likely be neccessary to press the return key at the end of
       each line, rather than letting the line wrap around.

          One way to tell if your word processor generates the CR/LF at
       the end of each line is to use the DOS "TYPE" command to view the
       text file on the screen. If the text is not indented as you would
       see it in the word processor, then you will need to press return
       at the end of each line.

          Avoid using the tab key in the text. Instead, indent using
       the space bar. All other text formatting commands used by your
       word processor should be avoided also. If it is possible, save
       the file with your word processor in unformatted mode.




      Line length:

          A line MUST be 74 characters or less. If the line is longer
       than 74 characters, unexpected results may occur. One common
       result is when the entire page shifts up by one line. Take care
       to follow this guideline.

      Recompiling:

          The reference text file must be recompiled after each time
       it is modified. If it is not recompiled, the help text displays
       will overlap, and the topic definition line may be visible on
       the screen.

{{ Files involved,  3,1,0 }}

     Files involved


     "myfile.txt",  when compiled, creates an index "myfile.hnx".

      Ŀ          Ŀ          Ŀ
                                                          
        Text    ----->    EZcomp.exe     ----->    Text   
        file    ----->    (compiler)     ----->    index  
                                                          
                          


         The index file name is created using the first part of the
      text file name and adding ".hnx" as the extension. The index
      file will be placed in the same subdirectory as the text file.

{{ Command line,    3,2,0 }}

     Command line - EZcomp.exe


      Usage: EZcomp MYFILE.TXT [-pu] [-ps]

         From the DOS prompt, enter the following command to compile
      a help text file:

      EZcomp MYFILE.TXT

      The compiler runs for a moment, creates the index "myfile.hnx"
      using the text file "myfile.txt", and returns to the DOS prompt.

      To compile the text and print an unsorted report of the topics,
      enter this command:

      EZcomp MYFILE.TXT -pu

      To print a sorted report of the topics, substitute "-ps" on the
      command line, or include both "-pu" and "-ps" for both reports.

{{ Reporting,       3,3,0 }}

     Reporting

      Shown below is a sample report generated by EZcomp.exe. The
   report is printed once in the natural order that topic definitions
   are found in the text, and once in the sorted order that is used
   by EZhelp.exe.

   ----------------------------------------------------------------------
   EZcomp v1.0    Reference Index report, unsorted: ezhelp.txt   Page  1
   ----------------------------------------------------------------------
   Menu    Menu                     Next   Line    Line
   number  order   Topic            menu   number  count   Offset  Size
   ------  -----  ---------------   -----  ------  ------  ------  ------
        1      1  What's EZhelp?                8      91     244    2753
        1      2  3 easy steps                 99      22    3025     462
        1      3  Writing text          2     121       4    3515      35
        1      4  Compiling text        3     125       4    3578      35
        1      5  Using EZhelp          4     129       4    3641      35
        1      6  Registering                 133      70    3704    2928
        1      7  ---------------             203       2    6660       4
        1      8  Charityware?                205      24    6692    1177

{{ Memory needed,   4,1,0 }}

     Memory needed

      EZhelp menus and help text windows allocate and release memory
   as they are used. The amount of memory required will depend on the
   size and levels of the menus. The program will have a pool of free
   memory to use in the size of (64k - size of ezhelp.exe). If there
   is no free memory to allocate, the program will display an error
   message and exit.

{{ Files involved,  4,2,0 }}

    Files involved

                              

     Ŀ          Ŀ
                      <-----    Text  
                      <-----    index 
       EZhelp.exe             
       (help text             
        driver)               Ŀ
                      <-----    Text  
                      <-----    file  
               


        EZhelp.exe uses the text file created with a word processor or
     text editor, and the index created from the text file with
     EZcomp.exe, to drive the displays of menus and help text. If the
     text file or text index is not found (as specified in the command
     line), EZhelp will display an error message and exit.

{{ Command line,    4,3,0 }}

     Command line - EZhelp.exe

   Usage: EZhelp MYFILE.TXT [-Mnnn -Jnnn -Bn -Snn -An -Dn -En -Ln ]

   MYFILE.TXT   The name of a text reference file to be used. Up to
                40 characters may be used for the full path and file
                name. The index MYFILE.HNX is assumed to reside in
                the same subdirectory.

   -Mnnn        The number of the menu to start at. The program will
                begin by displaying the Topic descriptions for that
                menu, as defined in MYFILE.TXT. All subsequent menus
                from the point of the startup menu will be accessible.
                If none is specified, the default is 1. The maximum
                menu value possible is 255.

   -Jnnn        The number of the topic in the start menu specified
                to display directly. If the -Jnn option is used, the
                menu will not be shown, and the help text for topic
                -Jnnn in menu -Mnnn will display. The maximum topic
                value possible is 255.


   -Bn          A number to define the menu and help text window
                borders. There are four different choices, as shown
                below. The default is 1.

                         Ŀ   ͸   ͻ   ķ
                          1     2     3     4 
                            ;   ͼ   Ľ

   -Snn         A number to define the size (in lines) of the help text
                window display. The minimum window size is 4, and the
                maximum is 23. The default is 23 lines.

   ---------------------------------------------------------------------
   Override options - the next four options will override the default
   data file. To set the option ON, use 1. To set it OFF, use 0.
   ---------------------------------------------------------------------

   -An          Automatic window sizing.

   -Dn          If this option is selected, the page number of the
                reference will display at the lower left of the screen.


   -En          This option will display error messages, should an
                error occur.

   -Ln          This option will display text at the top or bottom
                of the screen. 1 = TOP, 0 = BOTTOM, default = 1.

   Examples: 1) EZhelp MYFILE.TXT

                Start MYFILE.TXT at menu 1, use all defaults.

             2) EZhelp MYFILE.TXT -M4 -J7 -S15

                Jump directly to the display of topic 7 in menu 4. Set
                the text display window to 15 lines.

             3) EZhelp MYFILE.TXT  -E1 -A1 -L1

                Start MYFILE.TXT with error messages and automatic
                window sizing ON. Display text at the top of the screen.

   Note: The order of the specified options is not critical.
{{ Examples,        4,3,90 }}

   .... menu 90 is next ....

{{ Distribution,    4,5,0 }}

     Distribution

      Unregistered and registered users may distribute copies of this
   package in its complete form, including EZhelp.exe, EZcomp.exe,
   EZsetup.exe, EZhelp.txt and EZhelp.hnx, and user's manual. We
   encourage you to do so.

      Registered users may bundle EZhelp.exe with their own
   applications and distribute unlimited copies. If a registered
   user distributes EZhelp.exe, the file name may not be changed.

      For more information on registering EZhelp, select the
   "Registering" topic.
{{ Enhancments,     4,6,0 }}

     Enhancements
 
      Here is a list of enhancements that are being considered for
   the next version of EZhelp.

        Variable length topics
        Page breaks embedded within the help text
        Override options within the help text
        Hypertext links to other topics in the reference window
        Help text printing
        Single-line scrolling

      If you have any suggestions for enhancements to this program,
   send us a postcard or letter.

{{ ---------------, 4,7,0 }}

{{ Quick summary,   4,8,0 }}

     Quick summary of commands

      Topic definitions
      
      {{  topic name,    menu #,       menu order,     next menu  }}

          1 - 15 chars   all of the    0 for sort on   0 for display
          ended with a   topics in     topic name;     text to follow;
          comma          a menu have   Other - use     Other - display
                         the same #    order chosen    the next menu
      Compiling
      
      EZcomp MYFILE.TXT [-pu] [-ps]

      Note: Use your own help text file in place of MYFILE.TXT. Use
            the -pu and -ps options to print a report on the text file
            topics, unsorted or sorted.

      Running EZhelp
      
      Usage: EZhelp MYFILE.TXT [-Mnnn -Jnnn -Bn -Snn -An -Dn -En -Ln ]

{{ 1 more menu,    90,0,91 }}

   .... menu 91 is next ....

{{ 2 aaaaaaaaaaaa, 90,0,0  }}
{{ 3 aaaaaaaaaaaa, 90,0,0  }}
{{ 4 aaaaaaaaaaaa, 90,0,0  }}
{{ 5 aaaaaaaaaaaa, 90,0,0  }}
{{ 6 aaaaaaaaaaaa, 90,0,0  }}
{{ 7 aaaaaaaaaaaa, 90,0,0  }}
{{ 8 aaaaaaaaaaaa, 90,0,0  }}
{{ 9 aaaaaaaaaaaa, 90,0,0  }}
{{ 10 aaaaaaaaaaa, 90,0,0  }}
{{ 11 aaaaaaaaaaa, 90,0,0  }}
{{ 12 aaaaaaaaaaa, 90,0,0  }}
{{ 13 aaaaaaaaaaa, 90,0,0  }}
{{ 14 aaaaaaaaaaa, 90,0,0  }}
{{ 15 aaaaaaaaaaa, 90,0,0  }}
{{ 16 aaaaaaaaaaa, 90,0,0  }}
{{ 17 aaaaaaaaaaa, 90,0,0  }}
{{ 18 aaaaaaaaaaa, 90,0,0  }}
{{ 19 aaaaaaaaaaa, 90,0,0  }}
{{ 20 aaaaaaaaaaa, 90,0,0  }}
{{ 21 aaaaaaaaaaa, 90,0,0  }}
{{ 22 aaaaaaaaaaa, 90,0,0  }}
{{ 23 aaaaaaaaaaa, 90,0,0  }}
{{ 24 aaaaaaaaaaa, 90,0,0  }}
{{ 25 aaaaaaaaaaa, 90,0,0  }}
{{ 26 aaaaaaaaaaa, 90,0,0  }}
{{ 27 aaaaaaaaaaa, 90,0,0  }}
{{ 28 aaaaaaaaaaa, 90,0,0  }}
{{ 29 aaaaaaaaaaa, 90,0,0  }}
{{ 30 aaaaaaaaaaa, 90,0,0  }}
{{ 31 aaaaaaaaaaa, 90,0,0  }}
{{ 32 aaaaaaaaaaa, 90,0,0  }}
{{ 33 aaaaaaaaaaa, 90,0,0  }}
{{ 34 aaaaaaaaaaa, 90,0,0  }}
{{ 35 aaaaaaaaaaa, 90,0,0  }}
{{ 36 aaaaaaaaaaa, 90,0,0  }}
{{ 37 aaaaaaaaaaa, 90,0,0  }}
{{ 38 aaaaaaaaaaa, 90,0,0  }}
{{ 39 aaaaaaaaaaa, 90,0,0  }}
{{ 40 aaaaaaaaaaa, 90,0,0  }}
{{ 41 aaaaaaaaaaa, 90,0,0  }}
{{ 42 aaaaaaaaaaa, 90,0,0  }}
{{ 43 aaaaaaaaaaa, 90,0,0  }}
{{ 44 aaaaaaaaaaa, 90,0,0  }}
{{ 45 aaaaaaaaaaa, 90,0,0  }}
{{ 46 aaaaaaaaaaa, 90,0,0  }}
{{ 47 aaaaaaaaaaa, 90,0,0  }}
{{ 48 aaaaaaaaaaa, 90,0,0  }}
{{ 49 aaaaaaaaaaa, 90,0,0  }}
{{ 50 aaaaaaaaaaa, 90,0,0  }}
{{ 51 aaaaaaaaaaa, 90,0,0  }}
{{ 52 aaaaaaaaaaa, 90,0,0  }}
{{ 53 aaaaaaaaaaa, 90,0,0  }}
{{ 54 aaaaaaaaaaa, 90,0,0  }}
{{ 55 aaaaaaaaaaa, 90,0,0  }}
{{ 56 aaaaaaaaaaa, 90,0,0  }}
{{ 57 aaaaaaaaaaa, 90,0,0  }}
{{ 58 aaaaaaaaaaa, 90,0,0  }}
{{ 59 aaaaaaaaaaa, 90,0,0  }}
{{ 60 aaaaaaaaaaa, 90,0,0  }}
{{ 61 aaaaaaaaaaa, 90,0,0  }}
{{ 62 aaaaaaaaaaa, 90,0,0  }}
{{ 63 aaaaaaaaaaa, 90,0,0  }}
{{ 64 aaaaaaaaaaa, 90,0,0  }}
{{ 65 aaaaaaaaaaa, 90,0,0  }}
{{ 66 aaaaaaaaaaa, 90,0,0  }}
{{ 67 aaaaaaaaaaa, 90,0,0  }}
{{ 68 aaaaaaaaaaa, 90,0,0  }}
{{ 69 aaaaaaaaaaa, 90,0,0  }}




{{ 1 more menu,    91,0,92 }}

   .... menu 92 is next ....

{{ 2 bbbbbbbbbbbb, 91,0,0  }}
{{ 3 bbbbbbbbbbbb, 91,0,0  }}
{{ 4 bbbbbbbbbbbb, 91,0,0  }}
{{ 5 bbbbbbbbbbbb, 91,0,0  }}
{{ 6 bbbbbbbbbbbb, 91,0,0  }}
{{ 7 bbbbbbbbbbbb, 91,0,0  }}

{{ 1 cccccccccccc, 92,0,0  }}
{{ 2 cccccccccccc, 92,0,0  }}
{{ 3 cccccccccccc, 92,0,0  }}
{{ 4 cccccccccccc, 92,0,0  }}
{{ 5 cccccccccccc, 92,0,0  }}
{{ 6 cccccccccccc, 92,0,0  }}
{{ 7 cccccccccccc, 92,0,0  }}
{{ 8 cccccccccccc, 92,0,0  }}
{{ 9 cccccccccccc, 92,0,0  }}
{{ 10 ccccccccccc, 92,0,0  }}
{{ 11 ccccccccccc, 92,0,0  }}
{{ 12 ccccccccccc, 92,0,0  }}
{{ 13 ccccccccccc, 92,0,0  }}
{{ 14 ccccccccccc, 92,0,0  }}
{{ 15 ccccccccccc, 92,0,0  }}
{{ 16 ccccccccccc, 92,0,0  }}
{{ 17 ccccccccccc, 92,0,0  }}
{{ 18 ccccccccccc, 92,0,0  }}
{{ 19 ccccccccccc, 92,0,0  }}
{{ 20 ccccccccccc, 92,0,0  }}
{{ 21 ccccccccccc, 92,0,0  }}
{{ 22 ccccccccccc, 92,0,0  }}
{{ 23 ccccccccccc, 92,0,0  }}
{{ 24 ccccccccccc, 92,0,0  }}
{{ 25 ccccccccccc, 92,0,0  }}
{{ 26 ccccccccccc, 92,0,0  }}
{{ 27 ccccccccccc, 92,0,0  }}
{{ 28 ccccccccccc, 92,0,0  }}
{{ 29 ccccccccccc, 92,0,0  }}
{{ 30 ccccccccccc, 92,0,0  }}
{{ 31 ccccccccccc, 92,0,0  }}
{{ 32 ccccccccccc, 92,0,0  }}
{{ 33 ccccccccccc, 92,0,0  }}
{{ 34 ccccccccccc, 92,0,0  }}
{{ 35 ccccccccccc, 92,0,0  }}

