Rmth, version 1.0
-----------------

A combination of a shell emulator, wish tutorial, and remote interpreter that
uses Beth, based on the rmt demo program in /lib/tk/demos in the Tk distribution
package.

Special Features of Rmth:

	- Takes wish commands or exec commands.
	- Output of exec command can be gradual, just like Beth I/O pipes
	  either standalone or with addinput.
	- Automatic completion of filenames, variable/array names,
	  Tcl commands and procedures, with optional listbox to display
	  possible endings to ambiguous completions.
	- Automatic expansion of file glob patterns, variable/array values,
	  and Tcl bracketed-command evaluation
	- Automatic history substitution
	- Commands can be automatically executed in a remote Tk interpreter.
	- Quickly learn a Tk procedure or command's arguments.
	- Optional listbox to indicate correct options for a Tk command.

	+ All of Beth's features!

Rmth understands wish commands, if it does not recognize the command as
legitimate in wish, it assumes the command is a shell command and passes it to
exec. Either way, it prints out the result and any errors generated. (See the
exec(n) manpage for more information on exec.) One can also have graduated
output from an exec command, to do this either append a @ to the command, or
turn on the 'Gradual output' checkbutton off the File menu (which is already on
by default).

Be aware of some of the differences between rmth and a real terminal. Rmth does
not redirect stdout or stderr, so things like puts will still put things out
onto your terminal, not the rmth window. This also means that interactive
commands like patch still take input from the terminal. And, although you can
pass a single command implicitly to exec, you can't pass multiple exec commands
implicitly; you have to specify 'exec cmd1 ; exec cmd2'. Exec also does not
recognize backquotes, so things like `pwd` don't work. And exec also does no
implicit file globbing. (Rmth does expand glob patterns, but only after hitting
Tab, or if the glob is the last word on the command line.)

Rmth adds a new menu, called rmth, to Beth's menubar. The first item, called
Application, indicates what interpreter to execute the commands in. If any but
local is selected, than all wish/exec commands are executed in the remote
interpreter. Note that gradual reading is not possible in remote interpreter
execution. The other menu options are analogous to rmth's extra keybindings,
which are described below.

Rmth also supports many types of completion and history substitution. Pressing
Tab in the text window has the same effect as on entries, completion of
filenames, glob patterns, variable names/values, or Tcl commands is performed.
The expansion is performed with respect to whatever interpreter is being sent to
at the time. In addition, rmth supports history substitution, where tabbing on
!<history> returns the event in the history stack (see the history(n) manpage
for details), and !!<Tab> yields the most recent event. Upon hitting <Return>,
rmth does only history expansion and file globbing. Only commands which didn't
yield errors get added to the history stack.

Rmth uses all of beth's keybindings. However, they act slightly differently in
rmth. In particular, most browse bindings will skip over the prompt before each
command, so, for example, you get the entire line minus prompt upon
triple-clicking button 1. And most edit bindings will not work on text before
the last prompt, or while a command is being executed. Finally, the help command
is slightly changed, it brings up both Beth's standard help file and this file.

Rmth also adds the following keybindings:

	Tab, C-Tab	Tab completion, like in Beth entry widgets.
	Return		Execute command
	C-L		Clear all text before line with insert cursor.
	C-N		Go to beginning of next command
	C-P		Go to beginning of previous (or current) command
	C-U		Erase current command, like in Beth entry widgets (C-u)

Upon startup, rmth sources the .rmth file either in the pwd or in your home
directory. Via Beth, it also sources .beth in $HOME or pwd. The file
rmth.config.tcl is an example configuration file, you can use it by copying it
to $HOME/.rmth. It contains code for displaying the current working directory
(in whatever interpreter is being used at the time).

If a wish or exec command generates an error, the error is printed and the
command is brought back up after the new prompt, so you can re-execute it after
correcting the command. However, certain errors are handled specially by rmth.
There is an info label under the rmth text window. It is normally hidden, but it
gets brought up under certain cases when a message doesn't really belong in the
rmth text window, but should be made known to the user. The label will disappear
if you click button 1 over it, or when you execute the next command. When a
command generates an error in the info label, nothing gets added to the text,
and so you can edit the same command line to fix the command.

If rmth has trouble sending a command to a remote interpreter, then the error is
brought up in a dialog box, as usual, but rmth also automatically switches back
to the local interpreter.

Sometimes a command passed to exec terminates normally, while still reporting an
error, and sometimes the error causes the command to terminate abnormally. In
this case, exec usually sends an error of its own, however this error is not put
in the rmth window, it is merely brought up on the info label. The error from
the shell command does, however, get put in the rmth window.

It is an error to indicate gradual reading in a remote interpreter. If you
merely leave the 'Gradual output' option on in a remote interpreter, it will be
ignored. However, if you explicitly imply gradual output by appending your
command with a @ in a remote interpreter, an error will appear on the info
line.

If you press Tab after entering a wish procedure, the arguments of the procedure
get displayed on the info label.

If you enter the wrong number of arguments in a wish command, or you give a bad
option to a wish command, an appropriate Tk error message is brought up on the
info label.

If the Tk error message to a wish command contains possible correction values,
the values are brought up in a listbox. You can either click 'OK' and fix the
command manually, or select an item in the listbox, and rmth will correct the
command for you.

These error routines make rmth very useful as a wish command interpreter. Using
command completion, you can get the full name of any incomplete wish command or
procedure by pressing Tab on an incomplete command/procedure. With a complete
procedure, pressing Tab returns you a list of the procedure's arguments.
Pressing Return with the wrong number of arguments tells you the correct number
of arguments for a command or procedure. Also pressing Return with an incorrect
option or command argument will often get you a list of the possible correct
values to use. And finally, you can complete Tk variables and arrays, or
evaluate Tk bracketed expressions, or see a complete variable's value by
pressing Tab.


RCS Change Log
--------------

	$Log: README,v $


Maintainer
----------
David Svoboda
svoboda@ece.cmu.edu
