                    Copyright IBM Corporation 1989

                         All Rights Reserved

Permission to use, copy, modify, and distribute this software and its
documentation for any purpose and without fee is hereby granted,
provided that the above copyright notice appear in all copies and that
both that copyright notice and this permission notice appear in
supporting documentation, and that the name of IBM not be used in
advertising or publicity pertaining to distribution of the software
without specific, written prior permission.

IBM DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING
ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT
SHALL IBM BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES
OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS
SOFTWARE.




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

This directory contains all source code and documentation associated
with the XGKS library.  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, the Unidata Program Center (UPC) of the
University Corporation for Atmospheric Research (UCAR) in Boulder,
Colorado, has accepted responsibility for its maintanence and
evolution.  The UPC also runs a mutual-aid-society mailing-list for
XGKS user's.  To join the mailing-list, or to otherwise correspond with
the UPC about XGKS, send e-mail to

    xgks-request@unidata.ucar.edu	(IP address: 128.117.140.3)

After which, you can post an article to the XGKS mailing-list by
sending to

    xgks@unidata.ucar.edu.




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

The structure of the XGKS source directory-tree is


	       |-progs--
	       |
	       |        |-binding--
	       |-doc----|
	       |        |-userdoc--
	|-xgks-|
	       |-fontdb-
	       |
	       |        |-fortran--
	       |        |
	       |-lib----|          |-cgm--
			|          |
			|-src------|-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
		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/xgks	Contains the source for the XGKS library.

    lib/src/cgm	Contains the source for the Compute Graphics Metafile
		"backend" to XGKS (not implemented yet).

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

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




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

Two additional pieces of software must *already* be installed on your
system in order to build XGKS.  The pieces are fortc(1) and UDPOSIX --
both, of which, are sub-components of the larger Unidata Application
Program Environment (UDAPE) package.  UDAPE is available via anonymous
FTP from host unidata.ucar.edu [128.117.140.3], file `pub/udape.tar.Z'

The fortc(1) package allows one to write FORTRAN-callable C-functions
in a portable manner.  It uses sed(1) and m4(1) to transform
almost-C-code into its FORTRAN-callable counterpart.  This
transformation is necessarily operating-system dependent.

The udposix(3) package allows one to write C code with almost no
`#ifdef's using a subset of the union of Standard C and POSIX.
Discrepancies in the underlying environment are hidden by a set of
header-files, interface functions, and programming conventions.

XGKS has been rewritten using these two packages for increased
portability and ease of maintenance.  The UPC regrets the additional
effort this requires from installers of XGKS, but sees no reasonable
alternative.

XGKS has been installed on many platforms, including:
    
	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
	DECstation 3100	under ULTRIX 4.1 & 4.2
	HP 9000/720	under HPUX 8.0
	Sun3		under SunOS 4.0.3, 4.1, & 4.1.1 (using both 
			    /usr/bin/cc and /usr/5bin/cc)
	Sun4		under SunOS 4.1 & 4.1.1
	IBM RS6000	under AIX 3.1
	Cray Y-MP	under UNICOS 5.1.11

The Makefile(5)s in this distribution support the creation and
installation of shared-libraries under the SunOS 4.1.* and AIX 3.1
operating-systems.  This is also the default action on those systems.

If your system is not one of the above, and you must consequently
modify the Makefile(5)s, please send the modifications to the UPC so
that they can be incorporated in future releases.  (NB: The Makefiles
might appear unnecessarily complex; however, such complexity is
necessary as the Makefile(5)s are used on so many different
platforms).

To install XGKS on your platform, perform the following steps:

    1) Edit the file Makefile in the root directory.  Make appropriate
       changes to the "anticipated" macros near the top of the file.

       In addition, if your operating-system isn't one of AIX,
       DomainOS, HPUX, NeXTOS, SunOS, Ultrix, or UNICOS, then you will
       have to tell the C compiler what the names of certain
       FORTRAN-callable routines are.  Edit the file
       `lib/fortran/fortxgks.h', adding a section similar to that which
       begins `#ifdef OS_sunos' -- using the obvious OS_...  macro for
       your system and redefining the indicated function names to their
       FORTRAN-callable counterparts.

    2) Type "make" in the directory containing this file.  You can pass 
       command-line arguments when doing this.  For example:

           make all OS=domainos_10.3.2 DESTDIR='/usr/um/xgks' \
               LIBTYPE=nonsharable >& Make-apollo &

    3) If step 2 went ok, type "make install".

    4) If step 3 went ok, type "make clean".

The structure of the installation after step 3 will be:

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

where:

    DESTDIR     is whatever you made it in the root Makefile
                (suggestion: /usr/local);

    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 (under SunOS and the
                shared-library option, this will be "libxgks.s{a,o}.*"
                instead);

    libfxgks.a  is the Fortran interface to XGKS (under SunOS and the
                shared-library option, this will be "libfxgks.s{a,o}.*"
                instead);

    xgksfonts   is a directory which contains the XGKS fonts;

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

In addition, the source directory "progs" will contain the executable
program "hanoi", which is a Towers-of-Hanoi demonstration (kinda cute
actually) and the Fortran demonstration programs "star" and "gksdemo".
None of these programs will be installed.

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 PLEA
                               ------

If you have problems with XGKS, please send fixes to the UPC.  They'll
be incorporated so that the next poor grunt won't have such a tough
time.

Similarly, if you have a contribution to the evolution of XGKS, by all
means, send it to the UPC.

    And don't forget the mailing-list!


Regards,
Steve Emmerson          xgks-request@unidata.ucar.edu
