
LIME v0.01.1b
The definitive LInux MEnuing System!
(C)opyright 1994-1995, B. Scott Burkett, All Rights Reserved

------------------------------------------------------------------------------
INSTALLATION
------------------------------------------------------------------------------

1) cd into the ./src directory and type "make".
2) Once LIME has been successfully constructed, type "make install".  Be sure
   to edit the Makefile in the ./src directory (install path, etc).
3) Configure the control file ("./data/lime.ctl").
4) Configure your menus ("./menus/*")
5) Have at it.  You can use the sample "limelogin" file in the ./contrib
   directory as a starting point for a login wrapper.

------------------------------------------------------------------------------
LIME CONTROL FILE
------------------------------------------------------------------------------

LIME uses a "control file" to set up certain global operational parameters.
By default, LIME looks for "./data/lime.ctl", although this can be overidden
by the "-c" command line option.

LIME ignores any lines in the control file which begin with ";", "#", or "%".
In addition, blank lines are ignored.  The following is a list of the valid
keywords which may be used within the LIME control file:


BASIC CONFIGURATION KEYWORDS
----------------------------

  SYSOPNAME:  This is simply the name of the system operator.  (Not currently 
              used).

 SYSTEMNAME: The name of the system (Not currently used).

   LOCATION: The location of the site. (Not currently used).

 SCREENPATH: The location of all custom screens and newsfiles.

   MENUPATH: The location of all LIME menu definition files.

LOGFILEPATH: The path in which LIME should create its logfiles.  If this
	     keyword is omitted, then logging is disabled.  Log files take
	     on the filename of: lime.[username].log.  This allows you to
	     easily track each user.

    TIMEOUT: If specified, determines the number of seconds that a user may
	     remain idle before LIME terminates their session.  If this keyword
     	     is omitted, then LIME does not perform any timeout handling.

EXTERNAL USER HOOKS
-------------------
MAINMENUHOOK: If specified, tells LIME to run the file it points to before
	      presenting the user with the main menu.

  LOGOFFHOOK: If specified, tells LIME to run the file it points to before
	      logging the user out.

------------------------------------------------------------------------------
TERMINAL CONFIGURATION FILE
------------------------------------------------------------------------------

LIME uses ANSI compliant screen codes for utilizing color.  This seemed a bit
easier to work with than the ncurses calls.  In fact, take a look at ansi.c
for the ColorStr() function.  Pretty handy if you ask me.

In order to determine if a user's terminal is capable of handling these codes,
LIME uses a terminal configuration file.  This file should be called
"./data/limeterm.conf".

The format of each line is:  [term] [ansi_capable]

where "term" is a regular expression which represents the user's TERM setting
The "ansi_capable" value is simply, Y or N, and reflects whether or not that  
particular terminal setting supports ANSI screen sequences.

The stock limeterm.conf file should suffice for most folks.

------------------------------------------------------------------------------
MENU FILES
------------------------------------------------------------------------------

At the center of LIME is its menu engine.  While it is functional, there are
certainly a number of additional features I plan on adding in the near
future. 

First, a few basics on LIME's menu handling.  All menu files should be placed
in the directory specified by the MENUPATH keyword in your control file.  
LIME also needs the name of the starting menu (main menu).  This is passed
via the "-m" command line option (i.e. lime -mmain.mnu).

The first thing you must decide is which of LIME's two methods of menu    
handling you will employ.  LIME has an internal menu scheme.  This internal
scheme isn't necessarily the prettiest site to behold, but its quite a
charming device for lazy folks. ;-)  LIME also supports custom menu screens,
which are great for the more ambitious administrators out there.

Each menu file contains a number of keywords, each of which will be discussed
now.  The standard comment lines also apply to menu files (#, ;, %).

.externalmenu

  This keyword should only be used if you are using custom menu screens.  If
  this keyword is not specified, then LIME will use its internal menu scheme.
  Its value specifies what the "base" file name of the custom menu screen is.
  (See the section on LIME's file name conventions for more information).

	Example: .externalmenu main

.externalmenucolor

  This keyword specifies the color which should be applied to custom menu
  screens.  Its value is a standard LIME color string (see the section on
  color strings for more information).

	Example: .externalmenucolor cyan on black

.menutitle

  If using the internal menu scheme, this keyword specifies the title of
  the menu.  This keyword is REQUIRED for internal menus.  

	Example: .menutitle "Welcome to ABC, Inc! [MAIN MENU]"

.options

  This keyword designates the start of the "options" block.  This is 
  essentially where the functionality of a given menu is defined.  A number
  of menu commands may be placed after this keyword.  Each menu command
  assumes the following format:


.end

  This keyword signifies the end of the ".options" block.  This keyword
  *MUST* be present!


------------------------------------------------------------------------------
CREATING MENU OPTIONS
------------------------------------------------------------------------------

Recall the format of a menu option from the previous section:


      hotkey, command, description, grouplist, secondary field, passwd, color

Here is a quick breakdown:

  hotkey

	This represents the keystroke attached to the menu option.

  command

	May be any of the following:

		jump
			Jump to a new menu.  Place the menu name in the
			secondary field.

		return
			Return to the calling menu.
			
		showfile
			Display a file.  The file name should be placed in
			the secondary field.

		screenset
			Display a screenset.  The base name of the screenset
			should be placed in the secondary field.
		
		extern
			Execute an external command.  The command line to be
			executed should be placed in the secondary field.

		blank
			A blank entry.  In the internal menu scheme, this will
			insert a blank line on the output.  This option is
			ignored for custom menus.

		display	
			For internal menus only.  The contents of the
			secondary field are displayed to the output.

		goodbye
			Terminate the session.

  description

	This represents the description of the menu item.  This is only
	used for the internal menu scheme.

  grouplist 
	
	A list of user groups (GIDs) which have access to this option.
	More than one GID may be specified, if they are dash separated.  
	In addition, a value of "*" allows access to all groups.

  secondary field

	A catch-all data field.

   password

	If a password is desired for a given option, it may be specified
	here.  A blank value or "*" indicates no password.

   color

	If you wish to override the internal menu colors for an option,
	place the custom color string here.  This value is ignored for
	custom menus. 


  Example menu options:
  ---------------------	

  Here is a menu option which uses the hotkey "M" (or "m") to jump to a 
  menu called "mail.mnu".  Note that all groups are allowed ("*"), and
  there is no password or custom color option.

  	M,jump,Mail Facilities,*,mail.mnu

  Here is a menu option which uses the hotkey "U" to provide a UNIX
  shell.  A password of "secret" has been imposed on this option.  This
  option is only available to users who belong in the groups 0, 1, 10, or 26.
  A custom color string has also been added.

	U,extern,Shell (BASH),0-1-10-26,/bin/bash,secret,flashing red on black

  Here is that same menu option, but with the password removed:

	U,extern,Shell (BASH),0-1-10-26,/bin/bash,*,flashing red on black

  Unused fields can be skipped over by just leaving them blank as well:

	U,extern,Shell (BASH),0-1-10-26,/bin/bash,,flashing red on black

See the sample menu files which were included with the distribution for some
additional examples.

------------------------------------------------------------------------------
LIME COLOR STRINGS
------------------------------------------------------------------------------

LIME uses a rather nifty scheme for specifying colors.  Wherever LIME accepts
a custom color, it may be specified as a string, which adheres to the 
following format:

	[flashing | bright] foreground "on" background 

Examples:

	white on black			(gives you grey on black)
	bright white on black		(Gives you true white on black)
	bright black on black		(Gives you dark grey on black)
	yellow on blue			(Gives you brown on blue)
	bright yellow on blue		(Gives you true yellow on blue)
	flashing red on white		(Gives you blinking red on grey)

------------------------------------------------------------------------------
LIME FILE NAME CONVENTIONS (SCREEN SETS)
------------------------------------------------------------------------------

LIME uses a rather bizarre method of naming its text files and custom menus.
I still have no idea what prompted me to do this, but it has some useful
functionality all the same.

LIME uses the following naming convention for its text files and custom
menu screens:

SCHEME 1:

	[basename].GID.SEQUENCE.asc/ans

	where:

		basename is the base file name (news, bulletin, hello, etc)
		GID is the group ID that users need in order to view it 
		SEQUENCE is a numeric identifier (1+)
		asc/ans is either ASCII or ANSI format.

	This is the first scheme that LIME will use in order to find a file
	you specify.  For instance, if the user had a GID of 10, and you
	wanted LIME to show him the file called "welcome", it would look for:

		welcome.10.1.asc/ans
		welcome.10.2.asc/ans
		welcome.10.3.asc/ans
		.
		.
		welcome.10.n.asc/ans

	This scheme allows you to create a number of "welcome" files for all
	users who have a GID of 10. The "asc/ans" is the extension that LIME
	will tack on the end, depending on whether or not the user has an ANSI
	capable terminal or not.  if no .ans file is found, LIME will revert to
	the .asc version.  The only difference is that you should only create
	custom .ans files for users who have an ANSI capable terminal.  To be
	quite honest with you, I would just stick to plain old ASCII.  Why
	get fancy?

		
SCHEME 2:

	To continue with the "welcome" example, LIME will then attempt to
	match the following convention:
	
	[basename]SEQUENCE.asc/ans

	where:

		basename is the base file name (news, bulletin, hello, etc)
		asc/ans is the graphics extension (see SCHEME 1)

	Examples:

		welcome1.asc/ans
		welcome2.asc/ans
		welcome3.asc/ans
		.
		.	
		welcomen.asc/ans

This naming scheme is also used for menu options which use the "screenset"
command.

A few special screen set names are hardcoded into the code:

	welcome

		Shown when users first connect
	news

		Shown after welcome...

	timelimit
	
		Shown when a user times out (idles out)

	goodbye
		
		Shown when a user exits LIME

------------------------------------------------------------------------------
COMMAND LINE OPTIONS
------------------------------------------------------------------------------

-a	Force ANSI mode
-c	Specify a different control file than "lime.ctl"
-m	Specify the starting menu (required)
-d	Enable debug logging

