The ABC Programmer's Handbook by Leo Geurts, Lambert Meertens, and Steven Pemberton

Appendix 2 ABC Implementations

Workspaces
Error messages
Key bindings
Running ABC
Workspace options
Special tasks
Running non-interactively
The Atari ST implementation
The IBM PC implementation
The Macintosh implementation
The Unix implementation

We have tried to make the behaviour of all ABC implementations as identical as possible. Therefore, this appendix is only about machine particularities such as what files are involved, where they are kept, and so on. With all implementations, you should first check if there is a file README on the disk or tape, and if so read it: it will be an update on the documentation.

Workspaces

When you run ABC for the first time, it creates a directory (or folder) called abc where it makes separate directories for each workspace you make. This directory is created in your home directory on Unix, in the folder where ABC was started from on the Macintosh, and in the root directory of the current disk on other implementations. Additionally, in directory abc , it creates a file wsgroup.abc which maps workspace names to directory names, and gives the remembered name of the last workspace used.

In each workspace directory, the system creates files ending with the following names:

.cmd for commands
.zfd for zeroadic functions
.mfd for monadic functions
.dfd for dyadic functions
.zpd for zeroadic predicates
.mpd for monadic predicates
.dpd for dyadic predicates
.cts for permanent location contents.

Additionally it makes the following in each workspace:

perm.abc mapping ABC names to file names

position.abc position when a file last visited

suggestion.abc suggestions for this workspace.

Error messages

All implementations, except on the Macintosh, use a file abc.msg which contains nearly all error messages produced by ABC. You can translate this file, to produce a foreign-language version of the error messages. Messages marked with an asterisk `*' are system errors, and in principle shouldn't occur, so do not need to be translated. ABC looks for this file in a number of places: in the directory where you started ABC up, in the workspaces directory mentioned above, or in one of the directories in the PATH environment variable, if set.

In other words, put the messages file in the same directory as the ABC program itself, or in the workspaces directory.

On the Macintosh, the errors are resources which you must edit with a resource editor.

Key bindings

ABC comes with a standard set of ` key-bindings' (which keys are used for which operation) to suit the keyboard of the machine you are using. To see these defaults, type ? at the command prompt >>> . You can change these bindings by running the program abckeys (though not on the Macintosh).

This program is self-documenting, and allows you to specify your own bindings for the operations described in the chapter on using ABC. For any operation you may specify as many alternatives as you wish. If a new binding clashes with another binding, the old binding is removed.

The program then writes a file in the abc directory mentioned above, specifying the bindings. This file is then read on start-up by the ABC system.

This file is called abc.key , except on Unix, where you may have one such file for each terminal type you use. There, each file is called abckeys_ term, where term is the contents of the Unix environment variable TERM .

There are three special entries that you can define. The entry ignore is for any sequence you want the system to ignore (this is mainly useful for using the ABC system using a modem on a noisy telephone line). The entry term-init specifies characters that are sent to the screen when ABC is started; you can use this to send characters to set the screen background colour for instance, or to set programmable function keys, if your terminal has them. Similarly, term-done specifies what is to be sent when ABC finishes.

Running ABC

Apart from running ABC as described in the chapter on using ABC, there are a number of optional flags that you can give when starting ABC up.

Workspace options

Starting ABC up with

abc -w name

starts in workspace name , instead of the default (which is whichever you were in last time, or in workspace first , if this is the first time).

Starting with

abc -W dir

uses the group of workspaces in dir instead of the abc directory mentioned above. You can combine it with the -w option, for example:

abc -W c:\programs -w demo

Finally,

abc -w path

uses path as the current workspace (in which case no -W option is allowed). For instance,

abc -w c:\programs\demo

The difference between this, and the example above, is that the system doesn't use c:\programs as a repository for other workspaces, and doesn't make the wsgroup.abc file, so you can't change workspace from within ABC using this form.

Special tasks

There are a few special options for dealing with workspaces from outside ABC.

abc -i tab

fills table tab with text lines from standard input. Use the -w option to be sure of which workspace it will be put in. For instance, on Unix and MS-DOS,

abc -w demo -i text < readme

will convert the file readme in the current directory into an ABC table called text in workspace demo .

Similarly

abc -o tab

writes such a table out to standard output. For instance

abc -w demo -o text > newfile

The command

abc -l

lists the how-to's in a workspace on standard output; you can then send this output to the printer. Use the -w option to be sure of which workspace will be listed. For instance, on MS-DOS:

abc -l -w demo > prn:

Finally, there are two options to restore the ABC internal files, if they have been accidentally lost, or if you have added some how-to's to a workspace independently of the ABC system:

abc -r

recovers a workspace when its index is lost, for instance

abc -w demo -r

and

abc -R

recovers the index of a group of workspaces.

Running non-interactively

You can give the names of files containing ABC commands to ABC, and then it runs the commands instead of starting up interactively. Input for READ commands then comes from the standard input. For instance, if the file run contains

WRITE 2+2

then the command

abc run

will cause 4 to be written. Similarly, if run contains

DEMO1

then the command

abc -w demo run

will run the command DEMO1 from the workspace demo , and then stop.

The Atari ST implementation

There are four files supplied: the program abc.tos itself, the help file abc.hlp , the error message file abc.msg , and the program abckeys.tos for changing your key bindings. When running ABC, you may use the mouse as described in the chapter on using ABC.

If you start ABC up from the desktop, and you want to use the options given above, like -w , you should rename abc.tos to abc.ttp . There is an additional facility for redirecting input and output: the parameter >outfile redirects all output from ABC to the file called outfile , and similarly <infile takes its input from the file called infile (you can call the files anything you want).

There is a bug in some versions of the Atari desktop that converts all lower-case letters to upper-case when you give the options. This means that you can't use the options -w and -r (because the program sees them as -W and -R ). If you have this bug and you want to use these two options, use the letters -x and -s instead (the next letters in the alphabet after W and R ).

The IBM PC implementation

There are four files supplied: the program abc.exe itself, the help file abc.hlp , the error message file abc.msg , and the program abckeys.exe for changing your key bindings.

If your screen size is non-standard, or your machine is not 100% BIOS compatible (which is unusual these days), you can specify the screen-size, and whether to use the BIOS or ANSI.SYS for output, by typing after the A> prompt, before you start ABC up, one of the following:

SET SCREEN=ANSI lines cols

SET SCREEN=BIOS lines cols

If you are going to use ANSI.SYS , be sure you have the line

DEVICE=ANSI.SYS

in your CONFIG.SYS file. Consult the DOS manual for further details.

The Macintosh implementation

There are three files supplied: the program MacABC itself, the help file MacABC.help , and MacABC.doc , a MacWrite document containing a version of the help file. The help file should be in the same folder as MacABC, or in your system folder. To change the error messages, you must use a resource editor.

ABC runs in a single window. You'll notice that most operations, as well as being possible from the keyboard, are also menu entries. You can start ABC up by double-clicking the MacABC icon in which case you start up in the last workspace used, or by double-clicking on any icon in a workspace, in which case you start up in that workspace. In this latter case, if the filename of the icon you clicked on ends in .cmd , that how-to is executed, but the how-to must not have any parameters.

Instead of the special option flags mentioned above, most of the tasks, like recovering a workspace, can be done from the File menu.

The Unix implementation

If the system has been set up right, you should be able to say man abc to get online documentation about ABC.

There is an additional option when running ABC:

abc -e

uses the editor named in the Unix EDITOR environment variable as editor to edit how-to's.

Apart from the abckeys_* files mentioned above, ABC gets some of its information about the terminal from termcap (in particular whether there are arrow keys, and whether there are function keys), and some information from the stty settings (in particular what your interrupt character is; see the manual for stty if you want to change it).

If your version of Unix supports job control, you can suspend ABC in the normal way (usually using control-Z).

Finally, if your terminal has a mouse, ABC can support it if there is a way for the mouse to send a click and its position as a sequence of characters.

To configure ABC to be able to do this, use abckeys to set the operation to the characters that get sent when a click occurs, and add two extra fields to your termcap entry to specify how the system finds out where the click occurred: sp which gives the characters that have to be sent to enquire where the click occurred, and cp which says what the reply looks like. These are both in the same format as other cursor-addressing strings in termcap - see the termcap manual for more information.

If the mouse click sends the position as well, you must set the [ goto] operation to the initial characters that get sent (minus the position) and set sp to the empty string.

As an example of one of the more popular interfaces, in an xterm window, if you set your ABC term-init (using abckeys ) to send the characters ``ESC [?9h '', mouse-clicks will then send their position as ``ESC [M xy'', where x and y are two characters specifying the position. So, specify that the binding for the [goto] operation (still using abckeys ) is ``ESC [M '', and add the following two fields to your termcap entry: sp=:cp=%r%+!%+! (sp is empty because a mouse click sends the position).

You should set term-done in abckeys to ``ESC [?9l '' so that mouse clicks return to their normal behaviour when you leave ABC.

The ABC Programmer's Handbook by Leo Geurts, Lambert Meertens, and Steven Pemberton