                            INTRODUCTION
                            ------------

This directory contains all source code and documentation associated
with the XGKS package.  XGKS is an X11 window system based version of
the ANSI Graphical Kernel System.  XGKS is a full GKS system (level
2C).  This library was developed at the University of Illinois, Urbana
campus, department of Computer Science and was funded by IBM TCS.  The
project was headed by Prof.  Bill Kubitz and Prof. Roy Campbell.
Development of XGKS was done by Greg Rogers, Sung Hsien Ching, and Yu
Pan.  Testing and improvements to XGKS were performed by IBM Technical
Computing Systems in Cambridge, Mass.  The IBM developers were Todd
Gill, Bruce Greer, David Owens, and Michael Wojcik, and Project Leader
Amy Pitts.

Neither the University of Illinois nor IBM support XGKS anymore.
Fortunately, however, Steve Emmerson of Louisville, Colorado has accepted
the maintenance of XGKS as a hobby.

The XGKS project resides at <http://xgks.sourceforge.net>.  Please go
there for all your XGKS needs (releases, fora, support, CVS repository,
contributions, etc.).



                   SOURCE DIRECTORY OVERVIEW
                   -------------------------

The structure of the XGKS source directory-tree is


	       |-progs--
	       |
	       |        |-binding--
	       |-doc----|
	       |        |-userdoc--
	|-xgks-|
	       |-fontdb-
	       |
	       |        |-fortran--
	       |        |
	       |-lib----|          |-cgm--
			|          |
			|-c--------|-gksm-
				   |
                                   |-x----

where:

    xgks	Is the root directory (the one containing this file)

    progs	Contains utility programs

    doc		Contains documentation (e.g. "xgks.3")

    doc/binding	Contains the source for a document describing the
		1988 C language binding for XGKS

    doc/userdoc	Contains the source for a document describing the
		GKS implementation-specific details of XGKS

    fontdb	Contains the XGKS fonts

    lib		Contains the implementation of the XGKS runtime-library

    lib/fortran	Contains the source for the Fortran interface to XGKS

    lib/c  	Contains the source for the XGKS library.

    lib/c/cgm	Contains the source for the Compute Graphics Metafile
		"backend" to XGKS.

    lib/c/gksm
		Contains the source for the GKS Metafile (GKSM) "backend"
		to XGKS.

    lib/c/x	Contains the source for the X Window System "backend" to 
		XGKS.




                           INSTALLATION
                           ------------

Installation instructions can be found in the file INSTALL.

XGKS has been installed on many platforms.  I have installed and verified
its behavior on the following systems (`uname -srvm' output):

    AIX 2 3 000109423500                using /bin/cc
    HP-UX A.09.05 A 9000/715            using /bin/c89
    IRIX 5.2 02282015 IP20              using /bin/cc
    OSF1 V3.0 347 alpha                 using /bin/cc
    SunOS 5.3 Generic_101318-59 sun4m   using /opt/SUNWspro/bin/acc
    SunOS 4.1.3 1 sun4m                 using /usr/local/lang/acc
    ULTRIX 4.4 0 RISC                   using /bin/cc

Users report that it also installs and works on the following systems:

    Apollo DN3000       under DomainOS 10.2,   BSD4.3, with C compiler
                        68K Rev 6.7(316)
    Apollo DN4000       under DomainOS 10.3.2, BSD4.3, with C compiler
                        68K Rev 6.8(168)
    Apollo 425T         under DomainOS 10.3.5
    VaxStation II       under Ultrix 3.5, 4.0, & 4.1
    Cray Y-MP           under UNICOS 5.1.11

The structure of the installation is nominally:

                            |-defcolors
                            |-font
                            |-mi
                  |-bin-----|-pline
                  |         |-pmark
                  |         |-hanoi
                  |         |-star
                  |         |-gksdemo
                  |
         |-prefix-|-include-|-xgks.h
                  |
                  |         |-libxgks.a
                  |-lib-----|
                  |         |-xgksfonts-
                  |
                  |-man-----|-man3-|-xgks.3

where:

    prefix      is whatever you made it when you invoked `configure' (see
		file INSTALL).

    defcolors   displays the default X colormap (set DISPLAY first);

    font        displays the fonts used by XGKS (set DISPLAY first);

    mi          is a simple GKS Metafile (GKSM) interpreter 
                (usage: mi <display> <file>);

    pline       displays the polyline types used by XGKS (set DISPLAY
                first);

    pmark       displays the marker types used by XGKS (set DISPLAY
                first);

    hanoi       is a Towers-of-Hanoi demonstration (set DISPLAY first);

    star        is a imple fortran program to draw a star (set DISPLAY first);

    gksdemo     is a Fortran program that demonstrats most of XGKS 
		capabilities (set DISPLAY first);

    xgks.h      is the header-file that every XGKS application must
                #include;

    libxgks.a   is the XGKS runtime library.

    xgksfonts   is a directory which contains the XGKS fonts;

    xgks.3      contains the XGKS man(1)ual pages.

Fonts used by XGKS are dynamically loaded when first referenced.  Thus,
the fonts must be installed on the machine where the XGKS application
executes.

The font path is compiled into the library.  However, it is possible to
move the fonts without having to recompile XGKS by setting the
environment variable "XGKSFontDir" to the new path before executing an
XGKS application.  This variable setting will tell XGKS at runtime
where to find its fonts.




                            DOCUMENTATION
                            -------------

In addition to the man(1)ual pages that will be installed during the
installation procedure, there are two other documents you should be aware
of.  The first describes the C-language binding used by XGKS.  To obtain
hardcopy, go to directory "doc/binding", edit the makefile (if necessary),
and type "make hardcopy".

The second document details the implementation-specific aspects of GKS
particular to XGKS.  To obtain hardcopy, go to directory "doc/userdoc",
edit the makefile (if necessary), and type "make hardcopy".

A good general book on GKS is "Computer Graphics Programming: GKS - The
Graphics Standard" by G. Enderle, K. Kansy, and G. Pfaff.  It's published
by Springer-Verlag and its ISBN numbers are 3-540-16317-4 and
0-387-16317-4.




                            KNOWN PROBLEMS
			    --------------

HP-UX A.09.05:

    There is apparently a bug in the implementation of the shared
    FORTRAN runtime library.  This bug is frequently (but not always)
    tickled by XGKS.  The symptom is the crash and core dump exemplified
    by the program `star' in the progs/ subdirectory:

	% ./star
	/lib/dld.sl: Bind-on-reference call failed 
	/lib/dld.sl: Invalid argument
	ABORT instruction (core dumped)

    I don't know of any workaround, other than to use a C main program
    instead of a FORTRAN one.

SunOS 5.3:

    There is apparently a bug in the implementation of the FORTRAN
    runtime library which prevents the handling of asynchronous X events
    when executing a FORTRAN READ.  The workaround is to use something
    like the BWAIT routine in the file progs/star.f rather than a
    FORTRAN READ.



Regards,
Steve Emmerson
