		  Installation Notes
		       on the
		    Xgopher client


These notes describe Xgopher version 1.2, completed in November 1992.


+---------------------+
| 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.  Please
	     see the note below if you must use X11 Release 4.


+--------------+
| 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).  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, many 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.)

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

4. make
   (this will compile the 25 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, entries in this
   file 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!  Remove all of the application defaults from previous
	       versions of Xgopher before you attempt to run Xgopher 1.2.


   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, say ~/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 your X (or OpenWindows) libraries are installed,
   this will possibly be the file /usr/lib/X11/app-defaults/Xgopher.

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

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, the
   four files that need to be installed are:

   xgopher	this is the xgopher 1.2 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.
   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.

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 OW3-site.def in the Xgopher directory, which
	should rectify the problems.  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 above 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

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

		     mv 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.


(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.
	
	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 OW3-xmkmf.patch contains this patch.

	You should NOT be using the file 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 for non-OpenWindows
	systems.




+---------------+
| 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.


+--------------------------------+
| Alternate root server and port |
+--------------------------------+

An alternate root gopher server and port may be specified on the
command line.  For example

       xgopher gopher.micro.umn.edu
    or
       xgopher gopher.somewhere.else 95


+------------------------+
| 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.

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.



+--------------------+
| Image File Support |
+--------------------+

Xgopher can view image files (file of gopher type 'I').  Although
there are many image file formats in use, many people use a small
number of different types, with GIF format one of the most common.

When an image file is selected for processing, Xgopher retrieves the
file, then runs another program to display the image on an X display.
This second program is often "xloadimage".  The installer of Xgopher,
or any user, may change this to be any other program that is available.
xloadimage is a particularly nice program because it will display 
other file types besides GIF using heuristics to determine the type
of the file.

The string "Xgopher.imageCommand:  xloadimage" shows the default setting
of this resource.  Other interesting choices are:

    xloadimage                   (normal behavior, with messages output)
    xloadimage -quiet            (to suppress messages from xloadimage)
    xv                           (another nice gif viewer available)

xloadimage is not a part of the Xgopher distribution.  Many sites that
run X already have this program installed.  If you need xloadimage,
you may retrieve it by anonymous ftp from

    export.lcs.mit.edu: contrib/xloadimage.3.03.tar.Z

    (Note: the version number may change!)

this is the MIT archive of contributed X software.  At this writing,
xloadimage 3.03 was the current release.


+------------------------------------+
| 3270 Telnet Sessions for X Windows |
+------------------------------------+

X3270 is an alternative to tn3270 that many people prefer.  Whereas
tn3270 executes as an application within an xterm window and doesn't
understand X at all, X3270 is a true X application.

Xgopher 1.2 has been tested with each of these 3270 emulators.
tn3270 is available (vendor-supplied) on most Unix systems.  X3270
is publicly available software, but not supplied as a part of Xgopher.
X3270 may be acquired from the alt.sources archives.
One way to access these archives is by anonymous ftp to wuarchive.wustl.edu.
The files are in the directory /usenet/alt.sources/articles, and the file
names are 5798.Z, 5799.Z, and 5800.Z.  These three files together 
contain the program source.  I built the source on an IBM RS/6000 with
virtually no change (okay, one minor syntax fix).

The IBM 3278 terminal character set and behavior is closely emulated by
X3270.  Colors are used to distinguish normal, bold, and input fields.
Keyboard mapping is a problem with all 3270 emulator programs; you
will most likely be modifying one of the supplied keyboard maps in the
X application defaults file.

For Xgopher sessions you may use either tn3270 or X3270, whichever you
prefer or have access to on your system.  The default of last resort
is specified in the Xgopher source file conf.h.  This is overridden by
the system-installed application defaults file (usually
/usr/lib/X11/app-defaults/Xgopher).  Finally, users may use whichever
program they choose by modifying their own X resource values.
(And REALLY FINALLY, the telnet and tn3270 commands may be modified
during an Xgopher session by an options panel selection!)

The usual Xgopher command to start tn3270 is:
    xterm -e tn3270     or     aixterm -e tn3270 (for IBM AIX systems)

If you choose X3270 instead, the command is:
    x3270


+------+
| Icon |
+------+

A bitmap image is supplied in the directory ./bitmaps/xgopher.xbm
which is suitable for use as a window manager icon.  If xgopher.xbm
is installed into the directory <pathname>, you can use it as an
icon bitmap under mwm by including the lines in your mwm resource 
file:

    Mwm*useClientIcon:              True
    Mwm*Xgopher*iconImage:          <pathname>/xgopher.xbm

Similar resources apply to twm.  In your .twmrc file, use:

    # if the directory containing xgopher.xbm is not already
    # in your bitmapFilePath, add:
    IconDirectory                   "<pathname>/bitmaps"
    Icons
    {
        "Xgopher"       "xgopher.xbm"
    }

For both mwm and twm other resources may affect your icon appearance
also; these examples are only meant to help you get started.

You may want to install this file in the directory /usr/lib/X11/Xgopher/,
where the help file is already stored (in many X11 installations).

If you do put the icon bitmap somewhere, you may want to modify
the Xgopher man page to provide this information to the end users.


+-------------------------+
| Testing and Portability |
+-------------------------+

The Xgopher client has been compiled and tested by the author on:

 . IBM RS/6000 model 220 and other models running AIX 3.2.1
       client:   MIT's X11R5
       X server: IBM's AIXWindows 1.2.1
       NOTE:     (If you compile with IBM's X11R4 you may still need to
                  compile the Athena widget library yourself.  Compile all
		  the stuff under /usr/lpp/X11/Xamples, or just that library.)

 . Sun 4 (SparcStation) running SunOS 4.1.2
       client:   MIT's X11R5
       X server: Sun's OpenWindows 3 and remote display

       client:   Sun's OpenWindows 3
       X server: Sun's OpenWindows 3 and remote display

 . Sequent running Dynix 3.1.1 (a BSD-derived system)
       client:   MIT's X11R5 - libraries and client compiled with gcc
       X server: display to remote machine

 . Intel 486/33 running BSD/386 release 0.9.1 (gamma release) from BSD, Inc.
       client:   MIT's X11R5 - libraries and client compiled with cc (gcc)
       X server: X386

 . Convex running ConvexOS (Unix)
       client:   MIT's X11R5
       X server: display to remote machine

 . Silicon Graphics IRIS-4D running IRIX 4.0.1
       client:   Whatever SGI supplied (X11R4 variant)
       X server: display to remote machine

 . Various X servers have been tested including IBM X terminals.

E-mail response to previous versions of Xgopher indicate that it
has been successfully installed on many other systems including
HP, SGI, and Ardent.

The author would appreciate any assistance in fixing problems that
will allow Xgopher to be used on other platforms.


+----------+
| 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.2.  A couple of the more time consuming
requests will show up in a future release.

I especially want to thank Dawn Endico for finding the Sun
OpenWindows patches.  And a big thanks to Prentiss Riddle and
Richard A. Schafer of Rice University for commenting on an early
version of Xgopher 1.2.  Once again, John Franks of Northwestern
University has done a great job of testing - thanks, John!

I also borrowed some of the bookmark saving code from the
Unix curses client, written by Paul Lindner (I think) at UMN.

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