Using ABC

abc - ABC interpreter & environment
abckeys - change key bindings for 'abc'

Synopsis

abc [ -g dir ] [ -w name ] [ -c name ] [ -e] [ file ... ]
abc [ -g dir ] [ -w name ] -i tab | -o tab
abc [ -g dir ] [ -w name ] -l | -p | -u [file ... ]
abc [ -g dir ] [ -w name ] -r | -x
abckeys

Description

Without options or files, the ABC interpreter is started, using the ABC editor, in the last workspace used or in workspace 'first' if this is your first abc session. A workspace is kept as a group of files in a directory, with separate files for each how-to and location. The workspace directories themselves are kept by default in the directory $HOME/abc. On Windows, $HOME is the folder My Documents.

Workspace Options

-g dir
use group of workspaces in 'dir' instead of $HOME/abc.
-w name
start in workspace 'name' instead of last workspace used.
-w path
use 'path' as workspace (no -g option allowed).
-c name
use 'name' as central workspace (default: $HOME/abc/abc).
-c path
use 'path' as central workspace.

Run Options

-e
Use $EDITOR as editor to edit definitions, instead of ABC editor.
file ...
Read commands from file(s) instead of from standard input; input for READ commands is taken from standard input. If a file is called '-' and standard input is the keyboard, the ABC system is started up interactively for that entry.

Special tasks - table handling

-i tab
Fill table 'tab' with text lines from standard input.
-o tab
Write text lines from table 'tab' to standard output.

Special tasks - workspace handling

-l (Letter L)
List the how-to's in workspace to standard output.
-p
Pack how-to's and locations from a workspace to standard output.
-u [ file ... ]
Unpack how-to's and locations from file(s) or standard input in workspace.

Special tasks - recovering

-r
Recover a workspace when its index is lost: useful after a machine crash if the ABC internal administration files didn't get written out.
-x
Recover the index of a group of workspaces.

Usage

(This is necessarily a very brief description; see 'The ABC Programmer's Handbook' for full details.)

When ABC starts up interactively, it displays a prompt and awaits input.

Use 'QUIT' to finish an ABC session.

Typing and Suggestions

As you type, the system tries to suggest a possible continuation for what you have typed; to accept the suggestion, press [accept] (by default this is bound to the [tab] key; type '?' to find out the bindings for the keyboard you are using). If you don't want to accept the suggestion, just carry on typing (you can always type character for character, ignoring the suggestions). Usually the system knows where a letter must be capital and where not, and you usually don't have to use the shift key; however, in the few places where both a lower-case and an upper-case letter would be legal (for instance for AND), you have to type the letter upper-case.

When you type a control command, like WHILE, the system provides indentation automatically for the body of the command; to reduce the indentation one level, type [return].

Correcting and Editing

The [undo] key (by default bound to [backspace]) undoes the last key you typed. Repeatedly typing it undoes more and more, up to a certain maximum number of key-presses.

To correct other parts, you must put the 'focus' onto the part you want to change. The focus is displayed by underlining or reverse video. [Widen] and [extend] make the focus larger, [first] and [last] make it smaller.

[Delete] deletes the contents of the focus.

[Copy] copies the contents of the focus to a buffer, or if the focus is not focussed on anything, copies the contents of the buffer back to where you are positioned.

Moving the Focus

[Upline] and [downline] focus on one line above or below. [Previous] and [next] move the focus left and right. [Up], [down], [left], and [right] move an empty focus around. [Goto] widens the focus to the largest thing at the current cursor position. [Mouse] moves the focus to the largest thing at the position of a mouse-click.

Other Operations

[look] redraws the screen; [record] records all keystrokes until the next time you press [record] -- [play] replays them. [Redo] redoes the last key(s) undone; [interrupt] interrupts a running command.

Workspaces

To create a new workspace, or go to an existing workspace, type '>name'. To go to the last workspace you were in, type a single '>'. To get a list of workspace names, type '>>'.

How-to's in the central workspace can be invoked in any other workspace. Shared locations used in central how-to's access locations in the current workspace, however. The default central workspace is $HOME/abc/abc; it can be changed with the '-c name' option. To edit how-to's in the central workspace, you must go to it.

How-to's

To create a new how-to, just type the first line of the how-to. This creates the new how-to, and allows you to type the body. Use [exit] to finish it (by default [esc][esc]).

To visit a how-to, type a colon, followed by the name of the how-to. Again, use [exit] to exit. To visit the last how-to again, or the last how-to you got an error message for, type a single ':'. To get a list of the how-to's in this workspace, type '::'.

To edit a location, type a '=' followed by the name of the location. To re-edit it, type a single '='. To get a list of the locations in the workspace, type '=='.

Key Bindings

The binding of editing operations like [accept] to keys may be different for your keyboard; type a '?' at the prompt to find out what the bindings are for your keyboard.
To redefine the keys used for editor operations, run 'abckeys'. This produces a private key definitions file. You will be given instructions on how to use it.
Keys labeled f1...f8 are function keys. On Unix, the way to type these is terminal-dependent. The codes they send must be defined by the termcap entry for your terminal.
If a terminal has arrow keys which transmit codes to the computer, these are used for Up, Down, Left and Right. Again, the termcap entry must define the codes. See termcap (5).

Mouse and Goto

The [mouse] operation can be used to move the focus using your mouse. For simple cases, the program 'abckeys' is smart enough to work out the behaviour of your mouse, and add suitable definitions to your key definitions file. If it fails you must add some extra definitions yourself: apart from [mouse] you should define [mouse-format] and possibly [mouse-sense] in your key definitions file, according to which of the following schemes applies: 1) a mouse-click sends a sequence of characters that includes the position information, or 2) a mouse-click sends a fixed sequence, and the terminal must then be asked where the click occurred.
For 1) [mouse] must be bound to the initial sequence that the mouse click sends, [mouse-sense] should be empty, and [mouse-format] should describe the rest of the sequence.
For 2) [mouse] should be set to the fixed sequence the mouse click sends, [mouse-sense] to the string that should be sent to the terminal to ask for the click position, and [mouse-format] to the format that describes the reply.

The [goto] operation is of most use if the cursor can be moved locally at the terminal, and the terminal can then be sensed for the cursor position. You must define two extra operations for this in your key definitions file: [cursor-sense] which gives the string that must be sent to the terminal to sense the cursor position, and [cursor-format] which should define the format of the reply.

Mouse click and cursor sense formats

A format that describes the mouse click or cursor reply sequences, has the following possibilities (based on the cursor-addressing format of termcap(5)):
All characters in the string literally match the corresponding character in the reply, except a % followed by other characters, which have the following meaning:

The following two do not match anything in the input, but affect the way numbers are interpreted:

Key Definition Format

A key definition should be on one line in the key definitions file as follows: 
   [operation-name] = "definition-string" = "representation-string"
The operation-name can be any regular operation, or one of [mouse-sense], [mouse-format], [cursor-sense] and [cursor-format]. The definition string can use '\e' or '\E' for the ESC character, or the normal escape sequence in C strings for control characters (like '\015' for the RETURN or CR character). The representation string must be a string of printable characters for use in the help summary.

Example

An xterm window sends a mouse click as 'ESC [ M c x y' where c is a single character , ! or ", depending on which button is pressed, and x and y are single graphic characters starting at '!'. So, [mouse] can be bound to 'ESC [ M' and the format would be '%.%r%+!%+!', e.g.: 

   [mouse] = "\e[M" = "mouse-click"
   [mouse-format] = "%.%r%+!%+!" = ""
The representation string for the mouse-format can remain empty since it won't be displayed in the help summary.
Another possibility is to bind [mouse] to "\e[M ", "\e[M!", and "\e[M\"", and set the format to "%r%+!%+!".
(To get xterm to send mouse clicks, you have to initially send the string 'ESC [ ? 9 h' which you should put in your [term-init] binding as "\e[?9h".)

A uw window sends a mouse click as a mouse-down sequence and a mouse-up sequence, of the style 'ESC m y x 0 ESC m y x @', where x and y are single characters of the same style as xterm. So you can bind [mouse] to "\em", and the format to \&"%+!%+!0\em%+!%+!@", or "%+!%+!%." (in the second case, [mouse] gets called twice in quick succession).

On a Hewlett Packard 2640b, the terminal can be asked for the current cursor position with the string 'ESC \(ga DC1'; it returns the position in the format 'ESC & a x c y Y CR', where x and y are numbers. Therefore you should add to your key definitions file: 

   [cursor-sense] = "\e`\021" = "" [cursor-format] = "\e&a%r%dc%dY\015" = ""

Files

$HOME/copybuf.abc
copy buffer between sessions
$HOME/abc/wsgroup.abc
table mapping workspace names to directory names
$HOME/abc/abc$TERM.key
private key definitions file (Unix only)
$HOME/abc/abc.key
private key definitions file (non-Unix)
position.abc
focus position of edited how-to's in workspace
perm.abc
table mapping object names to file names
suggest.abc
suggestion list for user-defined commands
types.abc
table with codes for type-checking between how-to's
*.cmd
command how-to's in this workspace
*.zfd,
*.mfd, *.dfd function how-to's in this workspace
*.zpd,
*.mpd, *.dpd predicate how-to's in this workspace
*.cts
permanent locations in this workspace
abc.msg
messages file, used for errors (not on Macintosh)
abc.hlp
helpfile with this text (MacABC.help on Macintosh)

The latter two are searched for first in your startup directory, then in $HOME/abc, and finally, on Unix, in a directory determined by the installer of ABC. On a PC, $HOME = My Documents.

PC Implementation

There are four files for running ABC, the program abc.exe itself, abckeys.exe for changing your key bindings, the help file abc.hlp, and the error messages file abc.msg. (See FILES above.)

If you want to use a window size other than the default 25 x 80, you can specify the screen-size by typing after the C> prompt, before you start ABC up, the following: SET SCREEN=BIOS lines cols

See Also

Authors

Eddy Boeve, Frank van Dijk, Leo Geurts, Timo Krijnen, Lambert Meertens, Steven Pemberton, Guido van Rossum.

Address

ABC Distribution, CWI/AA, Postbox 4079, 1009 AB Amsterdam, The Netherlands.
E-mail: abc@cwi.nl

Summary of Special Actions

:name
Visit how-to called 'name'
:
Visit last how-to referred to
::
Display headings of how-to's in this workspace
=name
Visit contents of location 'name'
=
Visit last location visited
==
Display names of permanent locations in this workspace
>name
Visit workspace 'name'
>
Visit last workspace visited
>>
Display list of workspace names
QUIT
Leave ABC

Summary of Editing Operations

Name Default Keys Short description
Accept [TAB] Accept suggestion, focus to hole or end of line
Return [RETURN] Add line or decrease indentation
Widen f1, [ESC] w Widen focus
Extend f2, [ESC] e Extend focus (usually to the right)
First f3, [ESC] f Move focus to first contained item
Last f4, [ESC] l Move focus to last contained item
Previous f5, [ESC] p Move focus to previous item
Next f6, [ESC] n Move focus to next item
Upline f7, [ESC] u Move focus to whole line above
Downline f8, [ESC] d Move focus to whole line below
Up [up arrow], [ESC] U Make new hole, move up
Down [down arrow], [ESC] D Make new hole, move down
Left [left arrow], [ESC] , Make new hole, move left
Right [right arrow], [ESC] . Make new hole, move right
Goto [ctrl-G] New focus at cursor position
Mouse mouse-click New focus at position of mouse-click
Undo [BACKSPACE] Undo effect of last key pressed (may be repeated)
Redo [ctrl-U] Redo last UNDOne key (may be repeated)
Copy f9, [ctrl-C], [ESC]c Copy buffer to hole, or focus to buffer
Delete [ctrl-D] Delete contents of focus (to buffer if empty)
Record [ctrl-R] Start/stop recording keystrokes
Play [ctrl-P] Play back recorded keystrokes
Look [ctrl-L] Redisplay screen
Help f10, [ESC]? Print summary of editing operations
Exit [ctrl-X] Finish changes or execute command
Interrupt (as set by 'stty') Interrupt command execution
Suspend (as set by 'stty') Suspend ABC (only for shell with job control)

Notes:

[Ctrl-D] means: hold the [CTRL] (or [CONTROL]) key down while pressing D.
[ESC] w means: press the [ESC] key first, then w.