The Elsbeth Toolkit The Problem and Solution Tk provides many widgets, and provides a few rudimentary functions to perform on those widgets (many of them introduced in Tk4.0). But they are very rudimentary, and for anything but the most basic problems, one needs various extensions. For example, an entry widget provides keys to move the insert, and add or delete text, but it provides no innate search capability. Many different solutions are attempted to fix this problem. 1. Many programs simply extend the functions on-the-fly for whatever widgets they are using. For example, Tknews lets you write a posting to a file, (actually it appends to the file, creating it if necessary). This improves Tknews's functionality, but no other program can use this feature. 2. Several systems that involve text editing provide simple (or not-so-simple) text editors. The jstools library includes jedit, an excellent text editor, plus several other programs that use the functions provided by jedit, which provide a uniform interface to functions like text searching. However, the functions are still unavailable to other programs outside jstools. 3. Some toolkits provide functionality includable in new Tk programs, but require the programmer to incorporate the functionality into their application. The searchbox tool provides the text-search mechanism used by TkMan, and allows you to incorporate it into your program. Thus, you can add TkMan's text-search function to another Tk program, but this requires a bit of programming work. 4. Some toolkits provide a large set of simple functions to be included in any Tk program without modifying that Tk program. The Emacs-bindings package by Paul Raines can be used on any Tk program to give some Emacs functionality to Tk text widgets. Toolkits like this add functionality independent of the Tk application actually running, so they will (theoretically) work under any application. The only disadvantage here is that they don't come with any applications of their own (except simple demoing scripts). 5. The Teacher Hypertools package is an example of the latter, a set of programs that add code to remote programs to increase their functionality. No programming work on the part of the user is required. The main disadvantage of the Teacher Hypertools is that the improvements made to remote applications are temporary; there is no general mechanism that enables a remote program to always run with the features provided by one or more hypertools. The Elsbeth toolkit hopes to unify these five approaches to extending Tk widget functionality. It provides a library of bindings to add functions like search/replace, interactive window sizing/movement, completion, and many other goodies to most of the standard Tk widgets. The user can access them in five ways: 1. The widget functions are all provided as an indexed Tcl library (in the /lib directory). The programmer can use the functions by adding the library directory to his auto_path. 2. The widget functions can be taught to a remote widget using an appropriate Teacher Hypertool. 3. This toolkit provides thbind, a program which allows the user to invoke any Tk application with the bindings provided by the Elsbeth toolkit. The user simply calls thbind with the application's name and arguments as arguments (to thbind). If you have one program that should always use the Elsbeth bindings, you can simply have that program source the file lib/tk.tcl. If you want every Tcl program to use the Elsbeth bindings, set your TK_LIBRARY environment variable to point to elsbeth's lib directory. This loads up the Elsbeth bindings, as well as standard Tk initialization upon startup of any application. 4. This toolkit also provides Elsbeth, a comprehensive text editor based on the bindings provided herein. 5. This toolkit also contains several other programs built on elsbeth, that use elsbeth's functionality in their own special ways. The toolkit comes with online documentation, provided in different ways, depending on the approach used to invoke the functions: 1. Comments in library code to aid in linking a program correctly to the routines provided by the library. 2. Each hypertool has a 'help' menuoption, describing the functions it teaches, and how to use the hypertool itself. 3. Applications started with thbind don't provide documentation on the elsbeth bindings per se, but they do bring up a menubar containing all the available functions and their associated keybindings on any widget, simply by pressing button-3 over the widget. Pressing button-3 again makes the menubar disappear. 4. Elsbeth has a Help command, which brings up a window showing full documentation on Elsbeth's functions. You can also press button-3 in any Elsbeth widget to get a menubar of available functions. 5. Of the applications that use elsbeth, rmth provides its own documentation. The other programs are much smaller and have documentation at the top of their source code. Special Features of the Elsbeth Toolkit Here are some of the features provided in the library. They are available from all approaches; you can give them to your remote application using thbind or a teacher hypertool, or you can use them in elsbeth: - Compatible with Tk versions 4.0 and higher. - Global search/replace, for strings or regular expressions. - Unlimited undo, including undoing replace. - Optional horizontal and vertical grids and scrollbars. - Piped I/O to files or standard shell commands. Piped input is shown as it gets read, and the widget can be browsed during reading. - Execute wish/exec commands, with I/O with any 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 N times. - Execute a function in all widgets of the same class with one key. - Windowing functions for resize, move, raise, iconify. - Parentheses balancing (also brackets, quotes, C comments...). - Text marking and painting, various forms of highlighting. Here are some special features of Elsbeth: - Brings up any number of files, each in its own text window. - Can place all files in one toplevel window, or put each file in its own toplevel, letting you arrange them to your liking - Switching between multiple Elsbeth windows from the keybaord. - Simple modes for: Text, HTML, C, Lisp, Tcl, Perl - For each file, Elsbeth remembers things like window size & placement, cursor location, marks, and grids across sessions. Installing and Configuring the Elsbeth Toolkit This set of tools is completely written in Tcl/Tk. To configure the toolkit to run on your system, you can do either the quick 'n dirty approach or the slow & sure approach. If you want to change default bindings or behavior of the library tools, use the slow&sure approach, otherwise you're better off with the Q&D one. The quick'n dirty approach: In lib/tk.tcl, you will see: set tk_library {/afs/ece/usr/tcl/lib/tk4.0} source $tk_library/tk.tcl set auto_path "/usr/users/svoboda/src/elsbeth/lib $auto_path" The first line should reflect the directory of the Tk (4.0 or higher) library, and the last line should reflect the location of elsbeth's library. The slow 'n sure approach is useful if you want to change the default keybindings, or some of the behavior of the teacher hypertools. You don't need to hack around with files in the lib or aux directory to do this. Simply start up bin/makebeth, and select, first the "Binding Library" menuoption, then the "Make Elsbeth" menuoption, and then quit. Both options will take about a minute to compile the appropriate files. Before doing either menuoption, you can tweak the hypertools around to your liking...select makebeth's Help menuoption for details. NOTE: These tools require that you have wish version 4.0 or greater in your $PATH as just 'wish'. You can run any tool by typing ' ' or just 'elsbeth/bin/' or just ' if you add elsbeth/bin to your $PATH. If you don't have wish in your PATH, you can change the top line of each program in the /bin directory to reflect the location of wish. Makebeth, however, will still require that wish be in your path to create elsbeth and the binding libraries properly. ANOTHER NOTE: Don't run makebeth if you've already set TK_LIBRARY to the elsbeth/lib directory...that would be bad. What are Teacher Hypertools? See the file th.background for basic information about Teacher Hypertools. Contents of the Elsbeth Toolkit: bin: All programs; not all are hypertools. lib: All code taught by hypertools. aux: All code used by hypertools and elsbeth, but not taught to other programs. Teacher Hypertools Provided: Nearly all of these are used by elsbeth, and all of them can teach things to other programs. browseth Teach traversal, scrolling and selection commands to widgets busyth Teach an application to indicate when it is busy commandeth Teach remote programs to prompt the user for wish or shell commands. completh Teach many different types of completion to textual widgets cth Teach text widgets to format C comments and functions edith Teach basic text editing commands to widgets filebrowseth Turn text widgets into simple file/directory browsers fileth Teach file I/O to widgets focuth Teach keyboard focus switching between widgets gridth Add row and column numbers to text, listbox and entry widgets historyth Teach remote entries to remember their previous contents htmlth Teach text widgets to format HTML iterath Teach widgets to iterate commands many times at once. lispth Teach text widgets to format Lisp comments and functions marketh Teach text widgets to highlight important regions of text makebeth Create Elsbeth (see above) multh Teach multiple widgets of same class to work with each other painth Teach text widgets to paint certain regular expressions paragrath Teach text widgets about paragraphs parenth Teach widgets to help keep parentheses and other delimiters balanced resizeth Teach widgets to shrink and expand themselves scrolleth Add and remove scrollbars to scrollable widgets searcheth Teach widgets to search for strings, glob patterns, or regular expressions taggeth Add a menu of tags to a text widget tclth Teach text widgets to format Tcl comments and procedures windowth Teach programs to resize, move, and iconify their windows th This is a 'catalog' program that lets you run any of the other hypertools listed above, the easiest way to access the hypertools is to run this program. To run it type "bin/th". Other programs available: elsbeth The editor. els A bare-bones text viewer. It takes same parameters as elsbeth, and brings up all text widgets, but adds no bindings. elsclient Takes elsbeth parms. Finds an already-running elsbeth process, or starts a new one. Exits when windows given to it are closed. Useful for programs that like to invoke an editor and wait for it to finish. rmth A wish and shell interpreter that uses Elsbeth's features. thbind A handy way of using the elsbeth binding library; it sources the library and then calls the program and args in $argv. thcolors A virtual color displayer, also uses elsbeth thfonts A virtual font displayer, uses elsbeth bsend A mail-sending program using elsbeth bread A mail-reading program using elsbeth bith A mail-notification program, loads up bread These three programs were created to process my mail quickly and easily. (I use mh on a Dec3100 running Ultrix4.4.) I make no gaurentees regarding their portability. Some other noteworthy files: aux/bindings.th/bindings This contains all the key and menu bindings taught by hypertools, in a single file for changeability. You can change the bindings in this file, or you can change them individually in each hypertool, or in makebeth. aux/elsbeth.bindings.tcl This file contains the key and menu bindings for elsbeth. It is created from aux/elsbeth.tmpl by bin/makebeth's 'Make Elsbeth' feature. If this file doesn't exist, bin/elsbeth behaves like bin/els. aux/elsbeth.help The help file for elsbeth; it is also created by makebeth. aux/rmth.HELP.txt Additional help file for rmth aux/elsbeth.rc My own ~/.th/elsbeth file...shows my preferences aux/thbind.rc Same thing for thbind. aux/rmth.rc Same thing for rmth. aux/mh_profile Excerpt of my ~/.mh_profile, which links bread and bsend to some of mh's commands. lib/bind.Misc.tcl Elsbeth's binding libraries. Created lib/bind.*.tcl by makebeth. lib/tk.tcl Analogous to tk.tcl in Tk's library. Loads up Tk bindings, then elsbeth bindings. Resets tk_library to the Tk library (in case it was set to the elsbeth library). Elsbeth & Teacher Hypertools: Copyright (c) 1994, 1995 David Svoboda Permission to use, copy, modify, and distribute this software is hereby granted, provided that the above copyright line appears at least once in source code taught by Teacher Hypertools, and in documentation relating to said code. However, permission is not granted to modify the copyright insertion code. This basically means: if a Teacher Hypertool sticks a copyright message in code it teaches, and you copy that code to a file, leave the copyright message in. And include it in your documentation. If it doesn't stick a copyright in code, don't worry about it. Go ahead and fiddle around with the Teacher Hypertool source code, and improve it (and drop me a line if you do, I'd be interested), but don't change the code that inserts copyright notices. Disclaimer I don't see how its possible, but if this software crashes your system, destroys your hard disk, posts to alt.flame asking for mail-bombs, etc. etc, I didn't do it, man. :) Bugs 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 Elseth 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 Elsbeth. If you get a reproduceable Tk error which you suspect is a bug in Elsbeth, check the documentation in the hypertools to see if your bug is mentioned in its documentation. For example, if you get an error message when pressing a close parentheses, you might check the parenth hypertool's documetation (just run it and press 'Help'). If your bug is mentioned there, I know about it, and either considered it a feature, or too hard to fix. If you know of a fix, workaround, or simply a better way of doing things, please tell me. If you get a bug which is not covered in the hypertools documentation (or its simply in the wrong one), please let me know. (If its merely covered by a different hypertool, that's still a stylistic bug that I can fix by writing better documentation :). 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 Elsbeth 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 Elsbeth. (a few are mentioned in the TODO file) The best way to extend Elsbeth is by writing a Teacher Hypertool teaching your new feature and include it in makebeth (which can be a simple or complex job depending on the hypertool). Of course, a quick means of extension is to write a script that first calls elsbeth and then adds your feature. (Thcolors, thfonts, and rmth all do this), but then only elsbeth can use your new feature. Putting it in a hypertool allows any program to use it. If you make any popular hypertools or improvements, I would like to hear about them; Elsbeth WWW Page There is a WWW Page devoted to Elsbeth, located at: http://www.ece.cmu.edu/afs/ece/usr/svoboda/www/elsbeth/homepage.html Send questions and comments to David Svoboda . Last modified: December 11, 1995