Path: utzoo!utgpu!cs.utexas.edu!usc!ucsd!pacbell.com!pacbell!pcbox!pjc
From: pjc@pcbox.UUCP (Paul J. Condie)
Newsgroups: alt.sources
Subject: menu(1) part 2 of 14
Keywords: menu
Message-ID: <436@pcbox.UUCP>
Date: 26 Dec 90 20:04:05 GMT
Organization: Yet Another Box - Casto Valley, Ca.
Lines: 1131


#!/bin/sh
# this is part 2 of a multipart archive
# do not concatenate these parts, unpack them in order with /bin/sh
# file menu.1 continued
#
CurArch=2
if test ! -r s2_seq_.tmp
then echo "Please unpack part 1 first!"
     exit 1; fi
( read Scheck
  if test "$Scheck" != $CurArch
  then echo "Please unpack part $Scheck next!"
       exit 1;
  else exit 0; fi
) < s2_seq_.tmp || exit 1
echo "x - Continuing file menu.1"
sed 's/^X//' << 'SHAR_EOF' >> menu.1
XFor example:
XAssuming $SNAME is a multiple worded value to be assigned to a field.
X
X	field_defaults = "cat \fIfilename\fP |
X		while [ $? -eq 0 ]
X		do
X			read LINE
X			[ $? -ne 0 ] && break
X			set $LINE
X			SCODE=$1
X			shift
X			SNAME=$*
X			echo $SCODE  \\\\"$SNAME\\\\"
X		done"
X.fi
X.TP 15
X[ after_screen = "" ]
XA command to be run after the user exits the screen.
XThis command does not get run if the user presses the \fIKEY_CANCEL\fP
Xkey to exit the screen.
X
XDiagnostics
X.RS 15
XThe following actions are taken by menu depending on what exit code your
Xcommand uses.
X.TP 8
X0
XAOK.
XIf your command prints something to stdout,
Xthat output (up to a newline) will be displayed to the screen as a message
Xto the message line before prompting for input again.
X.TP 8
X1
XIssue a audible bell.
XIf your command prints something to stdout,
Xthat output (up to a newline) will be displayed to the screen as a message
Xto the message line before prompting for input again.
X.TP 8
Xanything else
XNo action.
X.RE
X
X.RS 15
Xnote:  Other return codes will be added depending on demand.
X.RE
X
X.TP 15
X[ exit_last_field ]
XIf exit_last_field is specified, after the user presses return on the last field
Xthe input will be accepted and the user will exit the screen (this is as if the
Xuser had pressed the KEY_ACCEPT).  Don't ask me Lee wanted it.
X.TP 15
X[ exit_on_cancel ]
XOnly exit from the screen when the user presses the \fIKEY_CANCEL\fP key.
XThis is useful in combination with the \fIafter_screen\fP keyword if you
Xwant the capability, for example, to add a bunch of records without exiting
Xthe screen.  In this case, the \fIKEY_ACCEPT\fP key would add the record(s) 
Xby running the \fIafter_screen\fP command and 
Xthe user would signify he is done by pressing the \fIKEY_CANCEL\fP key.
X.br
XFor a good example of this see the sadmin.m menu script with the adduser
Xshell script in the utilities.d/m.d directory.
X.TP 15
X[ text = row col text ]
XAllows you to put any text at a specified row and column within the input
Xwindow.  Where the first number is the row (base 0) and the second number
Xis the column (base 0).  Remember the border of the window will take up
Xtwo rows and two columns.  The text will be written to the window before
Xany of the field stuff is placed on the window.  Any number of text lines
Xmay be specified up to \fIMAXTEXT\fP (20) defined in menu.h.
XIt's up to you to make sure your text stays in the window.
XThe text may contain terminal attributes.
X.RE
X
XField Arguments:
X.RS 4
X.TP 15
Xfield_name
XThe environment variable name that the data will be assigned to.  The field_name
Xmust begin with a "$", just to remind you that it is a environment variable 
Xthat I 
Xam using.  Although, the "$" is not actually used in the environment variable 
Xname.  This screen argument (field_name) tells menu that you are starting 
Xa new field
Xdefinition.  ..soooo...  It has to be the first argument for a field.  
XAll other field
Xarguments for that field_name follows after, but before the next field_name.
X
XThe user's input is immediatly accessable, via the environment variable,
Xas soon as the user exits the field.  If the \fIKEY_CANCEL\fP is pressed
Xto exit the screen.  All environment variables are set back to their original
Xvalues, before the screen was entered.
X.TP 15
Xfield_row
XThe row this field will appear on (base zero).
XThe window is drawn with a box on the outer edge, row zero and the last 
Xrow (window_rows) is used for the box.
X.TP 15
Xfield_col
XThe starting column for this field (base zero).  
XIf you have a field_label you need to allow enough room to place the label 
Xto the left of the field, also, the field terminators.
XThe window is drawn with
Xa box on the outer edge, so, column zero and the last column (window_cols) 
Xis used for the box.
X.TP 15
Xfield_length
XMaximum length of this field.  For field types SET and MENU this argument
Xbecomes optional, the field length is automatically set to the longest set value
Xin the field_range.
X.TP 15
X[ field_label = "" ]
XA Label to be placed to the left of the field.
X. \ **********************************
X.TP 15
X[ field_mask = "" ]
XValid masks for a field depend upon the type of field
Xyou specified, see (field_edits).  Basically the mask says what character
Xpositions in the field you allow input, what type of character allowed at that
Xposition, and what kind of a format do you want for the field.
X
XThe \fIfield_length\fP should not include character positions where no input
Xis allowed in the mask (format characters), because format characters
Xare not returned into \fIfield_name\fP.  For example, \fIfield_edits = DATE,
Xfield_mask = "MM/DD/YY"\fP.  The "/" is a format character.  The cursor
Xwill skip over those positions in the field.  Only the characters typed in
Xthe MM DD YY positions will be in the environment variable \fIfield_name\fP.
XThe field_length would be six.
X
XBecause the mask is so closely tied to the \fIfield_edits\fP, a complete
Xdescription of what mask characters are valid with what field types is 
Xdescribed under
X\fIfield_edits\fP.  Any character in the mask that is not listed as a valid
Xmask character for that field type becomes a format character.
X. \ ---------------------------------
X.TP 15
X[ field_edits = UPPER_AN ]
XThis argument defines edit checks to be performed on the
Xinput characters as they are being typed in.  If no mask is provided then
Xthe field type itself determines the edit checks to be performed on all
Xcharacters in the field.
X.RS 15
X.TP 11
XALPHANUM
XAny alpha/numeric character is allowed.
X.br
XValid mask characters:
X.nf
X	space	alpha/numeric
X	A	alpha
X	9	numeric
X	U	alpha only - convert to upper case
X	V	alpha/numeric - convert alpha to upper case
X	H	???
X.fi
X.TP
XALPHA
XAlpha only.
X.br
XValid mask characters:
X.nf
X	A	alpha
X.fi
X.TP
XNUMERIC
XNumeric only.
X.br
XValid mask characters:
X.nf
X	9	numeric
X.fi
X.TP
XUPPER
XConvert to upper case.  Only alpha permitted.
X.br
XValid mask characters:
X.nf
X	U	upper alpha
X.fi
X.TP
XUPPER_AN
XAlpha and numeric permitted.  Convert alpha characters to upper-case.
X.br
XValid mask characters:
X.nf
X	V	upper alpha/numeric
X.fi
X.TP
XHEX
XOnly hex characters permitted.
X.br
XValid mask characters:
X.nf
X	H	???
X	space	???
X.fi
X.TP
XSTATE
XValid two character Post Office abbreviations for the fifty states.
XA edit check is done for a valid state.
X.br
XValid mask characters:
X.nf
X	SS	two character state
X	S	???
X	space	???
X.fi
X.TP
XZIP
XPost Office zip code.
X.br
XValid mask characters:
X.nf
X	99999-9999	???
X.fi
X.TP
XDATE
XA valid date.
X.br
XValid mask characters:
X.nf
X	MM	month  (01-12)
X	DD	day  (01-31)
X	YY	year  (00-99)
X	YYYY	full year with century
X.fi
XThe mask must contain at least MM and DD.  If no mask is specified for the
Xfield a default mask of "MMDDYY" is used.
X.br
XSome examples:
X.nf
X	MMDDYY
X	MM/DD/YY
X	YY-MM-DD
X	MM  DD  YYYY
X.fi
X
XThe \fIfield_range\fP argument may contain any of the following keywords
X(case insensitive)
Xand the appropriate edit will be performed (see \fIfield_range\fP for more
Xinfo).
X.nf
X	sun,mon,tue,
X	wed,thr,fri,sat	- validate date entered against day of week.
X	No_Holidays	- no holidays allowed.  
X			  This is validated against the file 
X			  /usr/lib/acct/holidays by default.  
X			  Modify GetInput.h to change default.
X	GT_Today	- date must be greater than todays date.
X	GE_Today	- greater than or equal to todays date.
X	LT_Today	- less than todays date.
X	LE_Today	- less than or equal to todays date.
X.fi
X.TP
XTIME
XA time field.
X.br
XValid mask characters:
X.nf
X	HH	hours  (01-12)
X	MM	minutes  (00-59)
X	SS	seconds  (00-59)
X	TT	tenths  (00-99)
X	II	military hours  (00-24)
X.fi
XSome examples:
X.nf
X	HH:MM
X	HH:MM:SS
X	HH:MM:SS:TT
X	II:MM
X	II:MM:SS
X	II:MM:SS:TT
X.fi
X.TP
XSET
XThis field type specifies a set of values that are acceptable in the input 
Xfield.
XThe acceptable values within the set are specified in the \fIfield_range\fP 
Xargument.  
XThe user selects one of the set values specified in the field range by
Xpressing the space bar, which will toggle through the set values,
Xor by pressing the first character in the desired value.
X
XThe format of the field_range can only be comma separated values 
X(ex. "CA,ID,TX").  
XRange values, such as "1-5", don't work.  You would have to say "1,2,3,4,5".
X.br
XThe field length is automatically set to the longest set value in the 
Xfield_range.
X.TP
XMENU
XThis field type is similar to the SET type.  The difference is when the user
Xattempts to type something in the field a pop-up menu of available choices
Xare displayed, as specified in field_range.  
XThe user makes a selection by hi-lighting the choice and pressing return.
X.br
XSee SET type for specifying the field range.
XThe limit is ten items in the field range.
X.TP
XPROTECT
XThis X's out the field so that what is entered on the keyboard can not be seen
Xon the screen.  Useful for password entry.
X.RE
X. \ ---------------------------------
X.TP 15
X[ field_range = "" ]
XA set of valid ranges permitted for this field. 
XRanges may be specified as comma separated values ("ONE,TWO,THREE") 
Xor as a inclusive range ("1-5"), or a combination of both ("1-5,M,E").
XThe comma separated range values are "or" conditions not "and" conditions,
Xexcept for
XDATE ranges.  Date range "mon-fri,No_Holidays" means date must be mon-fri
Xand not a holiday.
XRange values must be compatible with the field_edits that you have selected.
XMaximum length of this field is 1k.
X
XInstead of hard coding the range values a command may be specified,
Xenclosed in grave accents, that will echo to stdout the range values to
Xbe used.  The command will be run once upon entering the screen.
X.br
XSome examples:
X.nf
X	"1-10"
X	"5,10,15,16"
X	"1-10,20,M,E,32-40"
X	",CA,TX,ID"
X	"mon-fri"
X
X	### this command builds a field_range of valid printers
X	"`lpstat -p | awk '{ print $2 }' |
X		for printer in `cat`
X		do
X			if [ \\"$printer\\" = \\"unknown\\" ]
X			   then continue
X			fi
X			if [ -z \\"$RANGEVALUES\\" ]
X	      		   then RANGEVALUES=$printer
X	      		   else RANGEVALUES=\\"$RANGEVALUES,$printer\\"
X			fi
X			echo $RANGEVALUES > /tmp/menu.tmpfile
X		done
X		cat /tmp/menu.tmpfile`"
X.fi
X. \ ---------------------------------
X.TP 15
X[ field_min = 0 ]
XIf field_mustenter is selected then this is the minimum
Xrequired input.  Otherwise, it is the minimum required input only if they try 
Xto input something.
X.br
XWarning: If you select a \fIfield_adjust\fP that blank fills then this 
Xoption will have no meaning because there will be spaces in the field.
X.TP 15
X[ field_adjust = NOFILL ]
XIndicates whether to adjust the text right or left within the field
Xand whether or not to zero or blank fill the field.
X.RS 15
X.TP 15
XNOFILL
Xno action.
X.TP
XRTADJ_ZFILL
Xright adjust, zero fill
X.TP
XRTADJ_BFILL
Xright adjust, blank fill
X.TP
XLFADJ_ZFILL
Xleft adjust, zero fill
X.TP
XLFADJ_BFILL
Xleft adjust, blank fill
X.RE
X. \ ---------------------------------
X.TP 15
X[ field_mustenter ]
XMarks this as a must enter field.  Default is that the field is not
Xa must enter field.
X. \ ---------------------------------
X.TP 15
X[ field_prompt = "" ]
XPrompt message to be displayed.
X. \ ---------------------------------
X.TP 15
X[ field_terminator = "[]" ]
XCharacters to terminate the field with.  The left one goes on the left, 
Xthe right one goes on the right.  Funny how that works.  I recommend
Xto use terminators on input fields and no terminators (spaces) for
X\fIfield_noinput\fP fields.
X. \ ---------------------------------
X.TP 15
X[ field_noinput ]
XIf field_noinput is selected then the cursor will skip over this field.  A
Xdisplay only field.
X.TP 15
X[ before_field = "" ]
XWhat goes into the quoted string is a shell command that is passed into a 
Xpopen(3) call before any input is done or default values displayed.
X
XDiagnostics
X.RS 15
XThe following actions are taken by menu depending on what exit code your
Xcommand uses.
X.TP 8
X0
XAOK. Continue to prompt for input.
XYour command may print to stdout, up to a newline, enviroment variable 
Xsettings to change the values of your \fIfield_names\fP.  For example
X"$FIELD_1=value1 $FIELD_2=value2 ...".  The new values are displayed 
Ximmediately to the fields.
X.TP 8
X1
XAOK.  Continue to prompt for input.  If your command prints something to stdout,
Xthat output (up to a newline) will be displayed to the screen as a message
Xto the message line.
X.TP 8
X2
XSkip this field.  Same effect as specifying \fIfield_noinput\fP, only this 
Xhappens at runtime.
X.TP 8
Xanything else
XDo nothing.
X.RE
X
X.RS 15
Xnote:  Other return codes will be added depending on demand.
X.RE
X
X.TP 15
X[ after_field = "" ]
XWhat goes into the quoted string is a shell command that is passed into a 
Xpopen(3) call after the user exits the field.
XThis command does not get run if the user presses the KEY_CANCEL key 
Xwhile in this field.
X
XDiagnostics
X.RS 15
XThe following actions are taken by menu depending on what exit code your
Xcommand uses.
X.TP 8
X0
XAOK. Continue to next field.
XYour command may print to stdout, up to a newline, enviroment variable 
Xsettings to change the values of your \fIfield_names\fP.  For example
X"$FIELD_1=value1 $FIELD_2=value2 ...".  The new values are displayed 
Ximmediately to the fields.
X.TP 8
X1
XStay on this field (re-input).  Issue a audible bell.
XIf your command prints something to stdout,
Xthat output (up to a newline) will be displayed to the screen as a message
Xto the message line before prompting for input again.
X.TP 8
Xanything else
XDo nothing.
X.RE
X
X.RS 15
Xnote:  Other return codes will be added depending on demand.
X.RE
X
X.RE
X.RE
X. \ --------------------------------------------------------------------------
X
X.PP
X.nf
X \fB.EXIT\fP [ command ]   [ \\ ]
XExit description text.
X.fi
X.IP "" 6
XExit menu program.  This can be used if you want to exit as a user
Xselectable option.  There should be only one .EXIT per menu.
X.br
XIf command is present a system(3S) will be called, with command as the
Xargument, before exiting.  The command will be executed even if the user uses
Xthe "E" command (see help) to exit, as long as there is a .EXIT 
Xin current menu.  If you
Xwant to make sure a particular command gets executed when the user exits you
Xshould have a ".EXIT command" in every menu.
X. \ --------------------------------------------------------------------------
X
X.PP
X.nf
X \fB.GETINPUT\fP  screen_name [ [!]variable=value ... ] [ \\ ]
XOption description text.
X.fi
X.IP "" 6
XDisplays a predefined screen and prompts for input
Xas outlined in the screen definition.
XAfter the user has pressed the \fIKEY_ACCEPT\fP
Xthe environment variables, specified by the \fIfield_name\fP argument
Xis set equal to the data the user entered in that field.
XIf no data was entered for a field the environment variable is set equal to
X"".
XThe after_screen command is executed after every \fIKEY_ACCEPT\fP.
XIf \fIKEY_CANCEL\fP is pressed the environment variables are not set.
X.br
XThe screen_name is what was used in the .DEFINE_SCREEN keyword.
XThe \fIvariable=value\fP are set at runtime (when the user selects the
Xoption).
X
X
XThe cursor moves from field to field based upon the order of the fields in
Xthe \fI.DEFINE_SCREEN\fP keyword.  
XBelow is listed the various keys used in a GETINPUT, the action they perform 
Xand their default value.  In addition to the default values, if the terminal
Xhas a associated curses key defined (see curses.h) that key may also be used.
XFor example, ^j is the default value to traverse forwards through the fields
Xbut if the down arrow is defined for KEY_DOWN, in curses, then the down arrow 
Xmay also be used.  Not all keys may have an associated curses key.
XThe "^" indicates press and hold the control key.
X.br
XSee \fIMenu Initialization File\fP to customize the values of the keys.
X
XMover Keys:
X.nf
X	KEY_RETURN  (^m)	Traverse forwards through the fields.
X	KEY_DOWN  (^j)	Traverse forwards through the fields.
X	KEY_UP  (^k)		Traverse backwards through the fields.
X	KEY_TAB  (^i)		Fast forward through the fields.
X	KEY_BTAB  		Fast reverse through the fields.
XField Editing Keys:
X	KEY_BEG  (^b)		Place cursor at beginning of field.
X	KEY_END  (^e)		Place cursor at end of input in field.
X	KEY_RIGHT  (^l)	Forward space within the field.
X	KEY_LEFT  (^h)		Backspace within the field (non-destructive).
X	KEY_BACKSPACE  (^h)	Same as KEY_LEFT.
X	KEY_EOL  (^d)		Delete from cursor to end of field.
X	KEY_DL  (^c)		Clear field and home cursor.
X	KEY_DC  (^x)		Delete a character.
X	KEY_IC  (^t)		Toggle between type-over and insert mode.
XOther Keys:
X	KEY_HELP  (?)		Display help screen.
X	KEY_REFRESH  (^r)	Redraw the screen.
X	KEY_ACCEPT  (^a)	Accept all input and exit screen.
X	KEY_CANCEL  (esc)	Cancel all input and exit screen.
X	KEY_SAVE  (^f)		Save screen to a file.
X	KEY_PRINT  (^p)	Print screen to lp.
X.fi
X. \ --------------------------------------------------------------------------
X
X.PP
X \fB.GNAME\fP menuname menufile
X.IP "" 6
XDefine a goto name for a menu so that the user may go directly to that
Xmenu by typing in the menu name (G "return" menuname "return").  
XMenuname is the name you want
Xthe user to input.  Menuname has to be one word and is limited to fifteen
Xcharacters.
XMenufile is the unix filename for that menu.  The .GNAME
Xis not accessible to the user until the menufile that you have placed the .GNAME
Xin has been displayed.  If all .GNAME's have been placed in the main menu
Xthen they will all be accessible to the user as soon as the main menu has
Xbeen displayed.
X.br
XInstead of having the user type (G "return" menuname "return") try 
X(control g).
X
XWarning:
X.br
XThis should not be used to goto a pop-up (.POPMENU) type menu.  It doesn't
Xwork too well.  If your .MENU calls a .GETINPUT screen or sets environment
Xvariables before it calls the menu those will not be called if you use a
Xgoto for that menu.
X
XNot supported in a \fI.POPMENU\fP menu.
X. \ --------------------------------------------------------------------------
X
X.PP
X \fB.INCLUDE\fP menufile
X.IP "" 6
XInclude a menu script file.  This is so you don't have to type the same 
Xscreen definition in all the menu files that you want to use it in.
XAlthough, it could be used for any menufile.
XIt is significant where you place the .INCLUDE in your menufile, depending on
Xwhat is in the .INCLUDE menufile.  Think of it as if you were typing it in
Xat this point in the menu file.
X
XThe file is looked for first in the current directory and
Xthen in \fI$MENUDIR\fP.  The \fImenufile\fP may be a environment variable or 
Xabsolute pathname of the file.
X. \ --------------------------------------------------------------------------
X
X.PP
X \fB.LINE\fP [ StandoutLine ] [ DumbLine ]
X.IP "" 6
XDraws a standout line underneath your last title line to
Xsplit the options portion of the screen from the title portion.
XPlace after last \fI.TITLE\fP.
X.br
XSee .BOX for description of line types.
X
XNot supported in a \fI.POPMENU\fP menu.
X. \ --------------------------------------------------------------------------
X
X.PP
X.nf
X \fB.MENU\fP menufile  [ [!]variable=value ... ]  [ GETINPUT screen_name ]  [ [!]variable=value  ... ]   [ \\ ]
X Option description text.
X.fi
X.IP "" 6
XDefines this option as a sub-menu.  When user selects this option
Xthe menu defined in "menufile" will be parsed and displayed.
X
XThe [ GETINPUT ] option allows you to display a screen and prompt a user for
Xinput.  The screen is displayed before parsing of the new menu is begun.
XThis could be used to prompt a user for a password with a .UNIX in the calling
Xmenu using checkpass(1) to check permission to run the menu.
XCompliments of Victoria.
X
XA environment variable may be specified in the Option description text.
X.br
X
XThe optional variables are environment variables that will be set equal to
Xthe value specified when the user selects this option.  
XPlacing them before or after a GETINPUT call causes them to be set either
Xbefore or after the GETINPUT screen is called.
XThis can be used
Xto pass data to a sub menu.  Maximum length of the .MENU line is 700 bytes.
X
XNot supported in a \fI.POPMENU\fP menu.
X. \ --------------------------------------------------------------------------
X
X.PP
X.nf
X \fB.POPMENU\fP [ NoDim ] menufile [ row column ] [ [!]variable=value  ... ]  [ \\ ]
X Option description text.
X.fi
X.IP "" 6
XDefines this option as a pop-up menu.  When user selects this option
Xthe script file "menufile" will be parsed and displayed.  
XThe optional row and column (upper left corner) is where you want the pop-up 
Xmenu to pop-up.  If row and column is omitted then the menu will be placed
Xas close to the option, that is selecting it, as possible.
XSee \fI.SETENV\fP for \fIvariable=value\fP.
X
XThe [ NoDim ] flag tells menu not to dim the box on a inactive menu.  The
Xdefault is to dim inactive menus.  That way the user can easily see what
Xmenu they are working with.
X
XA environment variable may be specified in the Option description text.
X
XThe options in a pop-up menu can be selected by hi-lighting the option
Xand pressing return, or ESC to cancel.  The pop-up menu goes away after
Xan option has been selected and you are put back in your calling menu 
X(the calling menu is reparsed).
XThis keyword was provided for those options where the user would go over to
Xa menu select an item then return back.  A printer select menu would be ideal
Xfor this keyword.
X
XYou can toggle between full character matching and single (first) character
Xmatching by pressing KEY_IC/KeyIC key.
X. \ --------------------------------------------------------------------------
X
X.PP
X.nf
X \fB.SETENV\fP  [ BELL ] [!]variable=value [ [!]variable=value ... ] [ message ]   [ \\ ]
X Option description text.
X.fi
X.IP "" 6
XWhen the user selects this option it will set
Xa variable to a value in the the current environment (i.e. the menu
Xenvironment).  This is useful if you want something like a printer menu
Xlisting available printers and changing the $LPDEST so all print jobs
Xwill go to the new printer.
XThe \fImessage\fP argument is what is printed to the screen so the user
Xcan get feed back that his selection did something.
XThe \fIBELL\fP argument provides an audible beep if the variables were
Xset successfully.
X
Xnote:
X.br
X      If the message has a "=" sign in it menu will think it is a
X      "variable=value" and will try to set a environment variable.
X. \ --------------------------------------------------------------------------
X
X.PP
X.nf
X \fB.SPACE\fP
X.fi
X.IP "" 6
XPut a space in between options.
X
XNot supported in a \fI.POPMENU\fP menu.
X. \ --------------------------------------------------------------------------
X
X.PP
X.nf
X \fB.SYSTEM\fP [ [ variable=value ... ] GETINPUT screen_name ] command   [ \\ ]
X Option description text.
X.fi
X.IP "" 6
XDefines this option as a system call.  When user selects this option
Xa system call will be executed, with command as the argument. Since the command
Xis a argument to system(3S) anything you can type at the $ prompt you can
Xput in the command.
XMaximum length of \fIcommand\fP is 1k.
XA environment variable may be specified in the Option description text.
X
XThe [ GETINPUT ] option allows you to display a screen and prompt a user for
Xinput that could be used as command line arguments to the command.  
XThe screen_name is a defined screen name.
XSee .GETINPUT and .DEFINE_SCREEN for more information.
X.br
XThe optional \fIvariable=value\fP arguments associated with the GETINPUT
Xare set at runtime, when the user selects this option.  This could be
Xused to have a dynamic window_title in your GETINPUT screen.
X
XExample: Say you need to prompt the user for a $DATA field then pass that 
Xfield into
Xyour program, lock the program so that program cannot be run until this one 
Xfinishes
Xand you want to kick the program off in the back ground.  You
Xcould try something like this (see lock(1),unlock(1)):
X.nf
X   .SYSTEM     GETINPUT  screen1 \\
X		lock program_name; \\
X		if [ $? -eq 0 ] \\
X		   then	(nohup program_name $DATA; nohup unlock program_name)& \\
X		   else	echo "Program Already Running."; \\
X			echo "Press [ Return ] to continue ...\\c"; \\
X			read reply \\
X		fi
X   Option Description Text.
X
X
X
XNote: No error checking is done for \fIcommand\fP.  If error checking is
Ximportant for your application you will need to build it into 
Xyour \fIcommand\fP.
X.fi
X. \ --------------------------------------------------------------------------
X
X.PP
X.nf
X \fB.TEXT\fP [-]row [-]column
X Text goes on this line.
X.fi
X.IP "" 6
XAllows you to put any text at a specified row and column on the \fIstdscr\fP 
Xscreen (base 0).
XA negative row and/or column indicates number of rows from the bottom of the
Xscreen or number of columns from the right of the screen (relative addressing).
XFor example, \fI.TEXT -4 -20\fP will display text on the 4th row from the
Xbottom and the 20th column from the right.  This could be useful if your users
Xare using different sized terminals/windows.  If the row and/or column are 
Xgreater than the window size the text will get displayed on the last row or
Xlast column of the screen.
X
XThis keyword could be used to
Xplace a prompt text next to the cursor.  The \fI.TEXT\fP is only active for
Xthe current menu.  If you want the same text to appear in every menu you
Xwill need to put a \fI.TEXT\fP in every menu.
XTerminal attributes may be placed in the text line (see Terminal Attributes).
X
XA environment variable may be specified within the text.
X
XThe last line of the screen is used to report error messages, like 
X\fIInvalid Option\fP.  Your text will probably get erased if put on the last
Xline.
X. \ --------------------------------------------------------------------------
X
X.PP
X.nf
X \fB.TITLE\fP
X Title Line text.
X.fi
X.IP "" 6
XDisplay a title line top of menu.
XTitle lines will start at row zero.
XMultiple .TITLE lines may be defined up to MAXTITLE (6) defined in
Xmenu.h file.
X
XThe title line consists of three sections defined as follows:
X.br
Xleft text...center text...right text
X.br
XText you place in the three sections will be either left justified,
Xcentered, or right justified on the screen.  The "\fB...\fP" are used to
Xseparate the sections.
X
X.RS 6
X.PP
XA substitutable variable may be specified within the title line text.
XThe character $ is used to introduce substitutable 
Xparameters, in the form of ${\fIparameter\fP}.
XThe value, if any, of the \fIparameter\fP is substituted.  The braces are 
Xrequired only when \fIparameter\fP is followed by a letter, digit, or 
Xunderscore that is not to be interpreted as part of its name.  See sh(1) 
Xfor more info.
X.TP 6
X$DATE
Xmay be placed anywhere in title text and the system date (mm/dd/yy) will
Xbe displayed.
X.TP 6
X$TIME
Xmay be placed anywhere in title text and the system time (hh:mm zz) will 
Xbe displayed.
X
X.TP 6
X$MAIL
XThe \fI$MAIL\fP is a special environment variable.  This turns on the mail
Xnotification facility.  $MAIL may be placed anywhere in the title text and when
Xthe user has mail to be read the word "\fBMAIL\fP" will be displayed in
Xreverse video at that location in the title line, with an audible beep.
XThe MAIL environment variable needs to be set to the users mail file, ex.
X"MAIL=/usr/mail/pjc".  The environment variable \fIMAILCHECK\fP is used to
Xdetermine how often to check for mail.  See mail(1).
X.br
XIf you have a hierarchy of menus for your application \fI$MAIL\fP only needs
Xto be in the first menu.
X
XWarning: If menu is run with the set uid bit set, menu will be unable to
Xdetermine if your mail is being forwarded, because it won't have read
Xpermission on your mail file, and \fIMAIL\fP will be displayed all the time
Xon machines where you forward your mail.
X.TP
XTerminal Attributes
XAttributes may be specified anywhere in the title text as follows:
X.nf
X\\S = Standout
X\\B = Bold
X\\U = Underline
X\\D = Dim
X\\R = Reverse Video
X\\L = Blink
X\\N = Normal
X
Xexample: \\RThis text is reverse video.\\N Now normal.
X
Xnote: Terminal attributes are terminal dependent.
XBerkeleys' version of curses only supports Standout.  Attributes may
Xalso be combined.
X.fi
X
XFor \fI.POPMENU\fP there is no left,center,right sections.  The title is
Xcentered.  You can have only one \fI.TITLE\fP in a pop-up menu.  No attributes
Xand/or environment variables are supported in the title for pop-up menus.
X.RE
X. \ --------------------------------------------------------------------------
X
X.PP
X \fB.UNIX\fP  [ REDRAW ]  [ GETINPUT screen_name ]  command  [ \\ ]
X.IP "" 6
XA system(3) call with command as the argument is executed immediately 
Xwhen found while parsing the 
Xmenufile.  Can be used to set function keys on terminal.  Warning: if
Xyou use this to set function keys and the function keys are changed in
Xanother program, they do not get reset back to what they were in the menu.
XMaximum length of command is 700 characters.
X
XThe [ GETINPUT ] option allows you to display a screen and prompt a user for
Xinput, before the command is run.
XThe window_pos argument to DEFINE_SCREEN must be specified in order to use
Xthe screen here, because, menu is unable to automatically figure out where to 
Xput the screen because this is happing during the parsing stage.
XAdditionally, the \fIDEFINE_SCREEN\fP must be declared before the \fI.UNIX\fP.
X
XThe [ REDRAW ] flag instructs menu to redraw the menu screen after your command
Xhas been executed.  This is recommended if your command writes anything to
Xthe screen.
X
XDiagnostics
X.RS 10
XThe following actions are taken by menu depending on what exit code your
Xcommand uses.
X.TP 8
X0
XAOK. Continue to parse the next keyword.
X.TP 8
X1
XQuit/Exit the menu program.
X.TP 8
X4
XReturn to previous menu and display the error message 
X"Not Authorized to run menu.".
X.TP 8
X> 4
XQuit parsing this menu and return to previous menu.  No message.
X.RE
X
X.RS 6
XExample:  Authorize menu access.
X.nf
X         .UNIX grep $LOGNAME access_table >/dev/null 2>/dev/null \\
X		[ $? -ne 0 ] && exit 4 \\
X		exit 0
X.fi
X
XExample:  Build a menu script file at run time.
X.nf
X       ###  Printer Selection Menu
X       ###  Build a .POPMENU of available printers connected to a system.
X
X          .UNIX echo ".TITLE" > printers.m; \\
X	         echo "Printer Menu" >> printers.m; \\
X	         echo ".TEXT 23 0" >> printers.m; \\
X	         echo "Select A Printer." >> printers.m; \\
X	         lpstat -p | awk '{ print $2 }' | \\
X	         for i in `cat` \\
X	         do \\
X		     echo ".SETENV LPDEST=$i  Printer ($i) selected." >>printers.m; \\
X		     echo "$i" >> printers.m; \\
X	         done; \\
X	         exit 0
X
X          .POPMENU printers.m
X          Select Default Printer.
X.fi
X.RE
X. \ --------------------------------------------------------------------------
X
X.PP
X \fB.WINDOW\fP  first_row  last_row  first_col  last_col  [ heading ]
X.IP "" 6
XDefines a window area (rectangle) to display the options that follow this 
Xkeyword (up to the next \fI.WINDOW\fP or end of file).
XThe options are centered between first_row / last_row
Xand between first_col / last_col.
XThe \fIrows\fR and \fIcolumns\fR are absolute (base 0) and inclusive.  
XIt is up to you
Xto make sure they don't overlap (unless that's what you want), and
Xthat it is large enough to hold the options that follow.
XThe optional \fIheading\fR is text you wish centered over the window area
X(rectangle).
XIt is
Xdisplayed on \fIfirst_row\fR minus one.
XThe heading may contain terminal attributes as described under \fI.TITLE\fR.
XYour \fI.WINDOW\fP keywords should be placed after all \fI.TITLE\fP(s).
X.br
XFor example suppose you want two columns of options on the screen, one
Xof which will have a heading:
X.nf
X .WINDOW 0 23 0 39
X1. this option in left column
X2. this option in left column
X .WINDOW 10 23 40 79 \\R REPORTS \\N
X3. this option in right column
X
X.fi
XIf no .WINDOW is used a default of .WINDOW 0 screen_rows 0 screen_cols 
Xis used for all options.
X
XNot supported in a \fI.POPMENU\fP menu.
X. \ --------------------------------------------------------------------------
X
X.SH HELP SCREENS
XThe default help file for menu(1) is \fImenu.hlp\fP.  Additional help files
Xmay be used in a GETINPUT screen.  The following describes the the syntax of
Xa help file.
X
X\fBtagname\fP
X.br
X[ .TITLE   A Title May Be Placed Here. ]
X.br
XA tagname identifies a help screen and must be on a line by itself.
X.br
XThe text (with optional terminal attributes) to be displayed for this tagname 
Xis placed between the two tags.  Don't use tabs to space the text 
X(it don't work), you have to put in hard spaces.
XMore than one tagname may be placed in a help file.
XAny text outside of a tagname is ignored.
X.br
X\fBtagname\fP
X
X
XThe \fITABLE_OF_CONTENTS\fP tagname is a special tag describing what
Xis to be contained in the table of contents for help.  The following is the
Xsyntax for this tagname.
X.nf
X\fBTABLE_OF_CONTENTS\fP
Xhelpfile   tagname   description
Xhelpfile   tagname   description
X	etc...
X\fBTABLE_OF_CONTENTS\fP
X.fi
X
X
XBelow is shown the default help file for menu(1)  (menu.hlp).
XIt has four tagnames in it (TABLE_OF_CONTENTS, menu, popmenu, GETINPUT 
Xand help).  This file may be customized to fit your needs.
X
X.nf
X\fBTABLE_OF_CONTENTS\fP
Xmenu.hlp	menu		Menus      - Help using menus.
Xmenu.hlp	popmenu	Pop-menus  - Help using popmenus.
Xmenu.hlp	GETINPUT	Input      - Editing commands.
Xmenu.hlp	help		Help       - Using help.
X\fBTABLE_OF_CONTENTS\fP
X
X
X\fBmenu\fP
X .TITLE Menu Help
X
X  \\RMENU COMMANDS:\\N
X          m       \\D-  Go directly to main menu.\\N
X          p       \\D-  Return to previous menu.\\N
X          g or ^g \\D-  Go directly to a specific menu.\\N
X          h or ?  \\D-  This help screen.\\N
X          ^r      \\D-  Redraw the screen.\\N
X          e       \\D-  Exit.\N
X          !       \\D-  Enter a unix command.\\N
X
X  \\RSELECTING OPTIONS:\\N
X          -  Use "up arrow key", "^k", "down arrow key", "^j" or
X             "tab key" to place bar on option and press "return".    
X
X                  or
X
X          -  Enter option number and press "return".
X
X\fBmenu\fP
X
X\fBpopmenu\fP
X .TITLE Pop-Up Menu Help
XSELECTING OPTIONS:
X    To select an option press the "up arrow key",
X    "k", "down arrow key", "j" to place bar on
X    option and press "return".
X
X    KEY_CANCEL (esc)   - Cancel selection.
X\fBpopmenu\fP
X
X\fBGETINPUT\fP
X .TITLE GETINPUT Help
XMover Keys:
X        KEY_RETURN  (^m)    Traverse forwards through the fields.
X	.
X	. (etc.  see GETINPUT)
X	.
X        KEY_PRINT  (^p)     Print screen to lp.
X\fBGETINPUT\fP
X
X\fBhelp\fP
X .TITLE Using Help
XHelp displays consist of a description displayed in a window.
XIf the description doesn't fit in the window, the Up Arrow and
XDown Arrow keys can be used to view a few more lines of the 
Xdisplay.  Exiting the help system will return the display to 
Xthe state it was in when you asked for help.
X
X   The following keys are active in help:
X        KEY_CANCEL  (esc)	Exit help.
X        KEY_DOWN  (^j)	View a few more lines.
X        KEY_UP  (^k)	View the previous lines.
X        KEY_BEG  (^b)	Display first page.
X        KEY_END  (^e)	Display last page.
X        KEY_TOC  (^t)	Display help table of contents.
X\fBhelp\fP
X.fi
X
X.SH MENU INITIALIZATION FILE - (.menuinit)
XA menu initialization file can be provided that
Xcontains initialization commands
Xto menu.  This file is read when menu is first started.  The \fI.menuinit\fP
Xfile is first looked for in the current directory then in getenv("HOME")
Xthen in getenv("MENUDIR").  This file is not needed if the default settings 
Xsuffice.  
X
XBelow is listed a .menuinit 
Xfile with all the various initialization commands and their associated default 
Xvalue.  The decimal value is what is returned from a curses getch() call.  
X\fITry menu  -keys\fP.  Setting a key value to minus one disables the key, 
Xalthough the associated curses key, if any, is still active.
X
XNote: Menu(1) does character matching (case insensitive) on the option
Xdescription,
Xin addition to entering the number
Xof the option, to select a option.  The character matching is done after it
Xhas checked for any of the following keys.  So, for example, if you use the
Xdefault setting for KEY_EXITMENU (e) and you have a option titled "Enter ...".
XThe user will not be able to press a "e" for character matching on "Enter ...".
XThe exit menu process will be enabled.  This should be considered in
Xselecting your key values if full character matching is important.
X
X
X.nf
X     KEY_EXITMENU = 101	# (e)   Exit Menu Program.
X     KEY_MAINMENU = 109	# (m)   Go to main menu.
X     KEY_PREVMENU = 112	# (p)   Go to previous menu.
X     HOTKEYS			#       This causes the above menu keys to work without a carriage return.
X
X     KEY_GNAME = 103	# (g)   Go to a specific menu prompt.
X     KEY_POPGNAME = 7	# (^g)  Display "\fIGoto Menu\fP", GNAME pop menu.
X     KEY_RETURN = 13	# (^m)  Select hi-lighted menu option or traverse forwards through GETINPUT fields.
X     KEY_DOWN = 10	# (^j)  Traverse forwards through menu options or GETINPUT fields.
X			           Scroll help screen.
X     KEY_UP = 11		# (^k)  Traverse backwards through menu options or GETINPUT fields.
X			           Scroll help screen.
X     KEY_TAB = 9	# (^i)  Fast forward through menu options or GETINPUT fields.
X     KEY_BTAB = -1	#        Fast reverse through menu options or GETINPUT fields.
X     KEY_BEG = 2	# (^b)  Place cursor at beginning of a GETINPUT field.
X			           Display first page of help screen.
X     KEY_END = 5	# (^e)  Place cursor at end of input in a GETINPUT field.
X			           Display last page of help screen.
X     KEY_RIGHT = 12	# (^l)  Forward space within the GETINPUT field.
X     KEY_LEFT = 8	# (^h)  Backspace within the GETINPUT field (non-destructive).
X     KEY_BACKSPACE = 8    # (^h)  Same as KEY_LEFT.
X     KEY_EOL = 4	# (^d)  Delete from cursor to end of GETINPUT field.
X     KEY_DL = 3		# (^c)  Clear GETINPUT field and home cursor.
X     KEY_DC = 24	# (^x)  Delete a character in a GETINPUT field.
X     KEY_IC = 20		# (^t)  Toggle between type-over and insert mode in GETINPUT.
X     KEY_HELP = 63	# (?)  Display help screen.
X     KEY_TOC = 20	# (^t)  When in help display table of contents for help.
X     KEY_REFRESH = 18	# (^r)  Redraw the screen.
X     KEY_ACCEPT = 1	# (^a)  Accept all input from a GETINPUT screen.
SHAR_EOF
echo "End of part 2"
echo "File menu.1 is continued in part 3"
echo "3" > s2_seq_.tmp
exit 0