Psterm 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-1 (Patch Level 1) of psterm from the Grasshopper
Group.  The original 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.

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.
Psterm 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
	212 Clayton St.
	San Francisco, CA  94117

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

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


			Installation

Unpack the four shar files in an empty directory.

The installation has been tested on SunOS 4.0 on Sparc and 68020, and
on A/UX 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
psterm 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 you should be ready to:

	make

to create the binary program "psterm".  Then:

	make install

to install the psterm binary in /usr/NeWS/bin/psterm, the PostScript
code in /usr/NeWS/lib/psterm_1.ps, and the man page in /usr/man/manl/psterm.l.
Edit the Makefile if this is inappropriate on your system.

A tutorial called UsingPSTerm is also included.

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

	mv /etc/termcap /etc/termcap.orig
	cat psterm.tcap /etc/termcap.orig > /etc/termcap

If your system uses terminfo, you'll have to update your terminfo database as
well...  so, as root:

	tic psterm.tinfo

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 psterm 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
UsingPSTerm	Ascii text tutorial
bsd.c		bsd operating system interface
display.c	screen maintainence
io.c		low level input/output
main.c		argument processing, main()
patchlevel.h	revision level
psterm.1	man page
psterm.tcap	termcap entries
psterm.tinfo	terminfo entries
psterm_1.ps	PostScript code
ref/config_aux	A/UX specific configuration information
ref/config_sunos	SunOS configuration information
sampl.pstermrc	example .pstermrc file
sampl.user.ps	example user.ps 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 psterm can fill that
gap for a while.  There are, however, several fundamental problems with
psterm which limit its potential usefulness.  Many of the problems with
the original version of psterm 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 PSTERM TO KNOW
THIS!  Psterm 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.

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.  Psterm 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
psterm, 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: /u/eric/client/psterm/RCS/README,v 2.6 88/11/16 00:52:03 gnu Exp $
