GSMENU.DOC
GSMENU.EXE 7.3                                      03/08/94


  GSMENU.EXE may be used to provide a flexible user-specified menu of
  executable programs and batch file instructions.  GSMENU may also be
  used to run submenus, including submenus nested several levels deep.

  GSMENU.EXE requires about 40k of RAM to run.  It spawns .EXE programs
  and invokes a second copy of COMMAND.COM to run DOS commands and .BAT
  files.  The copy of COMMAND.COM requires about 35K of RAM to run.  If
  there is insufficient RAM to run a menu program, an error message
  will be displayed.

  GSMENU.EXE reads a datafile (given as command line input), which
  specifies the menu configuration and execution instructions.  This
  gives instructions on how to edit a menu data file for input to
  GSMENU.EXE.  GSMENU.EXE may then be used to read it and execute the
  programs or batch files listed.  GSMENU (starting with 6.0) also
  provides online help on how to run the menu through the <F1> key.
  This frees the message lines for a menu title banner.

  Below is an example of a EXAMPLE.MNU file which shows how to run EXE,
  COM, and BAT files, as well as how to call a submenu.  All lines in
  the data file must be present and come in the order listed below.
  Message lines, menu lines, and the title line must end with a tilde
  (~).  The tilde must be the last character on the line before a
  carriage return/line feed.  If no menu title is desired, simply have
  a tilde as the first character on the title line.

  NOTE:  The data file must be made with an ASCII editor, not a word
         processor.


  MENU COLORS

    The color attributes specify the colors used in the menu.  The
    color attributes are specified with a 3 character string
    structured as follows:

           character 1 = foreground intensity     - or L = low 
                                                  + or H = high

           character 2 = foreground color     colors:  R = Red
           character 3 = background color              G = Green
                                                       B = Blue
                                                       Y = Yellow
                                                       M = Magenta
                                                       C = Cyan
                                                       W = White
                                                       K = blacK

            Example:  +GK   will give high-intensity green characters
                              on a black background.
                      LWB   will give low intensity white characters
                              on  a blue background.

  MENU MESSAGES

    A maximum of four message lines may be defined. The number of
    message lines specified must agree with the number of actual
    message lines in the datafile.  If no message display is
    desired, set mssg_t = -1, and the number of message lines to 0,
    and do not include any message lines in the file.  In this case
    any values for mssg_l and mssgattr will be ignored, but a value
    must be provided for each.

  MENU TITLE

    If a title line is input, it will be printed on the top line of
    the menu box, if the menu box is long enough.  If no title is
    desired, set titleattr = 0 and put a single tilde as the first
    character on the title line.

  MENU OPTIONS

    A minimum of two menu options must be defined.  There may be a
    total of 20 options.  If a menu line has a character preceded by
    a left accent character (` = ASCII 96) in the line, that
    character will be highlighted and hitting that character will
    execute that option.  However, highlighted characters may not be
    duplicated.

  MENU COMMANDS

    Following the menu option strings is a section with the commands
    corresponding to each option.  There are two lines of
    information for each of the menu options.  The first line for
    each option contains the option number, used as a check, the
    number of command arguments, and the next menu option.  The
    first argument is the path\program name.  The second argument is
    the execution command.  Following this are any command line
    arguments.  See options 2 and 4 for examples of how to specify
    arguments for EXE and COM files, with and without command line
    arguments.  The command arguments must be separated by a comma,
    and must be listed in the order:

        PATH\PROGNAME.EXT,PROGNAME,ARG1,ARG2,ARG3,...,ARG8,

    NOTE:  There may be no more than 10 arguments for each menu option,
           including the path and command arguments, and the total
           length of all arguments must not exceed 128 characters.  


  RUNNING BATCH FILES

    A different format is required to run a batch file.  You must
    invoke a copy of COMMAND.COM, which then runs the batch file.
    See option 3 for an example.  The command arguments for a batch
    file must be listed in the order:

          COMMAND.COM,C:\,/C,C:\TEST\EXAMPLE.BAT,

    In this case the second argument tells where to look for
    COMMAND.COM, the third tells it to execute the following
    command, and the fourth is the name of the batch file to run.

    NOTE:  No arguments may be fed to the batch file.

    NOTE:  The second copy of COMMAND.COM requires about 35K of RAM.
           You may have insufficient memory to run large programs if
           they are started via batch files.


  RUNNING DOS COMMANDS

    A similar format is required to run a DOS command, such as DIR.
    You must invoke a copy of COMMAND.COM, which then runs the
    command.  See option 1 for an example.  The command arguments
    for a batch file must be listed in the order:

          COMMAND.COM,C:\,/C,DIR,

    In this case the second argument tells where to look for
    COMMAND.COM, the third tells it to execute the following
    command, and the fourth is the name of the DOS command to run.
    No arguments may be fed to the command.


  RUNNING SUBMENUS 

    An example of a submenu is given in option 4.  This option calls
    GSMENU.EXE with command line input of EXAMPLE2.MNU as the menu
    datafile.  When the second invocation of GSMENU.EXE is <ESC>aped,
    the program will return to the first invocation of GSMENU.EXE,
    running the commands contained in EXAMPLE.MNU.  DO NOT call the
    previous menu from a submenu -- a loop results which your PC will
    not like at all.  The call to run the submenu is recursive within
    the program.  You are not really running the program again, but
    the software cues on the word "GSMENU" as argument 2, and calls
    the function which reads the specified menu file and runs the menu.
    This means that each level of submenu only takes the amount of memory 
    required to hold the menu data (about 1K of RAM) instead of the 
    entire program plus menu data (about 40K).  Menus may be nested 
    several levels deep, but remember that each invocation of GSMENU 
    requires about 1K of RAM, so large programs may not have enough 
    room to run if nested too deeply.


  EXAMPLE DATA FILE:    

    NOTE:  In this example, comments are enclosed in square brackets.
           Comments are not normally included in menu data files.
           Lines should be left justified, except when indention is 
             desired in messages or title.  
           There should be no extra lines between the menu argument lines.  

    EXAMPLE.MNU           [name of GSMENU data file                         ]
    -WB +WR               [colors of message box, message text;             ]
    3 5                   [message box top line, left element;              ]
    1                     [# of message lines to follow;                    ]
    This is an example of GSMENU version 7.0~          [message line        ]
    -WK                   [color for menu title;                            ]
    EXAMPLE MENU~         [menu title line;                                 ]
    -WB -WB +RB -BW       [colors for menu box, options, hilited chars, bar;]
    10 15                 [menu box top line, left element;                 ]
    4                     [# of menu lines to follow;                       ]
    Show a `Directory~    [menu line 1 -- Run DOS command                   ]
    `Norton Edit a file~  [menu line 2 -- Run EXE file with command line arg]
    Run `TEST.BAT~        [menu line 3 -- Run BAT file                      ]
    Run Submenu `1  ~     [menu line 4 -- Run submenu                       ]
    1                     [menu start option                                ]
    1 5 4                           [Opt 1: # of arguments, next option     ]
    COMMAND.COM,C:\,/C,DIR,/o/p,    [Opt 1: command.com name,path,arg 1,    ]
                                    [        dos command,args               ]
    2 3 1                           [Opt 2: # of args, next option          ]
    NE.EXE,NE,THISFILE.DOC,         [Opt 2: path\program, command, args     ]
    3 4 1                           [Opt 3: # of arguments, next option     ]
    COMMAND.COM,C:\,/C,TEST.BAT,    [Opt 3: command.com name,path,arg 1,    ]
                                    [      path\filename.BAT                ]
    4 3 1                           [Opt 4: # of arguments, next option     ]
    GSMENU.EXE,GSMENU,EXAMPLE2.MNU, [Opt 4: path\program, command,          ]
                                    [       path\menufile.ext               ]


  VERSIONS:

Version:  1.0   Date:  06/14/92     Programmer:  Buttleman
          2.0          10/08/92                  Buttleman
              Modified to add color choices for menu, menubox, message,
                message box, and highlight.
              Modified to remove default file name to force file name 
                input.
          3.0          01/26/93                  Buttleman
              Modified to test input data file for acceptable input.
          4.0          05/11/93                  Buttleman
              Modified to use new POP_MENU, with ` to mark highlighted 
                options keystrokes.
          4.1          09/10/93                  Buttleman
              Modified to malloc the pmenu structure, to use less RAM. 
          4.2          09/17/93                  Buttleman
              Added hilite to <ESC> line and used revised POP_MENU.
          5.0          09/22/93                  Buttleman
              Major revision to make submenu calls to GSMENU recursive.
          6.0          11/04/93                  Buttleman
              Added <F1> help capability.  This allows the messages to be
                used for a title.
              Changed fscanf of message line to drop the \n and add 
                SKIPREAD().  This allows indenting message lines.  
          6.1          11/18/93                  Buttleman
              Fixed bug causing false error message if no menu title was
                provided.
          6.2          11/24/93                  Buttleman
              Fixed bug causing false error messages.
              Modified to read entire line with fscanf and then parse 
                info out with sscanf, in order to give better error messages.
          7.0          12/03/93                  Buttleman
              Substantially revised to use modified POPX(), modified from
                POP_MENU().  Now uses only about 500 bytes each submenu.
          7.1          12/16/93                  Buttleman
              Fixed bug in reading title if no title was desired.
          7.2          12/21/93                  Buttleman
              Fixed bug in optdata->args, making last arg NULL.
          7.3          03/08/94                  Buttleman
              Slight revisions for smaller code.
          7.31         03/31/94                  Buttleman
              Fixed bug in title on menu.