From: pjc@pcbox.UUCP (Paul J. Condie)
Newsgroups: alt.sources
Subject: menu(1)  part 2 of 11
Message-ID: <424@pcbox.UUCP>
Date: 6 Apr 90 17:30:40 GMT


#!/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
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 parseing 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.  This 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. \ --------------------------------------------------------------------------
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.
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.
X
XThe [ REDRAW ] flag instructs menu to redraw the 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 15
X0
XAOK. Continue to parse the next keyword.
X.TP 15
X1
XQuit/Exit the menu program.
X.TP 15
X4
XReturn to previous menu and display the error message 
X"Not Authorized to run menu.".
X.TP 15
Xanything else
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  10 50
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 carraige 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.
X     KEY_CANCEL = 27	# (esc)  Cancel all input from a GETINPUT screen or cancel a pop-up menu selection.
X			           Exit a help screen.
X     KEY_SAVE = 6	# (^f)  Save a GETINPUT screen to a file.
X     KEY_PRINT = 16	# (^p)  Print a GETINPUT screen to lp.
X.fi
X
X.SH EXAMPLE menufile
X.nf
X\fB###\fR     This is a example of a menu script file.
X
X\fB .AUTHORIZE\fR  pjc nortons boink mozart
X
X\fB###\fR	Initialize function keys for TERM=5425
X\fB .UNIX\fR  echo "\\033[1;2;0;0q  HELP          h\\r\\c"
X
X\fB###\fR	Define goto menu names.
X\fB .GNAME\fR  main  main.m
X\fB .GNAME\fR  reports  reports.m
X
X\fB###\fR     Title Lines Section.
X\fB .TITLE\fR
X  Version 3.00...\\RPACIFIC * BELL\\N...$DATE
X\fB .TITLE\fR
X $MAIL...Sample Menu...\\S$TIME\\N
X\fB .TITLE\fR
X ...MAIN MENU...
X\fB .LINE\fR
X
X\fB###\fR     Left column of screen - Options
X\fB .WINDOW\fR 0 23 0 39
X\fB .SYSTEM\fR who
XList who is on the system.
X\fB .SYSTEM\fR ps -ef; \\
X	echo "Press [ Return ] to continue.\\c"; read reply
XPrint process status table.
X
X\fB###\fR     Right column of screen - Options
X\fB .WINDOW\fR 0 23 40 79 \\R SUB MENU \\N
X\fB .MENU\fR reports.m
XGo to report menu.
X
X\fB .TEXT\fP 22 50
XSelection [ ? for help ]
X.fi
X
X.SH GENERALLY ACCEPTED GUIDELINES
X.PD 0.1
X.IP -> 3
XPut a meaningful title on the top of every menu.
X.IP -> 3
XProvide symmetric balance by centering the title and the menu options
Xaround the center axis of the screen.
X.IP -> 3
XChoose an organizing principle for the menu options.
XOrganize menu hierarchies according to the tasks users will perform, rather
Xthan the structure of the software modules.
X.br
XHints in organizing options:
X.RS 6
X.IP * 3
XChronological ordering
X.IP * 3
XAscending or descending numerical ordering
X.IP * 3
XItems grouped by physical properties, (Increasing volume, weight or temperature)
X.IP * 3
XAlphabetic sequence of terms
X.IP * 3
XGrouping of related options with spatial demarcation between groups
X.IP * 3
XMost frequently used options first
X.IP * 3
XMost important options first
X.RE
X.IP -> 3
XTo facilitate scanning, put blank lines between logical groupings of menu
Xoptions and after about every fifth option in a long list.
X.IP -> 3
XLimit the number of menu choices of one screen.
XThe breadth (number of options per menu) should be no more than eight and the
Xdepth (number of levels of menus) should be no more than four.
X.IP -> 3
XUse words for your menu options that clearly and specifically describe 
Xwhat the user is selecting; use simple, active verbs to describe menu options.
XUse common, short English words that clearly describe the action that the 
Xcommand will carry out; choose words that are distinctive from one another.
X.IP -> 3
XDisplay the menu options in mixed, upper and lower case letters.
X.IP -> 3
XBe sure that any function keys that you use will operate correctly on all of
Xthe different types of keyboards the users have.
X.IP -> 3
XBe consistent in the use of menu formats, procedures, and wording; the 
Xmapping of keys to functions; the naming of menu options.
X.IP -> 3
XOptions should suggest or entail closure.  If a menu option calls another
Xmenu (.MENU) the title of the option should be the title of the called menu
Xto provide continuity.  Likewise, if a menu option calls a program (reports,
Xscreens) the title of the option should be the title of the report/screen.
X.IP -> 3
XDisplay only information that the user needs to know.
X.IP -> 3
XEvery menu should indicate how to exit from the screen.
X.IP -> 3
XAvoid hyphenation of words between lines.
X.IP -> 3
XUse abbreviation and acronyms only when they are significantly shorter than
Xthe full text and when they will be understood by the user.
X.IP -> 3
XOptions in a multiple column list should be organized in vertical columns
Xwhich are read from left to right on the screen.
X.IP -> 3
XPut a least two spaces between the longest item in a column and the beginning
Xof the next column.
X.IP -> 3
XUse highlighting to emphasize important information only.  Do not overuse
Xit.
X.IP -> 3
XA \fI.POPMENU\fP, if possible, should appear as close to and to the right 
Xof the option that selected it.  Probably a \fI.GETINPUT\fP screen should also.
X.PD
X
X.SS References
XHuman Factors Engineering, User Interface Guidelines, Pacific Bell, Sept (1987)
X.PP
XShore, John, The Sachertorte Algorithm and Other Antidotes to Computer
XAnxiety, Viking Penguid Inc. (1985)
X.IP * 3
XShore's book for the general public which translates into why designing 
Xgood user interfaces are necessary.
X.PP
XBeer, S. and Schoefer, W., Screen Development Guidelines - Draft,
XVersion 1.0, Pacific Bell, April (1987)
X.PP
XRubinstein R., and Hersch H.M., with Ledgard, H.F., The Human Factor:
XDesigning Computer Systems for People.  Digital Press, Digital Equipment
XCorporation, (1984).
X.IP * 3
XRubinstein's work is very interesting and original.  The text is readable
Xand the ideas presented are clear and attractive.  This is not a text book.
X.PP
XFuture Technology Architecture District, Proposed Pacific*Bell Screen 
XStandards For NonProgrammable Terminals,  Pacific Bell, May (1988)
X.PP
XDumas Joseph S., Designing User Interface for Software, Prentice Hall, 1988
X
X.SH CREDITS
XPaul J. Condie	    8/18/86	original author
X.br
X{att,bellcore,sun,ames,pyramid}!pacbell!pcbox!pjc
X.br
X
XIrving Griesman			GetInput(3X)
X.br
XSam S. Lok			.POPMENU enhancements
X
X.SH NOTE
XIf memory size is important modify LoadKeys.c and remove all references
Xto keywords your application does not use then relink.  This will reduce
Xthe size of menu.
X
X.SH FILES
Xmenu.hlp    -  menu help file
X.br
X/usr/local/lib/menus	- some menus you might want to use or look at.
X.br
X/usr/local/lib/menus/sample.m    -  a sample menu file
X.br
X/usr/local/lib/menus/printers.m    -  printers pop-up menu
X.br
X/usr/local/lib/menus/reportsrn.m    -  report option input screen
X
XThe library of menus may vary from machine to machine.
X
X.SH SEE ALSO
XMenuAccess(1), curses(3X), system(3), mail(1), getenv(3), 
Xlock(1), unlock(1), GetInput(3X), checkpass(1), runrealid(1).
X
X.SH WARNING
XBecause menu uses the environment to pass and save data you are limited on the
Xvolume of data you can have based upon the size of your environment.  
XThis will vary from machine to machine.  If you see the 
Xmessage "Unable to allocate environment memory..." then you have reached
Xyour limit.  Actually you've surpassed the limit or you wouldn't have
Xgotten the message.  But lets not squabble.
X
XMenu has very little intellegence built in to check if you exceed the bounds
Xof any fields.  If menu core dumps, especially will a bus error, you are
Xprobably trying to load too large a value into a field.
X
X.SH BUGS
XCurses bug - When a attribute is the last character on the line (spaces don't 
Xcount) the attributes do not get turned off until it hits the next character 
Xon the next line.
X
X.PP
XWhen you use the mail notification $MAIL the alarms get buffered up when
Xthe cursor is just sitting there, so, as soon as the user types something
Xat the keyboard all the alarms that were buffered take off, which means, you
Xget a beep...beep...beep...beep.  This doesn't happen on AT&T 3b machines
Xbut I've noticed it on SUNS and ARETE machines.
XYou should take the -DALARM off the CFLAGS in the makefile which tells
Xmenu not to use the alarm(2) to check for mail, but check when a key
Xhas been pressed.
X
X.PP
XMenu has not really been tested on terminals/windows that is not 24x80,
Xok,ok... it hasn't been tested at all.  For the most part it should work
Xfine, EXCEPT (you knew that was coming), when you want to create columns
Xof options using the .WINDOW keyword.  The parameters to .WINDOW are
Xabsolute therefore when you line up your columns for a 24x80 terminal and
Xyour menu is run on say a 34x132 terminal your columns will not be
Xcentered right.  Probably a new keyword should be introduced ".COLUMN"
Xwhich would have some intelligence built in to try to center columns within
Xthe window space.  It might have some problems going from a larger window
Xto a smaller window if the columns won't fit.
X.br
XAnyone volunteer to write this one?
X
X.PP
XTerminal attributes sometimes don't work right.  Especially when putting
Xmultiple attributes on one line.  In all cases I've seen it is a restriction
Xof the terminal (hardware).
X
X.bp
X.SH PROGRAMMING NOTES
XThis section is for those of you who want to or need to add new keywords.
X.PP
XThe keywords that have been provided should accommodate most
Xapplication menus, however, if customization is needed the following
Xmay come in handy.  If you introduce any neat new keywords (say like 
X".IF THEN ELSE") I would
Xappreciate you sending them to me so I can incorporate them.  Send your
XParse, Show, and Run functions along with a copy of \fILoadKeys.c\fP.
X.PP
XMenu is primarily driven from the LoadKeys.c module.  This 
Xmodule describes to menu what keywords it needs to scan for and what
Xaction to take when found.
XThere are four sections in LoadKeys (see LoadKeys example) each of which 
Xneed to be
Xdefined if you are introducing a new keyword.  LoadKkeys provides three areas
Xof control (sections 2,3,4), and it is important that you know what you
Xwant to accomplish at each control point:
X.TP 4
XParse
XWhat do you want menu to do with your keyword once it has found it during
Xthe parsing routine?  Any data you need to store for a later step, etc..
X.TP 4
XShow
XHow do you want your keyword displayed to the screen?  Define as NULL if
Xnot appropriate.
X.TP 4
XRun
XIf the user selects an option that is your keyword, what do you want done?
X
X.PP
XIf you want to put debugging code in your functions then the following
Xformat should be used.
X.nf
Xextern int  debug;
Xif (debug)
X{
X	fprintf (stderr, "\\n[Function] <KeyWord> ...", ...);
X}
X.fi
Xwhere [Function] is the function name and <KeyWord> is the keyword being
Xprocessed.
X
X.SS ADDING A NEW KEYWORD
X.TP 8
XStep 1:
XDecide on the name of the new keyword.  For consistency sake, I suggest, it
Xshould begin with a "." and be all in caps.  Maximum length of keyword is
XMAXKEYLENGTH (15).  Then formulate a syntax for the keyword (what the user
Xneeds to type in the menufile).
X.br
XAlso, get clear in your mind what you want done at each of the three control
Xpoints.
X
X.TP 8
XStep 2:
Xvi LoadKeys.c
X.br
XStrcpy your keyword into the next available slot in KeyWord[], under SECTION 1.
XMake sure MAXKEYS in menu.h is >= the slot you strcpy'ied your keyword into.
XSee KeyWord[] below.
X
X.TP 8
XStep 3:
XIn SECTION 2 of LoadKeys.c assign the Parse function that is going 
Xto parse your keyword.
XIt should be assigned to the same slot as in SECTION 1.  First see if one
Xof the Parse functions already written will do the job.  If so use that one,
Xif not you will have to write one.  For consistency call it Parse????.c or
XPar????.c, and declare it at the beginning of LoadKeys.c.
XAll keywords must have a parse function.
XThis function is called immediately when your keyword is found while parsing
Xthe menufile.
XSee ParseKey[]() below.
X.br
XReturn Values:
X.RS 8
X.TP 9
X0
XContinue to parse next keyword.
X.TP 9
X-1
XQuit/Exit menu program.
X.TP 9
X-2
XReturn to main menu.
X.TP 9
X-4
XNOWAYJOSE - Not authorized to run this menu.
X.TP
Xanything else
XAbort this menu and return to previous menu.
X.RE
X
X.TP 8
XStep 4:
XIn SECTION 3 of LoadKeys.c assign the Show function (if your keyword is a
Xuser selectable option) that will display the
Xoption to the screen.
XIt should be assigned to the same slot as in SECTION 1.  First see if one
Xof the Show functions already written will do the job.  If so use that one,
Xif not you will have to write one.  For consistency call it Show????.c, and
Xdeclare it at the beginning of LoadKeys.c.
XThis function is called when displaying options to the screen.
XIf you don't need a Show function for your keyword assign slot to NULL.
XSee ShowKey[]() below.
X
X.TP 8
XStep 5:
XIn SECTION 4 of LoadKeys.c assign the Run function (if your keyword is a
Xuser selectable option) that will be called when the user selects this option.
XIt should be assigned to the same slot as in SECTION 1.  First see if one
Xof the Run functions already written will do the job.  If so use that one,
Xif not you will have to write one.  For consistency call it Run????.c, and
Xdeclare it at the beginning of LoadKeys.c.
XIf you don't need a Run function for your keyword assign slot to NULL.
X.br
XReturn Values:
X.RS 8
X.TP 9
X0
XAOK, continue with normal menu processing.
X.TP 9
XMAINMENU
XGoto main menu.  This is as if the user had typed an "M".
X.TP
XPREVIOUSMENU
XGoto previous menu.  This is as if the user had typed a "P".
X.TP
XQUIT
XQuit program.  This is as if the user had typed an "E".
X.TP
XSUBMENU
XIf you are introducing
Xa new submenu keyword (like \fI.MENU\fP) the Run??? function must return 
X(SUBMENU), a #define.
XRefer to \fIRunMenu.c\fP for an example.
X.TP
XGNAMEOFFSET + gindex
XGoto a specific (.GNAME) menu.
XWhere gindex = the index into the gnames array (base 0).
XThis is as if the user had typed a goto menu.
X.RE
X
X.TP 6
XStep 6:
XCompile your new functions, LoadKeys.c  and link into menu.  
XYour KeyWord should work.
XThere should be no need to change any of the existing driver routines 
X(other than LoadKeys.c)?
X
X
X.SS char  KeyWord[]
XThis array identifies all the keywords to be scanned for in your
Xmenufile.  Maximum number of keys is "MAXKEYS" defined in menu.h
Xfile.  Increasing MAXKEYS will allow more keys.
X
X.SS "int (*ParseKey[]) (keyword, menufile, menu, KeyWord, ParseKey, gnames, gfiles, gindex, opnumber)"
X.nf
Xchar		keyword[];
XFILE		*menufile;
Xstruct MenuInfo	*menu;
Xchar		KeyWord[][MAXKEYLENGTH];
Xint		(*ParseKey[])();
Xchar		gnames[][15], gfiles[][15];
Xint		*gindex;
Xint		*opnumber;
X.fi
XArray of pointers to functions that will be called to parse the
Xkeyword when found.  Any processing you want done while program
Xis parsing your keyword should be placed in this function.
XIf you have defined a new keyword you must
Xdescribe how that keyword is to be parsed.  Unless you are doing
Xsomething special ParseOption() should do the job.
XYour new function will need to malloc struct OptionInfo if you
Xwant to store some information for the option.  The following describes
Xthe data passed to all parsing functions.
X.RS 6
X.TP 6
Xkeyword
XThe keyword that was found in menufile.
X.TP 6
X*menufile
XA pointer to your menufile.  When function returns you must leave
Xthe pointer set to read in the next keyword.
X.TP 6
X*menu
XA struct holding information about the menufile.  You need to maintain
Xthe information for later processing. The Show and Run functions use the
Xinformation you store here.  See struct MenuInfo and struct OptionInfo.
X.TP 6
Xgnames
XThe goto menu names (.GNAME) presently defined (base 0).
X.TP 6
Xgfiles
XThe menufiles associated with the goto names (base 0) (.GNAME).
X.TP 6
Xgindex
XThe number of goto names (.GNAME) presently defined.
X.TP 6
Xopnumber
XThe last option number.  This is the number that will appear to the left
Xof the option, and the number the user will type in to select the option.
XYou should increment this for the next option if your keyword will
Xcontain a option number.
XThe option number should be set to zero for options you don't want a
Xnumber to appear to the left of the option.
X.nf
X.RE
X
X/*
X**     Menu structure layout
X*/
Xstruct MenuInfo
X{
X	char			name	[15];		/* file name */
X	int			wfrow;			/* window first row */
X	int			wlrow;			/* window last row */
X	int			wfcol;			/* window first col */
X	int			wlcol;			/* window last col */
X	int			row_cursor;		/* row for cursor */
X	int			col_cursor;		/* col for cursor */
X	unsigned		boxtype;		/* 0 = no box */
X	unsigned		linetype;		/* same as box */
X	int			titlecount;
X	int			optioncount;		/* base 0 */
X	struct OptionInfo	*option	[MAXOPTION];
X	struct ScreenInfo	*srn	[MAXSCREENS+1];	/* .DEFINE_SCREEN */
X							/* NULL = EOL */
X};
X
X
Xstruct OptionInfo
X{
X	char	keyword		[MAXKEYLENGTH+1];
X	int	opnumber;				/* option number */
X	char	description	[200];
X	char	command		[MAXLEN];
X	int	row;					/* row to display */
X	int	col;					/* col to display */
X};
X
Xstruct ScreenInfo
X{
X	char			name	[30];		/* screen name */
X	char			title	[100];		/* window title */
X	int			toprow;			/* upper left corner */
X	int			leftcol;
X	int			rows;			/* # rows in win */
X	int			cols;			/* # cols in win */
X	unsigned		boxtype;		/* 0 = no box */
X	int			exitlastfield;		/* after last field */
X	char			helpfile[16];
X	char			*fielddefaults;		/* init field command */
X	struct FieldInfo	*field	[MAXFIELDS+1];
X};
X
X
Xstruct FieldInfo
X{
X	char	name	[30];				/* field name */
X	char	label	[50];				/* field label */
X	int	row;					/* start position */
X	int	col;
X	int	length;
X	int	min_input;
X	char	mask	[100];
X	char	range	[1025];
X	char	type;
X	char	adjust;
X	int	mustenter;
X	char	prompt	[100];
X	char	terminator[3];				/* field terminators */
X	int	noinput;
X};
X.fi
X.RE
X
X.SS "int (*ShowKey[]) (menu, index)"
X.nf
Xstruct MenuInfo   *menu;
Xint               index;
X
X.fi
XThe following describes the data passed to all Show functions.
XArray of pointers to functions that will be called to display
Xthat option to the screen.  Unless you are doing something special
XShowOption() should do the job.
X.RS 6
X.TP 6
X*menu
XSee above for description of menu structure.
X.br
Xmenu.option[index]->description gets displayed to the screen.
X.TP 6
Xindex
XOption number in menu structure that is to be displayed.
X
X.SS "int (*RunKey[]) (menu, opnumber, KeyWord, ParseKey, ShowKey, RunKey, gnames, gfiles, gindex)"
X.nf
Xstruct MenuInfo	*menu;
Xint		opnumber;
Xint		(*ParseKey[MAXKEYS])();
Xint		(*ShowKey[MAXKEYS])();
Xint		(*RunKey[MAXKEYS])();
Xchar		KeyWord[MAXKEYS][MAXKEYLENGTH];
Xchar		gnames[MAXGNAME][15];
Xchar		gfiles[MAXGNAME][15];
Xint		gindex;
X.fi
XThe following describes the data passed to all Run functions.
XArray of pointers to functions that will be called when the
Xuser selects the option on the screen.
X.RS 6
X.TP 6
X*option
XSee above for description of struct OptionInfo.
X.br
Xoption->command is what is to be executed for this option.
X.RE
X
X.SS LoadKeys Example:
X.nf
XLoadKeys (KeyWord, ParseKey, ShowKey, RunKey)
X
X	char	KeyWord[][10];
X	int	(*ParseKey[])(), (*ShowKey[])(), (*RunKey[])();
X{
X	int	ParseTitle(), ParseOption();
X	int	ShowOption();
X	int	RunSystem();
X
X	/*
X	**   Section 1:
X	**   	Identify the new keyword here.
X	*/
X	strcpy (KeyWord[1], ".TITLE");
X	strcpy (KeyWord[2], ".MENU");
X	strcpy (KeyWord[3], ".SYSTEM");
X
X	/*
X	**  Section 2:
X	**	Identify the parse function for the new keyword.
X	**  	Every keyword needs a parse function.
X	*/
X	ParseKey[1] = ParseTitle;
X	ParseKey[2] = ParseOption;
X	ParseKey[3] = ParseOption;
X
X	/*
X	**  Section 3:
X	**	Identify the show function for keywords that are options.
X	**  	If ShowKey is set to NULL the option will not be displayed.
X	*/
X	ShowKey[1] = NULL;	/* Title gets displayed in the parse function */
X	ShowKey[2] = ShowOption;
X	ShowKey[3] = ShowOption;
X
X	/*
X	**  Section 4:
X	**	Identify the run function for keywords that are options.
X	**  	If RunKey is set to NULL the cursor will not stop at 
X	**  	the option.  The user will not be able to select it.
X	*/
X	RunKey[1] = NULL;	/* You can't select a title */
X	RunKey[2] = RunMenu;
X	RunKey[3] = RunSystem;
X}
X.fi
X
X
X
X
X.PP
XTHE END     (whew)
SHAR_EOF
echo "File menu.1 is complete"
chmod 0644 menu.1 || echo "restore of menu.1 fails"
echo "x - extracting Main.c (Text)"
sed 's/^X//' << 'SHAR_EOF' > Main.c &&
Xstatic char Sccsid[] = "@(#)Main.c	1.9   DeltaDate 1/22/90   ExtrDate 1/22/90";
X/*	PROGRAM	   Menu  (generic)
X**	AUTHOR	   Paul J. Condie
X**	DATE	   8/18/86
X*/
X
X#include	<curses.h>
X#include	<signal.h>
X#include	"menu.h"
X
Xint	MAILCALL = FALSE;
Xint	mailrow;
Xint	mailcol;
Xint	debug = FALSE;					/* debug flag */
X
X
Xmain (argc, argv)
X
X	int		argc;
X	char		*argv[];
X{
X	FILE		*fopen(), *menufile;
X	char		*getenv();
X	char		*findfile();
X	int		shutdown();		/* clean up before exit */
X	struct MenuInfo	menu;
X	int		(*ParseKey[MAXKEYS])(), 
X			(*ShowKey[MAXKEYS])(),
X			(*RunKey[MAXKEYS])();
X	char		KeyWord[MAXKEYS][MAXKEYLENGTH];
X/*
X**	menuname keeps track of nested submenus.
X**	mptr is the index into menuname 0 = main menu
SHAR_EOF
echo "End of part 2"
echo "File Main.c is continued in part 3"
echo "3" > s2_seq_.tmp
exit 0