BETH Library Modules
------------------------------------------
Keybinding Reference Page:


Library Overview: libraries.tcl

Add:	Abbreviations:	M-a
	Balancing:	M-J
	Collapsing:	M-O
	Code:	C:	C-A
		Lisp:	C-D
		Tcl:	C-E
		Text:	M-j
	Make output:	M-e


Region Bindings: regions.tcl

				Control-
				   P
Region:		Traversal:	 A + E
				   N
		Select:		   j
		Kill:		   U
				Control-
		Delete:		 H + D


Text Bindings: textbind.tcl

Paragraph:	Adjust:		M-j
		Split:		S-Return


Code Bindings: tclbind.tcl, cbind.tcl, lispbind.tcl

Comment:	Adjust:		M-j


Parentheses Balancing: balancebind.tcl

				 Meta-
Expression:	Traversal:	 A + E
		Select:		   j
		Delete:		 H + D
		Kill:		   U


Collapsing Text: collapsebind.tcl

Collapse:	Selection:		M-O	(Double-B2)
		Region:			C-O	 Double-B2
		All:	Regions:	C-Y
			Fillers:	M-Y
			Both:		C-M-y.

Expand:		All:			M-C-o


Makefile Output: makebind.tcl

Error:	Next:	M-e


Abbreviation Expansion: abbrevbind.tcl

Complete Word:		Tab
Possible Completions:	C-Tab
Abbreviation:	Add:	M-a
		Save:	M-C-w	'write_abbrevs <file>'
		Load:	M-C-w	'source <file>'


Library Overview: libraries.tcl
-------------------------------

This module provides some simple loading mechanisms for accessing the library
files. It provides the following services:

First it defines the global variables add_file where file.tcl is a library file,
The value of $add_file is the code required to load the module. There is one add
variable for every library module.

Secondly, it provides menu options and keybindings for the useful modules to
add. (Note that not all the library modules are included here, some are useful
to other modules, but not to the user). All the new menu options are under the
new Module menu. The current menu options and keybindings are:

Add:	Abbreviations:	M-a
	Balancing:	M-J
	Collapsing:	M-O
	Code:	C:	C-A
		Lisp:	C-D
		Tcl:	C-E
		Text:	M-j
	Make output:	M-e

Once a module is loaded, the corresponding menu entry is diabled. The keybinding
is also disabled, it is usually redefined by the module for other purposes.

Thirdly, it may load one or more of the libraries, depending on the suffix of
the file being loaded. For example, it may load the C module if the file ends in
".c". This is not done for command pipelines.


Region Bindings: regions.tcl
----------------------------

This module introduces the concept of 'regions' of text that have a distinct
beginning and ending. This module adds some simple editing and browsing commands
for regions. Note that this module cannot be loaded by itself, since it does not
provide a definition for what regions actually are...another module must load
it. An example use of this module is used by textbind.tcl (see below), where the
regions are considered to be paragraphs of text.

One can traverse between regions with C-N and C-P. C-N puts the cursor at the
beginning of the next region, and C-P puts the cursor at the beginning of the
previous region (or current one if it is not already there). One can select the
current region with C-j. M-a moves to the beginning of the current region, and
M-e goes to the end. 

				Control-
				   P
Region:	Traversal:		 A + E
				   N
		Select:		   j

If the file is editable, then several editing functions are also added. C-D
deletes from the cursor to the end of the region, and C-H deletes from cursor to
beginning of the region. Neither can be yanked, but both are undoable. Finally,
C-U kills the current region, it can be yanked, though not undone.

				Control-
Region:		Delete:		 H + D
		Kill:		   U

The region traversal and selection functions are appropiately added in the
Browse menu hierarchy, and the region deleteion functions are added to the Edit
menu. (Note that the menu entry will not be called Region, but rather something
more appropriate for whatever is being edited, such as Paragraph.)


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

This module 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.

Paragraph:	Adjust:		M-j
		Split:		S-Return

By default, paragraphs adjust to fit within the window width. You can change
this by resizing the window, or by changing the following variable:

	adjust_line_width 0

When 0, paragraph adjustment defaults to window width, when nonzero, paragraph
adjustment is restricted to the value of this variable.

In addition to these functions, this module loads up the paragraph module, and
defines a paragraph to be any text between two newlines (i.e. a double space).

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.

The paragraph splitting and reformatting functions are added to the Edit menu.
In addition the usual region functions are added to the appropriate entries in
the Browse and Edit menus.


Tcl Bindings: tclbind.tcl
-------------------------
C Bindings: cbind.tcl
---------------------
Lisp Bindings: lispbind.tcl
---------------------------

These modules get loaded when the text being edited is program code in Tcl,
C/C++, or Lisp/Scheme. They use the regions module, where regions are defined as
procedures or functions. Thus you can traverse to the beginning or end of a
procedure, or select one. If editing is allowed, you can also kill a procedure,
or delete all the procedure up to the cursor, or from cursor to end.

Each module also defines a function, M-j, to adjust the text in a comment. It
works much like M-j does in text documents.

Comment:	Adjust:		M-j

As in textbind, this option can be found under the edit menu.


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.

In browse mode, this module will indicate the partner of a right paren, bracket,
or brace, w/o inserting the new character.

When this module is loaded, it loads the regions module. While groups of
parenthetical, bracketed, or braced expressions are not full regions, since they
can nest, several functions are available for traversal and editing of these
groups of text. Each command below pops up a label requesting whether the region
enclosed in parentheses, brackets, or braces is to be used, the user responds by
hitting a parenthesis, bracket, or brace key. Any other key aborts the
operation.

One can select the current balanced expression with M-J. M-A moves to the
beginning of the current expression, and M-E the end.

				 Meta-
Expression:	Traversal:	 A + E
		Select:		   j

If the file is editable, then several editing functions are also added. M-D
deletes from the cursor to the end of the expression, and M-H deletes from
cursor to beginning of the expression. Neither can be yanked, but both are
undoable. Finally, M-U kills the current expression, and it can be yanked,
though not undone.

				 Meta-
Expression:	Delete:		 H + D
		Kill:		   U

The region traversal and selection functions are appropiately added in the
Browse menu hierarchy, and the region deleteion functions are added to the Edit
menu. All the menu entries added will be under the name Expression. Also the
Find option under the Extras menu contains a submenu of partners to look for,
each of which is equivalent to pressing }, ), or ].


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.


Protecting Text: preventbind.tcl
--------------------------------

This module cannot be loaded by itself, since it adds no keybindings or options
to Beth, it is mainly for use by other modules or applications. It provides tag
bindings to protect text under 3 circumstances: select, move, and edit. The
three variables most useful are

	prevent_select_tags

When a tag is appended to this variable (which starts out empty), any text with
that tag will not be selectable, either by keyboard or mousae. (Actually you
might be able to select the tagged text in entirety, but you won't be able to
select part of the tagged text), nor the characters immediately before and after
the tagged text.

	prevent_move_tags

When a tag is appended to this variable, any text with this tag cannot contain
the insert cursor. Most traversals (keyboard or mouse) will simply move the
cursor 1 character after the text, a few will put it at the beginning. (For
example, C-b will go to the beginning to you can cross over a tagged range of
text).

	prevent_edit_tags

When a tag is appended to this variable, any text with this tag cannot be
modified. Any such attempts will be aborted.


Collapsing Text: collapsebind.tcl
---------------------------------

This module enables text to be 'collapsed', that is, temporarily replaced with a
one-line description. This text can later be 'expanded', i.e. restored to its
original contents, and this collapsing and expansion can occur for multiple
ranges of text, and is transparent through saving text.

The basic command available is one that collapses a selection of text. Pressing
M-O with a range of text selected collapses that text. One can restore that text
by pressing M-O again. Double-clicking mousebutton 2 over the selection has the
same effect, it will collapse the selection, or expand the collapsed text under
the mouse.

Collapse:	Selection:	M-O	(Double-B2)

One can also expand all collapsed ranges of text by pressing C-M-o.

Expand:		All:		M-C-o

If the regions module is loaded, or if it gets loaded later, several more
functions are available. One can collapse a region simply by putting the insert
cursor into the region and pressing C-O. If the cursor is in a 'filler' area
between two regions, that filler gets collapsed, instead. The cursor moves to
after the collapsed region, so one can collapse the next region (or filler if
there is any), and one can collapse many regions using the universal-argument
key (C-u).

Pressing mousebutton 2 twice is redefined to collapse the region under the mouse
pointer, or expand it.

Collapse:	Region:		C-O	Double-B2

Finally, one can collapse every region, or every filler, or every region and
filler. C-Y collapses every region in the text, M-Y collapses every filler, and
C-M-y collapses every region and filler. They can be expanded one-by-one with
C-O or M-O, or all at once with C-M-o.

Collapse:	All:	Regions:	C-Y
			Fillers:	M-Y
			Both:		C-M-y.

This module uses the prevention module, to prevent text describing collapsed
areas from being selected or edited. Since no text is actually modified, one can
use the collapse module completely in browse mode.

All functions described here are contained in the Collapse submenu under the
Extras menu.


Makefile Output: makebind.tcl
-----------------------------

This module is useful for checking the output of Makefiles for warnings in C
programs, and Beth's standard Make command includes this module automatically.
Sometimes it may also be useful to add this module to rmth when doing an
interactive compilation.

This module provides one function, that of visiting a C file that a compiler
complains about. Once this module is loaded, pressing M-e brings up the first
compiler error message after the insert cursor. If the C file in the message is
not already being viewed by a Beth interpreter, a new Beth interpreter is
started up on the file. Otherwise, the interpreter editing the file is brought
up and its cursor is brought to the line where the error occured. The original
interpreter's cursor is moved to the line with the error, or the line before, if
a new file had to be edited. This way, you can successively press M-e to view
subsequent errors.

Error:	Next:	M-e

While this is tailored to the error messages of most C compilers, it is useful
for visiting files under other circumstances. In particular, this command
traverses down until it finds a line with a filename and a number, and then it
visits that file, going to the line number. So, some other commands, such as
grep -n with multiple files, will also generate output suitable for traversal
with M-e.

This option is found under the Extras menu.


Abbreviation Expansion: abbrevbind.tcl
--------------------------------------

This module implements two levels of abbreviation completion in the text
widget. 

The first we'll call general abbreviation, After any word is partially entered,
pressing Tab will complete the word, provided it already occurs somewhere in the
text. You must enter at least 2 of the first letters for tab completion to work,
otherwise tab behaves as it normally does. If the wrong word is brought up,
pressing Tab again will switch to a different word that is a legitimate
completion. This way, you can traverse through all the possible completions of a
word. Once all completions have been traveresed, pressing Tab again will yield a
beep, then more presses of Tab will bring the series again. In general, Beth
searches backwards from the insert cursor for the completion of the word, and
searches from the end of text if no match was found before the cursor.

Pressing C-Tab will bring up a dialog containing all the possible word
completions available. You can select 'OK' to leave the word unchanged, or
select one of the words to use that completion.

So Tab and C-Tab now work in the text widget in very similar manners to the way
they work in the entry widget.

Complete Word:		Tab
Possible Completions:	C-Tab

It is also possible to add 'fixed' abbreviations, which take precedence over
general abbreviations. However fixed abbreviations can map to more than one
word, while general abbreviations are restricted to one word. Also, fixed
abbreviations do not have to match the first few characters of their expansion.

The way to add a fixed abbreviation is to enter the abbreviation in the text
widget and then press M-a. An entry is brought up, and you enter the expansion
word(s) into the entry. From then on, pressing Tab after the fixed abbreviation
will return the expansion.

Abbreviation:	Add:	M-a

It is possible to save the current set of fixed abbreviations to file, and
reload them. To save the expansions, enter the wish-command (M-C-w):

	write_abbrevs file

where file is the filename in which to store the abbreviations. (It could be a
command pipeline.) To reload the expansions, enter the wish-command:

	source file

where file contains the abbreviations. (You can load abbreviations created by
Beth or jedit (from the jstools distribution) in this manner.)

All of the options described above are listed under a new menu called
Abbreviations. In addition, there are two options to save and load abbreviation
files in the Abbreviations menu.


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