4.2 Window Management System (wms part 1 of 4)

[Marc Lesure]

wms part 1 of 4

If your site decides on implementing wms, please send mail to the
author so he can send updates (if any) in the future.  Also, please
send all bug reports, problems, fixes, etc. to the author rather
than posting them to net.sources.bugs.

Marc Lesure
System Manager
Engineering Computer Center
Arizona State University
Tempe, Arizona

UUCP:	...!{ucbvax,ihnp4}!arizona!asuvax!lesure
     	...!ihnp4!terak!asuvax!lesure
CSNET:  lesure at asu
ARPA:   lesure%asu at csnet-relay

--------------------------------<cut here>----------------------------
# This is a shell archive.  Remove all lines before this one.
# Use 'sh <this file>' to unpack the contents.
#
# contents:
#       release
#       release/README
#       release/blurb
#       release/makefile
#       release/man7
#       release/mant
#       release/mant/DS
#       release/mant/msh.t
#       release/mant/wms.t
#       release/mant/wty.t
#
echo x - release
mkdir release
echo x - release/README
sed 's/^@@//' > "release/README" << '@@ END-OF-FILE'
/****************************************************************************\
 * Copyright 1985 by George Nelan, Arizona State University.                *
 * All rights reserved.  Permission to use, modify, and copy these programs *
 * and documentation is granted, provided that the copy is not sold and     *
 * that this copyright and permission notice appear on all copies.          *
\****************************************************************************/

The window management system tape release consists of these files:

README			- this file.    
blurb			- ...
makefile  		- construct and install the system.
man7       		- directory for installed manuals.
man7/msh.7		- installed manual for msh.
man7/wms.7		- installed manual for wms.
man7/wty.7		- installed manual for wty.
mant			- directory for uninstalled manuals.
mant/DS			- nroff string definitions.
mant/msh.t		- uninstalled manual for msh.
mant/wms.t		- uninstalled manual for wms.
mant/wty.t		- uninstalled manual for wty.
public			- public directory.
public/msh      	- executable msh.
public/termcap  	- sample terminal descriptions.
public/wms		- public wms directory.
public/wms/max.msh.c   	- msh configuration parameters source variables.
public/wms/max.msh.h    - msh configuration parameters absolute maximum values.
public/wms/max.msh.o   	- msh configuration parameters object code.
public/wms/max.wty.c   	- wty configuration parameters source variables.
public/wms/max.wty.h    - wty configuration parameters absolute maximum values.
public/wms/max.wty.o   	- wty configuration parameters object code.
public/wms/msh.bind.o	- msh main program binder object code.
public/wms/msh.h    	- msh control codes.
public/wms/msh.o   	- msh object code.
public/wms/wty.bind.o  	- wty main program binder object code.
public/wms/wty.o	- wty object code.
public/wty      	- executable wty.
source			- primary source code directory.
source/NOTES		- source code notes.
source/msh		- msh source directory.
source/msh/max.msh.h	- @ -> ../../public/wms/max.msh.h.
source/msh/msh.bind.c 	- msh main program binder source.
source/msh/msh.c	- msh source.
source/msh/msh.h	- @ -> ../../public/wms/msh.h.
source/msh/util.h	- @ -> ../util.h.
source/msh/relink	- script to aid source code symbolic linking
source/util.h		- simple utilities.
source/wty		- wty source directory.
source/wty/max.msh.h	- @ -> ../../public/wms/max.msh.h.
source/wty/max.wty.h	- @ -> ../../public/wms/max.wty.h.
source/wty/msh.h	- @ -> ../../public/wms/msh.h.
source/wty/util.h	- @ -> ../util.h.
source/wty/wty.bind.c	- wty main program binder source.
source/wty/wty.c	- wty source.
source/wty/wty.h	- wty virtual terminal prototype codes.

NOTES:

The installation procedure is as follows:
Since the default target directorys have been defined as subdirectorys of the
current directory (this release directory), when you type 'make' nothing 
will be made.  Everything is already installed.  If you wish to install the 
files elsewhere, then you need to edit the 'makefile' and change the target 
directory macros as described in that file.  After installing the manuals, 
it is a good idea to do a "man" on them.  The wty manual is a good start.

The shar version does not include object files or executables.  Thus, typing
'make' will indeed make some files. Lastly, suitable access permissions may 
have to be set - try:

	chmod a+r		<all files>
	chmod go-w		<all files>
	chmod a+x		<all executables, directorys>

Please relay bugs, fixes, improvements, etc. back to ASU for future updates.  

	George Nelan
	Engineering Research Center (ERC 207)
	Arizona State University
	Tempe, Arizona, 85287
	(602)-965-2791

	UUCP:	
	...{ucbvax,ihnp4}!arizona!asuvax!nelan
	...ihnp4!noao!terak!asuvax!nelan

	CSNET:	
	nelan at asu
@@ END-OF-FILE
echo x - release/blurb
sed 's/^@@//' > "release/blurb" << '@@ END-OF-FILE'
-----------------------------------------------------------------------------
			WINDOW MANAGEMENT SYSTEM

A window management system for 4.2bsd systems is being released by George 
Nelan at Arizona State University.  The system, WMS, is in the public domain 
and consists of :
- MSH, an executable meta-shell manager which resides on the host, manages
sub-shells (csh or user) via ptys, and coordinates communications with an 
external window manager by multiplexing standard I/O;
- WTY, a host-resident executable window manager built upon MSH, utilizing the 
TERMCAP database so that most programs can run in windows (vi,..);
- TOOLS, a set of code fragments to assist the do-it-yourself types in
developing their own [remote] window managers (PC,..) for linkage to MSH;
- DOCUMENTATION, a complete set of user manuals in the form of three 'man' 
entries; and last, but not least,
- SOURCE CODE.

A brief description of WTY follows:
WTY emulates a virtual windowing terminal on a variety of devices (vt100,..).
The underlying actual device must support controllable scrolling regions and
cursor motion as described by a [user-defined] TERMCAP entry. Windows are 
defined as multiplexed scrolling regions; all windows span the width of the 
display.  Each window is truly scrollable (without redraws) with all visible 
windows the same size.  WTY multiplexes sub-shell output into windows in a 
way that allows apparent concurrency.  A 'select current input window' command 
may be used to direct user input to any visible window.  Other commands allow 
window creation/deletion, opening/folding (making visible/invisible), 
labeling (windows are not bordered since context usually provides sufficient 
implicit discrimination clues - labels explicitly delimit borders), and 
buffer manipulation: create/delete (I/O recording), open/fold (enable/disable 
recording), and read selection (take a buffer as user input).  Window size 
information is communicated to sub-shells by a wty-generated "setenv TERM <X>" 
message, where <X> identifies a virtual terminal related to the window size.  
A resize command allows retransmission of this message at any time.  A 'nice' 
option on all commands which affect window size allows quiet dynamic
manipulation of windows (no automatic "setenv" messages are generated).  A
help command  provides a summary and the command character prefix may be user-
defined.

The system has been operational since June 1985 and seems to be fairly robust 
and relatively efficient.  We will provide a copy of the system in 1600 BPI 
TAR format if you send us:

- A mag tape (the system release is ~ 256KB).
- Return postage or a check payable for same made out to:
	"A.S.U. Engineering Computer Center"
  Or indicate shipping collect.
  Shipping will be via UPS unless you specify otherwise.

Upon special request, a shar version is available via UUCP.  As this file is
123KB long (~20 min @ 1200B), we prefer tape transfers.

Contact:

	George Nelan
	Engineering Research Center (ERC 207)
	Arizona State University
	Tempe, Arizona, 85287
	(602)-965-2791

	UUCP:	
	...{ucbvax,ihnp4}!arizona!asuvax!nelan
	...ihnp4!noao!terak!asuvax!nelan

	CSNET:	
	nelan at asu
@@ END-OF-FILE
echo x - release/makefile
sed 's/^@@//' > "release/makefile" << '@@ END-OF-FILE'
##############################################################################
#
# The default target directorys are subdirectorys of the current directory.
# You may wish to redefine the make macros something like:
#
# where the 'man' entries go:
# L = /usr/man/man7
#
# the 'man' # (as in L above):
# M = 7
#
# where msh, termcap, wms, and wty go:
# P = /usr/public
# 
# defaults:
L			= ./man7
M			= 7
P			= ./public
#
##############################################################################
#
#
# locals only (do not change):
p			= ./public
s			= ./source
v			= 1.7a # version
#
#
all::		
			@csh -c 'if (-e $@) rm $@'
#
all::			$P/wms $L/msh.$M $L/wms.$M $L/wty.$M $P/msh $P/wty
			@csh -c 'if (-e $@) rm $@'
			@echo done
#
$P/wms:
			csh -c 'if (!(-e $@)) mkdir $@'
#
$L/msh.$M:		mant/msh.t mant/DS
			cat mant/DS mant/msh.t > $@
#
$L/wms.$M:		mant/wms.t mant/DS
			cat mant/DS mant/wms.t > $@
#
$L/wty.$M:		mant/wty.t mant/DS
			cat mant/DS mant/wty.t > $@
#
mant/DS:		makefile
			echo '.ds V' $v > $@
			echo '.ds P' $P >> $@
			echo '.ds M' $M >> $@
#
$P/msh:			$P/wms/msh.bind.o $P/wms/msh.o $P/wms/max.msh.o
			cc -O $P/wms/msh.bind.o $P/wms/msh.o $P/wms/max.msh.o \
			    -o $@
			strip $@
#
$P/wms/msh.bind.o:	$s/msh/msh.bind.c 
			cc -O -c $s/msh/msh.bind.c
			mv msh.bind.o $@
#
$P/wms/msh.o:		$s/msh/msh.c $s/util.h $P/wms/msh.h $P/wms/max.msh.h
			cc -O -c $s/msh/msh.c
			mv msh.o $@
#
$P/wms/max.msh.o:	$P/wms/max.msh.c
			cc -O -c $P/wms/max.msh.c
			mv max.msh.o $@
#
$P/wms/max.msh.c:	$p/wms/max.msh.c
			cp $p/wms/max.msh.c $@
#
$P/wms/max.msh.h:	$p/wms/max.msh.h
			cp $p/wms/max.msh.h $@
#
$P/wms/msh.h:		$p/wms/msh.h
			cp $p/wms/msh.h $@
#
$P/wty:			$P/wms/wty.bind.o $P/wms/wty.o $P/wms/max.wty.o \
			    $P/wms/msh.o
			cc -O $P/wms/wty.bind.o $P/wms/wty.o $P/wms/max.wty.o \
			    $P/wms/msh.o -ltermcap -o $@
			strip $@
#
$P/wms/wty.bind.o:	$s/wty/wty.bind.c $P/wms/max.wty.h
			cc -O -c $s/wty/wty.bind.c
			mv wty.bind.o $@
#
$P/wms/wty.o:		$s/wty/wty.c $s/util.h $s/wty/wty.h $P/wms/msh.h \
			    $P/wms/max.wty.h
			cc -O -c $s/wty/wty.c
			mv wty.o $@
#
#
$P/wms/max.wty.o:	$P/wms/max.wty.c $P/wms/max.msh.c
			cc -O -c $P/wms/max.wty.c
			mv max.wty.o $@
#
$P/wms/max.wty.c:	$p/wms/max.wty.c
			cp $p/wms/max.wty.c $@
#
$P/wms/max.wty.h:	$p/wms/max.wty.h
			cp $p/wms/max.wty.h $@
@@ END-OF-FILE
echo x - release/man7
mkdir release/man7
echo x - release/mant
mkdir release/mant
echo x - release/mant/DS
sed 's/^@@//' > "release/mant/DS" << '@@ END-OF-FILE'
.ds V 1.7a
.ds P ./public
.ds M 7
@@ END-OF-FILE
echo x - release/mant/msh.t
sed 's/^@@//' > "release/mant/msh.t" << '@@ END-OF-FILE'
.TH msh \*M "1 July 1985"
.SH NAME
msh \- meta-shell manager (version \*V)
.SH SYNOPSIS
.B "\*P/msh"
.SH DESCRIPTION
.ad b
.PP
.I Msh 
is a stand-alone meta-shell manager intended for use with a remote 
window manager (such as a PC-resident program).
It coordinates activities between independent host sub-shells 
and a remote windowing terminal.
.PP
.I Msh
communicates with an external window manager over standard input and output.
Input to
.I msh
(output from the window manager) includes normal user-input text along
with commands generated by the window manager (in response to user actions).
These commands may cause
.I msh
to create a new shell (for a window), 
delete a shell, select another shell for input,
or terminate execution.
All user-input text is directed towards the shell currently selected for input.
.PP
Output from
.I msh
(input to the window manager) consists of multiplexed outputs from sub-shells.
The only command in this direction is a "change output window"
sequence which preceeds and identifies each sub-shell's output buffer packet.
.SH INTERFACE PROTOCOL
The
.I msh
interface protocol is defined by the (extended BNF) syntax:
.nf
<msh_input>     -> { <input_cmd> | TEXT }
<input_cmd>     -> <csi> <quit> 
                |  <csi> <set_input> 
                |  <csi> <create_csh> 
                |  <csi> <create_usr> 
                |  <csi> <resize> 
                |  <csi> <delete>
                |  <csi> <stop>          
<csi>           -> "\\0@"
<quit>          -> "A"
<set_input>     -> "B" <n>
<create_csh>    -> "C" <n> <tc>
<create_usr>    -> "D" <n> <tc> <sh>
<resize>        -> "E" <tc>
<delete>        -> "F" <n>
<stop>          -> "G" <f>
<n>             -> "1" | "2" | ... | "9"
<tc>            -> { ANY } ";" 
<sh>            -> { ANY } "\\n"
<f>             -> "0" | "1"
.fi
.nf
<msh_output>    -> { <output_cmd> | TEXT }
<output_cmd>    -> "\\027" <n>
.fi
.PP
Where TEXT is a non-ambiguous sequence of arbitrary characters,
ANY is any non-ambiguous character, and "" delimits literal strings 
("\\0" => null, "\\n" => newline, "\\027" => <CTRL-W>).
The (input) command sequence introducer is <csi>.
Shell (window) labels are given by <n>, and
terminal identification code strings are given by <tc>.
.PP
The <quit> command terminates execution of 
.I "msh."
.PP
The <set_input> command changes the current input shell to that labeled
by <n>.
All succeeding input is directed towards that shell, until another <set_input>
command.
.PP
The <create_csh> command creates a new c-shell (labeled by <n>) and sends
a <resize> string of the form 
.nf
        setenv TERM <tc>
.fi
to the shell.
.PP
The <create_usr> command creates a new user-defined shell given by <sh>.
.PP
The <resize> command sends a string of the form 
.nf
       setenv TERM <tc>
.fi
to  the current input shell.
This command is useful for cases where a shell could not previously receive
a <tc> string due to being in an improper state (e.g. in an editor).
.PP
The <delete> command deletes the current input shell and causes the shell
labeled by <n> to become the new current input shell.
.PP
The <stop> command suspends execution and returns control to the parent shell of
.I "msh."
The <f> flag defines the tty state after suspension.
With <f> = "0", the tty is reset to the state of the parent of
.I "msh;"
with <f> = "1", the state is left as is.
This flag is useful as a debugging aid.
.PP
The single <output_cmd> is the packet header for each shell's output buffer.
This command is indivisible (always two characters), but no such assumption can
be made concerning indivisibility of buffer packets (the TEXT).
This has ramifications for window managers which interpret virtual
terminal command sequences.
Shell output buffers are multiplexed on a prioritized polling basis so that 
echo response time is minimized while maintaining a high degree of output
concurrency.
.SH TTY INTERFACE
.PP
When 
.I msh 
begins, with one exception, the initial tty state is passed on to all 
sub-shells which are created.
The exception is that "stty -tabs" is explicitly set for the sub-shells;
this is because
.I msh
assumes that the remote window manager ignores incoming tabs from sub-shells.
After the initial state is picked up,
.I msh
resets several tty modes ala "stty new cbreak -echo -tabs nl".
All special characters are un-defined (i.e. stty <c> u) except for
the flow control characters (^S ^Q usually).
This is more-or-less equivalent to "stty raw" but allows automatic
flow-control and delay-processing (heh-heh).
.SH NOTES
.PP
.I Msh
assumes that all input commands are syntactically and semantically
correct \- it is the responsibililty of the remote window manager to assure
this is so.
Also, explicit initialization commands are required.
For each initial shell,
.I msh
expects to receive a <create_csh> (or <create_usr>) command for each shell.
.SH FILES
.B "\*P/wms/*"
.SH SEE ALSO
.B "wty(\*M)"
.br
.B "wms(\*M)"
.SH BUGS
.PP
It is possible that sub\-processes may still exist after
.I msh
is terminated.
Usually this occurs if backround jobs are left running in a sub\-shell
after quiting
.I "msh."
One should then do a ps command to check on stray processes.
.PP
The <break> key does not work.
It is best to rely upon your <kill> character if you regularly use <break> 
as a <kill> alias.
.PP
The <start> and <stop> characters affect flow-control globally \- there is
no way to get local (per shell) flow control.
.PP
If
.I msh
is executed for too long at a time, the operating system will renice it.
As this will slow things down quite a bit, it is advisable to quit
.I msh
then restart it again.
.SH AUTHOR
George Nelan
@@ END-OF-FILE
echo x - release/mant/wms.t
sed 's/^@@//' > "release/mant/wms.t" << '@@ END-OF-FILE'
.TH wms \*M "1 July 1985"
.SH NAME
wms \- guide to the window management system (version \*V)
.SH SYNOPSIS
.B "\*P/wms/*"
.SH DESCRIPTION
.ad b
.PP
.I Wms
consists of two executable programs,
.I msh
and
.I "wty;"
plus several code fragments which, when tied together in the correct manner,
can provide the basis for "do-it-yourself" window managers.
.PP
.I Msh
is a meta-shell manager that coordinates communication activities between
sub-shells on the host and a window manager by means of a bi-directional
communication-stream.
The window manager may either reside on the host itself, acting as a virtual
windowing terminal emulator, or it may reside on a remote machine (such as a
PC).
The code supplied with the system enables either configuration in a relatively 
simple and efficient way.
.PP
.I Wty
is a host-resident window manager which has been integrated with
.I msh
in a virtual windowing terminal configuration.
.I Wty
utilizes the
.B TERMCAP
database so that many different kinds of terminals can potentially support
the windowing emulation.
Both
.I msh
and
.I wty
are documented as separate
.I man
entrys.
.SH CODE FRAGMENTS
.PP
The following files are provided in \*P/wms/ as system code fragments:
.nf
    max.msh.c
    max.msh.h
    max.msh.o
    max.wty.c
    max.wty.h
    max.wty.o
    msh.bind.o
    msh.h
    msh.o
    wty.bind.o
    wty.o
.fi
.PP
The files "max.xxx.x" provide a mechanism for tuning variable parameters for
.I msh
and
.I "wty."
The ".h" files supply the absolute maximum values for the parameters,
the ".c" files supply the corresponding variable definitions, and 
the ".o" files are the compiler outputs for the ".c" files.
.PP
The "msh.h" file provides the 'defines' required for command input/output
by
.I "msh."
The file "msh.bind.o" is the object code binder for 
.I "msh."
.I Msh
is the result of linking "msh.o", "max.msh.o" and "msh.bind.o".
.PP
The file "wty.bind.o" is the object code binder for
.I "wty."
.I Wty
is the result of linking "msh.o", "wty.o", "max.wty.o" and "wty.bind.o".
.PP
The following sections describe how to utilize the code fragments for the
purposes of tuning or for the construction of customized window managers.
.SH TUNING MSH
.PP
The following parameters, found in "max.msh.c", can be adjusted as desired:
.nf
    MAXSLAVES
    MAXNOPOLLS	
    MAXSHELL
    MAXTCODE
    MAXCBUF
.fi
.PP
MAXSLAVES indicates the maximum number of sub-shells allowed to co-exist.
.PP
MAXNOPOLLS determines the maximum number of sub-shell output polls bypassed.
Larger values will cause sub-shells which have been recently quiescent to
have their first output burst delayed longer.
After this initial delay, however, succeeding outputs will not be delayed.
This effect serves to minimize excessive polls on sub-shells, thus providing
a measure of echo response time optimization.
This parameter does not apply to the current input shell when an echo is
pending.
.PP
MAXSHELL defines an upper limit on the size of shell name strings which may
be passed to
.I msh
via a <create_usr> command (q.v.).
.PP
MAXTCODE limits the size of terminal code strings which may be passed to
.I msh
via a <create_csh>, <create_usr>, or <resize> command (q.v.). 
.PP
MAXCBUF is the maximum size of I/O character buffers in
.I "msh."
.PP
Note: the default values for all parameters have been carefully chosen 
to provide near optimal performance.
Also, recall that "max.msh.h" indicates the absolute maximum values for
these parameters.
.PP
The procedure for retuning
.I msh
then consists of the following steps:
.nf
    edit:       max.msh.c
    compile:    cc -c max.msh.c
    link:       cc msh.o max.msh.o msh.bind.o -o msh
.fi
.SH TUNING WTY
.PP
The following parameters, found in "max.wty.c", can be adjusted as desired:
.nf
    MAXWINDOWS
    MAXLABEL
    MAXQBUF
.fi
.PP
MAXWINDOWS must be equal to MAXSLAVES in "max.msh.c".
Thus, to increase the number of windows in
.I "wty,"
MAXSLAVES and MAXWINDOWS must both be modified.
.PP
MAXLABEL must be the character equivalent of MAXWINDOWS.
.PP
MAXQBUF defines the size of I/O queues in
.I "wty."
Because of implementation considerations, this value should be set
to about MAXCBUF << 2.
Failure to adhere to this restriction may cause a run-time queue
overflow in
.I "wty"
resulting in execution termination.
.PP
Note: the default values for all parameters have been carefully chosen 
to provide near optimal performance.
Also, recall that "max.wty.h" indicates the absolute maximum values for
these parameters.
.PP
The procedure for retuning
.I wty
then consists of the following steps:
.nf
    edit:       max.wty.c
    edit:       max.msh.c             (if necessary)
    compile:    cc -c max.wty.c
    link:       cc msh.o wty.o max.wty.o wty.bind.o \\
                   -ltermcap -o wty
.fi
.SH CONSTRUCTING A CUSTOM DISCREET WINDOW MANAGER
.PP
A remote window manager residing on (say) a PC may be interfaced quite
simply with the host system.
.I "Msh"
provides all of the necessary work to coordinate and multiplex shell
activity.
Since
.I msh
communicates over standard input/output with the window manager,
all that is necessary on the remote end is to initiate contact with
The host, run
.I msh
on the host; then run the remote window manager.
.PP
This method of total window management is probably the most efficent and
powerful way to implement the system.
Advantages include significantly reduced host loading, not to mention the
generally higher quality graphics capabilities of many PCs relative to
standard terminals as described by TERMCAP.
See the manual entry for
.I msh
for more information.
.SH CONSTRUCTING A CUSTOM INTEGRATED WINDOW MANAGER
.PP
The procedure for implementing an integrated window manager with
.I msh
is somewhat more involved than the implementation of a discreet remote
window manager.
.I Wty
is the result of such an implementation.
.PP
The primary consideration in the window manager /
.I msh
interface is how to convert the standard input/output calls of
.I msh
into a procedural interface with the window manager.
This may be accomplished by substituting demand-driven procedure evaluation
for IO calls.
.PP
The basic IO call flow of
.I msh
may be described as:
.nf
    put(current_input_shell,get(stdin))
    for_each_shell,put(stdout,get(shell))
.fi
where necessary input command processing and output packet fragmentation
is implicit.
.PP
The basic IO call flow of a window manager can be described as:
.nf
    put(stdout,get(keyboard))
    put(screen,get(stdin))
.fi
where necessary input packet fragmentation and output command processing
is implicit.
.PP
Thus the put(stdout) of
.I msh
is linked to the get(stdin) of the window manager, and the
get(stdin) of
.I msh
is linked to the put(stdout) of the window manager.
In other words, a bi-directional pipeline exists between
.I msh
and the window manager.
.PP
This relationship can be exploited so that the IO link between
.I msh
and the window manager is eliminated; being replaced by
direct procedural evaluation.
.PP
Thus we have the following externally visible procedures in
.I "msh:"
.nf
    init_msh();
    abort();
    slave_driver();
.fi
.PP
.I Msh 
also requires that these procedures be linked with it:
.nf
    get_master(string);
    put_master(string,length);
.fi
where string is (char *), and length is (int).
Note: these are the procedures (along with main) which "msh.bind.o" 
supplys for "msh.o".
.PP
Thus, the window manager must provide a main program which essentially does the
following:
.nf
    ...
    init_msh();
    ...
    for (;;)
        screen_driver();
    ...
.fi
where screen_driver is part of the window manager and calls the
slave_driver procedure of
.I "msh."
The slave_driver procedure, in turn, calls get_master which must be supplied
by the window manager.
This call can be directed to get input from the user and process any
local commands.
.PP
When
.I msh
is ready to send an output packet, it calls put_master.
This call may be used to satisfy the original demand from screen_driver.
Thus one entire demand driven evaluation cycle can be completed upon a
return to screen_driver.
.PP
Note: each call to "slave_driver" of
.I msh
results in a poll of the next slave in the polling sequence.
.PP
The entire demand evaluation cycle can be visualized as:
.nf

main:
    ...
    init_msh
    ...
    for (;;)
        screen_driver
            get msh
                slave_driver
                    master_driver
                        get_master
                            get stdin (keyboard)
                        put shell
                    get shell
		    put_master
            put stdout (screen)
    |____
.fi
.PP
The procedure for compiling and linking the integrated window manager
is similiar to that for retuning 
.I "wty."
.SH FILES
.B "\*P/wms/*"
.br
.SH SEE ALSO
.B "wty(\*M)"
.br
.B "msh(\*M)"
.SH AUTHOR
George Nelan
@@ END-OF-FILE
echo x - release/mant/wty.t
sed 's/^@@//' > "release/mant/wty.t" << '@@ END-OF-FILE'
.TH wty \*M "1 July 1985"
.SH NAME
wty \- window manager (version \*V)
.SH SYNOPSIS
.B "\*P/wty"
[ n ]
.SH DESCRIPTION
.ad b
.PP
.I Wty
provides window management capabilities allowing
interaction with multiple concurrent shells
in a simple and efficient way.
The
.B TERMCAP
database is utilized so that a windowing terminal may be emulated on
a number of different terminals.
.PP
When started, the program creates
.I n 
windows and shells (the default is 2).
Up to four windows (in this version) may be specified.
.I Wty 
divides the screen into
.I n
equally sized, individually scrollable, horizontal regions (windows). 
Each window is assigned to an individual c-shell (csh), and is known to that
shell by means of the 
.B TERM
environment variable.
Thus, most programs which use TERMCAP (including vi) may be run under
.I "wty."
.PP
Output from all shells is made immediately available to their corresponding
windows.
However, at any one time, there is only one window which receives input
from the user.
This window is the
.I "current input window,"
and may be changed at any time by the user.
Except for 
.I wty
operation  commands,
.B all
inputs are presented to the current input window's shell as if the shell were
communicating directly with the user.
.PP
Windows may have a buffer allocated for them allowing for recording of all 
input/output for the window.
Buffers are implemented as named files so that they may be edited.
Such a buffer may then be read as input to another window.
.SH OPERATION
.PP
.I Wty
accepts these commands for operation, each preceeded by <ctrl-A>
(<n> is a numeric character window label):
.nf

    <n>         - change current input window
    c<n>        - create new current input window
    cn<n>       - create (nicely)
    d<n>        - delete current input window
    dn<n>       - delete (nicely)
    f<n>        - fold current input window
    fn<n>       - fold (nicely)
    o<n>        - open another current input window
    on<n>       - open (nicely)
    bc          - create new buffer for current input window
    bd          - delete buffer for current input window
    bf          - fold buffer for current input window
    bo          - open buffer for current input window
    br<n>       - read buffer <n> into current input window
    brl<n>      - read buffer <n> literally
    r           - resize current input window
    l           - label all windows
    h           - help
    =<c>        - set command character
    <ctrl-Z>    - stop
    qy          - quit
.fi
.PP
Windows are labeled numerically from top to bottom starting at '1'.
An input of <ctrl-A> <ctrl-A> results in one <ctrl-A> being passed
to the input window's shell.
An input of an invalid command rings the terminal's bell.
.PP
The change window command causes the current input window to become 
that labeled by <n>.
.PP
The create window command creates a new window labeled by <n> and
attaches a shell to it.
The new window becomes the current input window.
All windows are cleared and resized equally \- a new "setenv TERM"
command is sent to the attached shell.
The nice form does not automatically resize other windows.
.PP
The delete window command deletes the current input window and 
detaches its shell.
The current input window becomes that labeled by <n>.
All windows are cleared and resized equally.
The nice form does not automatically resize windows.
.PP
The fold window command temporarily removes the current input window from
the display (until an open command).
The current input window becomes that labeled by <n>.
All windows are cleared and resized equally.
The nice form does not automatically resize windows.
.PP
The open window command causes a previously folded window <n> to become visible
again.
This window becomes the new current input window.
All windows are cleared and resized equally.
The nice form does not automatically resize windows.
Note: all output from a shell attached to a folded window is lost 
until it becomes open again (unless a buffer is recording).
.PP
The create buffer command allocates a named file to the current input window
so that all suceeding input/output for the window may be recorded.
The name of the file is "wty.buf.<n>" (where <n> is the label of the current
input window), unless the environment variable
.B WTYB
has been defined; in this case, the WTYB variable defines the file name prefix
and a suffix string of the form ".<n>" is generated by
.I "wty."
If the buffer file already exists, a new buffer is 
.B not
created.
.PP
The delete buffer command closes the buffer file associated with the current
input window and deletes it from the file space.
.PP
The fold buffer command temporarily inhibits the recording of input/output
data for the current input window if it has a buffer attached to it.
.PP
The open buffer command causes a previously folded buffer (for the current 
input window) to become available for recording again.
.PP
The read buffer command reads the buffer associated with window <n> (if it
exists) and transfers its contents to the current input window as input data.
Any keyboard input during the transfer will terminate the transfer.
All character strings of the form "\\r\\n" in the buffer file are transformed
to the string "\\n" (this is a nominal transformation due to implementation
considerations \- sub-shells normally echo inputted \\r's as "\\r\\n").
The read literal form of the command inhibits this transformation.
.PP
The resize command causes the current input window's 
.B TERM
value to be sent again to its shell.
It is assumed that the shell is in a state where a new
.I setenv
command can be accepted.
Indeed, this command is useful in cases where a particular shell doesn't
receive previous resizing data.
.PP
The label command causes the label of each window to appear in its upper
right corner.
This can be useful as a reminder since windows are not re-labeled after
creation or deletion.
For each window, if a buffer is allocated for it, a 'B' is displayed
immediately following the label if the buffer is open; a 'b' is displayed
if it is folded.
.PP
The help command clears the current input window then displays a summary
of commands.
.PP
The set command character command changes the current command prefix character 
to the character <c>.
The default character is <ctrl-A>.
The new character may not be the same as the start/stop flow control 
characters.
.PP
The stop command temporarily suspends
.I "wty"
and returns control to UNIX.
An 'fg' command can be given later to resume operation.
.PP
The quit (yes, do it!) command terminates execution of
.I "wty."
.SH ENVIRONMENT VARIABLES
.PP
.I Wty
assumes that the TERMCAP file you use contains definitions for a master
prototype entry.
This prototype entry, named by the environment variable
.B WTYP,
defines the capabilities of a psuedo-device which
.I wty
requires for emulation.
Thus these environment variables must be defined before you execute
.I "wty:"
.B "TERM,"
which names the actual terminal you are using;
.B "TERMCAP,"
which should define the pathname of the file containing your TERMCAP
descriptions;
and
.B "WTYP,"
which names the prototype entry within TERMCAP.
(The
.B WTYB
buffer name variable is optional).
.PP
For those who use vt100 compatible terminals,
.B TERM
should be "vt100",
.B TERMCAP
should be "\*P/termcap" (or "/etc/termcap"), and
.B WTYP
should be "vwty_".
The file "\*P/termcap" provides sufficient definitions for vt100 users.
It may also be used as a guide in developing other definitions.
If you 
.nf
        setenv TERMCAP /etc/termcap
.fi
it is assumed that "/etc/termcap" has been edited
to contain a new vt100 definition and WTYP entry as 
given in the file "\*P/termcap".
If this is not the case, or if you use a local TERMCAP file (which is
faster anyway for programs that search for TERM entrys), then you need to
edit your own local TERMCAP file.
.PP
A new 
.B TERM
type entry is included in "\*P/termcap" for those who have access to ANSI
compatible terminals (these are vt100 functional supersets which allow local
editing functions).
The entry name is "ansi": 
.nf
        setenv  TERM ansi
.fi
and 
.B WTYP
should be: 
.nf 
        setenv  WTYP wty_
.fi
.br
.SH TERMCAP INTERFACE
.PP
This section provides additional details about the
.B WTYP
prototype entry and how it relates to actual devices.
This section is necessary reading if you do not
have a vt100 or ANSI compatible terminal, or if you are writing a new
TERMCAP entry.
It is assumed that you are familiar with the material covered in
.I "termcap(5)."
.PP
The primary capability required by
.I wty
for any terminal is a controllable scrolling region defined by
.B "cs."
The multiple scrolling regions of
.I wty
are controlled by multiplexing the scrolling region of
.B "TERM."
The 
.B cs
cap requires a top and bottom row parameter defining the
scrolling region.
These parameters are encoded in the same way as the parameters are for
.B "cm."
.PP
The specific caps required by
.I wty
for a given
.B TERM
definition depend, with two exceptions, upon the
.B WTYP
prototype definition.
The exceptions are
.B cs
and
.B "cm;"
controllable scrolling region and cursor motion are the only two caps
which 
.I must
be provided in your
.B TERM
definition.
.PP
For most other caps, if the
.B WTYP
entry defines a particular cap, then the corresponding cap in the
.B TERM
entry must also be defined.
Some caps which have reasonable defaults do not need an explicit definition
at all.
The caps: (bc, co, cr, do, is, ke, ks, li, nl, sg, ug, ve, vs, we, ws)
have defaults (respectively) 
of: (^H, 80, ^M, ^J, ?, ?, ?, 24, ^J, 0, 0, ?, ?, ?, ?);
where '?' means the empty string.
.PP
The
.B WTYP
prototype defines the specific caps required for all windows by
.I "wty."
Each differently sized window also requires a set of capabilities which
define the size of the window.
The caps
.B co
and
.B li
describe window size variables.
.B Co
should always be constant since windows are defined as scrolling regions
which extend across the entire display.
Thus the
.B li
cap is the only parameter determining window size.
.PP
Since each window's shell requires knowledge of its own window's size,
via the
.B TERM
environment variable,
this may be accomplished by extending the basic
.B WTYP
definition by defining a new entry for each different size window.
The entry must be named according to this rule:
The name of the
.B WTYP 
entry is the prefix of the new name, and the row/column size of the window
determines the postfix of the new name in the format: RxC, where R is the
same as
.B "li,"
and C is the same as
.B "co."
Thus, for a window of size 12x80, and (say)
.B WTYP
= "vwty_", then the name of the new entry would be "vwty_12x80".
Note that there must be an entry for
.B every
window size.
Window (row) sizes are computed by dividing the maximum number of rows by
the number of windows.
So, for example, if we have a 24-row host terminal, then we would need 
definitions for 24 rows (24/1), 12 rows (24/2), 8 rows (24/3), 
and 6 rows (24/4).
.PP
At this point, it may seem that the use of the
.B TERM
environment variable has been inconsistent \- this is not so.
Recall that
.I wty
creates new 
.I shells
for each window.
It is these shells which require that their
.I own
version of the
.B TERM
variable identify the size of their attached window.
The propagation of this information to each window's shell is handled
automatically by
.I wty.
This is the purpose of forming a new TERMCAP entry by concatenating the
.B WTYP
prototype prefix and the RxC format postfix as described above.
Since
.I wty
requires knowledge of the terminal it is controlling, the definition of
.B TERM
at the time of program initialization provides that knowledge.
.SH TTY INTERFACE
.PP
This section is presented for informational purposes only \- understanding
the details of the tty interface is not necessary in order to use
.I wty.
.PP
When
.I wty
begins, with one exception, the initial tty state is passed on to the 
sub-shells which are created for all of the windows.
In general, the actual setting of this state is more or less irrelevant 
to the correct operation of
.I "wty."
The exception is that "stty -tabs" is explicitly set for the sub-shells;
this is because
.I wty
ignores incoming tabs (^I) from sub-shells.
However, after this initial state is picked up,
.I wty
resets several tty modes ala "stty new cbreak -echo -tabs nl".
Also, all special characters are un-defined (i.e. stty <c> u) except for
the flow control characters (^S ^Q usually).
This is essentially equivalent to "stty raw" but allows automatic
flow-control and delay-processing (whew!).
.SH SEE ALSO
.B "msh(\*M)"
.br
.B "wms(\*M)"
.SH BUGS
.PP
Not all programs which use TERMCAP can run under
.I "wty."
In particular, those programs which attempt to control
.B cs
themselves will have little luck.
Fortunately, the number of such programs appears to be small.
.PP
It is possible that sub\-processes may still exist after
.I wty
is terminated.
Usually this occurs if backround jobs are left running in a sub\-shell
after quiting
.I "wty."
One should then do a ps command to check on stray processes.
.PP
The <break> key does not work.
It is best to rely upon your <kill> character if you regularly use <break> 
as a <kill> alias.
.PP
The <start> and <stop> characters affect flow-control globally \- there is
no way to get local (per window) flow control.
.PP
Due to the lack of internal buffering, when one resumes a stopped
.I "wty,"
the individual windows are not automatically redrawn.
For the same reason, creating or deleting windows automatically
clears and homes all windows (likewise for folding and opening).
.PP
If
.I wty
is executed for too long at a time, the operating system will renice it.
As this will slow things down quite a bit, it is advisable to quit
.I wty
then restart it again.
Another alternative is to stop (<ctrl-A><ctrl-Z>)
.I wty
and use the original shell as often as feasible.
This may delay the renice.
.SH NOTES
.PP
The TERMCAP definitions as given in "\*P/termcap" make a reasonable 
basis for your own local TERMCAP file.
Note two new capabilities:
.B we
and
.B "ws."
These (string) caps should be given to end and start a
.I wty
session (or when stopping and resuming).
Typically, they would include the same information as 
.I is
does but should explicitly set/reset the scrolling region.
Note that
.I is
should
.B not
explicilty set/reset the scrolling region.
.PP
The 
.B cl 
and 
.B cd
prototype caps are implemented by means of
.B ce 
only (in the host TERMCAP definition).
This means that cl and cd are not needed in the host definition.
.PP
The justification for pad counts in the TERMCAP prototypes is a little fuzzy.
Generally, depending on your own terminal, no pad delays need be given.
If
.I wty
seems to generate strange screen commands, a little delay time in things
like 
.B cm
in the prototype entry should fix things.
The reason this seems to occur is that programs which use the padding
information of TERMCAP (like vi) assume that they are talking directly to a 
terminal.
Injecting a program like
.I wty
between vi and a terminal can introduce delay timing discontinuities into
the output stream, not to mention the fact that 
.I wty
itself is sending control codes to the screen (thus adding to the general
chaos of control codes flocking to the terminal).
.SH AUTHOR
George Nelan
@@ END-OF-FILE
echo done