IanDarwin.OpenLookCDROM/NeWS/gterm/README

(Installation instructions are here in the README file, a few pages down.)

			Gterms Recent Changes

Gterm is a terminal emulator that runs under the NeWS window system.
Terminal-oriented applications (like the Unix shell) run inside it.
It displays their output, manages their input, and handles their
interaction with other programs that share the user's screen.
It will try to emulate any terminal described by "termcap", though due
to limitations in the termcap model it often fails at this;
it's best to use the "psterm" termcap entry unless you have special
requirements.

This is release Grass-2 (Patch Level 2) of gterm from the Grasshopper
Group.  The original psterm source from Sun Microsystems' NeWS 1.1
release is freely distributable under Sun's copyright, reproduced
below.  (Sun modified the copyright after the release, and supplied us
the revised wording that is used here.)  The modifications to that
source which were made at the Grasshopper Group are in the public
domain.

Gterm is the direct decendent of psterm, an expermental NeWS/PostScript
terminal emulator.  Gterm is different from psterm in that it can be used
all week long as the main terminal emulator in 'most any Unix or Unix like
environment.

Gterm has been modified to be different then psterm in these respects:

	Multi-Toolkit
		Gterm runs a protocol for terminals; which toolkit/GUI
		is wrapped around these terminals is up to the NeWS code
		loaded in the GTermDict_? by one of the gterm?XXXX.psh
		files.  This text describes the first toolkit that
		gterm (the Grasshopper Group version of Sun's psterm) ran
		under, LiteWindows on NeWS 1.1.  Note that with this
		design, a single gterm binary can talk to many different
		toolkits at the same time, with whatever GUI the NeWS
		end of the code wishes.

	Custom Parsers
		The general parsing of termcap entries is a tricky
		business, which can be VERY slow.  To make gterm as
		useful as possible, we have added custom parsers to
		gterm; users of the 'dumb' and 'psterm' termcaps will
		see very fast terminal emulation.

	NeWS extentions
		Using .gtermrc files and toolkit wrapping, very custom
		terminal emulators can be built, like console
		windows that have large fonts, windows with custom
		buttons or menu structures, etc.
  
When you see the phrase 'gterm?XXXX.psh' or GTermDict_?, the documen-
tation is not trying to confuse you but is leaving room for gterm to
expand and grow.  The '?' refer to the protocol level between the NeWS
code and the gterm; when ever something changes in this protocol, this
number will change.  The XXXX is a mangled name of the Toolkit which
is wrapped around the gterm window (mangled to fit into 14 characters
for Missed'em Five users).  This is the current scheme:

		System		Toolkit		gterm
		---------------------------------------
		NeWS 1.0	Lite 0		lte1 *
		---------------------------------------
		NeWS 1.1	Lite 1		lte1
		---------------------------------------
		OpenWindows	Lite 2		lte2 *
		    1.0		tnt 1.0		xxxx
		---------------------------------------
		OpenWindows	Lite 2		lte2
		    2.0		tnt 1.0		xxxx
				   or
				tnt 2.0		xxxx
		---------------------------------------
		xxxx = No current adaptor, * = untested

Gterm is the result of many people and companies working to build
better tools.  Much of this work could not have been done without the
support of:

	Grasshopper Group
	Eric Messick
	Capital Market Technologies, Inc.

We thank them for their time, ideas, sweat, and most importantly for
their patronage in supporting our work.

The Grasshopper Group sells and supports NeWS-related products.  Our
first product is MacNews, a port of NeWS for A/UX on the Macintosh-II.
Gterm is our second "product", though it is offered freely to the public
to make NeWS more usable on all systems, and to advertise our company.
You can reach us at:

	Grasshopper Group
	210 Clayton St.
	San Francisco, CA  94117

+1 408 978 7616	  orders, business questions, 8:30-5pm Pacific  orders@toad.com
+1 415 668 5998	  technical questions,	      afternoons Pacific  tech@toad.com

The Grasshopper Group modifications to gterm are by Eric Messick & 
||ugh Daniel, from designs by ||ugh Daniel & Eric Messick.  Please send
questions, comments, bugs, fixes, etc... to tech@toad.com.


			Installation

Unpack the shar files in an empty directory.

The installation has been tested on SunOS 4.1 on Sparc and 68020, and
on A/UX 2.0 on the Macintosh-II.  It should be fairly easy to port it
to other Unix systems.  If you do such a port, please send back the
changes required, as complete source files or "context diffs", to
the Grasshopper Group at tech@toad.com.  We will integrate your fixes and
post patches as required.

Some of the source files include <ref/config.h>.  The directory "ref"
is included, with sample config.h files.  Most of the effort of porting
gterm to another system, is in modifying one of these config files to
match the local programming environment.  Create a symlink to the
appropriate one as follows, replacing XXX with "sunos" or "aux".  If
your system doesn't have symbolic links, just link it or copy it
instead.

	cd ref
	ln -s config_XXX config.h
	cd ..

Now change the Makfile to comply with your system.  The only change
that most folks will have to make is to specify what version of NeWS
is running, by commenting in or out the right two of these four lines:

	# NeWS 1.1
	NEWSHOME=/usr/NeWS
	PSHDIR=${INSDIR}/lib

	# OpenWindows
	NEWSHOME=/usr/openwin
	PSHDIR=${INSDIR}/etc

Now you should be ready to:

	make

to create the binary program "gterm".  Then:

	make install

to install the gterm binary in ${NEWSHOME}/gterm, the PostScript
code files in {PSHDIR}/gterm?XXX.psh, and the man page in
/usr/localman/man1/gterm.1.  Edit the Makefile if this is inappropriate
on your system.

A tutorial called UsingGTerm is also included.

You might also install the psterm termcap in /etc/termcap, which
was designed specifically for gterm.  You will have to do this step,
and the next (terminfo) step if required, as root:

	mv /etc/termcap /etc/termcap.orig
	cat termcap.NeWS /etc/termcap.orig > /etc/termcap

If your system uses terminfo, you'll have to update your terminfo database as
well.  Gterm can find and use the termcap info on its own, but if you system
uses terminfo you will have to do this next step,  so, as root:

	tic terminfo.NeWS

Tic is in /usr/5bin if you have installed "System V Compatability"
under SunOS.  Remember to update the terminal descriptions on all of
the systems in your network, and to compile the psterm binary for all
machines, even if there is no news_server (or screen!) on machines like
Vaxen or Amdahls.

Note: the termcap and terminfo updates also include nterm descriptions.

That should be it... have fun.

If you find bugs, first read the BUGS file in this release.  Then, if
your bug is news to us (or if you have a fix for it), send email to
"tech@toad.com" describing which gterm you have (including the patch
level from patchlevel.h), how to reproduce the bug, what happens when
you reproduce it, and how to fix it if you know.


			Table Of Contents

  This set of shar files contains the following files:

BUGS		Text file containing known bug descriptions
Makefile	Makefile
README		This file
UsingGTerm	Ascii text tutorial
bsd.c		bsd operating system interface
display.c	screen maintainence
fkeys.psh	function key NeWS PostScript code
gterm.1		man page
gterm1lte1.psh	PostScript code for LiteWindows/NeWS 1.1 adaptor
gterm1lte2.psh	PostScript code for LiteWindows/OpenWindows adaptor
gtermstart.psh	PostScript code to decide what toolkit adaptor to use
io.c		low level input/output
main.c		argument processing, main()
parsers.c	Custom parsers for termcaps
patchlevel.h	revision level
termcap.NeWS	termcap entries
terminfo.NeWS	terminfo entries
ref/config_aux	A/UX specific configuration information
ref/config_sunos	SunOS configuration information
rshcommand.psh	Usefull NeWS code for starting remote gterms
sampl.gtermrc	example .gtermrc file
screen.h	description of screen data structures
selection.c	text selection handling routines
slave.c		process forking routines
sys5.c		System V operating system interface
tcap.cps	C to PostScript interface routines
tcap_ops.c	termcap screen manipulation functions
tcap_parse.c	termcap escape sequence parsing code
termcap.h	description of termcap data structures



			Notes

NeWS has urgently needed a good terminal emulator for some time.  We at
the Grasshopper Group hope that this version of gterm can fill that
gap for a while.  There are, however, several fundamental problems with
gterm which limit its potential usefulness.  Many of the problems with
the original version of gterm have been dealt with, but the program
has been stretched far beyond the original concept, and is approching
the limits of its design.

There is a fundamental conceptual problem with the idea of emulating a
terminal by reading its termcap entry.  The termcap entry describes how
to get a terminal to perform a certain set of tasks.  It does NOT
describe how the given terminal will respond to a sequence of
characters.  This is the information needed by a terminal emulator.  As
an example, consider the vt100 termcap entry.  Clearing the screen on a
vt100 does not home the cursor.  Unfortunately, the termcap string for
screen clearing (cs) is defined to both clear the screen and home the
cursor.  To cope with this, the termcap entry for clearing the screen
on a vt100 emits two escape sequences:  one for homing the cursor, and
one for clearing the screen.  BUT THERE IS NO WAY FOR GTERM TO KNOW
THIS!  Gterm thinks that in order to clear the screen, this double
sequence must be recieved, and WILL NOT RECOGNIZE JUST THE CLEAR SCREEN
SEQUENCE.  There is a similar problem with the h19 entry.  Codes which
are transmitted by the ``enter screen mode'' string are not defined
elsewhere in the termcap entry, so there is NO WAY for psterm to know
what to do with these.

We have gotten around much of the problem of parsing termcap entries
by adding custom parsers for the 'dumb' and 'psterm' termcaps.  Thus
when gterm is started up by default (or with the '-t psterm'), the
custom parser 'tc_display_psterm' is used insted of the general one,
giving excellent performance.

A more serious (though much more subtle) problem concerns the design of
the program itself.  It is not a good example of how to divide the
labor between the client side and the server side.  This is important
because we desperately need good examples of this poorly understood
aspect of NeWS programming.  The power and flexibility of a fully
programmable graphics server depend on programmers correctly dividing
tasks between client and server.  Gterm relies too heavily on the
client program for repainting the screen and repairing damage.  On the
other hand, the other common NeWS terminal emulator, Nterm, does too
much of its terminal emulation in PostScript, and its performance
suffers as a result.  The correct division point lies somewhere between
these two attempts.  As a result of the incorrect division of labor of
gterm, the addition of scrollbars was a difficult and painful task.
If the division had been made at the proper point, I am confident that
implementing scrollbars would have been painless and quick.


			Sun's copyright notice

The original copyright notice on Sun's NeWS 1.1 client program sources
required that it be distributed "as part of a product or program
developed by the user."  This prohibited a variety of noncommercial
distributions, like Usenet postings, source archives like uunet's, or
tape collections like Usenix's or Sun User Group's.  Sun graciously
modified their copyright and authorized us to replace the previous
notice with their new notice, which will be in their next NeWS release.
The whole thing is below (the relevant line is the fourth):

/*
 * This file is a product of Sun Microsystems, Inc. and is provided for
 * unrestricted use provided that this legend is included on all tape
 * media and as a part of the software program in whole or part.
 * Users may copy, modify or distribute this file at will.
 * 
 * THIS FILE IS PROVIDED AS IS WITH NO WARRANTIES OF ANY KIND INCLUDING THE
 * WARRANTIES OF DESIGN, MERCHANTIBILITY AND FITNESS FOR A PARTICULAR
 * PURPOSE, OR ARISING FROM A COURSE OF DEALING, USAGE OR TRADE PRACTICE.
 * 
 * This file is provided with no support and without any obligation on the
 * part of Sun Microsystems, Inc. to assist in its use, correction,
 * modification or enhancement.
 * 
 * SUN MICROSYSTEMS, INC. SHALL HAVE NO LIABILITY WITH RESPECT TO THE
 * INFRINGEMENT OF COPYRIGHTS, TRADE SECRETS OR ANY PATENTS BY THIS FILE
 * OR ANY PART THEREOF.
 * 
 * In no event will Sun Microsystems, Inc. be liable for any lost revenue
 * or profits or other special, indirect and consequential damages, even
 * if Sun has been advised of the possibility of such damages.
 * 
 * Sun Microsystems, Inc.
 * 2550 Garcia Avenue
 * Mountain View, California  94043
 */

@(#)$Header: /it/grass/gterm/RCS/README,v 2.11 1991/04/23 06:51:35 hugh Grass2 $