XGOPHER(1) X Version 11(Release 5) XGOPHER(1)
NAME
xgopher - gopher client for the X window system
SYNTAX
xgopher [-toolkitoption ...]
DESCRIPTION
xgopher is an X window system client interface to the gopher information
server. Xgopher provides access to tremendous amounts of information
which may be accessed from a local system or a remote information server.
The source of the information is generally transparent, with data
supplied from world-wide locations as easily as from a local on-campus
server.
The Gopher information system software is from the University of
Minnesota.
INTERACTIONS
The initial display will show the top level directory of gopher
information available. Selecting an item from this list will fetch the
contents of a file, subdirectory, or other information. The directory
display may be updated to show the new subdirectory.
A item is highlighted by pointing at a directory list item or a
previously marked directory (a bookmark) with the mouse and clicking the
left button. The display button marked "Fetch selection" is used to act
on the selection. An accelerator allows you to simply "click" a second
time on a highlighted item to activate the fetch.
By default, all interactions use only the left mouse button.
A directory is a collection of other files and directories. The
directory items are displayed in a list with an identifying symbol to the
left of each item. The symbol identifies the type of the item. The
symbols may be changed by the installer or by each user. The default
symbols are:
blank Text file
>> directory
<cso> a CSO name server (phone book)
<idx> a full text index search
<tel> a telnet session
<snd> a sound file (spoken, sound effect, or music)
<GIF> a GIF graphic file
10/89 Page 1
XGOPHER(1) X Version 11(Release 5) XGOPHER(1)
The file types are discussed below.
From all but the top level directory, the Go up a Level button
will return you to the parent of the currently displayed
directory. A keyboard accelerator allows you to press the "u"
key while the X pointer is anywhere on the main panel to
achieve the same action.
BOOKMARKS
If you are viewing a directory that you may wish to return to later, set
a bookmark there with the Set new bookmark button. This directory will
be displayed with your other bookmarks in the lower scrolling region
below the current directory list.
Later, no matter where you have browsed through the gopher directory
space, you may return to any bookmark by selecting it just as you would a
regular directory item. You are brought immediately to that marked
directory, in the same context that you were when you were last there.
This means, for example, that if you press Go up a Level, you are moved
to the parent of that now-current directory. The location of the
directory that you were in when you selected the bookmark is not saved
unless you explicitly marked it with a bookmark also.
Other buttons let you remove individual bookmarks or all of the
bookmarks.
The main gopher directory that you see when you first start Xgopher is
normally marked for you so you can easily and quickly return to the top
level.
TEXT DISPLAYS
When the item selected from the directory list is a text file, the
contents of the file are fetched and displayed as a pop-up text display
window. Help information is displayed in this way also.
The text display shows several command buttons and the text itself in a
vertically scrolling window. The buttons are: Done to release this text
file and window, Page down to position the text down one page, Page up to
position the text up one page, Print to send the contents of this display
to the printer, Save to save the contents of this display in a user-
specified file. The Print or Save buttons may not always be available.
They may be disallowed by the installer or system-wide resources file for
Xgopher.
Text displays use the text widget from the MIT-supplied Athena widget
set. The text is given a read-only attribute, but all of the position,
search, and selection capabilities of the widget are available. For the
user who knows how to use these functions, there is this additional
power. For example, entering control-S from the keyboard will bring up a
text search panel allowing you to scan for any string in the file. Other
Page 2 10/89
XGOPHER(1) X Version 11(Release 5) XGOPHER(1)
control sequences allow more flexible text positioning than is provided
by the scroll bar and paging buttons. All of these options are described
in the Athena widget set documentation of the text widget.
CSO NAME SERVER (Phone Book)
When the item selected is a CSO name server, a new window is displayed on
the X display. The name of the institution supporting the name server is
displayed at the top of the window. Below this are 4 areas. First are
the control buttons: Done closes the CSO name server window; Help
provides a text display with additional information; and Show Fields,
discussed below.
The next area is a single line text entry field where you type the name
of the person you are looking up. The name server will usually be able
to find someone by first name, last name, or both. Although, overly
general searches are prohibited. For example, trying to look up "smith"
is probably not a good idea in most of the United States. After entering
the name, type a carriage return (enter) or click the mouse on the Do
query button to submit the request. Additional buttons in the third area
allow you to clear the query or result text areas. The result is
displayed in the forth area, the bottom scrolling text region.
The Show Fields button displays a pop up menu. Select an item from this
menu to list the names and a brief description of the fields in the data
base being searched. Note that these fields may be different for every
institution! Listing default fields will show the things that are
returned for a normal query (usually name, address, phone number,
department, plus others). Indexed fields are those that you can use to
search for (usually name and perhaps office phone). Lookup fields are
those that can be used to narrow the search (for example, department).
Finally, Public fields are all the fields that can be viewed by everyone.
A query may include more than just a name, for example, legitimate
queries are:
john smith
This will return every John Smith in the selected data base.
If there are more than a handful, the name server will complain
that there are too many to give you. In this case, you may
want to try the next example.
smith department=biology
The department will help narrow the search to only those people
in the department of biology.
j* smith department=biology
A "*" matches any characters and will help if you are not sure
of the exact spelling of a name or only know initials.
10/89 Page 3
XGOPHER(1) X Version 11(Release 5) XGOPHER(1)
john smith department=biology return all
The return option may specify a field you are interested in or
the value "all" to get all public fields returned.
The CSO name server window may be left on the X display as long as you
like. Once displayed, it operates independent of the gopher directory
traversal. If you want to switch to search another institution's phone
directory you can select it from the appropriate directory list without
first closing a prior CSO name server window. The same window is re-used
for the currently selected institution.
INDEX SEARCH
An index search is a very powerful way of obtaining a list of documents
which contain (or do not contain) certain words. When you select an
index search item, a small pop-up panel asks you for a list of search
words. You can enter one or more words, plus the special reserved
boolean operators and, or, and not. For example, if you want information
on setting certain terminal parameters for Unix, you may enter:
terminal and setting or tset
which will find all documents in the search space which contain both the
words "terminal" and "setting", or the word "tset". The "or" is non-
exclusive so the document may contain all of the words. The input words
may be in upper- or lower-case, and will match words of either case.
After entering the words, press carriage return (enter) or click the
mouse on the "Do query" button and the search will be carried out.
The result of the index search looks very much like a normal gopher
directory of text files, but each file is one that matches your specified
criterion.
You will see a difference in the display of the text file, however.
Every word (or part of a word) that matches the index words will be
highlighted in the text display. This allows you to quickly locate the
parts of a document that are interesting to you.
TELNET SESSION
Telnet sessions are normally text-based information services, for example
access to University library holdings.
When you select an item which is identified as a telnet session, A new
xterm window (normal terminal emulator window) will be created and it
will be running a telnet session. It may take a few seconds for the
xterm window to show up. Some hosts that you connect to may require you
to enter a username (login name). If so, then Xgopher will pop up an
information window showing you the name to use once the telnet session is
started. Many telnet sessions require you to enter a terminal type as a
part of the startup interaction. Usually, you should choose vt100P, as
Page 4 10/89
XGOPHER(1) X Version 11(Release 5) XGOPHER(1)
the xterm commands are very similar to that of a DEC VT100 terminal.
Telnet sessions may be disallowed by the allowTelnet resource described
below. If telnet sessions are not allowed, an error message will be
displayed to that effect.
SOUNDS
If your X display is a workstation that supports sounds, then you can
play files containing spoken words, sound effects, or music through
Xgopher. Selecting a sound file will cause that file to be "played"
through your workstation's audio device. Only a single sound file can be
active at a time; you will be warned if you try to play a sound before a
previous one is through. Use the application resources hasSound and
soundCommand described below.
GIF FILES
If you have acces to a GIF display program on your worstation (xloadimage
is recomended) you can display GIF graphic files by selecting them
through Xgopher. Many GIf files can be displayed on the screen at the
same time.
RESOURCES
The application class is Xgopher. Most of the user-interface is
configured in the app-defaults file; if this file is missing a warning
message will be printed to standard error and the program will terminate.
All of the important defaults are established in the system app-defaults
file, normally installed as /usr/lib/X11/app-defaults/Xgopher.
The defaults mentioned below may have been changed by the installer for a
specific system. They may all be overridden in by individual
preferences. Application specific resources:
rootServer (class RootServer)
Specifies the initial gopher information server host name as an
internet address.
rootPort (class RootPort)
The port number of the top level gopher server to connect to.
The supplied default is 70.
helpFile (class HelpFile)
This is the absolute or relative path name of the file to be
displayed when the help command button is depressed. The
supplied default is /usr/lib/X11/xgopher/xgopher.help
mainTitle (class MainTitle)
The main title displayed above the listing of the top level
directory. The supplied default is "UIUC Gopher Information
Service".
10/89 Page 5
XGOPHER(1) X Version 11(Release 5) XGOPHER(1)
allowPrint (class AllowPrint)
If this boolean resource is true, text displayed in pop up
windows may be spooled to a printer by depressing a Print button.
If False, the button will not be displayed. The supplied default
is True.
allowSave (class AllowSave)
If this boolean resource is true, text displayed in pop up
windows may be saved to a user-specified file by depressing a
Save button. If False, the button will not be displayed. The
supplied default is True.
printCommand (class PrintCommand)
This is the print command used to spool a print request. Useful
examples of print commands are lpr or enscript. The gopher
internal file name containing the text is appended to the end of
the command supplied. As an option, if the 2 characters %s
appear in the print command string anywhere, they are replaced by
the file name. The %s may even appear more than once. If %s
appears, then the file name is not appended to the end. The
supplied default is: "# print" without the quotes. It is a
comment.
markRoot (class MarkRoot)
When true, a bookmark is automatically set at the top lever
(root) directory. If you do not want to have this bookmark set,
change the value of this resource to False. The supplied default
is True.
directoryTime (class DirectoryTime)
Directory entries for all active directories (current directory,
directories with bookmarks, and all of their ancestors) are saved
for this many seconds. After this time, their contents are
released and re-requested from the appropriate place when needed.
This caching of directory contents makes moving up the directory
tree and jumping to bookmarks quite fast. The very small
potential risk is that the contents of a directory in a gopher
server may be changed while the directory is stored. The
caching, freeing, and reloading of directories is transparent to
the user. The supplied default is 600. This is 10 minutes.
hasSound (class HasSound)
This flag indicated whether the X display being used has the
ability to play general sounds, such as spoken words, sound
effects, and music. For example, an X terminal will not normally
have this ability, but some workstations such as the Sun
SparcStation can play sounds. The supplied default is False.
soundCommand (class SoundCommand)
The command to use to get a sound file from the standard input
stream (stdin) to the audio device. On many workstations this
command may be called "play". Another command which may be
Page 6 10/89
XGOPHER(1) X Version 11(Release 5) XGOPHER(1)
useful is "cat > /dev/audio". The supplied command is started by
Xgopher as a separate process with sound data fed into its
standard input. This command is never executed if the hasSound
resource is False. The supplied default is "play" (without the
quotes).
hasGIF (class HasGIF)
This fag is used to indicate whether the X system being used has
the ability to display GIF images. The xloadimage utility is a
suggested utility for displaying GIF files.
GIFCommand (class GIFCommand)
This is the command used to display GIF images on your system.
Theis command must have two properties. a) It must be able to
take its input from sdin. b) It must be able to fork off when it
has its data to display. Xloadimage can do both these things with
its "-fork stdin" options.
allowTelnet (class AllowTelnet)
If this boolean resource is true, telnet sessions are allowed.
If False, they are inhibited with an error message displayed to
that effect. This resource should be False in secure
environments such as public access terminals, as it is easy to
start a shell from a telnet session. The supplied default is
True.
telnetCommand (class TelnetCommand)
The command Xgopher will use to start a telnet session. The host
and port number are added to the end of this command. The
resulting command is executed (via the system(3) function) to
provide a telnet session. In general, the telnet command should
be executed by an xterm as with the default (xterm -e telnet).
In some environments (such as OpenWindows), it may be useful to
specify the full path name of both the xterm and telnet commands.
For example, /usr/bin/X11/xterm -e /usr/ucb/telnet. This command
should be disabled for secure environments such as public access
terminals, as it is easy to start a shell from a telnet session.
the allowTelnet resource is False. The supplied default is
"xterm -e telnet" (without the quotes).
itemStart (class ItemStart)
Not normally changed by the user, this determines the amount of
memory dynamically allocated when xgopher starts execution to
hold gopher items (directory contents). The supplied default is
500.
itemIncrement (class ItemIncrement)
Not normally changed by the user, this determines the amount of
memory dynamically allocated each time xgopher needs additional
memory to hold gopher items (directory contents). The supplied
default is 50.
10/89 Page 7
XGOPHER(1) X Version 11(Release 5) XGOPHER(1)
dirStart (class DirStart)
Not normally changed by the user, this determines the amount of
memory dynamically allocated when xgopher starts execution to
hold gopher directories. The supplied default is 50.
dirIncrement (class DirIncrement)
Not normally changed by the user, this determines the amount of
memory dynamically allocated each time xgopher needs additional
memory to hold gopher directories. The supplied default is 10.
doubleClick (class DoubleClick)
Normally a gopher item or directory is selected by "clicking" on
it. Then the Fetch button is pressed to process the request. If
this resource is true, the fetch action may be invoked by simply
re-selecting the same item already selected. This is a double-
click on that item, although with no time limit between clicks.
The supplied default is True. It may be disabled for example, if
a touch sensitive screen replaces the mouse, to ensure more
reliable operation.
tempDirectory (class TempDirectory)
The directory for xgopher to create files that it will need for
display or other purposes, but will not exist beyond this xgopher
session. The supplied default is /tmp.
logFile (class LogFile)
If a file name is provided, all directory changes, remote host
connections, and errors are logged to this file. If nothing
else, it provides a trail of where you have been and allows some
simple diagnostics to determine what remote machines are not
accessible. If no file name is provided, no logging occurs. The
supplied default is no log file.
prefixFile (class PrefixFile)
This prefix is shown in the directory listing to the left of text
files. The supplied default is blank for text files.
prefixDir (class PrefixDir)
This prefix is shown in the directory listing to the left of
directory entries. The supplied default is 273 (an octal escape
sequence), which is a single character in the Latin-1 character
set which looks like >>.
prefixCSO (class PrefixCSO)
This prefix is shown in the directory listing to the left of
entries which are CSO name servers (phone books). The supplied
default is <cso>.
prefixTelnet (class PrefixTelnet)
This prefix is shown in the directory listing to the left of
entries which are telnet sessions. The supplied default is
<tel>.
Page 8 10/89
XGOPHER(1) X Version 11(Release 5) XGOPHER(1)
prefixIndex (class PrefixIndex)
This prefix is shown in the directory listing to the left of
entries which are full text index searches. The supplied default
is <idx>.
prefixSound (class PrefixSound)
This prefix is shown in the directory listing to the left of
entries which are sound files. The supplied default is <snd>.
prefixGIF (class PrefixGIF)
This prefix is used before GIF files in the directory listing.
The default is <GIF>.
prefixUnknown (class PrefixUnknown)
This prefix is shown in the directory listing to the left of
entries which are unknown file types. This prefix is not
normally displayed since Xgopher normally does not display file
types which it cannot further process. The supplied default is
<???>.
Widget specific resources:
The X Toolkit and Athena Widgets documentation covers the widget specific
resources. The most significant widget specific resources are mentioned
here.
font (class Font)
All text, label, and command button widgets have a font that can
be selected.
label (class Label)
All command button widgets and many labels text strings may be
changed, for example to another language.
FILES
/usr/local/lib/X11/app-defaults/Xgopher
/usr/local/lib/X11/xgopher.help
SEE ALSO
Installers should see the internal documentation for changes to the
configuration file before compiling and installing Xgopher.
BUGS
Some gopher file types are not yet supported. These are primarily binary
file types. They are intentionally omitted for now as the official
Minnesota Gopher Protocol document cautions that this file type and
protocol may change shortly. Duplicate servers are also not yet
supported.
10/89 Page 9
XGOPHER(1) X Version 11(Release 5) XGOPHER(1)
COPYRIGHT
Copyright 1992 by the Board of Trustees of the University of Illinois
This program with copyright notice intact may be freely distributed
without permission.
AUTHOR
Allan Tuchman, Computing and Communications Services Office, University
of Illinois at Urbana-Champaign, Urbana, Illinois. email to: a-
tuchman@uiuc.edu.
Page 10 10/89