			ROX-Session
			A very simple session manager
			by Thomas Leonard

Brief
~~~~~
ROX-Session is a simple and easy to use session manager. It is part of the
ROX project, but can also be used on its own. ROX project home website:

	http://rox.sourceforge.net


Conditions
~~~~~~~~~~
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

Please report any bugs to me, <tal197@users.sourceforge.net>.


Instructions
~~~~~~~~~~~~
First, compile ROX-Session, like this (from a directory containing ROX-Session):

	$ ROX-Session/AppRun --compile

Then, run it, like this (or click on it in a filer window):

	$ ROX-Session/AppRun

ROX-Session will offer to manage your session in future. If you accept, it will
create suitable .xsession and .xinitrc files for you and ask you to log out.
When you log in again, ROX-Session will be running.

To decide what programs to run when you login, ROX-Session tries to run the
script <Choices>/ROX-Session/Login, where <Choices> is tried as:

	~/Choices
	/usr/local/share/Choices
	/usr/share/Choices

until it finds the script. You can override this by setting the CHOICESPATH
environment variable.

If no script is found then it runs the Login script inside the ROX-Session
application directory instead. This default script will try to find a
window manager for you and will then try to load ROX-Filer with a panel
and a pinboard setup. It will then run all the programs in:
	<Choices>/ROX-Session/AutoStart

When you want to logout, simply run ROX-Session a second time.


Customising
~~~~~~~~~~~
If you want certain programs to be started automatically when you log in:

- Menu click on ROX-Session in a filer window and choose 'Auto Start...'
  from the menu. If you have an old version of the filer then you can do this
  manually by creating the directory '~/Choices/ROX-Session/AutoStart'.

- Symlink each application that you want to start into this directory (drag
  applications in with Control and Shift held down).

- You can also create script files in here if you want.

If you need even more control, copy the Login file from inside ROX-Session's
application directory into Choices/ROX-Session and edit it there.


Environment
~~~~~~~~~~~

ROX-Session does two extra things before running the Login script:

- If you have a 'bin' directory inside your home directory then it adds that
  to the front of your PATH environment variable.
- If you have a 'lib' directory, then it adds that to LD_LIBRARY_PATH.

These are done in the .xsession script because they may be needed to run
ROX-Session itself, or the failsafe session if ROX-Session can't be found.


Errors
~~~~~~
Because an error in the session system can stop you from logging in,
ROX-Session has a number of safety measures:

- If the .xsession script can't find ROX-Session then it will look for a
  window manager on its own, and will also try to give you an xterm.
  It will also use xmessage to explain what has happened.

- If ROX-Session hasn't been compiled when you try to run it, it will
  write an explanation to standard error (which might get logged rather
  than displayed) and then run an xterm instead. Use the xterm to compile
  ROX-Session as explained above and then logout (type 'exit' in the
  xterm).

- If the Login script returns an error code then ROX-Session will run an
  xterm and display a suitable message. Run ROX-Session a second time to
  logout, as usual (quitting the xterm won't do it in this case).


Message display
~~~~~~~~~~~~~~~
Every process has an error stream that it can write to. All processes run by
the Login script have their standard error output connected to ROX-Session's
logging system.

These messages are displayed in a popup window for five seconds.

As well as using this for displaying error messages you can write other things
to it too, eg...

Put:
	echo Loading Netscape... >&2
in Netscape's AppRun file to get a message letting you know it's loading, etc.


What's a session manager?
~~~~~~~~~~~~~~~~~~~~~~~~~
	The following is some background information about
	session managers in general. This is provided for
	interest only...

Most people use a program such as xdm (X Display Manager) to control their
X server. xdm displays a graphical login prompt, logs you in, starts your
X session and then, afterwards, resets the X server and does it again.

How does xdm know when you've finished?

Well, after xdm has verified your user name and password it runs a system-wide
Xsession script as you. Try 'locate xdm/Xsession' to find the file on your
system. When this script exits xdm resets the X server and restarts the login
process.

What does the Xsession script do?

It depends on your system, but usually it looks for an executable file called
'.xsession' in your home directory (note - as the name starts with a dot it is
hidden by default). If it finds one it runs it, otherwise it does some default
stuff. Your '.xsession' script runs all the programs you want running on
startup (such as a window manager, filer, xterm, etc). It runs all of these
programs in the background except the last one, which it execs. Here's a
simple example script (remember to make it executable!):

	#!/bin/sh
	twm &
	xclock &
	exec xterm

This runs the (ugly!) twm window manager and xclock in the background. It
then replaces itself with the xterm process. You can now kill twm and xclock
as you please, but when xterm quits your session is over. In this example,
xterm is your session manager. Using xterm as a session manager isn't very
smart...

Many people use a window manager as a session manager. However, this has a
couple of drawbacks:
1) You can't change your window manager without restarting your X session.
2) Window managers are quite complex programs and can crash from time-to-time.
   If your session manager crashes then your X session is over!


What does ROX-Session do?

Very little. When you run it from your '.xsession' file it just loads, runs
the Login script (as described above) and waits.

When you want to log out you simply run it a second time. The new copy sees
that the first one is running and sends it a message. The first copy displays a
box confirming that you want to log out and, if you say yes, quits.  This
causes your X session to be terminated. Save your data before logging out!!


!!!WARNING!!!

	An incorrect .xsession file can prevent you from logging in!
	Make sure you test it first, or are able to get a textual login
	if needed (Ctrl-Alt-F1 on Linux, or try pressing F1 instead of
	Return at the xdm prompt for a 'failsafe' xsession script).

