Basic X-Windows Setup for New Users
                               jimc, 960729

When you log on to a Mathnet or PIC X-terminal or workstation, you will get
a serviceable X configuration based on system default parameters.  Many
users will not need to change this configuration, but later in this handout
there are some suggestions to those who want to make simple changes.

To exit from X: the default session started with one xterm.  Exit from that
xterm and the whole session will terminate.  (See below for changing this
behavior.)

Basic documentation: Do "man X" for the introductory documentation for
the X Window System.  There you will find information on:
    Startup		(we use xdm)
    Displays		(set up automatically)
    Access Control	(set up automatically; we use XDM-AUTHORIZATION-1)
    Geometry		(usually the default is OK)
    Window Managers	(our default is twm; also see below)
    Fonts		(usually the default is OK)
    Font servers	(our X-servers know where they are)
    Colormaps		(usually the default is OK)
    Keyboard mappings	(usually the default is OK)
    Generic options
    Resource (option) database (most programs have reasonable defaults)
    Example command lines for many common X programs

For X security we use XDM-AUTHORIZATION-1.  Do not use the xhosts command
to bypass this security.  Please see the accompanying handouts "security"
and "rxterm" for suggestions in connecting to remote machines; contact our
bugs office if you still can't get a client running on a remote machine.

Execute "handout X/X11R6" to see a list of all the goodies available
in the Athena X11R6 distribution, plus some local additions.

If you are using a workstation, we prefer that you do as much work as
feasible on the workstation.  Your home directory is stored on a server
machine, and occasionally you will want to execute on the server, or on the
parallel processing machines.  To start an xterm (pseudo-terminal session)
on another machine (call it "remotehost"):  
	rxterm remotehost
The command is put in the background automatically.  Commonly used rxterms
can also be added to your window manager menus (see below).  If you execute
on your workstation you preserve server resources for people who don't have
workstations.

===== Window Manager

Your window manager provides many basic services such as moving windows
around, raising or locating buried windows, iconizing them, or closing them.
It also gives you pop-up menus of useful functions, if you click any of the
mouse buttons in the root (background) window.   Our default window manager
is "twm".  Do "man twm" for a description of its capabilities.  For twm,
mouse button 1 in the window's titlebar raises the window (so other windows
do not cover it); to move the window, hold down button 2 in the titlebar and
move the mouse. 

Keyboard data goes to whichever window the mouse cursor is in.  This
behavior can be changed to "click to focus" if you put a command in the
configuration file.  Microsoft Windows and Sun's Open Windows use the
"click to focus" model.  

Some other available window managers are tvtwm, fvwm, uwm and olwm.  See
their man pages to learn about their capabilities.  You can change your
window manager by editing your .xsession file (see below).

Window managers are controlled by configuration files, as described in
the man pages.  If you have no configuration file (.twmrc) for twm, we
give you the system default, /usr/X11R6/lib/X11/twm/system.twmrc
You can copy this file to .twmrc in your home directory, and add or
alter menus and features.  One feature often turned on is "RandomPlacement",
which lets windows automatically appear without the initial manual 
placement.

==== Your X Session

Your X session is produced when the system executes a program called
.xsession in your home directory.  If you have none, the system default is
/usr/X11R6/lib/X11/xdm/xsession.  To customize your session, copy that file
to .xsession, make sure it's executable, and edit it.  It's a Bourne shell
script (you could rewrite in csh or perl if desired.)  The system default
xsession file looks for a configuration file .twmrc (for the window manager
twm) and substitutes a system-wide default if not found; presumably you know
whether you have a configuration file for your window manager and what
system default you may want to specify (or copy and edit), so you can
simplify the .xsession script in this area.  

Your X session is over when .xsession finishes.  Persistent programs such as
xterm or xclock must be run in the background so following lines in
.xsession can be done -- except for the last line, which should be "exec"ed.
When that program exits, the session is over.

Our default xsession  finishes by "exec"ing xterm, so that your session is
over when that specific  xterm finishes.  Many people prefer to "exec" the
window manager, so when you give the window manager command to terminate, it
takes down the whole session with it.  Another alternative is to "exec"
xlogout; when you click on its button it sends "close" signals to all
clients and exits.

If you mess up your .xsession file, then when logging on, press F1 at the
end of your password instead of return.  You get a very simple setup with
no window manager, and you can edit .xsession to fix errors.  Also look for
the files .xsession-errors and .xsession-errors.old in your home directory. 
The latter file is where to look for evidence from a session that crashed.
In this configuration you can run (and safely kill) any window manager you
want, which is good for experimentation.  Run it in the background.

===== Program Options, Fonts, etc. etc.

Almost all aspects of operation of an X-windows program can be controlled
through the resource database.  You may provide a file .Xresources in your
home directory to contain your custom settings.  If you do not have this
file, we give you /usr/X11R6/lib/X11/mathnet.Xresources (or picnet).  You
may copy that file and change or add whatever settings you want.  Do "man X"
and hunt for the "Resources" section, to see the format of the file and some
of the generic specifications.  The program xrdb is used to transmit the
resource data to the X-server; it runs in your .xsession file (or the system
default).  See the man page for the special effects you can get.

===== Sun Open Windows (Openwin)

While the computing staff has no experience with Openwin and will be of
little help if you have Openwin-specific questions, we have tried to set up
our environment so it will work.  (Solaris machines only.)  To manually
experiment with Openwin, do:

	setenv OPENWINHOME /usr/openwin
	setenv MANPATH /usr/openwin/man:$MANPATH
	set path = (/usr/openwin/bin $path)
	olwm &

These would be done from a F1 login (see above) so you have no competing
window manager.  If you want to use Openwin permanently, edit your .xsession
file, remove the part that chooses the twmrc file (if you copied the system
default xsession) and add the equivalent Bourne shell commands:

	OPENWINHOME=/usr/openwin
	export OPENWINHOME
	MANPATH=/usr/openwin/man:$MANPATH
	export MANPATH
	PATH=/usr/openwin/bin:$PATH
	export PATH
	olwm &			# or exec olwm if at end of script

olwm uses a "click to focus" model where you have to click in a window to
send keyboard data to it, whereas Athena window managers use "focus follows
mouse" by default; whichever window the mouse cursor is sitting in gets the
keyboard data.  
	
If you are on a workstation and are going to use Display PostScript clients,
you should engage the Openwin X-server by, before login, clicking the
appropriate button on the server chooser.  (Wait a moment for the server to
start; it's kind of slow.)  This is only available on Solaris workstations. 

Many Openwin clients do not have "dismiss" buttons in dialog boxes, instead
relying on a "close" signal sent by the window manager.  olwm is said to
provide a standard function for this purpose.  It is very frustrating to
run such Openwin clients under a different window manager.  fvwm can send
"close" signals if you have set up its menus and/or titlebar decorations
appropriately.  See the man page (and good luck).  

It appears that all Athena X programs will work with the Openwin X-server
and olwm, while many Openwin programs will work with the Athena X-server
or X-terminals, and with other window managers, provided they do not use
the Openwin-specific features mentioned above.