                                 xenmenu v0.8b
                                   1 Mar 1998


                               Table of Contents

   I....................................................Description of xenmenu
  II....................................................Installing xenmenu
    A...................................................Quick Install
    B...................................................Detailed Install
 III....................................................Using xenmenu
  IV....................................................Securing xenmenu
   V....................................................Programming Menus
  VI....................................................Contacts


I. Description of xenmenu

Welcome to xenmenu 0.8b.  This program is a highly customizable, text-based
menu generator for UN*X systems.  With xenmenu, users have an easy-to-
understand yet flexable menu programming language with which to create
pleasing menus quickly and easily.  These menus, stored as plain ASCII files,
can be modified on the fly and reinstalled without having to recompile
anything or halting xenmenu while reconfiguring.  Xenmenu can also be used as
a secure user shell (See Section IV).

This is the first BETA release of xenmenu.  Although the code is now stable
enough to move out of the ALPHA stage, there are still probably bugs, the
installation process is not as easy as if could be, and the documentation may
not be complete.


II. Installing xenmenu

Xenmenu was written on and for the Linux operating system, but should compile
and run on most any UN*X system with an standard C compiler.  It has been
tested on BSDI 3.1 and Solaris 2.5.1 systems.  To compile xenmenu on your
system, follow one of the following procedures.

A. Quick Install

There is a script called install.sh that will allow you to configure and
install xenmenu and all of the support programs.  This script is not tested
really and is not as rhobust as it should be.  It is suggested that you follow
the Detailed Install instructions instead.

B. Detailed Install

1. Visit http://www.cs.purdue.edu/homes/steinkf/programs/xenmenu to get the
   latest version.
2. Unpack the source somewhere on the system that will be used to compile it.
   If you downloaded xenmenu-0.8b.tar.gz, entering

     gzip -d -c xenmenu-0.8b.tar.gz | tar xf -

   should decompress the package.  If you downloaded xenmenu-0.8a.tar.Z, then

     uncompress -c xenmenu-0.8b.tar.Z | tar xf -

   should decompress the package.  After unpacking the source, you will have a
   directory called xenmenu-0.8b.  Change into that directory, (e.g. type cd
   xenmenu-0.8b).
3. Run the configure script, (type ./configure).
4. Edit config.h (optional) and change any of the options that you want to.
   All of the options are documented in detail within the file.
5. Edit get_input.h (optional) and change any of the options that you want to.
   All of the options are documented in detail within the file.
6. Edit Makefile and change anything necessary.
7. Type make.  There should be no warnings or errors, (if there are, please
   send a note to the contact listed in Section VI).
8. If there are no errors or warnings generated in step 7, type make install
   to install the menu program into the directory specified in Makefile.  You
   may also run xenmenu from the directory you compiled it in.  If you want to
   do that, skip this step.
9. Make sure the default menu and menu home directory as defined in config.h,
   (if any), exist and you are ready to start writing your own menus (See
   Section V).

NOTE: The directory contrib contains some sample programs that you may find
      useful.  Please see the README in that directory for more information.
      There are also sample menus and text files in the sample_menus and
      sample_text directories.


III. Using xenmenu

Xenmenu can be called simply by typing xenmenu in which case it will attempt to
load and run the default menu as defined in config.h.  To run a menu besides
the default one, just run xenmenu as  menu <menufile>  where <menufile> is the
name of the menu you want to run.  If <menufile> resides in any directory
besides the menu home, (as defined in config.h), or the current directory, you
must include a pathname to <menufile>.  If security is set so that only menus
in a certain directory may be loaded, then you will not be able to load menus
under any other directory tree.  If multiple <menufile> arguments are given,
then only the first valid menu found is used.

You may also call menu with the -h argument to get a help description, or with
the -v argument to get a version statement.  If the -h or -v arguments appear
anywhere on the command line, than the first instance of either argument is
executed and no menu is loaded, (even if a menu file is given).

If no MAINMENU is defined in the config.h file, then you must supply menu with
the name of a menu to load.

Environment variables may be set within various configuration files that
xenmenu parses when loading.  The names of these files are defined in
config.h, (USERCONFIG, SYSCONFIG, and SECURECONFIG).  The format of these
files are:

ENVIRONMENT_VARIABLE VALUE

The ENVIRONMENT_VARIABLE is the name of the environment variable that you want
to set, (e.g. EDITOR), and VALUE is the value you want to set it to, (e.g.
/bin/vi).  If VALUE is not given, then ENVIRONMENT_VARIABLE is cleared.  The
configuration files, (if defined in config.h), are parsed in the following
order: SYSCONFIG, USERCONFIG, SECURECONFIG.  This means that if an environment
variable appears in more than one of the configuration files, the last file to
be parsed which contains the definition is what the variable will be set to.

Programs may also be run from within the configuration files by using the
following format:

run PROGRAM

The PROGRAM is the name of the program that you want to execute.  If SECURERUN
is defined in config.h, then PROGRAM must reside under that directory.
Otherwise, PROGRAM should reside somewhere in the PATH environment variable,
or a full path name should be given.


IV. Securing xenmenu

Since xenmenu is very flexable about what it can do and files it can run,
a security flag has been added (See config.h) to lessen the damage a user
can do to to others.  For example, suppose a user put the following line in
a menu:

run rm -rf ~

Whenever someone ran that menu, their home directory would be erased which is
probably not wanted.  To avoid problems like this, three directories are
defined in config.h: SECURERUN, MENUDIR, and VIEWDIR.  A SECURE flag is
also set in config.h that defines the level of security you want compiled in
to xenmenu.  The value SECURE can take are integers between 0 and 7.  The
following is a breakdown of the security levels:

0 - No security checks.
1 - Only files in SECURERUN may be run (symbolic links are OK).
2 - Only menus in MENUDIR may be loaded.
4 - Only files in SECUREDIR may be read.

SECURE may be any of these numbers or the sum of any.  For example, a value
of 7 (4 + 2 + 1) stands for full security.

It is important to keep in mind that files loaded or accessed securely will
automatically take a path as set by SECURERUN, MENUDIR, or SECUREDIR.  This
means that file declaration must be from that path.  For example, take the
following run command:

run /bin/ls

If SECURERUN is set to /usr/lib/menu/bin, then the above run command will
try to run /usr/lib/menu/bin/bin/ls which is probably not the desired file.
What you would do is make a symbolic link to /bin/ls from the SECURERUN
directory and change the above line to:

run ls

Another security feature is the ability to set environment variables for users
running xenmenu that they cannot change with their own configuration file.
This is enabled by defining a SECURECONFIG in config.h and creating the file
that SECURECONFIG points to.  The SECURECONFIG file is parsed after the
USERCONFIG and SYSCONFIG files, so any values that are set by them will be
overwritten, (See Section III).


V. Programming Menus

Menu files are plain text files that contain certain options and arguments.
Comments can be inserted into the menu file by inserting a # character as the
first character on the line.  Blank lines are ignored.  Sample menus may be
found in the sample_menus directory.

The following is a list of all the commands you can include in a menu file
and a description of what that command does.  Options in <> marks are required
arguments while ones inside [] marks are optional.

checkcase                Turns on case sensitive checking for input.  This
                         means that an option 'p' will be different than an
                         option 'P'.  This must be defined BEFORE any
                         options are defined.
nocheckcase              Turns off case sensitive checking for input.  This
                         is the default.
center       <string>    Centers the given string on the screen.  The string
                         will be "word-wrapped" as needed.
columns      [number]    Sets the number of columns to print options in to
                         [number].  You can change columns within the menu so
                         some options are printed one way and others another.
                         If [number] is not defined, then 1 column is used.
header       [header]    Defines the menu header to be [header].  If header
                         is blank, then MENUHEAD as defined in config.h is
                         used.
name         [name]      Defines the menu name to be [name].  If [name] is
                         blank, then [name] is cleared.
notype                   Surpresses the printing of the option type, (i.e.
                         menu, file, etc.) after the option name.
opttail      [string]    Defines [string] as the string to be printed after
                         an option value, (it is what seperates the option
                         value and the option name).
print [-n]   [string]    Prints [string] to the screen.  If no string is
                         defined, a blank line will be printed.  If [string]
                         contains something between '' marks, it is taken as a
                         command to be run.  To print a ' character, enter it
                         as ''.  Environment variables may be printed by
                         preceeding them with a $ mark.  To print a $
                         character, enter it as $$.  If the -n argument is
                         given, than a newline is not appended to the end of
                         [string].  Usually, all leading spaces and tabs are
                         removed from [string] before it is printed to the
                         screen.  In order to print leading spaces, begin the
                         string with a double quote.  Any double quotes within
                         the string are treated as literals and printed to the
                         screen.  A double quote found at the end of a string,
                         if the string begins with a double quote), is not
                         printed, however.  A double quote may also be used if
                         you want to print a -n at the begining of the string.
printfile    <file>      Prints the <file> to the screen.  If SECURE,
                         (defined in config.h), is > 4, then the path to
                         <file> is taken from SECUREDIR, otherwise <file>
                         should contain a path.
printheader              Prints the menu header.  The [header] will be
                         printed on the left side of the screen and the
                         [name] on the right side.  A default header value,
                         defined in config.h is used if header is not
                         defined.  No name is printed if not defined.
printline    [string]    Prints a line across the screen.  If [string] is
                         not defined, a line of dashes will be printed,
                         otherwise a line composed of [string] will be
                         printed.
prompt       [string]    Sets the menu prompt to [string].  If [string] is
                         not defined, then DEFAULTPROMPT defined in config.h
                         is used.  NOTE: Everything after the keyword prompt
                         and a space is taken as the prompt, (including
                         spaces).
run          <file>      Runs the defined file.  If SECURE, (defined in
                         config.h), is a 1, 3, 5, or 7, then the path to
                         <file> is taken from SECURERUN, otherwise <file>
                         should contain a path.
type                     Prints the option type, (i.e. menu, file, etc.) after
                         the option name.  This is the default.

Menu options are defined as follows:

option {
   <menu definitions>
}

The following menu definitions are recgonized:

NOTE: At least 1 of file, menu, run, or exit should be used in an option
      declaration.  If more then 1 is given, then the last one defined will
      be used, but only 1 should be defined within an option.

exit                    This means that the menu will exit if this option
                        is chosen.
file         <file>     This is the filename that will be read if the menu
                        option is chosen.  If SECURE, (defined in config.h),
                        is > 4, then the path to <file> will be taken from
                        SECUREDIR, otherwise <file> should contain a path.
menu         <file>     This means that the menu <file> will be loaded if
                        this option is picked.  If SECURE, (defined in
                        config.h), is a 2, 3, 6, or 7, then the path to
                        <file> is taken from MENUHOME, otherwise <file>
                        should contain a path.
run          <file>     This means that the program <file> will be run if
                        this option is picked.  If SECURE, (defined in
                        config.h), is a 1, 3, 5, or 7, then the path to
                        <file> is taken from SECURERUN, otherwise <file>
                        should contain a path.

comment      <comment>  This is an optional field which holds a description
                        of the menu item.
name         <name>     This is the name of the option.
noprint                 This will cause the option not to be printed to
                        the screen.
value        <value>    This is an optional field that holds the menu
                        "value" or what you press to access this option.
                        NOTE: Values will be automatically assigned by the
                        menu if none is given.


VI. Contacts

All comments, questions, and bug reports can be sent to Karyl F. Stein via
E-Mail to xenon@xenos.net.  If you are submitting a bug report, please be sure
to include the operating system and compiler being used as well as all error
messages; the more details the better.  Please see the file BUGS for a list of
known problems.

If you would like to contribute programs to the xenmenu distribution, please
contact xenon@xenos.net.
