Name: "macro_menu"
  Type: (Input) (Coroutine) 
  Language: C
  Author: John Stephen (Tessella Support Services plc), 1993
  Input: None
  Output: string - command, multi-line
	  string - comment
  Parameters:
          Choice browser 
  ENVIRONMENT VARIABLES
	  AVS_MacroMenuPath - string
	  AVS_MacroMenuFile - string

  Description:
  ------------
  This module navigates a menu structure which can be designed and configured
  by the user.  Each menu level is described by a single ASCII text file.

  A menu level contains several buttons with user-configurable names.  Each
  button results in one of three basic kinds of action in the module:
	1	load a new menu level
	2	pass a command to downstream modules
	3	go to a file to find a series of commands to be passed
		to down stream modules.

  Option 3 allows multiple commands to be played in background as the result
  of a single button press.

  The file containing the commands to be played in background is the second
  type of file associated with this system.  Thus there are two types of file:
  (1) the MENU FILE to define a menu level
  (2) the AUTOMATIC FILE which contains a series of commands to be executed

THE FORMAT OF THE MENU FILE:
# 
				begins a comment line, except:

#TITLE=my title 
				the menu title will be set to "my title"
				(Default is blank)

#SEPAR=|
				the character "|" will be treated as a
				separator within lines.
				(Default is tab '\t')

				The use of the delimiter means that strings
				may contain blanks

#NEWLINE=%			
				the character "%" within the command field
				(ie the fourth field of a line) will be
				substituted with carriage return characters
				(ie '\n') in the output.
				(Default is #)

my menu choice||||ignore||||comment||||command
				This is a line to define a single menu
				option.  Each menu file will contain several
				of these lines.  

				In this example "|" is used as a delimiter.
				Multiple adjacent delimiters are treated as
				a single delimiter which allows reasonable
				control over layout.

				The use of the delimiter means that strings
				may contain blanks

				The choice button on the menu will be set to
				"my menu choice".  

				The field "ignore" must be present as an
				arbitrary string but it is ignored.

				The field comment may be any string and this
				affects what action is taken by the module.

				The comment string tells the module how to
				interpret the command string.

				The command string is may be any string; any
				occurences of the NEWLINE character are
				substituted by a carriage return ('\n').

The comment string may have any value, but two values have special meaning:
	MENU - 		in which case the module will go to a file named in
			the corresponding command string.  This command string
			is concatenated with the value of AVS_MacroMenuPath.

	AUTOMATIC -	in which case the module will read a series of commands
			from an automatic file named by the command string.  As
			with the menu file's name the file will be found
			within AVS_MacroMenuPath.

	Any other comment string will be output on the "comment" output
	port, together with the corresponding command string which is
	output on the "command" port.  It is up to downstream modules
	to interpret these strings.  


The two environment variables are:
	  AVS_MacroMenuPath - directory containing the first menu file
	  AVS_MacroMenuFile - the name of the first menu file


THE FORMAT OF THE AUTOMATIC FILE:
# 
				begins a comment line, except:

#SEPAR=|
				the character "|" will be treated as a
				separator within lines.
				(Default is tab '\t')

				The use of the delimiter means that strings
				may contain blanks

#NEWLINE=%			
				the character "%" within the command field
				(ie the fourth field of a line) will be
				substituted with carriage return characters
				(ie '\n') in the output.
				(Default is #)

comment||||command
				This is a line to define a single menu
				option.  Each menu file will contain several
				of these lines.  

				In this example "|" is used as a delimiter.
				Multiple adjacent delimiters are treated as
				a single delimiter which allows reasonable
				control over layout.

				The use of the delimiter means that strings
				may contain blanks

				The choice button on the menu will be set to
				"my menu choice".  

				The field "ignore" must be present as an
				arbitrary string but it is ignored.

				The field comment may be any string and this
				affects what action is taken by the module.

				The comment string tells the module how to
				interpret the command string.

				The command string is may be any string; any
				occurences of the NEWLINE character are
				substituted by a carriage return ('\n').

The comment string may have any value, but two values have special meaning:
	MENU - 		in which case the module will go to a file named in
			the corresponding command string.  This command string
			is concatenated with the value of AVS_MacroMenuPath.
 			
			Any subsequent line in the automatic file will be
			ignored.

	AUTOMATIC -	in which case the module will read a series of commands
			from an automatic file named by the command string.  As
			with the menu file's name the file will be found
			within AVS_MacroMenuPath.

			Any subsequent line in the automatic file will be
			ignored.

	Any other comment string will be output on the "comment" output
	port, together with the corresponding command string which is
	output on the "command" port.  It is up to downstream modules
	to interpret these strings.