home *** CD-ROM | disk | FTP | other *** search
/ Shareware Overload / ShartewareOverload.cdr / wp / ezhelp.zip / USERS.DOC < prev   
Text File  |  1991-03-31  |  42KB  |  1,029 lines

  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.  
  16.  
  17.  
  18.  
  19.  
  20.  
  21.  
  22.                               EZhelp Reference
  23.  
  24.                                 version 1.4
  25.  
  26.                          A Shareware reference tool
  27.  
  28.                (C) Copyright Brain Child Systems, 1990-1991
  29.  
  30.                             All rights reserved
  31.  
  32.  
  33.  
  34.    Table of contents - EZhelp Reference
  35.  
  36.  
  37.         I.   Introduction to EZhelp . . . . . . . . . . .  1
  38.              A. What's EZhelp?  . . . . . . . . . . . . .  1
  39.              B. EZhelp features . . . . . . . . . . . . .  2
  40.              C. Four easy steps . . . . . . . . . . . . .  3
  41.              D. Defining reference use  . . . . . . . . .  3
  42.  
  43.         II.  Writing text . . . . . . . . . . . . . . . .  3
  44.              A. Forming an outline  . . . . . . . . . . .  3
  45.                 1. Example outlines . . . . . . . . . . .  4
  46.              B. Creating topics . . . . . . . . . . . . .  5
  47.                 1. Topic Descriptions . . . . . . . . . .  5
  48.                 2. Menu Groups  . . . . . . . . . . . . .  5
  49.                 3. Example reference  . . . . . . . . . .  6
  50.              C. Entering reference text . . . . . . . . .  8
  51.                 1. Reference file layout  . . . . . . . .  8
  52.                 2. Imbedded commands  . . . . . . . . . .  8
  53.                 3. Guidelines . . . . . . . . . . . . . .  9
  54.  
  55.         III. Compiling text . . . . . . . . . . . . . . . 10
  56.              A. Command line  . . . . . . . . . . . . . . 10
  57.              B. Reporting . . . . . . . . . . . . . . . . 10
  58.              C. Compiler error messages . . . . . . . . . 11
  59.  
  60.         IV.  Using EZhelp . . . . . . . . . . . . . . . . 11
  61.              A. Memory needed . . . . . . . . . . . . . . 11
  62.              B. Starting from other applications  . . . . 12
  63.              C. Command line  . . . . . . . . . . . . . . 12
  64.                 1. Examples . . . . . . . . . . . . . . . 13
  65.                 3. Runtime error messages . . . . . . . . 13
  66.                 4. Directory searching  . . . . . . . . . 14
  67.              D. Using EZsetup.exe . . . . . . . . . . . . 14
  68.              E. Distribution  . . . . . . . . . . . . . . 15
  69.              F. Registering . . . . . . . . . . . . . . . 15
  70.              G. Enhancements  . . . . . . . . . . . . . . 15
  71.              H. Quick summary . . . . . . . . . . . . . . 16
  72.  
  73.         Appendix A: Installing EZhelp Reference
  74.                                                                Page  1
  75.  
  76. I. Introduction to EZhelp
  77.  
  78.   A. What's EZhelp?
  79.  
  80.      EZhelp Reference is a set of tools to create and display a menu-
  81.   driven text reference. Virtually any information kept in a text
  82.   file (such as letters, users's guide files, office procedures) can
  83.   be turned into an EZhelp Reference file in a matter of minutes.
  84.   EZhelp Reference is easy enough for a novice to use productively,
  85.   but it also has features that programmers can appreciate, for use
  86.   with their own programs.
  87.  
  88.      This user's documentation is also organized into an EZhelp text
  89.   file, and you can see how the program works by typing "EZ" at the
  90.   DOS prompt to begin.
  91.  
  92.   EZhelp consists of three programs:
  93.  
  94.    EZcomp.EXE     -  A text compiler program that creates
  95.                   an index on help reference files you have
  96.                   created. This index file describes where topics
  97.                   begin and end within the text.
  98.  
  99.    EZhelp.EXE     -  The program that uses the help file and
  100.                   the index created with the compiler to drive
  101.                   the windows and text display.
  102.  
  103.    EZsetup.EXE -  A utility program that creates a default options
  104.                   file for use by EZhelp at runtime.
  105.  
  106.     You will need a text editor or word processor to create your text
  107.     files with. There are a few issues to be aware of when using a word
  108.     processor. For more information, check the section on Entering Text
  109.     on page 9. You will be more successful with this package if you
  110.     follow the hints on organizing your topics. More information can
  111.     be found in the Forming Outline section on page 3.
  112.  
  113.  
  114.   _________________________________________________________
  115.   EZhelp Reference
  116.   (C) Copyright 1990-1991, Brain Child Systems.
  117.   All rights reserved.
  118.  
  119.  
  120.                                                                Page  2
  121.   B. EZhelp features
  122.  
  123.          *  Pop-up menus - EZhelp menus automatically position
  124.                on the screen, and anchor to previous menus. All
  125.                backgroung screen areas are saved and restored
  126.                when the menu or window is removed.
  127.  
  128.          *  Sizeable text window - You can specify the size of the
  129.                help text window, ranging from 4 lines to 23 lines,
  130.                or allow the window to be sized automatically to
  131.                adjust to the size (in lines) of the help text.
  132.  
  133.          *  Choice of colors  - You can use EZsetup to choose the
  134.                colors for EZhelp to use at runtime.
  135.  
  136.          *  Choice of line style - You can specify the border line
  137.                style for EZhelp to use at runtime.
  138.  
  139.          *  Start at any menu level - You can start EZhelp at any
  140.                menu level or menu group using a command line option.
  141.  
  142.          *  Jump directly to any help topic - You can jump directly
  143.                to the help text of any topic in any menu - skipping
  144.                the menu display.
  145.  
  146.          *  First letter auto selection - You can specify if menu
  147.                choices will be made automatically when the first
  148.                letter of a unique menu topic is pressed, or if
  149.                the Return key will be required to select the topic.
  150.  
  151.          *  Page numbers can be displayed at the bottom of the help
  152.                window, if there is more than on page of text.
  153.  
  154.          *  Help text window anchor - Help text can be anchored at
  155.                the top or bottom of the screen.
  156.  
  157.          *  Error messages - Error messages can optionally be
  158.                displayed. Status codes are returned to the calling
  159.                program.
  160.  
  161.          *  Configurable display strings - The text that appears
  162.                at the top of the help text window for the Escape,
  163.                Page up and Page down keys can be changed.
  164.  
  165.          *  Optional sorting of topics - You can easily organize
  166.                your menu topics in a predetermined order, or have
  167.                them sorted and displayed alphabetically.
  168.  
  169.          *  Reference report - A reference report is available as
  170.                a command-line option with EZcomp, the text compiler.
  171.                This report lists all menus, topics, and links between
  172.                menus. Line numbers are also shown in the report,
  173.                to aid you in locating topics in your help text file.
  174.                The compiler also reports any errors encountered
  175.                in the text file, such as a missing comma or bracket,
  176.                and give the line number where the error occurrs.
  177.  
  178.          *  Free program updates - All registered users will be
  179.                notified of updates, and can obtain one free update,
  180.                less shipping and media costs.
  181.                                                                Page  3
  182.  
  183.   C. Three easy steps
  184.  
  185.      There are four steps to creating your own menu-driven help
  186.   reference text. First, working from a broad outline, organized
  187.   like a table of contents or hierarchical chart, write out Topic
  188.   Descriptions associated with each item of help text, and insert
  189.   them into the reference file using a text editor or word processor.
  190.   Second, compile the reference file using EZcomp, which creates an
  191.   index file to be used with the text.
  192.      After the index has been created on the reference file, you
  193.   can test the menus and display of each topic using EZhelp, then
  194.   establish the colors to use with EZhelp with the EZsetup utility.
  195.  
  196.      If you already have specific text written (on disk), you should be
  197.   able to easily insert Topic Descriptions based on an existing table
  198.   of contents. This will serve as a complete reference of the entire
  199.   application or manual. The following section should be read
  200.   beforehand, to pinpoint the type of functions that EZhelp should
  201.   perform.
  202.  
  203.  
  204.  
  205.   D. Defining reference use
  206.  
  207.      Before beginning to write out the Topic Descriptions for use in
  208.   the reference file, you should give some thought to the type of
  209.   help the reference will be needed for. A few specific questions you
  210.   can ask are:
  211.  
  212.      1) Is the reference to be organized around existing user's
  213.         documentation, or should it conform more closely to the
  214.         application itself?
  215.  
  216.      2) Is the reference to be used for field-level help, where menus
  217.         do not display, and the help text displays directly?
  218.  
  219.      3) Do you prefer a single-level menu or multiple-level menus
  220.         leading to the topic?
  221.  
  222.  
  223.      These questions will have an impact on the relation between the
  224.   menu topics you create and the behavior of the menus when the program
  225.   is running. You can create menus to accomodate all of the above
  226.   needs, all within the same reference file.
  227.  
  228.  
  229. II. Writing text
  230.  
  231.   A. Forming an outline
  232.  
  233.      Writing an outline is the essential first step to creating
  234.   the reference. It helps to begin with the most general subjects,
  235.   and narrow the subjects into sub-topics and further sub-topics.
  236.   The outline itself should have no more than sixteen levels of
  237.   sub-topics.
  238.  
  239.      The outline will show the relationships of menus in your
  240.   reference. You should define your menus in terms of the type of
  241.   reference you want to create, whether it is to contain a complete
  242.   topic index with multiple menu layers, or just field-level help.
  243.                                                                Page  4
  244.  
  245.  
  246.   Following is a simple example of an outline for a reference file
  247.   example, with three levels of topics:
  248.  
  249.    Outline example 1:            As organized in an EZhelp
  250.    Methods of transportation     Reference file
  251.  
  252.  
  253.    I.   Land                     Land, Water, and Air will be
  254.                                  assigned menu number 1.
  255.       a. Car
  256.       b. Bicycle                 Car, Bicycle, and feet will
  257.       c. Feet                    be assigned menu number 2.
  258.  
  259.    II.  Water
  260.  
  261.       a. Speedboat               Speedboat, Yacht, and Jet ski
  262.       b. Yacht                   will be assigned menu
  263.       c. Jet Ski                 number 3.
  264.  
  265.    III. Air
  266.  
  267.       a. Airplanes               Airplanes and Hot air ballon
  268.                                  will be assigned menu
  269.          1. Prop plane           number 4.
  270.          2. Glider
  271.          3. Jet                  Prop plane, Glider, and Jet
  272.                                  will be assigned menu
  273.       b. Hot air baloon          number 5.
  274.  
  275.  
  276.      This outline example would be useful to create a reference modeled
  277.   after users documentation, or where the topic is too complex to cover
  278.   with one choice.
  279.  
  280.  
  281.  
  282.   Following is another example with the same topics, reorganized into
  283.   single-level menus.
  284.  
  285.     Outline example 2:               As organized in an EZhelp
  286.     Methods of transportation        Reference file
  287.  
  288.     a. Land                          The assignment of menu numbers
  289.     b. Water                         would be the same in this
  290.     c. Air                           example. The difference here
  291.                                      is that all menus are single
  292.     a. Car                           level, and the associated
  293.     b. Bicycle                       reference would display after
  294.     c. Feet                          the topic is chosen.
  295.  
  296.     a. Speedboat                     This outline would be most
  297.     b. Yacht                         useful when a general
  298.     c. Jet Ski                       reference of a page or less
  299.                                      should be given on a topic.
  300.     a. Airplanes
  301.     b. Hot air baloon                This type of outline can
  302.                                      also be used to accomodate
  303.     a. Prop plane                    field-level help topics
  304.     b. Glider                        where the menu is not
  305.     c. Jet                           displayed.
  306.                                                                Page  5
  307.  
  308.      The next section, Creating Topics, shows how to create Topic
  309.   Descriptions from a general outline, and how you can create menu
  310.   groups of Topic Descriptions to use as complete references,
  311.   single-level menus, and field-level displays.
  312.  
  313.   B. Creating Topics
  314.  
  315.   Topic Descriptions
  316.  
  317.      The Topic Descriptions to be displayed in the pop-up menus can
  318.   be created from the outline. The topic itself is a line of
  319.   text that is inserted in your document, just above the point
  320.   where the help text begins for that topic.
  321.  
  322.   The topic consists of a topic name and three additional
  323.   parameters:
  324.  
  325.   {{  Topic Name,    Menu No.,    Menu Order,     Next Menu  }}
  326.  
  327.       * {{ - double brackets placed in the text will begin
  328.         a topic definition. A topic definition is ended with
  329.         another set of brackets }}.
  330.  
  331.       * Topic Name - you may use up to fifteen characters for the
  332.           topic, beginning with the first non-blank character
  333.           after the brackets.
  334.  
  335.       * Menu No. - this will identify the group of topics which
  336.           are to be shown on the same menu. The outermost menu,
  337.           or most general, should begin with 1 as a rule.
  338.  
  339.       * Menu Order - this will specify the order of the topic
  340.           among the other topics in the menu, from top to bottom.
  341.           If you wish the menu topics to be sorted alphabetically,
  342.           use 0 for the order number in each topic in the menu.
  343.           However, if 0 is used, it will not be possible to jump
  344.           directly to a topic from the command line using the
  345.           -J paramter.
  346.  
  347.       * Next Menu - if this topic leads to another topic
  348.           sub-menu, use the sub-menu number. If this topic leads
  349.           to the help text (the help text follows the topic in the
  350.           document), use 0.
  351.  
  352.  
  353.      Following this paragraph is a sample set of topic definitions
  354.   for a reference describing methods of transportation. Note that the
  355.   reference text for topics would be inserted after the topics where
  356.   the Next Menu parameter is equal to zero, but for clarity, the text
  357.   is omitted here.
  358.  
  359.   Menu Groups
  360.  
  361.      Menu groups allow you to duplicate topic names, or offer the same
  362.   topic in different ways. The examples in the section on Forming an
  363.   outline will be used here to create the Topic Descriptions for a
  364.   reference on Methods of Transportation.
  365.                                                                Page  6
  366.  
  367.   Example reference file: Transpor.txt
  368.   Subject: Methods of transportation
  369.  
  370.   EZhelp Topic Descriptions
  371.   for reference Transpor.txt
  372.  
  373.    {{ Land,             1, 1, 2  }}
  374.    {{ Water,            1, 2, 3  }}    menu 1, 3 topics
  375.    {{ Air,              1, 3, 4  }} ____________________
  376.  
  377.    {{ Car,              2, 1, 0  }}
  378.    {{ Bicycle,          2, 2, 0  }}    menu 2, 3 topics
  379.    {{ Feet,             2, 3, 0  }} ____________________
  380.  
  381.    {{ Speedboat,        3, 1, 0  }}
  382.    {{ Yacht,            3, 2, 0  }}    menu 3, 3 topics
  383.    {{ Jet ski,          3, 3, 0  }} ____________________
  384.  
  385.    {{ Airplanes,        4, 1, 5  }}    menu 4, 2 topics
  386.    {{ Hot air baloon,   4, 2, 0  }} ____________________
  387.  
  388.    {{ Prop plane,       5, 1, 0  }}
  389.    {{ Glider,           5, 2, 0  }}    menu 5, 3 topics
  390.    {{ Jet plane,        5, 3, 0  }} ____________________
  391.  
  392.  
  393.   In menu number 1, topic "Land" defines the following menu, number 2.
  394.   Also in menu 1, topic "Water" defines next menu 3, and topic
  395.   "Air" defines next menu 4. Topic "Airlines" defines a third menu
  396.   level, 5.
  397.  
  398.      This group of Topic Descriptions above fits the hierarchical
  399.   type of outline, which most closely matches user's documentation.
  400.   But suppose that this structure is not sufficient at all times. At
  401.   certain places in your application, you want the topic "Land" to lead
  402.   directly to a reference text window, instead of a sub-menu with Land
  403.   topics.
  404.  
  405.      All you would need to do is add another menu, perhaps identical
  406.   to menu 1 defined above, but give it another menu number:
  407.  
  408.    {{ Land,             10,   1, 0  }}
  409.    {{ Water,            10,   2, 0  }}    menu 10, 3 topics
  410.    {{ Air,              10,   3, 0  }} ____________________
  411.  
  412.      You could place these definitions anyplace in the reference file,
  413.   and follow the topic "Land" with the associated help text. The
  414.   example above would allow "Water" and "Land" to lead directly
  415.   to help text rather than another menu, because the Next Menu
  416.   parameter is zero.
  417.  
  418.                                                                Page  7
  419.  
  420.  
  421.      Later, when you want to access the topic "Land" in menu 1 or menu
  422.   10, you can start EZhelp and specify the startup menu number. If topic
  423.   "Land" in menu 10 corresponds to a field level help item, that is,
  424.   you don't want a menu to show, but to go directly to the display of
  425.   the reference text, you can call EZhelp specifying the startup menu
  426.   number and the topic to jump directly into.
  427.  
  428.   * Starting at the default menu, number 1
  429.  
  430.      EZhelp Transpor.txt
  431.  
  432.   This will start EZhelp with Transpor.txt, which contains the above
  433.   Topic Descriptions, and begin at the default menu number, 1. In this
  434.   example, the menus and reference text of menu 10 will not be
  435.   accessible.
  436.  
  437.   * Starting at a specific menu number
  438.  
  439.      EZhelp Transpor.txt -M10
  440.  
  441.   This will start EZhelp at menu 10, showing all three topics of the
  442.   menu. All other menus would not be accessible.
  443.  
  444.   * Jumping directly to a topic
  445.  
  446.      EZhelp Transpor.txt -M10 -J1 -S4
  447.  
  448.   This will start EZhelp at menu 10, but instead of showing the
  449.   other topic of menu 10, the reference text below topic "Land" would
  450.   display directly, in a text window of 4 lines.
  451.  
  452.   NOTE: If you choose to enter zero for each Menu Order parameter
  453.   in the Topic Description line, you cannot use the -J option to
  454.   jump directly to a topic.
  455.  
  456.   _________________________________________________________
  457.   If you like, you can start the above examples using the DOS batch
  458.   files EX1.BAT, EX2.BAT, and EX3.BAT supplied with the diskette.
  459.   The full set of EZhelp command-line options are described in more
  460.   detail on page 13.
  461.  
  462.      As the above examples show, you can create isolated menus within
  463.   the reference text for different purposes. The next section,
  464.   Entering text, shows the general layout of the reference file,
  465.   including Topic Descriptions.
  466.  
  467.  
  468.                                                                Page  8
  469.  
  470. C. Entering text
  471.  
  472.   Reference file layout
  473.   ----------------------------------
  474.     This is the basic layout of an EZhelp Reference file:
  475.  
  476.     +---------------------+
  477.     |.beginning of file   |
  478.     |                     |
  479.     |Comments (a)         |  (a) Optional comments may be placed
  480.     |                     |    at the beginning of the file, until
  481.     |Topic definition (b) |    the first Topic definition.
  482.     |                     |
  483.     |Accompanying text (c)|  (b) A topic definition line should
  484.     |                     |    always be followed with Accompanying
  485.     |Topic definition (b) |    text unless another menu is to
  486.     |                     |    follow.
  487.     |Accompanying text (c)|
  488.     |                     |  (c) The accompanying text will be
  489.     |Topic definition (b) |    assumed to continue until the next
  490.     |                     |    topic definition is found, or the
  491.     |Accompanying text (c)|    end of the file is reached.
  492.     |                     |
  493.     |.end of file         |
  494.     +---------------------+
  495.  
  496.      It helps to use the first part of the reference file for comments,
  497.   before the first topic definition. Take a moment to examine
  498.   Transpor.txt with your text editor. At the top, you'll see a table
  499.   where information on the topics and menus is kept. This is useful as
  500.   an overview of the reference text once you have begun to write.
  501.  
  502.   Imbedded commands
  503.  
  504.      You can imbed commands in your reference to control the display.
  505.   The commands must begin on the 1st column of a line.
  506.  
  507.   Command     Action
  508.   --------    ----------------------------------------------
  509.      ++       Forces the page to break at that point.
  510.  
  511.   Additional comments
  512.  
  513.      You can create additional comment sections in your reference file
  514.   by defining a Topic Description with a menu number that is never
  515.   used. For example, you could designate 199 to be a menu number that
  516.   indicates a comment section:
  517.  
  518.     {{ dummy menu, 199, 0, 0 }}
  519.  
  520.   All comments after this Topic Description and before another Topic
  521.   Description would not be displayed (assuming that you never start
  522.   EZhelp with menu 199 as the startup menu).
  523.  
  524.                                                                Page  9
  525.   Guidelines for Topic
  526.   Descriptions and reference text files
  527.  
  528.     An EZhelp Reference file MUST conform to these guidelines:
  529.  
  530.     1) Carriage return/line feed  (CR/LF):
  531.  
  532.           A carriage return/line feed pair must terminate every line in
  533.        the file. What this means for text written with many commercial
  534.        word processors (Microsoft Word, Wordperfect, others) is that it
  535.        may be neccessary to press the return key at the end of each line,
  536.        rather than letting the line wrap around.
  537.           One way to tell if your word processor generates the CR/LF at
  538.        the end of each line is to use the DOS "TYPE" command to view the
  539.        text file on the screen. If the text is not indented as you would
  540.        see it in the word processor, then you will need to press return
  541.        at the end of each line.
  542.  
  543.           Avoid using the tab key in the text. Instead, indent using
  544.        the space bar. All text formatting commands used by your
  545.        word processor (bold, underline, etc.) should be avoided also,
  546.        if your word processor cannot save a file unformatted. The
  547.        finished reference that you want to use as an EZhelp file must
  548.        be saved unformatted.
  549.  
  550.     2) Completeness of Topic Descriptions
  551.  
  552.           Each Topic Description must have a complete set of elements.
  553.        This includes an opening set of brackets, a Topic Name and
  554.        comma, Menu Number and comma, Menu Order and comma,
  555.        Next Menu, and a closing set of brackets. An incomplete Topic
  556.        description will be reported by the compiler.
  557.  
  558.     3) Line length:
  559.  
  560.           A line must be 76 characters or less. If the line is longer
  561.        than 76 characters, unexpected results may occur. One common
  562.        result is when the entire page shifts up by one line. Take care
  563.        to follow this guideline.
  564.  
  565.     4) Recompiling:
  566.  
  567.           The reference file must be recompiled after each time
  568.        it is modified. If it is not recompiled, the help text displays
  569.        will overlap, and the topic definition line may be visible on
  570.        the screen.
  571.  
  572.     5) File size
  573.  
  574.           The reference file may be as large as the unused memory on
  575.        your system, up to 640k. This should not be a limitation, but
  576.        if you need to know how much memory you have available, run
  577.        the DOS Chkdsk command.
  578.  
  579.     6) Number of menus and topics
  580.  
  581.           You may create up to 255 menus, with a maximum of 100 topics
  582.        in each menu. The maximum number of menu levels is 16.
  583.  
  584.                                                                Page 10
  585. III. Compiling text
  586.  
  587.      An index file is created for each reference file before it used
  588.   with EZhelp. The index file keeps information on the topics and menus,
  589.   and uses it to find the topic's text in the reference file. The
  590.   index file name is automatically created using the first part of the
  591.   reference file name and adding ".hnx" as the extension. The index file
  592.   will be placed in the same subdirectory as the text file.
  593.  
  594.      "myfile.txt",  when compiled, creates an index "myfile.hnx".
  595.  
  596.       +--------+        +---------------+       +---------+
  597.       |        |        |               |       |         |
  598.       |  Text  |----->  |  EZcomp.exe   |-----> |  Text   |
  599.       |  file  |----->  |  (compiler)   |-----> |  index  |
  600.       |        |        |               |       |         |
  601.       +--------+        +---------------+       +---------+
  602.  
  603.  
  604.   A. Command line
  605.  
  606.  
  607.   EZcomp MYFILE.TXT [-pu] [-ps]
  608.  
  609.  
  610.        From the DOS prompt, enter the following command to compile
  611.     a help text file:
  612.  
  613.     EZcomp MYFILE.TXT
  614.  
  615.     The compiler runs for a moment, creates the index "myfile.hnx"
  616.     using the text file "myfile.txt", and returns to the DOS prompt.
  617.  
  618.     To compile the text and print an unsorted report of the topics,
  619.     enter this command:
  620.  
  621.     EZcomp MYFILE.TXT -pu
  622.  
  623.     To print a sorted report of the topics, substitute "-ps" on the
  624.     command line, or include both "-pu" and "-ps" for both reports.
  625.  
  626.  
  627.  
  628.   B. Reporting
  629.  
  630.  
  631.   Topic report
  632.  
  633.      Shown below is a portion of the topic report generated by
  634.   EZcomp.exe. The reference file used was EZhelp.txt. The report
  635.   can be printed sorted or unsorted using the command line options.
  636.   If you give each topic a number in the Menu Order parameter of the
  637.   Topic Description line, the report will be identical whether sorted
  638.   or unsorted.
  639.                                                                Page 11
  640.  
  641.    ----------------------------------------------------------------------
  642.    EZcomp v1.4   Reference Index report, unsorted: transpor.txt   Page  1
  643.    ----------------------------------------------------------------------
  644.  
  645.    Menu    Menu                     Next  Line    Line
  646.    number  order   Topic            menu  number  count   Offset  Size
  647.    ------  ------  ---------------  ----  ------  ------  ------  ------
  648.         1       1  Land                2      35       4    1117      63
  649.         1       2  Water               3      39       4    1214      63
  650.         1       3  Air                 4      43       4    1311      63
  651.  
  652.         2       1  Car                        47       4    1408      53
  653.         2       2  Bicycle                    51       4    1495      57
  654.         2       3  Feet                       55       4    1586      45
  655.       .
  656.       .
  657.       .
  658.  
  659.   Items in the report
  660.  
  661.      Menu number, Menu order, Next menu, Topic - These are the same as
  662.         the parameters entered in the Topic Description. Note that if
  663.         zero is entered as the Next Menu parameter, blanks will show on
  664.         the report.
  665.      Line number - This is the line in the reference file where the topic
  666.         is found.
  667.      Line count - This is the total number of lines of the reference text
  668.         of the topic, including the Topic Description line.
  669.      Offset - This is the offset in bytes, from the beginning of the
  670.         file, where the Topic Description begins.
  671.      Size - This is the total number of bytes of the reference text of
  672.         the topic, including the Topic Description line.
  673.  
  674.  
  675.   Compiler error messages
  676.  
  677.      EZcomp reports any errors it finds in the reference text,
  678.   along with the line number where it was found. The possible
  679.   errors are:
  680.  
  681.     incomplete description on line nnn - The topic description was
  682.       not followed by a comma.
  683.     new line encountered on line - A topic description was not
  684.       terminated with a set of brackets.
  685.     number expected on line - Too many or too few items were found
  686.       in the topic description, or one of the items was not a
  687.       number as expected.
  688.  
  689.  
  690. IV. Using EZhelp
  691.  
  692.   Memory needed
  693.  
  694.      EZhelp menus and help text windows allocate and release memory
  695.   as they are used. The amount of memory required will depend on the
  696.   size and levels of the menus. The .EXE version of the program will
  697.   use up to 64k. If there is no free memory to allocate, the program
  698.   will exit. If the error message flag (see Command line below) is
  699.   set on, an error message will display.
  700.                                                                Page 12
  701.   Starting EZhelp from within other applications
  702.  
  703.      You can start EZhelp from within your applications and arrange the
  704.   menus and help to complement your program's operation. If you are a
  705.   C user, you can use the sample program, spawnhlp.c, to link into your
  706.   programs and start EZhelp. If you are using dBASE, you can use the Run
  707.   command. If your language of choice has a facility to load another DOS
  708.   program while your program is running, then you can use EZhelp.
  709.  
  710.      All screens are restored to their original state before EZhelp
  711.   exits, and EZhelp will return error codes to your program to indicate
  712.   if it terminated abnormally. This design keeps your program in
  713.   control.
  714.  
  715.   Command line
  716.  
  717.     EZhelp MYFILE.TXT [-Mnnn -Jnnn -Bn -Snn -Tmenu_title
  718.                        -An -Dn -En -Ln ]
  719.  
  720.     where...
  721.     MYFILE.TXT  The name of a text reference file to be used. Up to
  722.                 40 characters may be used for the full path and file
  723.                 name. The index MYFILE.HNX is assumed to reside in
  724.                 the same subdirectory.
  725.  
  726.    MYFILE.TXT   The name of a text reference file to be used. Up to
  727.                 40 characters may be used for the full path and file
  728.                 name. The index MYFILE.HNX is assumed to reside in
  729.                 the same subdirectory.
  730.  
  731.    -Mnnn        The number of the menu to start at. The program will
  732.                 begin by displaying the Topic descriptions for that
  733.                 menu, as defined in MYFILE.TXT. All subsequent menus
  734.                 from the point of the startup menu will be accessible.
  735.                 If none is specified, the default is 1. The maximum
  736.                 menu value possible is 255.
  737.  
  738.    -Jnnn        The number of the topic in the start menu specified
  739.                 to display directly. If the -Jnn option is used, the
  740.                 menu will not be shown, and the help text for topic
  741.                 -Jnnn in menu -Mnnn will display. The maximum topic
  742.                 value possible is 255.
  743.  
  744.    -Bn          A number to define the menu and help text window
  745.                 borders. There are four different choices, as shown
  746.                 below. The default is 1.
  747.  
  748.               ┌───┐          ╒═══╕          ╔═══╗          ╓───╖
  749.               │ 1 │          │ 2 │          ║ 3 ║          ║ 4 ║
  750.               └───┘          ╘═══╛          ╚═══╝          ╙───╜
  751.  
  752.               single line    single on      double line    double on
  753.                              sides, double                 sides,
  754.                              on top                        single on
  755.                                                            top
  756.                                                                Page 13
  757.  
  758.     -Tmenu_title This will allow EZhelp to use the specified string as
  759.                  the default for the startup menu. If two words are
  760.                  needed for the string, use the underbar character to
  761.                  separate them. The underbar will be replaced with a
  762.                  space at runtime.
  763.  
  764.     -Snn         A number to define the size (in lines) of the help text
  765.                  window display. The minimum window size is 4, and the
  766.                  maximum is 23. The default is 23 lines.
  767.  
  768.    ---------------------------------------------------------------------
  769.    Override options - the next four options will override the default
  770.    data file. To set the option ON, use 1. To set it OFF, use 0.
  771.    ---------------------------------------------------------------------
  772.  
  773.    -An          Automatic window sizing.
  774.  
  775.    -Dn          If this option is selected, the page number of the
  776.                 reference will display at the lower left of the screen.
  777.  
  778.    -En          This option will display error messages, should an
  779.                 error occur.
  780.  
  781.    -Ln          Anchor the reference at one of nine screen areas:
  782.                                             ┌───┬───┬───┐
  783.                                             │ 1 │ 2 │ 3 │
  784.                                             ├───┼───┼───┤
  785.                    The default is 5,        │ 4 │ 5 │ 6 │
  786.                    the center.              ├───┼───┼───┤
  787.                                             │ 7 │ 8 │ 9 │
  788.                                             └───┴───┴───┘
  789.  
  790.    -On          Overlap windows? Default = OFF
  791.  
  792.    Examples: 1) EZhelp MYFILE.TXT
  793.  
  794.                 Start MYFILE.TXT at menu 1, use all defaults.
  795.  
  796.              2) EZhelp MYFILE.TXT -M4 -J7 -S15
  797.  
  798.                 Jump directly to the display of topic 7 in menu 4. Set
  799.                 the text display window to 15 lines.
  800.  
  801.              3) EZhelp MYFILE.TXT  -E1 -A1 -L1
  802.  
  803.                 Start MYFILE.TXT with error messages and automatic
  804.                 window sizing ON. Display text at the top of the screen.
  805.  
  806.      Note: The order of the options specified is not critical.
  807.  
  808.   EZhelp runtime error messages
  809.  
  810.      There are four error conditions that can be encountered when
  811.      EZhelp is running. The following list describes each:
  812.  
  813.      * EZhelp... help file not found.    (return code 53)
  814.  
  815.           The help reference file was not located in the path specified
  816.        in the filename parameter. If no path is specified, the file is
  817.        assumed to reside in the same directory as EZhelp.exe.
  818.                                                                 Page 14
  819.      * EZhelp... index file not found.   (return code 54)
  820.  
  821.           The index file was not located in the same directory as the
  822.        help reference file.
  823.  
  824.      * EZhelp... insufficient memory.    (return code 50)
  825.  
  826.           EZhelp could not allocate the memory required for the index,
  827.        menu or help window.
  828.  
  829.      * EZhelp... topic not found.        (return code 51)
  830.  
  831.           EZhelp could not find the chosen topic in the reference file.
  832.        If EZhelp was started with the -J parameter, perhaps the number
  833.        was incorrect. If this error occurs without the -J parameter,
  834.        the Next Menu specified in the Topic Description chosen may be
  835.        incorrect, or the Next Menu may not exist in the reference file.
  836.  
  837.  
  838.   Directory Searching
  839.  
  840.      EZhelp looks for 3 files at runtime - the text file specified in
  841.   the command line, the index to go with the text file, and a startup
  842.   data file. The index file must be found in the same directory as the
  843.   text file.
  844.      The data file (EZhelp.dat) is located by first searching the
  845.   directory where the help and index files are located. If it is not
  846.   found, the directory containing EZhelp.exe is searched. If it is
  847.   not found there either, EZhelp will use the basic set of options:
  848.  
  849.     Title color:  black on white
  850.     window color: white on black
  851.     hilite color: black on white
  852.     letter color: bright white
  853.     border color: bright white
  854.  
  855.     First letter selection:  ON
  856.     Automatic window sizing: ON
  857.     Page number display:     ON
  858.     Error message display:   OFF
  859.  
  860.     Display strings:         PgUp, PgDn, Esc=Exit
  861.     Help text anchor:        Bottom
  862.  
  863.  
  864.   D. Using EZsetup.exe
  865.  
  866.      A utility program, EZsetup.exe, is included with this program
  867.   to allows you to establish run-time options for use with EZhelp.
  868.  
  869.      To start at the DOS prompt, type EZSETUP. The function key
  870.   commands for use with the 2 screens of the program will display
  871.   at the top of the screen. Press F1 to view the help text
  872.   written specifically for EZsetup. The help available on the first
  873.   screen is a menu level help several topics. The help on screen
  874.   two is field level, dependent on the entry field where the cursor
  875.   is located.
  876.  
  877.  
  878.                                                                Page 15
  879.   E. Distribution
  880.  
  881.      Unregistered and registered users may distribute copies of this
  882.   Shareware package for the trial use of others, and we encourage you
  883.   to do so.
  884.  
  885.      A reasonable "disk fee" or postage fee may be charged for the
  886.   distribution of this package, but that fee is not to exceed US $6.00
  887.   under any circumstances without the written consent of Brain Child
  888.   Systems.
  889.  
  890.      EZhelp.exe: Registered users may bundle EZhelp.exe with their own
  891.   applications and distribute unlimited copies. If a registered user
  892.   distributes EZhelp.exe, the file name may not be changed.
  893.      EZsetup.exe: Registered users may also distribute EZsetup for use
  894.   with their systems without further obligation. This utility can
  895.   be called from other applications to give the user control over the
  896.   EZhelp options.
  897.  
  898.  
  899.   F. Registering
  900.  
  901.      EZhelp is a shareware product, and may be used for a reasonable
  902.   trial period free of charge. What defines a reasonable trial period?
  903.   You may evaluate the package for 30 days, which should be enough
  904.   time to decide if you would like to continue using it.
  905.  
  906.      The basic registration fee is $25. This fee includes a diskette
  907.   with all EZhelp executable files, a user's guide on the diskette,
  908.   and one free update.
  909.  
  910.      To print out a copy of the registration form, use this DOS command:
  911.  
  912.      TYPE ORDER.DOC > PRN
  913.  
  914.   Disclaimer
  915.  
  916.   This program is sold without any express or implied warranties
  917.   whatsoever. Because of the diversity of conditions and hardware under
  918.   which this program may be used, no warranty of fitness for a
  919.   particular purpose is offered. The user is advised to test the
  920.   program thoroughly before relying on it. The user must assume the
  921.   entire risk of using the program. Any liability of seller or author
  922.   will be limited exclusively to product replacement or refund of the
  923.   purchase price.
  924.  
  925.   G. Enhancements
  926.  
  927.      Here is a list of enhancements that are being considered for
  928.   the next version of EZhelp. If you would like to see a particular
  929.   feature not listed here, send a postcard with an explanation.
  930.  
  931.      Additional imbedded commands
  932.      Hypertext links to other topics
  933.      Help text printing
  934.      Additional text in menu window
  935.  
  936.                                                                Page 16
  937.   H. Quick summary
  938.  
  939.  
  940.   Topic definitions
  941.  
  942.    {{  Topic Name,   Menu No.,      Menu Order,       Next Menu  }}
  943.  
  944.       1 - 15 chars   all of the     0 for sort on     0 for display
  945.       ended with a   topics in      topic name;       text to follow;
  946.       comma          a menu have    Other - use       Other - display
  947.                      the same #     order chosen      the next menu
  948.  
  949.  
  950.   Compiling text
  951.  
  952.      EZcomp MYFILE.TXT [-pu] [-ps]
  953.  
  954.      Note: Use your own help text file in place of MYFILE.TXT. Use
  955.            the -pu and -ps options to print a report on the text file
  956.            topics, unsorted or sorted.
  957.  
  958.  
  959.   Running EZhelp
  960.  
  961.      EZhelp MYFILE.TXT [-Mnnn -Jnnn -Bn -Snn -Tmenu_title
  962.                         -An -Dn -En -Ln -On]
  963.  
  964.      -Mnnn   menu number
  965.      -Jnnn   jump to topic in menu
  966.      -Bn     border style (1 - 4)
  967.      -Snn    window size
  968.      -An     first keystroke auto selection  }  1 = ON,  0 = OFF
  969.      -Dn     display page numbers            }    "        "
  970.      -En     turn on error messages          }    "        "
  971.      -Ln     anchor text at screen quadrant  }  1 - 9
  972.      -On     overlap windows                 }  1 = ON,  0 = OFF
  973.  
  974.                               Appendix A
  975.                      Installing EZhelp Reference
  976.  
  977.  
  978.      To install EZhelp Reference onto another drive, enter the
  979.      following commands at the DOS prompt.
  980.  
  981.       First, set the DOS prompt to the drive where the EZhelp
  982.       files reside.
  983.  
  984.       A:                         (get the source drive prompt)
  985.  
  986.       Then, start the installation batch, giving the source drive
  987.       and the drive where the files are to be installed.
  988.  
  989.       INSTALL X Y                (where X is the letter of the source
  990.                                  drive and Y is the letter of the
  991.                                  destination drive.
  992.  
  993.   For example, if you want to install EZhelp on your C drive, enter
  994.  
  995.       INSTALL A C
  996.  
  997.      This installation batch will create two subdirectories on
  998.   the destination drive, \EZHELP and \EZHELP\TCLIB.
  999.  
  1000.       \EZHELP subdirectory contents
  1001.  
  1002.          EZhelp.exe           command line executable module
  1003.          EZcomp.exe           reference compiler
  1004.          EZsetup.exe          EZhelp configuration utility
  1005.          EZhelp.txt           EZhelp user's reference
  1006.          EZhelp.hnx           EZhelp user's reference index
  1007.          EZhelp.dat           EZhelp startup data
  1008.          Transpor.txt         Example reference
  1009.          Transpor.hnx         Example index
  1010.          Anchor.txt           Example reference
  1011.          Anchor.hnx           Example index
  1012.          Users.doc            User's documentation
  1013.          Order.doc            Order form
  1014.          Install.bat          Installation batch file
  1015.          EZ.bat               Batch to start user's reference
  1016.          Ex1.bat              Batch to start example 1
  1017.          Ex2.bat              Batch to start example 2
  1018.  
  1019.       \EZHELP\SRC subdirectory contents
  1020.  
  1021.          Spawnhlp.c           sample C program to load ezhelp.exe
  1022.  
  1023.  
  1024.   _________________________________________________________
  1025.   EZhelp Reference
  1026.   (C) Copyright 1990-1991, Brain Child Systems.
  1027.   All rights reserved.
  1028.  
  1029.