grotwin (Part 7 of 7)

[nwh at hrc63.UUCP]

#!	/bin/sh
#	This is a shell archive. To extract the files type 'sh file'
#	This archive created on Thu Jul 10 13:35:39 WET 1986

echo 'shar: extracting 'grotwin.nroffman' ( 9945 characters)'
if test -f 'grotwin.nroffman'
then
	echo "shar: will not overwrite existing file 'grotwin.nroffman'"
else
	cat << \SHAR_EOF > 'grotwin.nroffman'
.nh
.TH GROTWIN 1
.SH NAME
grotwin \- windows on ordinary terminals
.SH SYNOPSIS
grotwin [-n][-t][-b][-h] [file]
.SH GETTING STARTED
Grotwin may be initiated on any tty device
(even a tty within itself).
If there is a file called .grotwin in your home directory,
or a file name is supplied, grotwin will create windows as
specified by the file with their optional associated
application programs.
Otherwise grotwin will start up with two default windows
of full size.
.PP
The grotwin system is ready as soon as the screen clears
at startup.  The last window to fire up is the one into which
initial input will be received.
Even before it appears, a user may type data and
window commands, the data will be queued (for that window),
whilst the window commands will act as soon as they can.

.SH OPTIONS
-n     Don't look for startup file in users home directory.
       Use default of two full page windows instead if no
       startup file is specified.

-t     Turn time off at startup (default is on).

-b     Make window borders standout if capability exists
       (generally tacky, not advised).

-h     Display manual page
       (since it might not be installed in man directories).

file   optional startup file describing the size and
       position of required startup windows.
.SH DESCRIPTION

Grotwin provides a windowing capability for users of normal
terminals.
It is especially useful for actions such as editing more than
one file at a time, editing and correcting errors, or for
occasions when more than one screen at a time is desirable.
Generally, the screen size of the terminal will not
allow more than two fairly decent sized windows to be totally visible
at any one time; it is often more useful to have full size
overlapping windows when more than two windows are required.


Windows

The grotwin environment always has one fixed window
which covers the whole screen;
its sole purpose is to provide a fixed background
pattern to enable
unused portions of the screen to be visible.
It also has a clock that displays the time in hours and minutes
at the centre of its top edge.
There must always be at least one other window in existence,
otherwise grotwin will assume (rightly or wrongly),
that the user has finished and will terminate.
A window consists of a border with an
identifying sequence on its top edge,
and an associated tty device within it.
Windows act as normal ttys (of varying sizes); they may
be generated and manipulated at will.
Windows are assigned unique visability properties that enable
them to overlap in much the same way as stacking sheets of paper.
A window will obscure portions of other windows which
overlap and have lower priorities than itself.
Priorities are assigned starting with the topmost window
as the highest, and the backmost as the lowest.
The current window (see Input to Windows), may under
user control be made the backmost window by hiding
it (see Window Commands);
this has the effect of making it the lowest priority
window in visibility terms, whilst maintaining it
as the current window for input.
The maximum number of windows that may be present at any one
time is limited by then maximum number of files that the
operating system system will allow a user to open concurrently.


Input to Windows

Only one window at a time may receive input from the keyboard;
this is termed the current window.  It is denoted by
a single '+' character at each top corner of that window.
This window is the one into which all typed
input (except window commands), will be received.
Input characters (as for a normal tty), may be queued for
each window.
This means that a user may type some characters in one window,
move to another window and type some more characters into that window.
The characters typed in the first window will be read
when the application in that window is ready to do so.
To switch input between windows,
either the number of the window can be supplied 0 - 9 (as identified
on the top edge of the window), or by the 'w' command.
The 'w' command takes the numerically next window (including
wrapround) and makes it the current window.


Output to Windows

Output to the windows is capable of occurring at any time (except
when looking at the manual entry or status of windows when it is
temporarily blocked).
Whether such output is displayed on the screen
depends on a windows visibility for all
of its possible character positions.


Window Commands

Window commands may be freely interspersed with normal user input.
They act immediatley unlike queued input to a tty.


WIndow Command Terminology

ctrl-a 'n'      means ctrl-a followed by ctrl-n or 'n'.

ctrl-a 'N'      means ctrl-a followed by 'N'

ctrl-a 'nN'     means ctrl-a followed by ctrl-n, 'n' or 'N'.

All commands are preceeded by ctrl-a,
just as you may have used reached this information summary.

The valid window commands are as follows :-

Command               Action

 'nN'           create new window
 'w'            make numerically next window current
 '0' - '9'      make selected window current
                (range 1 to 9)
 'xX'           expand window to full size
 'vV'           expand window vertically to full size
 'cC'           expand window horizontally to full size
 'zZ'           clear window
 'eE'           expose window
 'hH'           hide window
 'p'            page mode on - type any character
                for next page
 'P'            page mode off
 'o'            overwrite mode on - type any character
                for next page
 'O'            overwrite mode off
 'tT'           toggle between displaying and removing time
 'sS'           XOFF for current window
 'qQ'           XON for current window
 'R'            force process within window to terminate
                - achieved by sending following signals
                in implied order until one is successful
                or all have been used
                SIGHUP, SIGINT, SIGTERM or SIGKILL
 'F'            forced exit from program (no
                questions asked)
                - same as the 'R' option, but for
                all windows
 'iI'           display status of windows
 '?'            this message

otherchar       Character is input as if not preceeded
                by ctrl-a.  Therefore to enter ctrl-a,
                type 'ctrl-a ctrl-a'


Startup File

If no startup file is specified, grotwin will search for the file
$HOME/.grotwin to define the window sizes (this is expected
to be the normal case).
If this file is not found or is unreadable, the default is two
windows of full screen size.

The format of the startup file is as follows :-

    width height x_start y_start [command]


It should be remembered that a window has a border around it;
this is included in the window size specified.

    eg.  80 24 0 0       will define a window with a tty
                         which has 22 lines and 78 columns

Each window entry is checked to see if it is displayable
and within output device screensize.
If not, the start positions are adjusted accordingly.
Finally, if required, the width and height dimensions are adjusted.
Entry values of -1 and -2 have special meaning; for the
width or height -1 means the full screen width or height respectivley,
with -2 meaning half full screen width or height.
For the start position -1 means the full width or height minus the
the specified width or height, with -2 meaning
half the full screen width or height.

    eg.
        -2 -2  0  0      four non-overlapping windows
        -2 -2 -1  0      covering the whole screen
        -2 -2  0 -1
        -2 -2 -1 -1

Such values are particularly useful when grotwin is used on
different sized terminals.

    eg.  
        -1 -1  0  0      full width and height window


Any adjustments made to actually fit a window on the screen
are performed silently.

Command is optional and may be any unix command.
Since the shell is not used to parse the command, spaces are important;
a single space or tab character should be used to separate strings
(and of course things like pipes etc. as provided by the shell are
not available).

    eg. 'ftp   vax' would not work, whilst 'ftp vax' would.

If no command is given (the normal case),
grotwin will search the environment for the SHELL variable;
if found it will run that shell, otherwise it will default to
the Bourne shell (/bin/sh), simply because it is a standard
shell that all systems have.
.SH FILES
 $HOME/.grotwin
 /dev/ptyp[p-r]x
 /dev/ttyp[p-r]x
 /etc/utmp
.SH BUGS
This release has the following bugs (or features if you like):

Doesn't pause when a clear screen command comes along if
more output is ready.
This is to speed things up by accepting any following output and
displaying that along with the clear screen command.
Particularly noticable in vi where ctrl-l appears to have no
action (unless the window is large, you cannot see vi redraw).

Output granularity chosen is subject to question.

The use of a non-standard terminal type (grotty)
does mean that the grotwin display can get well muddled up
if escape sequences for other terminals are sent to it.
Grotwin really needs a vt100 terminal emulator and associated
TERMCAP entry.

Grotwin terminates when there are no user windows present.
It assumes that in such a situation it is probably better
to start grotwin again with selected default windows than
to ask it for new windows.

Various functions like page mode, XOFF etc. provide no indication
that they are selected (although this can be found out via
the window status option).

The ability to move or stretch windows by single characters.
This was tried but removed since this facility is best provided
by a mouse (rather than a keyboard), an object that
a normal terminal lacks.
.SH AUTHOR

 Nigel Holder
 Marconi Research,
 Chelmsford,
 Essex. CM2 8HN.

 UK JANET:       yf21 at uk.co.gec-mrc.u
 ARPA:           yf21%u.gec-mrc.co.uk at ucl-cs


 +44 245 73331   ext. 3219 / 3214

SHAR_EOF
if test 9945 -ne `wc -c < 'grotwin.nroffman'`
then
	echo 'shar: error transmitting 'grotwin.nroffman' (should have been  9945 charcaters)'
fi
fi

exit

Nigel Holder			UK JANET:       yf21 at uk.co.gec-mrc.u
Marconi Research,		ARPA:           yf21%u.gec-mrc.co.uk at ucl-cs
Chelmsford,
Essex. CM2 8HN.

+44 245 73331   ext. 3219 / 3214