FF0000">
UMENU Installation, Configuration, Education,
Operation and Troubleshooting
Copyright (C) 1999-2002 by Steve Litt
DISTRIBUTED AS IS: NO WARRANTEE!
See file COPYING in the program directory, or obtain
a copy of the GNU GPL from:
Free Software Foundation, Inc.
59 Temple Place, Suite 330
Boston, MA 02111-1307 USA
http://www.fsf.org/copyleft/gpl.html
Page Navigation
|
Other Navigation
|
Installation
Note: The 0.6.0 (alpha) version of UMENU works with Linux and has been
adapted to several Unices, and it has even been adapted to Windows, but
only the Linux version is available here. Later versions will work with
all Unices and possibly long-filename Windows without code changes at your
facility.
-
unzip or gunzip/tar --extract to a directory tree
-
Go to the directory below which you want to install the UMENU tree (let's
call it whatever)
- the UMENU tree (let's
call it whatever)
-
place umenu-0.6.0.tar.gz there
-
If the browser swaps underscores for some of the dots, i.e. umenu-0_6_0_tar.gz
just work with the filenames it gives you in the following steps.
-
gunzip umenu-0.6.0.tar.gz
-
tar -p --extract --file=umenu-0.6.0.tar --verbose
-
Go to the program directory just under the tree's root (whatever/umenu)
-
Issue the command perl -w ./umenu.pl x
-
The included x menu should run. Troubleshoot as necessary.
-
Try the command ./umenu.pl. x
-
If it doesn't work when the same command preceeded by perl did, there's
probably a problem with the #!/usr/bin/perl -w line at the top
of umenu.pl, getch, and/or some of the other .pl files. You can find the
location of perl on your system by doing the which perl command.
Fix the source files as necessary.
-
If you wish an easy way to access UMENU from any directory, modify line
1 of shellscript whatever/umenu/program/mm so it changes to the program
directory, then copy it to a directory on your path (like /usr/bin), and
make it executable. On multiuser systems, get permission from the administrator
to do this.
Configuration
To Correct Perl location
At the top of each .pl and .pm file in the program directory, there's a
line starting with #!/usr/bin/perl -w. Be sure to set that line
to the path for Perl on your machine. You can find the path to Perl by
issuing the command: n find the path to Perl by
issuing the command: which perl
After completing this step, you can run the menu with the ./umenu.pl
z command instead of including the perl command.
To Change the location of the Config file
The default location of the UMENU config file is whatever/umenu/program/umenu.cnf.
This is perfect on a single user machine, or on a multiuser machine where
all users use the same menuing system (and this is the usual case). However,
if, for a particular user, you want to change the location of his configuration
file, simply create and export environment variable UMENU_CONFIG with the
completely qualified path/filename to the config file the user needs to
use. Note that some per-user flexibility can be obtained using the default
config file (whatever/umenu/umenu.cfg).
To Change locations of menu definition files and temporary script directories
The default umenu.cfg contains these two lines:
menudir=../menudir/
scriptdir=$HOME/
They can be in any order. They must be accompanied by a trailing directory
separator (/ for Linux, \ for Win). Note that if it contains the string
'$HOME', the user's home subdirectory will replace that string. Except
in the case of the $HOME substitution, if a directory does not start with
a directory separator (or a drive, colon, and directory separator), it
is RELATIVE to the current directory. Since UMENU can be started only from
its program directory, the current directory will be the program directory
(whatever/umenu/program). It's the use of relative directories that allows
the UMENU program to function from a simple copy type installation.
The menudir line tells the program to where look for menu definition
files (the files that give the menu its submenus and commands). This is
a way to let each user have his or her own menu. However, given that there
can be 25 menus in the menudir directory (a-z except q), per-user menuing
is probably overkill for most.
The scriptdir line tells UMENU where to put temporary script files.
Those temporary script files are what actually run the desired command.
The user must have create and write rights to that directory, which is
why we defaulted it to $HOME. Note that normally functioning menu programs
will erase these script files immediately after completion of the command,
so there's normally no buildup.
To Change menu definitions
;
To Change menu definitions
A directory can hold up to 25 main menus (a-z except q). The main menu
invoked depends on the first argument after the ./umenu.pl command. Each
main menu can have a reasonable submenu hierarchy below it (reasonable
is 7 for msdos and win31, and over 30 for OS'es with long filenames). The
operation of each menu and submenu is governed by its Menu Definition File.
The Menu Definition File naming convention is as follows:
-
Main menu: @.mnu where @ is the letter representing the main menu.
-
Submenus: @$.mnu where @ is the letter representing the main menu, and
$ is the sequence of letters typed by the user to reach the submenu.
Changing menu definitions with a text editor
A single Menu Definition File governs the look and behavior of a single
menu or submenu. The naming convention is described in the previous paragraph.
Menu Definition Files have a specified structure. They are comprised
newline delimited lines. Each line can be any reasonable length. Menu programs
should function with lines up to 1024 characters in length. However, it's
best for menu designers to try to keep lines under 255 characters. Note
that in the future the Menu Definition File Specification will allow continuation
lines, relieving the menu designer from such artificial restraints.
Each line is comprised of three areas:
-
Area 1: The first character. Defines the function of the line, which is
a configuration option.
-
Area 2: The second character. Reserved for later use. At present used only
for visual separation. We recommend always putting an underscore in area
2. At present this area is ignored by UMENU.
-
Area 3: The rest of the line. The configuration data for the configuration
option declared in area 1.
The Menu Definition File is comprised of several Choice Zones. Each Choice
Zone begins with a Letter Line (L in column 1), and ends just before either
the next Letter Line or EOF. Each Choice Zone contains all info necessary
to display and handle a menu choice. Any information BEFORE the first u choice. Any information BEFORE the first Letter
Line pertains to the current submenu, not to one of its choices. Here are
descriptions of the various types of lines. The columns represent the char
1 flag, a short description of the option, whether it's required or optional,
and description of the data for that option:
L Letter Line req The letter pressed to invoke this choice
T Text Line req The choice description printed on the menu
C Command Line req Command to be run, or a special pseudo command
D Directory Line opt The working directory for the command
V driVe Line opt The working drive for the command (dos/win only)
P Prepath Line opt Path to add to the front of execution path
S Stop Line opt Any value pauses for user read after cmd execution
B Background line opt Runs entire script in the background
# Comment Line opt Ignored by menu program
E Env Var Line opt Environment var set before execution, unset after
= Special Line n/a For config programs, ignored by menu program
Notes:
-
Once again, a choice consists of everything from a Letter Line to, but
not including, the next Letter Line or EOF, whichever comes first. Anythingr comes first. Anything
above the first Letter Line pertains to the present submenu, not to a choice.
At the present time, the menu program recognizes only a T line above the
first letter. That T line is used as the menu's title.
-
Of the options acted on by the menu program (in other words, not # or =
or a character not defined above), only E can appear multiple times per
choice. Multiple occurrences per choice of any other options is a non-fatal
error, and only the first copy of a given option is recognized.
-
Prepath must be consistent with the OS, and must end with a path separator.
In other words, in Linux it might be /usr/bin:/sbin: while in
Windows it might be c:\windows;c:\windows\command;
-
All lines starting with characters not enumerated above, including any
that start with lower case letters, are ignored by the menu program.
-
Choice Letters with value Q hard code to terminate the present menu, and
either go up a level or leave the Univeral Menu System. This is done to
make menu authoring simpler, and to promote uniformity. Since the user
can press one too many Q's and accidentally exit the menu system, it's
often desirable to forgo the Q on the main menu, and instead have an X
(standing for eXit), with a command of ^. That way the X button will be
the only one that exits the entire system, while the Q button can quickly
move up the hierarchy.
Pseudo Commands
Pseudo commands consist of a single piece of punctuation. Instead of issuing
commands to the operating system shell, Pseudo Commands invoke menu navigation.
A carat (^) causes execution of the next menu up (equivalent to quitting
out of a menu). A tilde (~) tells causes execution of the next menu down,
specifically, the menu whose Menu Definition File consists of the the present
one with the choice's letter tacked on. In oth the choice's letter tacked on. In other words, if the user presses
the B key while in menu ra.mnu, and the C line under the Letter
Line whose data is B contains a tilde, the user will be presented with
menu rab.mnu.
Special Lines
Special lines start with equal signs (=), and are used only in configuration
programs. Configuration programs pass two Choice Zones: the source and
the destination. In that way error checking and file copying can be done
correctly. Here are examples the two special lines in use at present:
=_MENU=BA
=_BELOW=F
If we assume these are from the source record, the first line says that
the choice came out of the B menu, while the second says that on the BA
menu the choice was below the F choice.
If we assume these are from the destination record, the first line says
put it in the BA menu, and the second says put it below the F choice on
the BA menu.
Changing menu definitions with the supplied utilites
ATTENTION: Soon after 3/4/2002, a
new language called EMDL (Easy Menu Definition Language) will be documented,
and a free software EMDL to UMENU converter will be available from Troubleshooters.Com.
Configuring a menu system with EMDL is an order of magnitude easier than
editing individual UMENU .mnu files or the utilities described in this
section. Once the EMDL to UMENU converter is available, the utilities described
in this section will be DEPRECATED!
Note: These utilities are not tested well. Always back
up your Menu Definition Files before using these utilities.
The following utilities can add, delete and copy menu items, with submenu
hierchies if appropriate, by extracting, modifying, adding or deleting
menu data via source/destination choice pairs. The choice pairs are piped
between the utilities. These utilities must be in the same directory as
the OS, CHOICE & CONFIG .pm's, and must have the correct #!perl path
at their tops.
get.pl Extracts a choice (arg1) from a menu (arg0), pipes it on
chngBel.pl Changes choice position from stdin, pipes it on
chngCmd.pl Changes choice command from stdin, pipes it on
chngLtr.pl Changes choice letter from stdin, pipes it on
chngMnu.pl Changes menu of choice from stdin, pipes it on
put.pl Inserts choice from stdin into menu. No args -- all data in stdin
del.pl Deletes choice (arg1) from menu(arg0)
new.pl Creates choice records for new item, pipes it on
stdMnu.pl Adds all optional lines to choice from stdin, pipes it on
newMnu.pl Creates a new Menu Definition File
get.pl
Reads a choice (arg1) from a menu (arg0), and creates a source/destination
choice pair, which it passes on to stdout. At this point the source and
destination options are identical -- it's up to the following filters to
change the destination information.
chngBel.pl
Recieves the choice pair from stdin, and changes the destination's "Below"
letter to the value of its arg0, then passes it on to the nethen passes it on to the next filter via
stdout. It should be noted that a "Below" letter of carat (^) means "put
it at the top" of the destination menu.
chngCmd.pl
Recieves the choice pair from stdin, and changes the destination's command
to the value of its arg0, then passes it on to the next filter via stdout.
chngLtr.pl
Recieves the choice pair from stdin, and changes the destination's Choice
Letter to the value of its arg0, then passes it on to the next filter via
stdout.
chngMnu.pl
Recieves the choice pair from stdin, and changes the destination's menu
string (mainmenu letter plus keystroke sequence to the submenu) to the
value of its arg0, then passes it on to the next filter via stdout.
put.pl
Recieves the choice pair from stdin, evaluates all the changes between
source and destination, checks to make sure it's a legal operation (doesn't
overwrite anything, etc), then properly inserts the item into the destination's
menu at the proper "below" position, and does any necessary submenu copies.
Copying or moving a choice
A copy is done using a get, any filters needed to change letters, menus,
positions, etc, and a put. A move is done by copying, as explained in the
previous sentence, and then invoking del.pl, as explained in the next subsection.
del.pl
Deletes a choice (arg1) from a menu (arg0), including deletion of all that
choice's submenus. Requires the user to confirm by typing the word "delete".rm by typing the word "delete".
The most frequent use of del.pl is to make a copy operation into a move.
new.pl Creates choice records
for new item, pipes it on
Creates a new choice pair, with the destination having a menu indicated
by arg0, and a position (below) indicated by arg1, and pipes it to stdout
for further processing by filters and eventually put.pl.
stdMnu.pl
Recieves the choice pair from stdin, and "flushes out" the destination
by adding lines for all options. These added lines do not have data starting
in column 3. The main purpose of stdMnu.pl is to feed into an edit form
(implemented as a filter), but the edit form has not been created yet.
newMnu.pl Creates a new Menu Definition File
Creates a Menu Definition File, whose filename (minus the .mnu) is arg0.
The new Menu Definition File has a dummy title and a Quit choice, and nothing
else. Note that newMnu.pl neither reads from stdin nor writes to stdout.
It is not part of the filter chain.
Putting It All Together
These commands are combined, with the help of UMENU's prompted argument
substitution, on the UMENU distribution menu (menu x). From the main menu,
press C for configuration, M for menu, and there it is. If you want to
see how these commands are constructed (and this is probably the best UMENU
lesson you can take), press the v on the xcm menu to go into vi, and pull
up file xcm.mnu (use the :e xcm.mnu syntax).
Education
The best way to learn UMENU authoring is to examine existing menus, and
change them. For that reason, the distribution comes with the UMENU distribution
menu in directories whatever/umenu/menudir and whatever/umenu/menudir/org.
The one in org is intended to serve as the original, in case you need to
restore the original after a mistake.
As you develop more sophisticated menus, the files in whatever/umenu/menudir
will very definitely umenu/menudir
will very definitely become data you need to back up on a regular basis.
You'll ABSOLUTELY want to back them up before installing a new (or restoring
the same) version of UMENU.
If the time comes when you'd prefer to keep your Menu Definition Files
in a different place (probably with the rest of the data you back up),
it's as simple as moving them to another directory and changing the menudir=
line of the UMENU configuration file (default location, whatever/umenu/program/umenu.cnf,
changable with the UMENU_CONFIG environment variable).
Operation
Here is how to invoke the menu distributed with this UMENU distribution
(menu x)
-
Go to the program directory (whatever/umenu/program)
-
perl -w umenu.pl x
-
or ./umenu.pl x
if all perl #! lines point to perl.
-
Navigate the system by pressing keys. Note that submenus are denoted with
an elipses (...) before the item on the menu. Anything without an elipses
is either a command, or it quits out of the submenu or menu.
As of version 0.6.0, the following command line options are available:
--terminate
This option causes UMENU to terminate after running a command, instead
of going back to the menu. This option is intended for those wanting to
use UMENU as a "Start Menu".
--banneroff
This option removes the GNU GPL banner displayed upon exit from UMENU.banner displayed upon exit from UMENU.
--help
Provides some limited help text for UMENU.
--diag
Runs UMENU in the "diagnostic mode". This option replaces the old "D" second
argument of the old UMENU, which no longer functions. The "D" as the second
arg has been removed, so be sure to use --diag to run in diagnostic mode.
--license
Will display the GNU GPL license and/or information about the use of that
license in this program, but is not implemented yet.
Troubleshooting
In generalh1>
In general, read the documentation and use the Universal Troubleshooting
Process as outlined at http://www.troubleshooters.com/tuni.htm.
More will be added to this troubleshooting section as time permits.
Troubleshooting an Initial Installation
The defaults have been designed to produce a working menu. Always get the
default configuration to work before attempting any changes. Here are some
steps to take when the default configuration fails to produce a menu.
-
Make sure you're on a Linux box. The 0.6.0 version of UMENU works with
nothing else, at least without minor code changes.
-
Make sure there's no UMENU_CONFIG environment variable. If there is, get
rid of it.
-
Make sure the following files exist in whatever/umenu/program:
-
umenu.cnf
-
umenu.pl
-
OS.pm
-
CONFIG.pm
-
CHOICE.pm
-
UMENUGLOBAL.pm
Make sure umenu.cnf looks like the following:
menudir=../menudir/
scriptdir=$HOME/ |
Symptoms and Solutions
Commands with an S record don't pause like they're supposed to
Menu choices containing an S record like this:
S_1
or
S_0
or anything else after the underscore
Such a choice should pause after execution of the command, and wait for
a user keystroke.
Probably due to a bad getch file in the program directory (whatever/umenu/program).
Make sure getch is executable for all, and that its top line has the proper
path to perl (typically #!/usr/bin/perl -w). You can find the
path to perl by doing the which perl command.
h to perl by doing the which perl command.
Menu works with perl ./umenu.pl x or perl umenu.pl but
not ./umenu.pl x
For some reason umenu.pl isn't executable. This can be either that it needs
a chmod a+x command, or that its path to perl on the top line is wrong.
The top line should look like this:
#!/directory_containing_perl/perl -w
The directory containing perl is typically, but not always, /usr/bin. You
can find the path to perl on your machine by doing this command:
which perl