		  Installation Notes
		       on the
		    Xgopher client


These notes describe Xgopher version 1.3, completed in May 1993.


+---------------------+
| System Requirements |
+---------------------+

Xgopher requires Release 4 or 5 of the X window system, version 11.  It uses
the Athena widget set, the X toolkit intrinsics, and the X library.
Xgopher contains many dependencies on the Unix operating system.

PLEASE NOTE: Xgopher was developed using X11R5 platforms.  It should work
	     with X11R4 also, but may require a small change.  For most
	     computers, this change will not be necessary.  If you
	     receive errors when compiling with X11R4, see the note below.


+---------------+
| Documentation |
+---------------+

This README file contains installation instructions.
The Documents subdirectory contains considerable additional information
on porting Xgopher to other Unix systems and configuring Xgopher.

+--------------+
| Installation |
+--------------+

The Xgopher program will likely be obtained as a Unix tar file.
After using tar to extract the contents of this file, perform
the following steps.

1. Modify the configuration file (conf.h).  If you do not modify this
   file at all, then Xgopher will connect to the University of Illinois
   gopher server by default.  The comments in the file tell you what
   is expected.  Possibly little change will be necessary, but at least
   consider changing the default top-level gopher server host name to
   a server near you.  These are just the compiled-in defaults, most
   can still be changed at run-time to accommodate individual preferences.

   +------------------------------------------------------------------------+
   | OPEN WINDOWS ALERT!                                                    |
   |     If you are COMPILING with Sun's OpenWindows (Version 3) libraries, |
   |     replace step 2 with the steps outlined below for OpenWindows.      |
   +------------------------------------------------------------------------+

2. xmkmf
   (this will turn the Imakefile into a Makefile, if X11R5
   is properly installed on your system.)
   +------------------------------------------------------------------------+
   | If you do not have xmkmf or imake, you can edit and use the file       |
   | Makefile.NoNo (named to discourage its use), as your Makefile.         |
   | If you use Makefile.NoNo, skip step 3.                                 |
   +------------------------------------------------------------------------+

3. make depend
   (this will build the include file dependency information
   into the Makefile.)

4. make
   (this will compile the 37 or so source files and link them
   with X11 to produce the executable file xgopher.)

5. Modify the application defaults file (Xgopher.ad).
   Little change may be necessary.  However, the entries in this
   file (e.g., for host name, port number, help file name, etc.)
   override those defaults compiled into xgopher through
   the configuration file (step 1).

6. Make the application defaults file (Xgopher.ad) known to X.
   There are several ways to do this for testing without installing
   the file in a system directory.  Choose one of the following -
   whichever is most comfortable for you.


   IMPORTANT!  Although you can test Xgopher with old (pre Xgopher 1.3)
               resource files on your system, you may see some warning
               messages.  These are informatory only.  For final installation,
               remove all of the application defaults from previous
	       versions of Xgopher before you install Xgopher 1.3.


   a. xrdb -merge Xgopher.ad

   b. setenv XENVIRONMENT `pwd`/Xgopher.ad       
      (`pwd` will return the current directory, which should be the
      Xgopher source directory.)

   c. if you have your own app-defaults directory, for example, ~/app-defaults:
	 setenv XAPPLRESDIR ~/app-defaults/
	 cp Xgopher.ad ~/app-defaults/Xgopher
      Note the name change.

   COLOR OPTION: If you are using a color display, it is strongly
		 recommended that you also include the Xgopher
		 color resources.  if you used method (a) above, then
		 also use:
		     xrdb -merge Xgopher-color.ad -nocpp

		 Otherwise, consider using the file Xgopher-complete.ad
		 instead of Xgopher.ad.  The former file has all of the
		 color resources included in it.

		 This is sufficient for now, and to let you test.  For
		 permanent installation, see the later section of this
		 document which discusses color resources.

   For final installation, this file will be stored in the X
   application defaults directory, with the file named Xgopher.
   Depending on where your X (or OpenWindows) libraries are installed,
   this will be the file such as /usr/lib/X11/app-defaults/Xgopher.

7. to test:
      xgopher
   (this executes the xgopher program!)

       (If you see messages like this:
           Warning: Cannot convert string "indexLabel" to type Widget
        It means that you have old Xgopher resources left somewhere in
        your resource files or server.  The message is probably harmless,
        but you should get rid of the old files before installing Xgopher 1.3
        permanantly.)

   +------------------------------------------------------------------------+
   | SUN USER ALERT!                                                        |
   |     Whether you are using X11R5 or Sun's OpenWindows (version 3),      |
   |     you may receive an error saying that Xgopher cannot connect to     |
   |     the gopher server.  If this happens to you, see the additional     |
   |     help in the file Documents/Porting.                                |
   +------------------------------------------------------------------------+

8. to install Xgopher on your system:
   With root privileges:
       make install
       make install.man
   this should install the 4 files needed by Xgopher.

   If you wish to install all of the files manually instead of using the
   "make install" sequence, the four files that need to be installed are:

   xgopher	this is the xgopher 1.3 program.  It may be installed
		as the file xgopher in /usr/local/bin, for example.
   xgopher.help the help text file.  It may be installed with this
		name in /usr/local/lib, for example.  Note that its
		path name was compiled in to Xgopher through the Imakefile.
		The resource file (Xgopher.ad) can override this.
   Xgopher.ad	the X application defaults file.  It may be installed
		as Xgopher, in /usr/lib/X11/app-defaults, for example.
   xgopher.man	the user documentation (man page).  It may be installed
		as xgopher.l (letter l), in /usr/man/manl, for example.


+-------------+
| OpenWindows |
+-------------+

Many people compile with MIT's X11 library then use Sun's OpenWindows
server.  This is never a problem.  

   +------------------------------------------------------------------------+
   | If you are compiling Xgopher with the MIT X11 software, you should     |
   | not be using this part of the installation instructions.  Return       |
   | immediately to step 2 above.                                           |
   +------------------------------------------------------------------------+

Some problems arise when compiling with the OpenWindows 3 libraries.
OpenWindows 2 cannot be used as it is an implementation of X11R3.

I will try to help people who want to compile with OW3, but I do not
have good access to such a system, nor am I proficient with its use.
With this caveat, I will say that I have invested considerable effort 
to understand the problems people have been reporting with OW3 and
in modifying the Imakefile to avoid these problems.

(Solaris 2.1)
    My comments here apply to SunOS 4.x, not necessarily to Solaris.
    I have had somewhat better luck in my quick visit with Solaris 2.1
    using the "standard" procedures - with one exception.  For Solaris 2.1,
    in the Imakefile, I needed to chande the line

		     EXTRA_LIBRARIES  =  -lm
    to
		     EXTRA_LIBRARIES  =  -lm -lsocket -lnsl
    (This line is commented out in the Makefile; you may need to include it
    depending on your networking software configuration on your Sun.)
    With this change you can probably continue with the installation
    procedure as documented above.

    You also may need to uncomment out the line beginning "LOCAL_DEFINES"
    which defines the symbols SYSV and SVR4 in case your imake templates
    do not already define these symbols.


Sun supplies a version of xmkmf and imake.  However, these point
to incorrect directories for the build and installation of software.
Also, their Xmu library is broken for dynamic loading.

   +------------------------------------------------------------------------+
   | There are two solutions to this problem.  Choose one of the following: |
   |                                                                        |
   |  (1) Use the work-arounds I suggest below.                             |
   |  (2) Fix everything the right way, patching Sun's software             |
   |                                                                        |
   | Your desire and ability to modify system files may determine your      |
   | choice.                                                                |
   +------------------------------------------------------------------------+

Use either method (1) or method (2) below - not both.

(1) To use the work-around:

	I have provided the file Documents/OW3-site.def in the Xgopher
	directory, which should correct enough of the problems with Sun's
	imake template files to allow you to build Xgopher.  Feel free to
	modify this file if you need to.  You will rename it to site.def
	in step 2c below.


	To compile with OW3, replace step 2 of the installation instructions
	with the following:

	  2a. Make sure that your environment variable OPENWINHOME is set
	      to the proper directory - the top level of your OW3 tree.

	  2b. Edit the Imakefile to uncomment the 3 lines which are
	      well-marked in the Imakefile:

		     MKDIRHIER        = BourneShell $(BINDIR)/mkdirhier
		     EXTRA_LIBRARIES  = -lresolv -lm
		     XMULIB           = -lm -Bstatic -lXmu -Bdynamic

	      (Or, Stew Ellis suggests that you can avoid the use of
	      -Bstatic by using the parameter "-assert nodefinitions".
	      Use the following line instead of the XMULIB defined above:
		     XMULIB           = -assert nodefinitions -lXmu
	      I have not tested this.)

	  2c. Rename or copy the file Documents/OW3-site.def to be site.def.
	      For example:

		     cp Documents/OW3-site.def site.def

	      This file is read by the imake command to build your Makefile.

	  2d. Instead of xmkmf, use the following command:

		     imake -DUseInstalled -I. $OPENWINHOME/lib/config
	      
	      Be sure that this is the imake from $OPENWINHOME/bin/imake
	      and not an X11 directory.  Use "which imake" or check your
	      path if you are not positive.
		

	The -Bstatic load option (in step 2b) is necessary to avoid loader
	warnings of unresolved externals for:

	    _get_vwShellWidgetClass
	    _get_applicationShellWidgetClass

	I have tried loading without -Bstatic.  I get errors telling me that
	these are missing, but the resulting xgopher binary still seems to
	work.  If you are willing to risk a possible future error, you may
	omit the -Bstatic option.  (Larry Butler butler@rex.cs.tulane.edu
	reports that the binarys work fine with either the OpenWindows X
	server or MIT's X11R4 server and twm, but that they kill openlook.
	I think he is refering to the OpenLook Window Manager.)


(2) To fix everything the right way, patching Sun's software:

	* NOTE *  I have not tested these patches and cannot take
		  responsibility for their correct behavior.
		  They have been kindly supplied by a Sun user
		  (Dawn Endico).
	
	Apply the following patches to Sun's libXmu and libXt:

		libXmu:	100573-03.tar.Z
		libXt:	100512-02.tar.Z

	They are available from: iskut.ucs.ubc.ca:/pub/ubc/sun-patches
	                     or: dragon.cso.uiuc.edu:/SUN-FIXES

	
	Apply the supplied patch to the OpenWindows xmkmf software.
	The file Documents/OW3-xmkmf.patch contains this patch.

	You should NOT be using the file Documents/OW3-site.def.  That file
	is only for working around Sun's xmkmf as a temporary fix.

	Then you can use xmkmf as described in step 2 of the installation
	instructions for non-OpenWindows systems.

	You may still need to load with -lm (the math library).  If
	you get unresolved external references to routines such as
	sin, cos, pow, floor, then insert the line:

	    EXTRA_LIBRARIES  =  -lm
	
	near the start of the Imakefile




+---------------+
| X11 Release 4 |
+---------------+

There has been considerable interest in compiling Xgopher under X11R4.
I have tried to provide that capability to the extent possible.
If you use X11R4, certain tests in the file compatR4.h should detect
this and automatically define the symbol XGOPHER_X11R4.

  Unlike previous versions of Xgopher, you should not need to take
  special action to compile with MIT's X11R4 libraries.  However, some
  vendor libraries may fail these tests.

If these tests fail, then you should define this symbol
yourself in the file conf.h by removing the comments from the define
statement (or use -DXGOPHER_X11R4 as a compiler option).  This will cause
the compiler to omit some minor R5 specific things without loss of
functionality.

I cannot promise to maintain this backwards compatibility forever.
I do not have good access to an X11R4 library for testing so
I must depend on feedback from others to detect release-dependencies.



+---------------+
| Customization |
+---------------+

The installer may wish to customize some of the Xgopher features
such as the image display, telnet, or other commands.  These are 
all described in the file Documents/Install-Customization.  This
document also mentions some alternative "plug-compatible" widgets
that could be used to modify the appearance of Xgopher.

There is another writeup, Documents/Customization, which describes
changes that a user may use in configuring Xgopher.  This latter
file should be available to knowledgable end-users.


+------------------------+
| Color Resource Support |
+------------------------+

The supplied defaults file (Xgopher.ad) will work fine on all color
displays and black & white displays.  It has no color definitions.
Depending on your users of Xgopher, you may want to install certain
versions of these app-defaults files.

This section is for the installer of Xgopher.  A separate document,
"Customization", provides information for other users of Xgopher.

If EVERY Xgopher user has a black and white display screen, then just
use the file Xgopher.ad.  (You needn't read further in this section.)

If EVERY Xgopher user has a color display screen, then you can use
the file Xgopher-complete.ad, which has colors defined in addition
to all the rest of the resources.  Rename it to be Xgopher.ad and
install it as Xgopher in the system defaults directory.

In many cases, both black and white screens and color screens are
present at an installation.  If so, it is poor practice to install
the color resources file only - monochrome users may get poor results
such as black characters on a black background.

One suggestion is to install the standard Xgopher.ad file, then
let each color user keep their own resources file with only color
preferences.  This file would be used in their personal .Xdefaults
or xrdb data files.  The file Xgopher-color.ad can be copied to
get a suggested set of colors.

For sites running X11R4 and using both color and non-color displays,
the above is the only solution.  It will also work with X11R5.

There is another possibility for sites with X11R5.  I encourage you to
look at the "customization" option that will allow you to install both
color and B&W resource files, and conditionally load the color one
automatically depending on the screen you are using.

For X11R5, the Imakefile will handle the installation of both the
monochrome and color resources files:

    Xgopher-color.ad  as  Xgopher-color
    Xgopher.ad        as  Xgopher

Then, each and every user can add the following to the file they
input to xrdb:

    #ifdef COLOR
    *customization:   -color
    #endif

The #ifdef will determine whether you are on a color screen, and if
so, use the color resource file.  The color resource file "includes"
the standard Xgopher resource file.



+----------+
| Problems |
+----------+

Please report and problems, suggestions, or portability problems to
the author of xgopher.  e-mail contact is preferred:

	Allan Tuchman
	Computing and Communications Services Office (CCSO)
	University of Illinois at Urbana-Champaign
	1304 W. Springfield Ave.
	Urbana, Illinois   61801
	USA

	(217) 244-0048
	a-tuchman@uiuc.edu



+--------------------+
| Other Contributors |
+--------------------+

Thanks to all people who took the time to send me their comments,
suggestions, and problems in previous versions of Xgopher.
All bug reports and most of the suggestions have been
incorporated into Xgopher 1.3.

Of course, the present author assumes responsibility for any
problems introduced.
