flash.1

.\" -*- nroff -*-
.\" Copyright 1996 Stephen Fegan (steve@netsoc.ucd.ie)
.\"
.\" This is free documentation; you can redistribute it and/or
.\" modify it under the terms of the GNU General Public License as
.\" published by the Free Software Foundation; either version 2 of
.\" the License, or (at your option) any later version.
.\"
.\" The GNU General Public License's references to "object code"
.\" and "executables" are to be interpreted as the output of any
.\" document formatting or typesetting system, including
.\" intermediate and printed output.
.\"
.\" This manual is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public
.\" License along with this manual; if not, write to the Free
.\" Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139,
.\" USA.
.\"
.TH FLASH 1 "18-May-97"
.SH NAME
flash \- A menu shell with hotkeys and process group management

.SH SYNOPSIS
.B flash [\-hVl] [\-b basedirectory] [\-d delimiter] [\-e escape] [\-c comment] [menu file]

.SH DESCRIPTION
\fBflash\fP loads \fImenu file\fP, interprets and displays it. The menu is 
made up of a combination of 
\fItoken structures\fP seperated by line breaks.

.SH OPTIONS
.TP
.I "\-h"
Print a help message and usage information.
.TP
.I "-V"
Print version information and compile\-time defaults.
.TP
.I "-b basedirectory"
Set the directory that \fBflash\fP should expect to find its configuration
files. 
.TP
.I "-d filename"
Set the debug file to \fIfilename\fP.
.TP
.I "-c command"
An ordinary shell would run \fIcommand\fP, flash just logs the attempt
to the syslog.
.TP
.I "menu file"
Load menu from \fImenu file\fP.

.SH FILE FORMAT
\fINote: I will be using `:' as the token delimiter,
`\\' as the escape character, and `#' as the
comment character throughout this document. Directive
matching is case insensitive.\fP

Flash files are made up of a series of \fItoken structures\fP 
and \fIdirectives\fP. There is a limit of one token structure or 
directive per line.

Lines beginning with `#' will be ignored by \fBflash\fP.
Characters preceded by `\\' will be treated literally by \fBflin\fP.

.SH Directives
Directives tell \fBflash\fP how to interperet text. 
.TP
.I "Menu [menu options] name"
Starts a menu named \fIname\fP, all following lines will be interpereted as 
\fImenu token structures\fP until the \fIEndMenu\fP is read. If a menu
\fImain\fP is present in the file it is stared first, otherwise the first
menu encountered is used.
.TP
.I "RCBlock [rc options]"
Interperet the following lines as \fIrc token structures\fP until 
\fIEndRCBlock\fP is read. These blocks allow configuration of \fIflash\fP
or execution of programs at run time.
.TP
.I "RCFile [rc options] filename"
Read \fIfilename\fP and interperet its  lines as \fIrc token structures\fP 
until the end of the file. 
.TP
.I "Module [module name] [module options]"
.TP
.I "Include filename [filenames...]"
Include further menu files.
.TP
.I "MainMenuName name"
Specify the name of the initial menu. Defaults to "Main".
.TP
.I "NoBox"
Default to displaying menus without border boxes.

.SH Menu [menu options] name
.PP
A number of \fImenu options\fP may be used to control the appearance 
of the menu on the screen. Options are seperated by whitespaces.
.TP
.I "NoBox"
The menu should be displayed without a border box.
.TP
.I "Left"
The menu should be displayed on the left of the screen.
.TP
.I "Right"
The menu should be displayed on the right of the screen.
.TP
.I "Top"
The menu should be displayed at the top of the screen.
.TP
.I "Bottom"
The menu should be displayed at the bottom of the screen.
.TP
.I "Offset y x"
Offset the menu \fIy\fP lines and \fIx\fP columns from the location
specified using the above options.
.TP
.I "Password x"
Set an access password for this menu. \fIx\fP is the access password
encrypted using SHA. Passwords can be generated using the \fIshacrypt\fP
program included with the distribution.
.PP
The menu is defined by \fItoken structures\fP, which are enclosed within 
a \fIMenu directive\fP, with one 
structure per line. A token structure is made up of at least two fields 
separated by delimiters. The last field \fBmust\fP end with a delimiter.
The format of the token structure is:
.RS
.LP
Token:Name:Options:Args:Prompt:
.RE

Where \fIToken\fP is the type of item to display. \fIName\fP is the 
name of the item as displayed on the menu. The \fIOptions\fP sets flags
which control the display of the item and in some cases the response 
to selection of the menu item. \fIArgs\fP is 
an item dependent argument field. \fIPrompt\fP is a text string which
is used in some of the tokens. Every token line must at least contain the 
\fIToken\fP and \fIName\fP fields, the others are either optional or
present in only some of the tokens. For compatibility with menus from
\fIflin\fP the fields have the following precidence which determines in
what order they are interpreted Token, Name, Args, Prompt and Options.


.B "Menu Tokens"
.TP
.I "Title"
Title inserts a non-selectable title line in the menu.

.RS
.RS
Title:Name:
.br
or
.br
Title:Name:Options:
.RE
.RE
.TP
.I "Nop"
Nop inserts a non-selectable line in the menu. If the item text is blank 
then a horizontal line will be displayed.

.RS
.RS
Nop:Name:
.br
or
.br
Nop:Name:Options:
.br
or
.br
Nop::
.RE
.RE
.TP
.I "SubMenu"
SubMenu creates a link to another menu named in the \fIArgs\fP field.

.RS
.RS
SubMenu:Name:Args:
.br
or
.br
SubMenu:Name:Options:Args:
.RE
.RE
.TP
.I "Exec"
Exec executes the command specified in the \fIArgs\fP field. The process
is put into a seperate process group. Note that the command is started using
\fIexecvp\fP which will search the PATH if the command is not specified
absolutely, this may not be what you want for a secure setup.

.RS
.RS
Exec:Name:Args:
.br
or
.br
Exec:Name:Options:Args:
.RE
.RE
.TP
.I "Args"
Args executes the command in the \fIArgs\fP field with user inputted 
command-line arguments. The optional \fIPrompt\fP field contains the 
prompt for the dialog box. \fIUse with care!\fP If you use this improperly, 
you could open up a big security whole on your system.

.RS
.RS
Args:Name:Args:
.br
or
.br
Args:Name:Args:Prompt:
.br
or
.br
Args:Name:Options:Args:Prompt:
.RE
.RE
.TP
.I "Exit"
Exit exits the current menu, returning to the previous menu. If Exit is 
executed in the main menu \fIflash\fP will quit.

.RS
.RS
Exit:Name:
.br
or
.br
Exit:Name:Options:
.RE
.RE
.TP
.I "Quit"
Exits \fIflash\fP.

.RS
.RS
Quit:Name:
.br
or
.br
Quit:Name:Options:
.RE
.RE


.B "Menu Token Options"

There are a number \fIOptions\fP defined for all of the menu tokens. These
control the display of the item on the menu. These are 
.RS
.TP
.I "L"
Display the item flush left on the menu
.RE
.RS
.TP
.I "C"
Display the item centred in the menu
.RE
.RS
.TP
.I "R"
Display the item flushed right in the menu
.RE
.RS
.TP
.I "Kx"
Define a hotkey x for this menu item.
.RE

In addition the following options are defined for the 
.I "Exec"
and
.I "Args"
tokens
.RS
.TP
.I "P"
The output from the process should be paged using a default pager
.RE
.RS
.TP
.I "N"
\fIflash\fP should not pause for the user to press a key when the
process exits unless it returns an error.
.RE
.RS
.TP
.I "&"
The process should be started in the background.
.RE

.SH RCFile [rc options] filename
.SH RCBlock [rc options]
.PP
A number of \fIrc options\fP may be used to select what scope the
block has.
.TP
.I "Login"
The RCBlock or RCFile should only be processed if the shell is a login
shell.
.TP
.I "System"
This option is available in RCFile only. It specifies that the file to
be read will have system rc privilage. Commands can be restricted so that
they can only appear in system rc files. All RCBlocks are system. System
RCFiles are sought relative to the \fIbaseaddress\fP while non-system RCFiles
are sought in users' home directories.
.PP

.SH EXAMPLE MENU
Here is an example menu (comment character is `#', delimiter is `:'):

.RS
.nf
#!./flash -b.
#
# test.menu	-	sample menu implementation for flash
#			to try it out type:
#			`./flash test.menu' or `./test.menu'
# Main menu
Menu NoBox NoColour Top Right Offset 1 -2 Main
	SubMenu:Electronic Mail:C:Mail:
	SubMenu:Network Facilities:C:Facilities:
	SubMenu:Local Chat:C:Talk:
	SubMenu:Who Else Is Online?:C:Else:
	SubMenu:Other System Information:C:SysInfo:
	SubMenu:Customise Your Account:C:Customise:
	SubMenu:Send Comments to Netsoc:C:Comments:
	SubMenu:Read Help Files:C:Help:
	SubMenu:Administration Menu:C:Admin:
	Title::
	Quit:Logout:C:
EndMenu

Menu Mail
	Title:Read, Send or Review your e-mail:
	Nop::
	Nop::
	Exec:Elm:N:elm:
	Nop:Powerful - built in encrypted mail support:
	Exec:Pine:N:pine:
	Nop:Very easy-to-use, excellent help facilities:
	Exit:Exit this menu:
EndMenu

Menu Facilities
	Title:Programs to do with Network Access:
	Nop::
	SubMenu:Network News:News:
	SubMenu:World Wide Web:Web:
	Nop::
	Exit:Exit This Menu:
EndMenu

Menu News
	Title:Read, Reply to and Barf at Network News:
	Nop::
	Exec:Tin:N:rtin:
	Nop:Tin is an easy to use, menu based news reader.:
	Nop:Type `h` for help within the program.:
	Exit:Exit this menu:
EndMenu

Menu Web
	Title:"Surf" the World Wide Web:
	Nop::
	Exec:Lynx:N:lynx -noprint -restrictions=editor,file_url,exec,shell:
	Exit:Exit this menu:
EndMenu

Menu Top Left Offset 2 -1 Password "tY30PCrOhbICLLXA6z3pTVs" Admin
	Title:Account Administration:
	Nop::
	Exec:Change Finger Information:/usr/bin/chfn:
	Exec:Start up tcsh:/bin/tcsh:
	Args:Run any command::Enter command to run:
	Nop::
	Exit:Exit This Menu:
EndMenu

Menu Bottom Left Offset 0 -1 HotKeys
	Title:Global HotKeys:
	Nop::
	Exec:p\: Pine:NKp:pine:
	Args:f\: Finger:PKf:finger:Who do you want to finger:
	Args:w\: W:PKw:w:Who do want to look for:
	Args:l\: Last:Kl:last -20:Enter optional username:
	Exec:e\: Elm:NKe:elm:
	Args:t\: Telnet:Kt:telnet:Enter host and optional port:
	Exec:b\: rBash:NKb:bash -version:
	Nop::
	Exit:Back to last menu:
EndMenu

RCBlock System
	restrict all except pause

	# Turn on exec logging
	set logging

	# Set Mail notification with timeout 5 sec
	set mailnotify 5

	# System Backgrounds
	set background system.bg.1:system.bg.2:system.bg.2a

	# Turn on TOP_BAR clock
	set barclock

	# Pager to use when an exec/args menu item has a P flag
	set execpager "less -E -P'Press Space to continue'"

	# Lock screen - saver frame timeout (ms) and backdoor password
	set lockscreensaver 80
	set lockbackdoor "tY30PCrOhbICLLXA6z3pTVs"
EndRCBlock

RCFile System Login system.flashlogin
RCFile .

.fi
.RP

.SH GRIPES
The way the menu token fields are handled is horrible. This man page is 
even worse. Anyone want to volunteer a nicer one.

.SH BUGS
The current release has some built in limits on line length etc.

.SH AUTHOR
Stephen Fegan (steve@netsoc.ucd.ie)

.SH CONTACT
The flash mailing list: flash@netsoc.ucd.ie.