UCLink Menu System(1)

NAME
menu- UCLink Menu System

SYNOPSIS
menu [-d] [-t]

DESCRIPTION
The UCLink menu system provides a simple menu interface for users on a UNIX system. The motivation behind its development was to provide a simple, easy to use interface for novice users for commands and applications on a system used for email and Internet access. However, the design is general. The menus and commands corresponding to menu entries are specified in a configuration file, and can be changed without changing the program.

It is designed to be invoked at the end of the user's .login file, probably by exec menu; then exiting the menu system will log the user off.

OPTIONS
The options are mainly for debugging purposes:

-d  dumps all the nodes in the internal table.

-t  lists all the entries in the menu system, indented to show the menu levels.

Menu Interface
The menu interface is patterned after the interface in the UNIX Gopher Client developed at the University of Minnesota. The system may be used on any type of terminal or windowing system and uses the full length of the window.

As the system is designed to be used by novices and to be invoked by exec menu to become the user's shell, interrupts and jobs control are suspended while in the menu.

The first time the user uses the menu system, an introduction is printed out.

The user can use any of several methods to navigate in the menu system. Here is a sample menu:

		The Post Office
-->	1.  Use Pine to send and receive mail.
	2.  List messages in my "inbox".
	3.  List most recent messages in my "inbox".
	4.  Set up mail forwarding or a vacation message/
	5.  Managing mailing lists/
	6.  Use the BSD "mail" system/

The arrow, "-->", indicates the current position in the menu. A line ending in "." indicates a command; a line ending in "/" indicates a menu.

You can move within a menu by pressing the down and up arrow keys. To execute a command or bring up a menu, move to its line and press the right arrow. To return to a previous menu, press the left arrow or "u".

The vi editor commands "j", "k", "l", "h", and the pico/jove/emacs editor commands cntrl-n, cntrl-p, cntrl-f, cntrl-b are equivalent to down-arrow, up-arrow, right-arrow, left-arrow.

Entering a line number moves to that line and invokes that command or menu.

Entering "/" followed by a string goes to the next line in the current menu containing that string, and invokes that command or menu.

Pressing "m" results in switching to the main, i.e. initial, menu.

When "q" is pressed, the system asks the user if the user wants to quit. If the user enters "y", the menu system is exited. "Q" exits with no question. If the menu system is invoked by "menu", exiting returns to the shell. If it is invoked by "exec menu", then exiting logs off the user.

Both control-r and control-l redraw the screen.

"?" causes a description of menu system commands to be displayed.

"*" causes a short message to be displayed describing the current menu entry, i.e. the entry to the right of the arrow, to be written on the bottom of the screen.

Short Cuts
The UCLink menu system allows the user to define short cuts. The short cuts are invoked by typing a letter which stands for the short cut; the defaults are:

    f  "finger"
    g  UCLink Gopher
    n  read Usenet news
    p  Pine mail system
    t  "talk"
    x  UNIX shell

For example, normally to access Pine you must first go to the Post office menu, and then select Pine. Using the "p" short cut, you can access Pine directly from any menu by pressing "p", without going through the "Post office" menu.

You can go to a menu of the sort cuts by pressing "v".

Short cuts are similar to bookmarks in Gopher, except that short cuts are named with letters and can be invoked at any time without needing to go through the short cut menu.

To define a short cut for the current line, press "a". Then the menu system prompts you to enter a letter to name the short cut or to press Return to cancel defining the short cut. Pressing "A" adds a short cut for the current menu.

Letters used by the menu system, e.g. "q" for quit, can not be used for short cuts. All other letters may be used. Lower case and upper case are treated separately; e.g. you can use "b" and "B" to designate separate short cuts.

There is a limit of 15 short cuts. Short cuts can be deleted by pressing "v" to go to the short cut menu and pressing "d" at the appropriate line. You can even delete the default short cuts.

If you define or delete short cuts, this is remembered in the file .menurc in your home directory.

Environment Variables

When the menu system runs, it needs to know the name of a directory containing programs, the configuration file, help files, etc. The default is built into the program, but can be overriden by setting the MENU_DIR environment variable before invoking the menu system.

When the menu system starts up, it sets the following environment variables:

MENU_LIB - the directory which contains scripts and binaries which may be invoked by the menu system but which are not standard UNIX commands. This directory is added to the UNIX search path. MENU_LIB is set to $MENU_DIR/lib.

USER - this is set by looking in the password file for the current logon name.

NAME - if not already set, this is set from the first subfield of the gecos field of the password file, or, if that is null, it is set to "no name".

EDITOR - if not already set, it is set to the value of the VISUAL environment variable, or if that is not set, it is set by default to "pico".

NEWS_READER - if not already set, it is set by default to "tin".

PAGER - if not already set, it is set by default to "more -d".

INTERNALS

The system consists of three parts: the menu driver program, the menu configuration file, and a library of programs and scripts to implement menu selections which don't correspond to UNIX commands. The configuration file, menu.config defines the menus to be displayed and the corresponding commands to be executed.

The menu configuration file has two parts, the first part specifies the menus and the second part specifies a default list of shortcuts. Each definition of a menu or command uses two lines; the first line specifies the type, either command or menu, a token of up to 12 characters to be used as a name in menu descriptions, and a title to be displayed in menus. The second line of a command entry begins with "==" followed by the command to execute if this menu entry is selected. Here is an example:
    CMND frm_tail List most recent messages in my "inbox"
    ==from | tail -20
The name is "frm_tail"; the title is List most recent messages in my "inbox". If selected, the command "from | tail -20" is executed. The name "frm_tail" is only for internal use only.

The second line of a command entry generally starts with two equal signs, i.e. "==". It is possible to specify an option between the two equal signs. The options are:

=e= This entry may change an environment variable. The menu system will fork the script to execute the command. However the script can not change an environment variable in its parent, the menu system. When this option is specified, after the script has been executed, the menu system checks if the last line of the user's .cshrc is a setenv command. If so, the menu system interprets that command and saves the environment variable value in the environment of the menu system. This makes it possible for the menu to have entries to choose a news reader, editor, pager, etc. and have these take effect immediately. Note that the script better make sure there are no other definitions of this environment variable in .cshrc or .login .

=g= This command will invoke a gopher client and connect to a gopher server. Before invoking the gopher client, the screen is cleared and a warning is displayed:

    You are about to enter the Internet Gopher system
    Type "q" to quit Gopher and return to the UCLink Menu System
    Now Connecting to XXX, port YYY

    Then the user is prompted as to whether he or she really wants to leave the menu system or whether they want to cancel the request. This special interface was added because early menu system users lost track of when they were in the menu system and when they were in a gopher.

=t= This entry uses telnet or tn3270 to connect to a remote host. Before connecting, the screen is cleared and a warning is displayed:

    Warning!!!!!, you are about to leave the UCLink
    menu system and connect to another host.
    If you get stuck, press the control key and the "]" key,
    and then type quit.
    Now Connecting to XXX

    Then the user is prompted as to whether or not he or she really wants to leave the menu system.

=i= This option enables interrupts and special control characters, e.g. control-Z for suspend, during the execution of this entry. This is used in the entry which starts up a normal UNIX shell.

Two special tokens are recognized in commands: $host and $etc. $etc is replaced by $MENU_DIR/etc, and is the location of many text files, as in the command: ==$PAGER $etc/Intro.text $host causes the menu system to prompt for a host and to fill in that host in the command string. E.g. the command string for starting an ftp session is: ==ftp $host

A menu entry consists of two lines; the first contains the word MENU in uppercase letters, then the token used as a name for the menu, then the title to be displayed when this entry is in a menu. The second line consists of a list of names of entries which make up this menu. In the following example, the menu titled The post office includes six entries:

    MENU PostOf The post office
    pine from frm_tail Forwrdng Mail_lists Othr_mls

Entries in a menu may be either commands or menus. They are listed in the menu in the order specified. A command or menu can occur in several different menus; i.e. the menu system is organized more like a graph or web than a tree.

Two entries must exist, a menu named "main" where the menu system starts, and an entry named "Short_Cuts" which is the menu containing the list of short cuts.

Blanks lines and lines beginning with "#" are interpreted as comments. A line beginning with "End-Menu" terminates the definition of the menus.

The list of default short cuts appears after the "End-Menu" line. These consist of "ShortCut:" followed by a letter followed by the entry name for the command or menu, e.g.:

    ShortCut: f finger
    ShortCut: g uclnk-gphr
    ShortCut: n newsq
    ShortCut: p pine
    ShortCut: t talk
    ShortCut: x UNIX
    End
These are only used if the user does not have a list of short cuts in their .menurc file in their home directory.

LOGGING
Logging is turned on if the file $MENU_DIR/logs/Menu_logging exists. The log for a session is written to file $MENU_DIR/logs/x where x is the first letter or digit of the logon. Since many users write to the same log file, the files must be writeable by all, and are typically mode 511 and owned by "consult". Simple navigation, e.g. moving up or down a line in a menu, is not logged, but almost everything else.

Here is the log entry for a typical menu session:

    l>:annrel Sep  5 14:03
    lB:begin
    l+:pine
    lC:pine
    lT:SIGHUP
    lE:000017/00004
    l<:

Each line in the entry for a session begins with the last letter of the logon name. The first line includes the logon name and time. The next to last line includes the elapsed time in second and the number of events logged.

Since many users write to the same log, and the log is not locked for writes (logging isn't important enough to wait for), there may be simultaneous updates, so check for matching ">:" and "<:" if you really need exactness. For efficiency, the log entries are buffered internally, and written all together when the session ends. In rare cases, the log may be written out in segments, with the "B:" only in the first segment and the "E:" only in the last segment.

The types of logged records are:

    + Use a short cut
    ? Get help on menu system via "?"
    * Get help on menu item via "*"
    a Add a short cut for the current line
    A Add a short cut for the current menu
    B Begin menu session
    C Execute command
    d Delete a short cut
    E End menu session
    M Enter menu
    P Parity error (only 5/session logged)
    T Terminate via EOF, ERR (too many errors), hangup (SIGHUP)

FILES

~/.menurc
    If the user has specified short cuts, they will be listed here; otherwise it will be zero length. If this file does not exist, the introductory message in etc/Intro.text is displayed.

The following are in directory $MENU_DIR:

etc/Help.text
    The help text displayed by typing "?"
etc/Intro*
    Text for introductions to sections of the menu system. Use in commands, e.g.: "$PAGER $etc/Intro.text" displays the introduction for new users.
etc/help/*
    Text of help files displayed by "*". Name of files must be the same as the corresponding menu entry name.
etc/menu.config
    The menu configuration file
logs/[a-z0-9]
    Log files where logs are written.
logs/Menu_logging
    File whose presence indicates logging is to be done.
logs/Start_logging
    Script to turn on logging
logs/Stop_logging
    Script to turn off logging
lib/*
    Scripts invoked by commands in the menu system.

NOTES
This menu system was written by Jerry Berkman, Workstation Support Services, U.C. Berkeley.