Version 0.94 2/15/99
Ethan Gold <etgold@cs.columbia.edu>
http://www.cs.columbia.edu/~etgold/software/tkRunIt/
Freshmeat.net appindex record: 911881415

TkRunIt is a simple text entry widget which allows you to
run command lines without resorting to a full shell. Of course
it's written in Tcl/Tk so it probably has as much overhead as
starting an xterm with a shell, but it's cute anyway.
TkRunIt has several cousins, but implements a slightly different
interaction philosophy as well being as a good little exam
procrastination timesink.

Please read the INSTALL document that accompanies this distribution.

Features:
---------
(see Options section below for a detailed list)

* interactive filename completion (tab), including filenames with
  embedded spaces
* interactive environment variable name completion (tab)
* Full command history with simple !, !!, !!!, and prev/next syntax
* Complete(?) keyboard bindings for running, completing, history
  and quit
* Command-line parameters are inserted into the entry widget
  so runit can be used as a trivial generalized file handler for
  something like Netscape or whatever.
* all options, colors, and directives settable from config file
* -wait and -persistent options for synchronous and
  continuous operation (in addition to standard "&" syntax)
* All output sent to an optional message box
* Verbose output can be set in the config file or toggled interactively
* Completely navigable from the keyboard
* chdir (cd) implemented internally as in a normal shell
* "autokill" option which captures backgrounded job PID's to pass
  to the kill command


Options:
--------
The runitrc.sample file enumerates all of the settable options which
are described below. Some of the options are also supported on the
commandline. The rcfile (~/.runitrc) must be valid tcl code.
Note that all widths and heights are in units of characters and lines
respectively.

maxhist: the number of history items to save (enforced at startup time)
wtitle: the window title
bgcolor: background color for the entry widget
fgcolor: foreground (text) color for the entry widget
hicolor: border highlight color for the entry widget
vbhicolor: border highlight color for the entry widget in verbose mode
borderwidth: border width of the entry widget
listfont: font to use for the contents of the listbox
defaultfont: font to use unless otherwise specified
             defaults to "Helvetica -12"
labelfont: font to use for the messages and output
mesgfont: font for the text window messages
maxwidth: maximum width for the message output
maxheight: maximum height for message output and listbox
defaultcmd: a default command string to show in the entry widget on startup
verbose: boolean which toggles the message widget for output, errors,
	and run status (for persistant) in addition to the file completion
	listbox
showlabel: display a little label in verbose mode
location: geometry-style location description i.e. "+10-500"
	  -l, --location commandline switches override this value
wait: boolean indicating that runit should wait for the executed
	command to complete before quitting oraccepting more input
	"--wait" or "-w" commandline switch forces wait to be true.
persistent: boolean indicating whether or not to exit after each command
	is executed. The "--persistent" and "-p" commandline options
	force persistant to be true. (+w, +p turn off wait and persistent
	respectively)
mouseloc: boolean indicating that the window should appear under
	the current mouse location. --mouseloc and -m on the commandline
	turn this on, ++mouseloc and +m turn it off
autokill: boolean indicating that backgrounded jobs should have their
	PID placed back into the commandline in the form "kill $PID"

Bindings:
---------
tkRunIt is designed to be entirely navigable from the keyboard.
I've crafted the keybindings to fit the way I work and
expect things to work. Since I haven't figured out a good
way of putting bindings into a config file, they can only
be changed by editing the program source directly. However,
I think they are reasonably consistant with expected behaviors.
The conditions governing the appearance and disappearence of the
file list box are pretty hardcoded and not very configurable except
by turning off the verbose flag entirely.

	entry widget:
	-------------
	Return: execute the current command
	Tab: complete the filename (assumed to be the last item)
	     may generate a listbox if "verbose" is true
	Shift-Tab: focus on the main output area, command output or
		completions
	Up, Control-p: previous item in history
	Down, Control-n: next item in history
	Control-v: toggle verbose on and off
	Control-c: clear commandline
	Escape, Control-w,q: quit
	!.*: run the last command matching the initial expression
	     following the !
	![0-9]+: run the command number matching the number following
		the !
	!!: run the previous command
	!!!: display the numbered command history

	file completion listbox:
	------------------------
	Return: replace incomplete path with listbox's current file
	Control-Return: Same as return for first selection, but keep
	                the listbox active and append subsequent
			selections to the commandline
	Double-Button-1: same as Return
	Tab: reset focus to the text entry widget
	Control-v: toggle verbose on and off
	Control-a: select all
	Control-c: hide completions, leave commandline alone
	Escape, Control-w,q: quit

	command output textbox:
	-----------------------
	Tab: reset focus to the text entry widget
	Control-v: toggle verbose on and off
	Control-c: hide output, leave commandline alone
	Escape, Control-w,q: quit

Future:
-------
* ability to toggle listbox independant of messages
* configurable gravity so you can stick it at the bottom of the
  screen and still see the verbose output
* I may have figured out dynamic keybindings - soon to be configurable
* `` syntax for shell output substitution?
* persistant width resizing? or resized height becomes new max height?
  feedback please!
* write a man page
* $PATH binary completion

Bugs:
-----
* history limiting is only enforced at startup. This is probably
  sufficient for most situations.
* No substitutions implemented for history (nor will there be)
* Even after a reorg, the code is still pretty ugly.
* Running multiple copies of runit causes some screwy history
  behavior - hopefully fixed.

Changes:
--------
	Since 0.92
* Added autokill option to put PID's from backgrounded commands
  into the command entry widget in the form "kill $PID"
* History view now scrolls to the bottom by default
* Clicking in output window or file completion listbox now sets
  focus to that widget.
* Fixed (mostly) problem saving blank/cancelled commandlines as empty
  strings
* Fixed (I hope) problem sometimes not saving recent history items
	across multiple instances
* Mouseloc option now makes sure that the window shows up entirely
  on the screen

	Since 0.90
* tweaked Control-c binding in message widget so that toggling
  verbose doesn't bring back cancelled output.
* added Shift-Tab binding to entry widget which transfers focus
  to the other displayed widget (command output or completions)
* --mouseloc switch to pop up window under the mouse
* fixed and improved label updating - hadn't used it in so long
* cursor now starts at the end of the text in the entry widget
  at startup
* better output behavior in general

	Since 0.85
* squashed bug where a non-wildcard parameter following a wildcard
  parameter would be appended without a space to the preceding
  parameter, resulting in a bogus commandline
* added more complete color configuration for those with
  truly bizarre taste.
* fixed (please test) the manual resizing bug. Now the window
  will properly resize itself after manual fiddling. The new
  size will NOT be persistant.

	Since 0.82
* squashed showlabel initialization bug
* squashed expanding label bug/artifact
* tilde and environment variables properly expanded in execution
* interactive environment variable selection in verbose mode (like  files)

	Since 0.80
* cursor at end of line after filename disambiguation
* added ESC to quit keybindings
* turned Control-c into context-specific cancel instead of quit
* squashed startup w/o history bug
* switch to turn off the verbose label (it started annoying me)
* new verbose highlightcolor to indicate verbose is active in case
  you run tkRunIt without a titlebar like I do
* +w, ++wait, +p, ++persistant for turning off the related values
* -l, --location for position geometry (the tcl interpreter steals
  -g, --geometry unless you use --)
* pipes can now be used without surrounding spaces
* wildcard command execution courtesy of ToyKeeper
* multiple command execution with semicolons
* cd now handled as an internal command as in a shell

	Since 0.77
* cleaned up internals to make the code more managable and reduce
  nasty side effects
* disabled text entry in the output text widget - selecting still works
* multiple file selection in the listbox via the keyboard
* initial matched substring for ambiguous file patterns is now inserted!
* !!! displays complete numbered history
* history size now enforced at startup
* commands with trailing "&" without a space are now handled properly
* wish now started via sh, simplifying installation procedure

	Since 0.76
* filenames with embedded spaces are now handled properly
* filenames in the completion listbox are now sorted
* a couple more keybindings in the command output widget

	Since 0.75
* turned extended selection on in the listbox and mapped Control-a
  to select-all
* made sure that multiple selections would be properly substituted
  into the commandline
* replaced mesg widget output with scrollable text box

	Since 0.70
* matched width of listbox to that of entrybox (assuming fonts are the
  same) rather than to the widest item in the list
* added options for setting fonts and widths for entry box and listbox
* added default selection to listbox so hitting return before
  making a selection (or tabbing out) doesn't give an error

	Since 0.65
* status line and catching command output and posting to message box
* listbox for ambiguous file completion
* commandline switches in GNU format

	Since 0.60
* entry widget cleared after command execution
  while persistent

	Since 0.51
* improved bad-file-completion selection heuristic
* fixed bug in ! history matching
* rcfile
* -wait and -persistent

Acknowledgements:
-----------------
Thanks to ToyKeeper (Scott Scriven <scriven@cs.colostate.edu>
for his wildcard command execution patches and comments.
And thanks to everyone who's given bug and feature feedback - that's
what keeps me motivated to release.

License:
--------
This program is distributed under the GNU public license.
Please see the LICENSE file accompanying this distribution
for details.

