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 , 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: /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 "/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.