BETH
----

Beth stands for Browsing & Editing Tcl Hypertool, and is intended as a text
browser and editor for X.

Special Features of Beth:

	- Compatible with Tk 3.6 / Tcl 7.3
	- Global search/replace
	- Unlimited undo, including undoing replace.
	- Optional horizontal and vertical grids.
	- Piped I/O to files or standard shell commands, with ability to read
	  output into text widget gradually, either standalone or with addinput
	- Execute wish/exec commands, with I/O with text widget.
	- 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
	- Execute a function in all Beth interpreters.
	- Execute a function N times
	- Windowing functions for resize, move, raise, iconify
	- Switching between multiple Beth interpreters from the keybaord.
	- Menus...each function has a corresponding menu item, plus menu
	  items to assist in the syntax of complex command options.
	- Library of optional modules including:
		- Parentheses balancing (also brackets and braces)
		- Textual documents.
		- Code (C/C++, Lisp/Scheme, Tk/Tcl)
		- Collapsing text module.
		- Abbreviations module

Unlike other text browsers, this is not the type of program you start up only
once per login session. It is intended to be run in multiple instances, and it
also can be used as a 'slave' for other applications. Multiple instances of Beth
running simultaneously keep track of each other (via Tk's send), and thus
provide the same power and flexibility provided by multi-buffer editors like
emacs. Yet, as separate processes, each Beth instance can be configured for
special-purpose applications without disturbing the other instances.

Beth is also a source-modular tool. Each source file adds a set of bindings; you
can extend Beth easily by adding new source bindings. Also you can extract
source code easily from Beth. For example, suppose you want to include
parentheses balancing in your Tk app, but you don't want all of Beth. If your
app uses a Text widget, all you need do is source the balancebind.tcl file, with
a few global variables set. This alleviates the problem of having to use
multiple editors because they have mutually exclusive features you need.


Installation
------------

After unpacking Beth, you should:

1. Edit beth.tcl with your (soon-to-be-ex (-: )-favorite editor, and follow the
instructions at the top of the file.

2. Copy beth.tcl to your favorite bin directory, and rename it beth.

The 'HELP' file provides in-depth explanation of the functions and keybindings
provided by Beth, including a quick-reference chart. Pressing Meta-Control-h in
Beth, and then hitting Return brings up a Beth window on the HELP file.

If it exists, Beth sources the file $HOME/.beth, and also the file [pwd]/.beth,
to provide arbitrary configuration options, such as extra bindings, procedures,
and options. The file beth.config.tcl is an example of a .beth file, you can
modify it, (after copying it to $HOME/.beth).


Embedding Examples
------------------

In the directory examples are some example programs that embed Beth inside
other applications. See examples/README for details on these programs and on
embedding Beth.


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

	$Log: README,v $
# Revision 4.1  1994/05/16  16:23:51  svoboda
# Added some simple library modules
#
# Revision 4.0  1994/04/11  15:28:26  svoboda
# Added string completion, menus, grid
#
# Revision 3.2  1994/04/05  17:39:16  svoboda
# Added string completion, addinput, other goodies
#
# Revision 3.1  1994/02/17  21:12:53  svoboda
# Bugfixes, tkcolor colormap workaround
#
# Revision 3.0  1993/12/13  18:14:14  svoboda
# Added shell commands, I/O pipes
#
# Revision 2.2  93/07/26  12:31:05  svoboda
# Fixed paging and indent bugs
# 
# Revision 2.1  93/07/25  15:22:39  svoboda
# Made embedding easier, added indent function
# 
# Revision 2.0  93/07/16  13:54:07  svoboda
# Added undo/word-traversal options
# 
# Revision 1.0  93/06/23  11:59:56  svoboda
# Beth is first released
# 


Copyright
---------

Copyright (c) 1993 by David Svoboda (svoboda@ece.cmu.edu)
Department of Electrical & Computer Engineering 
Carnegie Mellon
All rights reserved.

Permission is granted to use, modify, and distribute this software freely,
provided that thie copyright section appears in all copies of this software.
However, one may not charge for it or include it with software which is sold.

If Beth is embedded within a larger system, or if Beth cooperates with an
independent system via IPC or some variant thereof, that system is not covered
by this copyright, and may have a different copyright.

In no event shall Carnegie Mellon be liable to any party  for direct, indirect,
special, incidental, or consequential damages  arising out of the use of this
software and its documentation, even if Carnegie Mellon has been advised of the
possibility of such damage.


Bugs / Suggestions
------------------

Doubtless there will be bugs, or rather, 'features' you and I didn't count on.
The Tk error should complain of any errors that a bug causes. Keep in mind, that
the Tk error mechanism is also used to report errors from wish or exec commands
and I/O pipelines. So you could get a Tk error by telling Beth to exec "rm /usr"
(unless you happen to be root :), but this is not a bug. Also some commands will
terminate abnormally, even if they do what you want. A good example of this is
diff, which will return nonzero status if any differences occurred, which Tk
will interpret as an error message. So you will get the output you want, but
there will be a Tk error message saying the process ended abnormally. You might
also get an error message if you interrupt a gradual process. However, these are not bugs in Beth.

If you do get a reproduceable Tk error which you are sure is a bug in Beth, mail
me the contents of Tk's error stack trace, along with what you were doing to
invoke the error. Include the versions of Tk,Tcl,X and your hardware and
software platforms. If Tk does not report an error, but Beth does not do what
you want, it could be a bug, or a feature. If you feel strongly that this is a
bug (it is not mentioned in the documentation, and you cannot work around it,
for example), send me a letter describing the problem.

There are many things that can be added to Beth. (a few are mentioned in the
TODO file) Beth has been designed to allow you to extend it with your own
modules. It stores the name of the text widget in the global variable $text, the
frame widget messages appear in $frame, and the quit button is named
$quit_button. The easiest way to extend Beth is to write your own module using
these variables and source it in your .beth file. If you make any popular
extensions, I would like to hear about them; they might get incorporated in the
next version of Beth. I do not wish to weigh Beth down with features, but a
'Beth library' of optional modules might be a good idea in the future. The
textbind.tcl and balancebind.tcl modules are good examples of optional modules,
since beth.tcl does not load them, but rather they are loaded by your own .beth
file.

Send bug reports and suggestions to:
David Svoboda	svoboda@ece.cmu.edu
