BETH: A Browse & Edit Tcl Hypertool
------------------------------------------
Keybinding Reference Page:

Browsing: browsebind.tcl

                          Control-
                             p                    Up
Single Char Movement:      b + f      or      Left + Right
                             n                   Down

                           Meta-
Single Word Movement:      b + f

                                                 Shift-
                            M-,                    Up
Edge of Page Movement:  C-a  +  C-e    or      Left + Right
                            M-.                   Down

                                                          Meta-    Shift-
                 M-z            M-v   Prior                 <      Prior
Scrolling: Line:  |       Page:  |  or  |        Document:  |  or    |
                 C-z            C-v    Next                 >      Next
                                 (space)
                                                 Any: scrollbar button2

Select	Line 	C-K (C-k)
	Region	C-W Select (C-w)
	All	M-W S-Select
	Any	button1
	Clear	C-c

Mark	Set	C-space
	Xchange	C-x

Center cursor	C-l

Goto line	M-g

Quit		M-q Button-quit


Window Commands: windowbind.tcl

Toggle Control:	M-C-c

           Control-              Control-
              [                    Up
Resize:     ] + }      or      Left + Right
              {                    Down

            Meta-                 Meta-
              [                    Up
Move:       ] + }      or      Left + Right
              {                    Down

        Control-Meta-         Control-Meta-
              [                    Up
To Edge:    ] +        or      Left +

One can think of this as:

Control-	=Resize		=Shrink (up/left)	-Open	=rows
Meta-		=Move	-Shift-	=Expand (down/right)	-Closed	=columns
Control-Meta	=To Edge

Window:	Iconify:M-I
	Raise:	M-i

Region:	Browse:	M-C-x
	Print:	M-C-p
	Indent:	C-i


Editing Commands: editbind.tcl

Kill:	line:	C-k
	region:	C-w

Paste:	C-y	Insert	button3

		Previous:	Next:
Delete:	Char:	C-d Delete	C-h
	Word:	M-d		M-h
	Region:				C-Delete Button1-Delete

Case:	Upper:	M-u
	Lower:	M-l
	Cap:	M-c

Open line:		C-o
Quote:			C-q
Transpose:	Chars:	C-t
		Words:	M-t

Log:	Last:	M-C-l
	Kill:	M-C-k
	Undo:	M-C-u


Entry Commands: entrybind.tcl

Entry/Text Toggle:	Escape
Destroy Entry:		C-g

                          Control-
Single Char Movement:      b - f    or      Left - Right

                           Meta-
Single Word Movement:      b + f

                          Control-             Shift-
Line Movement:             a - e    or      Left - Right

Scrolling:	Any: button2

Select	Line 	C-K
	Region	C-W Select
	All	M-W S-Select
	Any	button1
	Clear	C-c

Mark	Set	C-space
	Xchange	C-x

Center cursor	C-l

           Control-              Control-
Resize:     ] - }      or      Left - Right

Kill:	line:	C-k
	region:	C-w

Paste:	C-y	Insert	button3

		Previous:	Next:
Delete:	Char:	C-d Delete	C-h
	Word:	M-d		M-h
	Region:				C-Delete Button1-Delete

Case:	Upper:	M-u
	Lower:	M-l
	Cap:	M-c

Quote:			C-q
Transpose:	Chars:	C-t
		Words:	M-t

Paste:		C-v
Kill:	all:	C-u


File Access: filebind.tcl

			Prompt
File:	save:	M-s	M-S
	read:	M-R	M-r
	insert:		M-C-i
	visit:		M-C-v


Incremental Search: searchbind.tcl

		 New		Old
Search:	Forward: C-s Find	C-S
	Reverse: C-r S-Find	C-R
	Regexp:	 C-M-s

Search:	Again:	Forward:	C-s Find
		Reverse:	C-r S-Find
	Exit:			Return C-g


Query Replace: replacebind.tcl

		New	Old
Change:		C-c	C-C

Change:	Search	Again:	Forward:	C-s Find
			Reverse:	C-r S-Find
	This one:			C-c
	All:				C-C
	Exit:				Return C-g


Text Bindings: textbind.tcl

				Meta-
Paragraph:	Traversal:	a - e
		Select:		C-j
		Adjust:		M-j
		Split:		S-Return


Startup: beth.tcl

Command-line arguments: all but last
	-c Causes Beth to seize control upon startup.
 	-i Causes Beth to start up iconified. This option overrides -c.
 	-b Browse mode only, no editing provided.
	-t Title Adds the next word to Beth's window & icon title.
Command-line argument: last
	-	Standard input.
	X	The X Selection
	name	The contents of the file indicated by name


Multiple Beth Interpreters: interpbind.tcl

		All	Shown
Switch:	Next:	M-N	M-n
	Prev:	M-P	M-p

Switch:	To:	M-C-b


Key Bindings: keybind.tcl

Universal Argument:	C-u

All:		M-K
	Shown:	M-k


Overview of BETH
-----------------

Beth is a simple word-processor modeled after Emacs. Upon heavy use of Emacs,
I have come to the following postulates over what Beth should be capable of:

1. Emacs is keyboard-oriented (the result of predating mice), and achieves its
functionality soley with key-bindings. This has a significant advantages over
more current editors in that it does not require the user to alternate between
two hands on keyboard and one on keyboard / one on mouse. The user can thus
enter commands faster. (A disadvantage is the learning curve for key-commands,
much slower than for a GUI.)

Like Emacs, Beth should be completely accessable from the keyboard
(particularly the QWERTY section) so the user need not switch constantly between
keyboard and mouse. While it will have mouse-support, and support for the
arrow-keys and numeric keypad, all mouse and special-key functions also can be
accessed through the QWERTY keyboard.

2. Many of the mouse-based editors run considerably slower than Emacs. Their
slowness is hidden by the GUI and command-entry by mouse, and only becomes
apparent when the user tries to execute keys bound to various functions
repeatedly.

Like Emacs, Beth should be fast enough to handle the fastest typists on text
entry (which Tcl naturally provides). In addition, simple functions like
cursor-movement that are used heavily and repeatedly should reveal no lethargy
on the part of the system.

3. Gnu-emacs contains Meta-Lisp, a language useful for extending the editing
functions. This makes for a widely configurable system.

Beth is written in Tcl, which contains many LISP-like features. While Meta-LISP
is only useful inside Gnu-Emacs, Tcl can be used for many programming functions
besides text-editing.

4. Emacs (in most incarnations) is very large, and takes up a lot of space. It
is slightly slow in starting up, and thus is not well suited for small
start-and-stop editing jobs.

Beth, thanks to Tcl's interpretive nature, is a smaller program than Emacs, and
thus starts more quickly. Using X and running as a background process, it is
ideal for quick browsing/editing of small documents, since one has access to
both the calling shell and Beth in different windows. In addition, Beth can
run in a 'browse' mode, which loads only the functions necessary for browsing,
thus saving load time.

5. Emacs allows multiple buffers per session, making it well-suited for editing
many files in one session. This and it's slow load time make it a
'run-once-and-add-new-files' editor.

Beth only edits one file at a time. For multiple-file-editing, you run one
instance of Beth on each file. Thus each Beth interpreter is self-sufficient.
Tcl's send command is useful for 'inter-beth' communication. In addition, there
are several modules which provide functions to switch between Beth
interpreters, or execute a command in all interpreters.

6. As a terminal-based editor, Emacs provides no GUI.

Probably the most important point here. While the current GUI for Beth is
minimal, Tcl allows for the quick addition of graphical functions and
customizability.

7. The text widget provides all the necessary functionality for text editing; no
alternate widget is necessary.

8. I won't think of everything. People will want features I never thought to
add. Beth is therefore very modular, and simplifies module-adding as much as
possible.


The Text Window: widgets.tcl
----------------------------

The following core widgets are made by Beth:

Text: 	The text widget contains the actual text that will be edited. Note that
the normal text bindings have been replaced with BETH bindings. The only
bindings that remain are the bindings for mousebuttons 1 and 2. Button 1 is used
to select text, and button 2 is used for scanning. (see the Text(n) manpage for
details).

Scrollbar:   A scrollbar that assists in scrolling through the text widget.

Interpreter entry:   This is an entry widget that contains the name of the
interpreter running Beth. Note that its contents may not be changed, the only
bindings allowed in it are mouse button 2 (for scanning) and mouse button 1
(which selects the enitre interpreter name) In this way every Beth process
advertises its interpreter name, so the user can interactively send commands to
the running interpreter (from a remote wish script, for example).

Quit button: A standard button that when pressed, closes down Beth. Note that
this button can be invoked from the keyboard (see Browsing)


Browsing: browsebind.tcl
------------------------

This section handles simple browsing functions (those that don't modify the
text). It first disables most regular keys, any key with no other function is
set to ring the bell.

Simple cursor movement:

For single-char movement, C-b moves back one char, and C-f moves forward. For
single-line movement, C-n moves down a line, and C-p moves up. These are the
same bindings provided by Emacs.

The arrow keys (Left,Right,Up,Down) are also bound to these same functions.

                          Control-
                             p                    Up
Single Char Movement:      b + f      or      Left + Right
                             n                   Down

One can also traverse words. In Tk, a word is a sequence of letters, numbers, or
_ or any single character not one of the above. M-b moves backward one word, and
M-f moves forward one word.

                           Meta-
Single Word Movement:      b + f

To go to one edge of the text window, the following are used:
C-a goes to the beginning of the current line, C-e goes to the end.
M-, goes to the beginning ot the top line on the page, M-. goes to the last
character on the page (to be precise, it goes to the character one before the
first non-visible line; this is usually the last char). These are the same
bindings provided by Emacs.

Pressing Shift and an arrow key will execute these same commands.

                                                 Shift-
                            M-,                    Up
Edge of Page Movement:  C-a  +  C-e    or      Left + Right
                            M-.                   Down

To scroll the text by one line, one can use C-z for scrolling up and M-z for
scrolling down. To scroll by one page, one can use C-v to go down, or M-v to go
up. One can also page down and up with the Prior and Next keys. Also, in browse
mode (where text entry is disabled) the space bar will page down. (in normal
editing mode, this, naturally, inserts a space). Finally, one can go to the
beginning of the text with M-<, and to the end with M->. Or one can use S-Prior
or S-Next for beginning and end of text, respectively.

                                                          Meta-    Shift-
                 M-z            M-v   Prior                 <      Prior
Scrolling: Line:  |       Page:  | or   |        Document:  |  or    |
                 C-z            C-v    Next                 >      Next
                                 (space)
                                                 Any: scrollbar button2

To select text, one can use C-K to select a line. Repeatedly hitting C-K adds
more lines to the selection (this is just like Emacs, except Emacs kills the
text instead of selecting it.) In Browse mode, C-k has the same functionality.

The C-space key sets a mark, just like in Emacs, and one can then use C-W to
select the region between the mark and the insert cursor. (emacs is similar, but
kills the region instead of selecting it.) The Select key has the same
functionality as C-W, and in Browse mode, C-w also has the same functionality.

One can automatically select all of the text by hitting M-w. Or one can hit
S-Select.

The selection is exported as the X selection, so you can paste a selection in
Beth into another Beth interpreter, or, in fact, any application which can
take the X selection.

And, you can select arbitrary lengths of text by using mouse button 1 (see
text(n) for details.)

Finally you can clear the selection by hitting C-c or making another selection
in or outside Beth.

Select	Line 	C-K (C-k)
	Region	C-W Select (C-w)
	All	M-W S-Select
	Any	button1
	Clear	C-c

The C-x key switches the location of the insert cursor and the mark.

Mark	Set	C-space
	Xchange	C-x

One can set the cursor at the center of the scrren (vertically) by hitting C-l. (Note this does not move the cursor...it just scrolls the text)

Center cursor	C-l

One can go to any arbitrary line by hitting M-g. An entry widget will be brought
up, and the user enters a location to go to. (see Entry Bindings). If the user
enters a number, the cursor moves to the beginning of that line (just like
Emacs). In addition to specifying a line number, the user can instead enter any
index accepted by the Text widget (see text(n) for details) 

Goto line	M-g

Finally, the user can quit Beth by hitting M-q, or clicking on the 'Quit'
button.

Quit		M-q Button-quit


Window Commands: windowbind.tcl
-------------------------------

This section includes commands to handle geometry management, calling up other Beth interpreters, control, and various windowing functions.

Beth uses Tcl's global grab routine (see grab(n) for details about grab) to
direct the input focus. A beth editor that has a grab in effect is said to be in
control. While an editor is in control all mouse events are disabled except the
ones within that editor. When no editor is in control, the focus for mouse and
keyboard events is determined by the window manager. An editor in control will
display a 'Grab' label. Note that you cannot perform X events on a grabbed
window's titlebar using the mouse, but you can perform X events inside the
grabbed window. Fortunately, beth provides keybindings for window functions like
resize and iconify. Also note that you cannot grab an iconified window.

The standard key for control is M-C-c. It toggles control on or off.

Toggle Control:	M-C-c

Tcl's text widget can be arbitrarily small or large, but it determines the
geometry of the window. The window geometry is gridded by the size of the font
in the text window. (see the wm(n) manpage for details on geometry management).

One resizes the window by enlarging or shrinking it by a single row or column at
a time. During this resizing the title bar and text remain stationary and the
bottom or right edge moves in the specified direction. To shrink the window
horizontally, one uses C-[, to expand it one uses C-{. To shrink the window
vertically, one uses C-], to expand it, one uses C-}. Hitting Control over one
of the arrow keys has the same effect.

One can think of the functionality by what each key does to the lower right
corner:

           Control-              Control-
              [                    Up
Resize:     ] + }      or      Left + Right
              {                    Down

One can also move the window one column/row in any direction. Here the window
size remains constant. M-[ moves the window up one line, M-{ down one line, M-]
right one char, and M-} left one char. Using Meta with an arrow key achieves the
same effect.

            Meta-                 Meta-
              [                    Up
Move:       ] + }      or      Left + Right
              {                    Down

Finally, one has the option of placing the window at the top or the left of the
screen. C-M-[, and C-M-Up move the window to the top edge, and C-M-] and C-M-Left move it to the left edge.

        Control-Meta-         Control-Meta-
              [                    Up
To Edge:    ] +        or      Left +

One can think of this as:

Control-	=Resize		=Shrink (up/left)	-Open	=rows
Meta-		=Move	-Shift-	=Expand (down/right)	-Closed	=columns
Control-Meta	=To Edge

M-I iconifies the current window. The window automatically turns off control
when iconified. M-i performs back-to-back iconify and deiconify commands, which
has the effect of raising the window. If the window had control before M-i, it
regains control after being deiconified.

Window:	Iconify:M-I
	Raise:	M-i

Beth only shows one view of it's editing buffer. To see two views, you could
start up another Beth with the same contents. However, there is a command,
M-C-x, which brings up another Beth containing the currently selected text. So
you can 'clone' your current text by selecting all of it (M-w) and browsing the
selected text. (M-C-x).

There is a command C-i to indent the selected region. It prompts for an indentation prefix, to be inserted at the start of every line. This is useful for indenting a textual paragraph or commenting out lines of code.

Finally there is a command for printing a region of text (or the entire text).
M-C-p will print the selected region (or the entire text if no region is
selected)

Region:	Browse:	M-C-x
	Print:	M-C-p
	Indent:	C-i


Editing Commands: editbind.tcl
------------------------------

This module sets up basic editing commands. Text entry is enabled. A checkbutton
is displayed that becomes set when the file is modified.

One can erase text in one of two ways. Killing text removes it from the window,
but puts it in a 'kill' buffer, just like in Emacs. It also selects the text in
the kill buffer, so it can still be pasted by Beth, or any other X
application.

One can kill a line of text with Control-k, just like Emacs. Be careful, though.
Control-k will remember the last point where text was killed from, and one can
increase the kill region by hitting Control-k repeatedly; however, unlike Emacs,
a single 'kill session' is not terminated by hitting another key, it is
terminated when a kill occurs at some point different than the previous kill.
This can occasionally yield unexpected results upon pasting killed text. In
addition to C-k, one can kill the region between the insert cursor and the mark
with C-w. As before, C-c clears the selection, whether it be in the main text
region or the kill buffer.

Kill:	line:	C-k
	region:	C-w

Pasting is done with C-y, which will insert the contents of the X selection
before the insertion cursor. The X selection may be created with one of Beth's
select functions, or from the kill buffer, or from another X application. The
Insert key and mouse button 3 (normally unused in Tcl) have the same
functionality.

Paste:	C-y	Insert	button3

In lieu of killing, one can delete characters or ranges of text, never to be
seen again. C-d removes the character after the insert cusror and C-h removes
the one before the cursor. The Delete key has the same functionality as C-h. You
can delete words as well. The M-d key deletes the range of the word from the
cursor to the end, and the M-h key deletes from the cursor to the beginning of
the current word. When the cursor is at a word boundary, these delete the next
and previous word, respectively. Also, you can delete the current selection by
hitting C-Delete, or by hitting Delete with mouse button 1 pressed. Thus button
1 is useful for both selecting and deleting text.

		Previous:	Next:
Delete:	Char:	C-d Delete	C-h
	Word:	M-d		M-h
	Region:				C-Delete Button1-Delete

There are a few functions to change the case of a range of letters. M-u, for
example, converts all letters within the selected region to UPPER CASE. If no
selected region exists, the characters between the cursor and the end of the
current word are UPPERCASED. M-l is similar, but it converts its range to lower
case. Finally, there is M-c, which Capitalizes Its Range Of Text.

Case:	Upper:	M-u
	Lower:	M-l
	Cap:	M-c

There are a handful of other editing features. C-o inserts a newline character
*after* the insertion cursor. C-t has the effect of transposing the two
characters adjacent to the cursor. For word transposition, M-t transposes two
words around the cursor. Actually, M-t transposes three words, which usually
does the right thing, exchanging two alphanumeric words while leaving intact the
whitespace between them. Finally, C-q allows one to enter a control character
directly into the text.

Open line:		C-o
Quote:			C-q
Transpose:	Chars:	C-t
		Words:	M-t

Last, but not least, you can undo most commands that alter the text. The key
M-C-u will undo the last undoable cmd (even if you have done other commands that
are not undoable). Multiple undo's are possible, and the variable max_undos
determines how many are possible at one time, when set to -1 (the current
setting) there is no limit.

Currently any Paste, Delete, Indent, Case, Adjust, File-insert, Transpose, or
Search/Replace can be undone. (These are all the simple editing commands that
cannot be undone with a single keystroke, commands like Kill and Backspace are
easy to undo by themselves.)

A word of warning about undo's: most commads that are undoable use marks to
store the locations where they performed actions. Should the text around those
marks be deleted, the marks may move around in unpredictable ways. For example,
if deletions used marks, they would get bunched up together, and would not undo
properly, hence deletions use absolute indices instead of marks.

If one is unsure about what might get undone by a M-C-u press, one can view the
last command on the undo log, by typing M-C-l. One can clear the log with
M-C-k.

Log:	Last:	M-C-l
	Kill:	M-C-k
	Undo:	M-C-u


Entry Commands: entrybind.tcl
-----------------------------

In Tcl, entry widgets are similar to text widgets, except that they only provide
one line for entry. Thus they are useful for entering parameters like numbers
and simple words. Most functions that take arguments get them from the userr via
entry widgets. 

When any entry widget is active in Beth, one can toggle the cursor between entry
and text by hitting Escape. One can also destroy the entry widget and exit
whatever function was invoked with C-g. Both Escape and C-g work in either entry
or text widgets.

Entry/Text Toggle:	Escape
Destroy Entry:		C-g

Entrys themselves take many of the same commands that the text widget takes, but
realize that the keybinding will affect the entry widget only if the cursor is
in the entry widget, likewise the keybinding will affect the text widget only if
the cursor is in the text widget.

The following keys perform the same function in entries that they perform in
text. (Be aware that word cmds behave slightly differently in entries than in
text, due to the fact that text widgets have a concept of a word, while Entries
do not.)

                          Control-
Single Char Movement:      b - f    or      Left - Right

                           Meta-
Single Word Movement:      b + f

                          Control-             Shift-
Line Movement:             a - e    or      Left - Right

Scrolling:	Any: button2

Select	Line 	C-K
	Region	C-W Select
	All	M-W S-Select
	Any	button1
	Clear	C-c

Mark	Set	C-space
	Xchange	C-x

Center cursor	C-l

           Control-              Control-
Resize:     ] - }      or      Left - Right

Kill:	line:	C-k
	region:	C-w

Paste:	C-y	Insert	button3

		Previous:	Next:
Delete:	Char:	C-d Delete	C-h
	Word:	M-d		M-h
	Region:				C-Delete Button1-Delete

Case:	Upper:	M-u
	Lower:	M-l
	Cap:	M-c

Quote:			C-q
Transpose:	Chars:	C-t
		Words:	M-t

There are two entry bindings that do not correspond to text bindinngs.C-v has
the same binding for entries as C-y, it pastes the X selection. This is a
holdover from the original entry bindings. Finally, C-u kills the entire
selection retion. This is also a holdover from Tcl, but in Beth, one can still
paste text removed by C-u.

Paste:		C-v
Kill:	all:	C-u


File Access: filebind.tcl
-------------------------

This module introduces file I/O access. It brings up two label widgets on the
display, one displaying the current path of the loaded file, and one displaying
the current file name. Pressing mouse button 1 over either label replaces its
contents with a '-', pressing button 1 again brings the path or name back again.
This is useful for keeping the bottom status line short.

With file bindings, Beth monitors the contents of the text buffer (via the
modification checkbutton, see the editbind section for details.) It also
monitors the modification time of the file, and thus will know if the contents
of the text buffer differ from the contents of it's associated file. Any attempt
to load a new file (or the same one), or to quit will require a confirmation
dialog if the modification checkbutton is set. (see the dialog section for help
on using the dialog)

File selection is done with XF's file selection widget (see the XF help for info
on the file selector.) Beth ensures that neither the file selection widget nor
the dialog widget affect control.

The file bindings are as follows:

To save the current file, use M-s. M-s will prompt if no current filename is
known to Beth, otherwise it will silently save the file (and turn off the
modification checkbutton). To force file prompting, so you can save to a
different file, use M-S.

M-r reads in a new file, specified by the user. M-R is similar, but it 'reverts'
to the old file, it reads the old file without prompting (of course, if the
current buffer is modified, it will require confirmation.) Both M-r and M-R
erase the old contents of the text buffer.

To read a file without destroying the text contents, use M-C-i. It inserts the
contents of the (to-be) specified file before the insert cursor.

Finally M-C-v can be used to bring up another incarnation of Beth on a specified
file.

			Prompt
File:	save:	M-s	M-S
	read:	M-R	M-r
	insert:		M-C-i
	visit:		M-C-v


Incremental Search: searchbind.tcl
----------------------------------

Beth has a search system that performs a search on the string as the user types
it in. It can search forward from the insert cursor to the end of text, or
backwards from insert to beginning.

Entering search brings up a label named "Search" or "Reverse Search" depending
on the direction, and an entry containing the search string. To enter the search
mode, press C-s. C-r is similar, but it goes in reverse direction. C-S and C-R
are like C-s and C-r, except they bring up the previous contents of the search
entry; they are useful for searching the same string over and over again. The
Find key has the same function as C-s, and Shift-Find is the same as C-r

		 New		Old
Search:	Forward: C-s Find	C-S
	Reverse: C-r S-Find	C-R

The search entry accepts all entry bindings, including C-g (destroy entry) and
Escape (entry-text toggle). Every key pressed, including a control key that may
modify the entry performs another search. When a search string is found in the
text it is tagged with the 'search' tag. (There are no highlight bindings to the
search tag; it is recommended you add one, see the Startup section for details
on configuring the tags) The insertion cursor is moved to the region of the
search tag when a search succeeds.

Some keys have special bindings in the search entry. C-s performs another search
on the string, after the currently found one. If none exist, it signals an error
message. Pressing C-s after a failed search starts the search over from the
beginning. C-r is similar, except it goes in the reverse direction, and starts
from the end of text if pressed after a failed reverse search. The Find and
S-Find keys are bound to C-s and C-r in search mode, just like in regular mode. 
Finally, Return has the same effect as C-g, it exits the search.

Search:	Again:	Forward:	C-s Find
		Reverse:	C-r S-Find
	Exit:			Return C-g

Beth also has regular expression search. The keybinding C-M-s starts a search
for a regular expression the user inputs. This search is not incremental; to
actually perform the search, the user must hit C-s after entering the regexp.
There is also no reverse regular expression search. Other than C-r, and the
incremental aspect, regular expression searching has the same keybindings as
regular searching.

Search:	Regexp:	C-M-s


Query Replace: replacebind.tcl
------------------------------

This module implements global replace and query replace functionality in Beth.
It adds no bindings to the text widget, it merely extends the bindings of the
incremental search facility.

When the cursor is in the search entry (and thus has the special search
bindings), some extra bindings are added: One can enter replace mode by hitting
C-c. One can also use C-C, this also enters replace mode, but uses the previous
string; this is useful for doing the same search/replace in a variety of
sections in the text.

		New	Old
Change:		C-c	C-C

Entering replace mode brings up a new label named "Change to" and an entry with
the current replacement string (which would be empty if you used C-c). The
Escape key lets you toggle between this entry and the search entry and the text
widget. You can exit both search and replace with C-g or Return.

To change the current instance of the search string (that is, the instance
highlighted with the search tag), press C-c. It makes the change and moves on to
the next instance (or complains if there is none). Using C-c in conjunction with
C-s and C-r, you have the full functionality of a query replace system. You can
use query-replace with incremental search in both directions and with regular
expression search. Finally, you can issue a global replace with C-C. It replaces
all future instances of the search string with the replace string and destroys
the search and replace widgets. Note that this does not change all
occurrences...just the ones between the inseartion cursor and the end of text
(or beginning, if the current search direction is reverse).

Change:	Search	Again:	Forward:	C-s Find
			Reverse:	C-r S-Find
	This one:			C-c
	All:				C-C
	Exit:				Return C-g

Exiting replace mode automatically exits the search mode as well, and informs
you how many occurrences were replaced.


Parentheses Balancing: balancebind.tcl
--------------------------------------

This module implements balancing of parenthesis, brackets, and braces. It adds
no new keybindings or widgets to the screen, but, when loaded, it adds to the
bindings of the close paren, bracket, and brace a balancing routine. This
balancing routine ensures there is an open partner to the one just entered, and
highlights it if it exists, otherwise it complains about an imbalance. If a
partner exists, it then checks the region between the insertion cursor and the
partner to make sure things are internally consistent. It counts the number of {
and }'s for example, and complains if they are unequal.


Text Bindings: textbind.tcl
---------------------------

This module is only loaded when the startup file is a text document (i.e. it
doesn't end in .c or .tcl...see Startup for loading details) It implements some
text functions, and sets the text widget to word-wrap mode. Normally typing
beyond the end of the right edge merely moves the cursor to the next line on the
left column (though to the text widget it's still one line of text), and cares
not if it has broken a word across the edge. With word-wrap mode on, it will
move the entire word to the next line. (See text(n) for details on wrap mode.)

Note that lines to the text widget are not quite like lines to the user. To the
text widget, a line is a sequence of chars separated by a newline, but the user
sees an array of columns and rows. Line commands like C-n and C-p are
interpreted by the text widget's concept of lines. Thus if you type a multi-line
paragraph with no newlines, the text widget considers this as one line, and C-n
and C-p (and other line functions) will behave slightly different than
expected.

Two functions exist to alleviate this problem, however. The Return key, in
addition to entering a newline, will break up the line into several if it is
longer than the window's width. This should not visibly change the text, but it
fixes the behavior of line functions like C-n and C-p.

The other extreme is when many short lines appear in the text. Normally you want
paragraph lines to take up the entire width of the window, and splitting up long
lines via the Return key accomplishes this for lines that are too long, but
lines that are too short are another problem, and operations such as adding
newlines, or changing the window width can exacerbate this problem. Therefore
there is a function, bound to M-j, which adjusts the currently selected text so
it takes up the width of the window and contains no wraps. M-j does this by
first removing all newlines from the selection, and then splitting the selection
up into lines of the appropriate length. M-j operates on the selected region, or
on the current paragraph if no text is selected.

Several functions for paragraph selection and traversal are provided. A
paragraph is any range of text bounded by two newlines (or the beginning/end of
text). One can select the current paragraph with C-j. M-a moves to the beginning
of the current paragraph, and M-e goes to the end. Finally you can create a new
paragraph with S-Return, it simply adds two newlines.

				Meta-
Paragraph:	Traversal:	a - e
		Select:		C-j
		Adjust:		M-j
		Split:		S-Return

The indentation function C-i is also slightly changed. It works the same way as
before, but if no region is selected, C-i will indent the current paragraph.
Also it adjusts the paragraph to a shorter width before indenting, so no lines
wrap.


Dialogs: dialog.tcl
-------------------

This module is used by a few functions that contain long messages and a choice
of options, one of which is always encased in an extra frame; that is the
default option. Since all options are buttons, you can select one by clicking on
it. In addition, you can select an option by pressing a number key, 1
corresponds to the leftmost option, 2 to the next leftmost one, etc. Finally,
hitting Return automatically selects the default option.


Startup: beth.tcl
------------------

The file to start up Beth is beth.tcl. It takes the following command-line
arguments:

	-c Causes Beth to seize control upon startup.

 	-i Causes Beth to start up iconified. This option overrides -c.

 	-b Browse mode only, no editing provided. With this option, Beth starts
up in Browse mode. This mode only contains the functions from browsebind.tcl,
windowbind.tcl, interpbind.tcl, keybind,tcl, searchbind.tcl and entrybind.tcl,
none of which allow modification. Browse mode is useful for quick perusal of
files. Without this option, Beth also loads the filebind.tcl, replacebind.tcl,
and editbind.tcl modules.

	-t Title Adds the next word to Beth's window & icon title.

The last argument to Beth indicates what is to be edited or browsed. The
following options exist:

	-	Standard input. This is useful for pipes.
		(Example: ls -l | beth.tcl -)
	X	The X Selection
	file	The contents of the file indicated by pathname. If this file
does not exist, the text widget is left blank, but the file is remembered as a
new file, so saves automatically go to that file. The first save will create the
new file.

The startup file also checks for the existance of a .beth file in the user's
HOME directory, and if it exists, sources it. This enables the user to customize
Beth to his needs. For example, the user may specify when to load various other
modules, such as textbind.tcl. A sample .beth file might look like this:

-----
# Beth configuration file

$text tag configure search -background gold
$text tag configure balance -background magenta
catch {label_expand_toggle $frame.fpl fsBox(path)}

# Always load balancebind.tcl
set balance_list {{\( \) parenright} {\[ \] bracketright} {\{ \} braceright}}
source $beth_dir/balancebind.tcl

# Decide whether to load textbind.tcl
if {([file extension $option] == "") ||
     ([file extension $option] == ".tmp")} {
	source $beth_dir/textbind.tcl
}

# Print command
set print_cmd "| lpr -m -p -T [lindex [wm title .] 1]"
-----

The startup file performs the following operations:

1. Loads the widgets.tcl module, which creates the text widget and fills it with
its initial contents.
2. Loads the appropriate modules for browsing or editing.
3. Loads $HOME/.beth
4. Parses the command-line options.

The following constants are set by beth, but may be useful to the user for
reference or modification:

	option [lindex $argv [incr argc -1]]

This is usually the last command-line argument, and will generally be the
initial file to load, or X or -. However, if Beth is embedded in another
program, this variable may be set to a null string, in which case Beth does not
fill the text widget with anything.

	configs [lrange $argv 0 [incr argc -1]]

This is set to all command-line arguments but the last one, and will generally
be any switches Beth was called with (-b, -i, etc). A program embedding Beth can
set these switches to modify Beth's startup behavior.

	browse_cmd "beth.tcl -b X"
	visit_cmd "beth.tcl "
	help_cmd "beth.tcl -b HELP"

Used to start remote Beth interpreters under browse-region, visit-file, and help
commands.

	modified 0

Set when file is modified.

	undo_data {}
	max_undos -1
	max_undo_label 30

Undo material. Undo_data contains the log of undos. Max_undos specifies a limit on the size of undo_data, when -1 there is no limit. Max_undo_label specifies the maximum length of the string displayed by M-C-l.

	flash_time 3000

Length of time (in ms) labels are displayed.

	label_abbrev "-"

Replaces contents of labels upon a press by Button1. (This only affects permanent labels)

	e_ratio 1

Ratio of cursor to right end of entry before entry starts scrolling to the left.
(This is used to keep the cursor in view.)

	confirm_save_msg " has been modified. Do you want to save it first?"
	save_msg "Select a file to save"
	read_msg "Select a file to read"

You'll see these after pressing M-[RrSs].

	shiboleth "$text configure -background"

A recognition system for beth interps. A Beth interp must pass this test (i.e.
not throw an error) to be recognized as such.

	mutual_edit_conflict_msg " is being editied by another interpreter.
 What should I do?"

When a Beth interp tries to edit a file another Beth interp is already editing,
you'll see this message. Used to ensure mutually exclusive editing.

	default_universal_number 10

The default number of times a command gets executed by universal-argument, if a
numerical parameter is not specified.

	replace_msg "Change to: "
	search_msg "Search: "
	reverse_search_msg "Reverse Search: "
	search_failed_msg "Search failed: "
	reverse_search_failed_msg "Reverse Search failed: "
	regexp_msg "Regexp Search: "
	regexp_failed_msg "Regexp Search Failed: "

You'll see these message during Search and Replace operations.

	frame .frame

The widget path of the frame that messages and entries get posted to. If already defined before Beth starts, Beth does not create a frame widget.

	text .text

The text widget. If already defined before Beth starts, Beth does not create a text widget or a scrollbar.

	quit_hook

Beth executes this code upon quitting, if it is defined. (If Beth is embedded in
another program, that program should call the quit_beth procedure (no args) to
quit, and set this hook to its own quit routines.)

	dont_make_quit_button

If already defined before Beth starts, Beth does not put up a QUIT button in the
frame. (Beth can still be exited via C-q)

	dont_change_title

If already defined before Beth starts, Beth does not change the window title
upon startup.

	config_file "$env(HOME)/.beth"

Besides sourcing .beth at startup, .beth is used for child Beth processes to
refer back to their parent.


Module Adding: sendfile.tcl
---------------------------

The sendfile.tcl module is useful to modify Beth interps while they are
running. It takes two command-line arguments, the name of the interpreter to
send to, and the file to send. In this way, for example, you could add the
text bindings to an interpreter that did not originally load them. The name of
the interpreter is displayed in the interpreter entry widget.


Multiple Beth Interpreters: interpbind.tcl
------------------------------------------

Each interpreter maintains a list of currently active interpreters, and can
interact with them via the send command. Upon startup, a new interpreter
reevaluates the active interpreter list, including itself, and passes this info
to all interpreters. When an interpreter changes crucial info about itself, or
quits, it informs every interpreter of the change. This ensures that interps
keep track of each other, and every interpreter has the same knowledge of active
interpreters.

Any interpreter that quits while in control gives control to the next
non-iconified interpreter on the list, if there is one. This way you don't lose
control by quitting or iconifying an interpreter.

The following functions can be used to traverse through all non-iconified
interpreters. M-n switches control from the current interp to the next one on
the list. If the end of the list is reached, it continues searching from the top
of the list. M-p is similar, except it searches backwards through the list.
Also, there is M-N and M-P, which work similarly, except they traverse through
iconified windows as well, deiconifying any window they land on.

		All	Shown
Switch:	Next:	M-N	M-n
	Prev:	M-P	M-p

Finally, there is a function, M-C-b, which lets you identify the interp to
switch to. It brings up an entry where you specify the interp to switch to, then
it goes to that interp. You can specify a Beth interp by entering the contents
of its titlebar. The buffer you switch to will be deiconified if necessary and
raised, and receives control.

Switch:	To:	M-C-b


Key Bindings: keybind.tcl
-------------------------

This module performs some operations dealing with the current keybindings. It
provides two main functions.

The first one is a universal-argument function, bound to C-u. It provides the
ability to iterate through a key many times. Pressing C-u brings up an entry
window which takes the iteration number. This entry accepts number keys, and
reacts in the usual entry fashion for Escape (toggle text/entry) and C-g
(destroy entry) However, any key other than Escape, C-g, or a number key is
considered the iteration key, and the function associated with that key is
iterated as many times as was specified in the entry. If the entry was blank,
the key is executed 10 times by default. One can use C-u in conjunction with
many other key functions. For example, the sequence "C-u 20 C-n" goes down 20
lines, the sequence "C-u 5 C-[" shrinks the window by 5 lines, and the sequence
"C-u Return" inserts 10 carridge returns.

Universal Argument:	C-u

The other feature provided is a function to send keybindings to a set of
currently active Beth interpreters, so pressing a single key in one interpreter
executes the appropriate function in each beth interpreter. (Keep in mind that
each interpreter may have a different function associated to a key, for example,
sending M-s to every interpreter will cause those in browse mode to beep, since
they don't have a binding for M-s, but those in edit mode will save their
contents. There are two bindings to this 'all' function: M-k, which elects to
send the next key to all interpreters that are not currently iconified, and M-K
which sends the next key to all interpreters. When M-k or M-K is pressed, a
label marked "All" is pressed to indicate the next key is going to many
interpreters. Once the key is pressed, the 'all' mode terminates.

All:		M-K
	Shown:	M-k

Pressing Escape in 'All' mode again causes 'All' mode to become permanent, in
which case every keybinding is sent to each interpreter, until the next
occurrence of Escape. Some example sequences are: "M-K M-s" saves every
interpreter's contents, "M-k M-<" goes to the beginning of each interpreter's
contents, "M-k M-I" iconifies each deiconified interpreter, "M-k Esc C-s foo"
brings up the next instance of "foo" in every shown interpreter, and "M-K M-q"
causes each interpreter to quit.

You can have more than one interpreter in All mode, however any keybinding
executed in All mode destroys All mode for each window except the one the
keybinding originated in.


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