WFORM(1)

NAME
wform - interactively edit a list

SYNOPSIS
wform [ -t title | -tf file [ -tc ] ] [ -h file [ -hc ] ] [ -ht text | -hf file ] [ -nl ] [ file ]

DESCRIPTION

Wform reads a series of lines from its input, or from the named file if given and allows the user to interactively select which lines will appear on its output. It is intended to be used in a pipe line filter to allow user control of the contents of the pipe line.

The screen is divided into three areas, the top area contains a title - this should be used to hold messages to tell the user what is going on. The next section contains the list of entries from the input. By default entries are numbered. Selected entries are highlighted using the standout mode of the terminal. The final area of the screen contains optional help text corresponding to the current entry (the one at which the cursor points). Help text is selected by searching for the text of the entry at the start of a line in the help file. If the text, followed by a space, is found the remainder of the line is output in the help region.

The keyboard ? key may also be used to display a help screen describing how to drive the program. The actions which the user can take are all done by pressing a single key:-

digit
    The digit keys, 0-9, cause selection of the relevant numbered entry. The nearest entry whose number mod 10 is equal to the value of the digit is selected, unless the cursor is already over this entry and it is selected - in which case the entry numbered 10 greater is selected. The cursor is positioned at the selected entry.

Home
    The cursor is moved to entry 0 (the first). The Home key on the keyboard does this (except under xterm(1) where the key does not generate a unique character sequence).

Up  The cursor is moved up one line - the upwards and leftwards arrow cursor keys and `h' and `k' do this.

Down
    The cursor is moved down one line - the downwards and rightwards arrows and the `j' and `l' keys.

Bottom
    The cursor is move to the last line - the `$' key does this.

Page Up
    The previous page of entries are displayed (ie the ones with the next lower numbers). The Page Up key, except under xterm.

Page Down
    The next page of entries are displayed (ie the ones with the next higher numbers). The Page Down key, except under xterm.

Continue
    Any unrecognised key causes a bell tone.

Select
    The `+' key causes the current entry to be selected. It will be highlighted.

DeSelect
    The `-' key causes the current entry to be unselected - it will no longer be highlighted.

Help
    The `?' key causes the help screen to be displayed, giving details of the key bindings. It remains displayed until a Down action. The only other key which has an effect is the Refresh action - which causes the screen to be redisplayed.

Exit
    Exit the program, outputing the currently selected entries on the programs output stream. Keys `e' and `E'.

Quit
    Quit the program - exiting with a non-zero error code. Keys `q' and `Q'.

Refresh
    The screen is redisplayed.

All input text may have embedded highlighting information - highlighting is switched on by \S and off by \E.

OPTIONS

-t title
    Gives the text to appear in the title area.

-tf file
    The title text is read from the given file.

-tc The title text is centred on the screen.

-h file
    The help text is read from the given file.

-hc The help text is centred in its window.

-ht text
    The given text overrides the default help screen text.

-hf file
    The text for the help screen is taken from the given file.

-nl Do not output line numbers - this option makes the use of the digit keys very difficult.

FILES
/dev/tty    Used for interactive IO

RETURN CODES

0   Normal exit code

1   The command line arguments were invalid.

4   Output failed - a write or a flush of the output stream returned an error code.

7   Initialisation failed - the curses package failed to initialise correctly. This may be caused by an invalid TERM environment variable or a terminal which does not support cursor addressing.

8   The user quit the program rather than exiting normally (either by using `q' or by SIGINT - control-C).

9   An internal error occured. This can be caused by a very long input files.

FEATURES

Wform does not deal with screen size changes.