---------- ---------- ---------- ---------- ---------- ---------- ----------
			  XTERM-SUN
---------- ---------- ---------- ---------- ---------- ---------- ----------

SUMMARY:
========
  Xterm-sun is an enhanced terminfo (and termcap) database entry for
  the xterm terminal program running under X11 on a Sun Workstation.

  The termcap and terminfo database entries for xterm (used in many
  programs, especially curses-based programs) are missing many function
  key entries.  This package seeks to rectify that situation.

  Included are definitions for the function keys <Home>, <End>, <PgUp>,
  <PgDn>, and <F1> through <F12>.

  Using xterm-sun lets you use those function keys in curses-based programs
  from within an xterm window.

DESCRIPTION
===========
  Xterm is one of the most widely used pieces of X-windows software.
  But it is certainly not one of the best.  The README file that
  accompanies it describes it as ``the most ugly program in the
  distribution''.  One flaw with xterm (IMHO) lies in its sparse
  termcap/terminfo entry, and in it's handling of function keys on the
  Sun keyboard.

  ASIDE:    I have never used Xterm on anything other than a Sun, so I
	    have no idea how it functions on those platforms.

  The termcap (and terminfo) entry for xterm is lacking definitions for
  the Home,End, PageUp, and PageDown function keys.  Furthermore, while
  it does contain definitions for functions keys F1 through F10, those
  definitions (at least on my system) are WRONG.  That is, they do not
  match the codes that are produced by xterm when those keys are
  pressed.

  This caused me some annoyance while developing a curses-based
  program.  I wanted to make use of the Home, End, PageUp, and PageDn
  in my program but was unable to.  Since I am not qualified to fix
  xterm (Somebody, please fix it!), I have instead put together an
  enhanced termcap and terminfo database entry for a Sun Sparc with a
  Type-4 keyboard.

  ASIDE:    These also work on a Sun3 with the type-2 keyboard.
	    However, I have not tested them extensively on such.  There
	    may be some problems lurking in the darkness, ready to
	    pounce on unsuspecting programmers.

RESTRICTION
===========
  These enhanced termcap / terminfo entries require that you run xterm
  with the ``-sf'' command line option, to force xterm to generate Sun
  function key escape codes.

  This is necessary, because with the default option (+sf, standard
  function key escape codes) I found that xterm produces NO output
  whatsoever when the Home, End, PageUp, or PageDown keys were
  pressed.

THE TERMCAP / TERMINFO FILES
============================

  There are two files included in this package: xterm-sun.ti and
  xterm-sun.tc.  xterm-sun.ti contains the terminfo database entry for
  a Sun, entitled xterm-sun.  The corresponding termcap entry is stored
  in xterm-sun.tc.  The xterm-sun.tc file was produced from
  xterm-sun.ti using ``/usr/5bin/infocmp -C''.

  Please refer to the comments in those files, for additional
  information.

  The ``vanilla'' xterm termcap / terminfo database entry contains
  definitions for only the keypad arrow keys.  (Yes, I know I already
  mentioned that it contained WRONG definitions for the function keys
  F1 through F10.  I'm trying to forget about that :-).  I have added
  the following function key definitions:

	<Home>, <End>, <Page Down>, <Page Up>, <Insert>, <F1> through
	<F12>, <Shift><End>, <Shift><Home>, <Shift><Left Arrow>,
	<Shift><Right Arrow>.

  NOTE:     Under ``xterm -sf'', xterm produces the same key codes for
	    function keys <F11> and <F12> as it does for the function
	    keys <Stop> and <Again>.  This may cause you some grief, be
	    careful.

  BEEF:     Why doesn't terminfo / termcap allow a shifted Up/Down
	    Arrow when it does have a shifted Left/Right Arrow?  What
	    about shifted PageUp/PageDown, after all, there are shifted
	    Home/End Keys.  Seems rather arbitrary.  Mutter mutter,
	    grumble grumble.

  Note that on a Sun3 with the type-2 keyboard, there are no function
  keys F10 through F12.  Also, the Home, End, PageUp, PageDown are not
  labelled as such.  They are:

	    Home :   R7
	     End :   R13
	    PgUp :   R9
	    PgDn :   R15

INSTALLATION
============
  There are a number of ways that you can install these database
  entries.

  1) Rename them from ``xterm-sun'' to ``xterm'' and replaces the
     standard entries in the termcap and terminfo databases with these
     enhanced entries.  This will require some fiddling on your part,
     since as distributed, these refer to the original xterm entries.

  This would cause the least amount of disruption for xterm users, but
  remember that these termcap / terminfo function key descriptions only
  work with ``xterm -sf''.

  2) Install the ``xterm-sun'' entries into your system termcap and
     terminfo databases.

  This is also a nice option, but like option 1, it requires System
  Administrator privileges.

  3) If you are a ``lowly user'' you can install them in your own
     home account.

  Pick a subdirectory under your user id (I use /lib/terminfo)
  and put the files there.

  Nothing special is required with xterm-sun.tc, but xterm-sun.ti must
  be compiled before it can be used.  See the man page for tic(8v) for
  instructions on that.  (Note:  tic is probably in /usr/5bin on your
  Sun system).

  When it is compiled, xterm-sun.ti will also produce a compiled
  ``xterm'' and ``vs100'' entry.  See the comments in xterm-sun.ti.
  Those can safely be deleted.

USAGE
=====
  For option 1 above, all you need to do to make this enhanced termcap
  / terminfo database entry available to all your curses programs is to
  remember to start xterm with the ``- sf'' option.

  If you choose option 2 above, you must also give the command like
  option ``-tn xterm-sun'' when you run xterm.

  Those of us forced to use option 3 above, have the most grief.

	Set your TERM environment variable to ``xterm-sun''.

	Set your TERMINFO environment variable to the parent directory
	of the directory where the compiled `xterm- sun' entry is.

	Set your TERMCAP environment variable to be the directory of
	where you stored `xterm-sun.tc'.  This MUST begin with a slash
	(`/') due to the way the function tgetent() works.  (See the
	source code of xterm, and the man page of tgetent() to learn
	more of this.)

        An example, based on option 3, above.
	   % setenv TERM xterm-sun
	   % setenv TERMINFO /usr/users/joeblow/termlib
		(the xterm-sun compiled terminfo entry is stored
		in the x subdirectory under termlib)
	   % setenv TERMCAP /usr/users/joeblow/termlib/xterm-sun.tc
	   % xterm -sf -tn xterm-sun &

TESTING
=======
  Included with this package is a simple curses program ``f1.c''.
  To compile this program, edit the Makefile to match your sight
  and then give the command ``make f1''

  If you then run f1, you can check and see that you can indeed
  detect the various function keys from within a curses program.

  REMEMBER to first set your TERMINFO and TERM environment variables.
  Oh yah, ``f1.c'' uses System V curses and terminfo, NOT termcap.

DISCLAIMER
==========
  I hope you find this package to be useful to you.  But I make no
  warranty as to accuracy/correctness of these files.  Caveat Emptor.

  This material is dated April 4, 1992.  Hopefully, someone will soon
  fix xterm, and this package will no longer be of any use to anyone.

FILES:
======
  README	- this file
  xterm-sun.ti	- terminfo database entry (see comments)
  xterm-sun.tc	- termcap database entry (see comments)

  Makefile	- makefile for f1.c
  f1.c		- simple curses program to test the terminfo entry

SEE ALSO
========
  xterm(1), curses(3v), termcap(5), terminfo(5v), infocmp(8v), tic(8v),
  tgetent(3x).

BUGS
====
  Hopefully none, but this *is* a beta release.

AUTHOR:
=======
  ...art mulder                       Department of Computing Science
  art@cs.ualberta.ca          University of Alberta, Edmonton, Canada
---------- ---------- ---------- ---------- ---------- ---------- ----------
