			ROX-Session
			Session manager for the ROX desktop
			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

ROX-Session sets up your desktop when you log in, and starts any
applications you ask it to. It allows you to set various settings, such as
the default font, cursor blinking and mouse behaviour (through a separate
application such as LookAndFeel).

It also allows you to choose a window manager, and change between window
managers without logging out.

You will need:

- ROX-Filer
- ROX-Lib
- D-BUS (with Python bindings; you need pyrex if building from source)

These in turn require:

- Python (2.2 or later)
- PyGTK (GTK 2 version)
- GTK 2


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 the mailing list:

	http://rox.sourceforge.net/phpwiki/index.php/MailingLists


The XSettings support code is taken from the XSettings sample implementation.
The conditions for this code are:

 Permission to use, copy, modify, distribute, and sell this software and its
 documentation for any purpose is hereby granted without fee, provided that
 the above copyright notice appear in all copies and that both that
 copyright notice and this permission notice appear in supporting
 documentation, and that the name of Red Hat not be used in advertising or
 publicity pertaining to distribution of the software without specific,
 written prior permission.  Red Hat makes no representations about the
 suitability of this software for any purpose.  It is provided "as is"
 without express or implied warranty.


Instructions
~~~~~~~~~~~~
Click on ROX-Session in a ROX-Filer window, or run the AppRun script
manually:

	$ ROX-Session/AppRun

ROX-Session will offer to manage your session in future. You can choose
whether to add ROX to the list of session managers on your login screen,
or to only set it up for the current user.

Once set up, it ask you to log out. When you log in again, ROX-Session will be
running. If you chose to install the single-user mode, you may need to choose
'Default' or 'Xsession' from your login screen's list of desktops. The code
for adding ROX-Session to the session manager has only currently been tested
with gdm2 and kdm.

When you want to logout, simply run ROX-Session a second time to display the
logout box. This box also contains a 'Session Settings' button which takes you
back to the options box, and the power management buttons (see below).


Listing ROX in gdm1
~~~~~~~~~~~~~~~~~~~
If you're using gdm 1 (the old GNOME display manager) then you can add ROX to
the list of sessions like this:

- Go to /etc/gdm/Sessions.

- Copy the .xsession that ROX-Session created in your home directory into this
  directory, as 'ROX'.

- Run gdmconfig.

- Go to Expert -> Login sessions and check that 'ROX' is listed.
  Add it if not.

ROX-Session is able to add itself to the gdm2 and kdm menus automatically.


Halt/Reboot/Sleep
~~~~~~~~~~~~~~~~~
As well as logging out (which normally returns you to the login screen), you
can get ROX-Session to perform other functions. These generally need to be
configured before use, although the defaults may work for you.

Clicking on one of the buttons simple executes the corresponding command
set in the Power section of the Options (Session Settings) box.

Halt
	This should be a command which turns off the computer. On many systems
	this can be simply 'halt', or 'shutdown -t now'. If normal users don't
	have permission to run halt you can use sudo or xsu:

	sudo halt
	xsu -c '/sbin/halt' -u root

	When using sudo, ensure that sudo allows the user to execute the
	command without entering a password, since ROX-Session does not
	provide a prompt.

Reboot
	A command to reboot the computer. This can be simple 'reboot' or
	'shutdown -t now -r'. sudo or xsu may need to be used, as above.

Suspend
	A command to put the computer into power saving mode. The default
	command 'xset dpms force off' simply turns the screen off.

	APM users could try 'apm -s' to suspend, while users of the newer
	ACPI could try 'echo 1 > /proc/acpi/sleep'.


Customising
~~~~~~~~~~~
When you log in, ROX-Session performs these steps:

1. Set up any custom environment settings.
2. Run a window manager.
3. Run ROX-Filer.
4. Run the Login script, which runs everything in the ROX-Session/AutoStart
   configuration directory by default.

These steps are explained in the following sections.


Environment
~~~~~~~~~~~
In the .xsession script, before ROX-Session is started, ~/bin is added to
the front of your PATH (if the ~/bin directory exists).

If $BROWSER isn't set, ROX-Session sets it to ROX-Session/browser. This little
script gets the configured browser and runs it. Most programs use $BROWSER when
they want to open a web-browser.

Then, ROX-Session loads and runs each Python module in
$XDG_CONFIG_DIRS/rox.sourceforge.net/ROX-Session/Environment.py.

Typically, you'll override this by creating a file called
~/.config/rox.sourceforge.net/ROX-Session/Environment.py. A sample file
called ROX-Session/Environment.py is provided, but is not used unless you
copy it to a configuration directory.

The first $XDG_CONFIG_DIRS/rox.sourceforge.net/ROX-Session/Styles file is
loaded to theme ROX-Session itself. If no configuration file is found,
the one inside ROX-Session is used. This can be used to customise the look
of ROX-Session.


Window manager
~~~~~~~~~~~~~~
The first time you log in, ROX-Session chooses a window manager for you.
If the window mananger crashes, or you quit it, ROX-Session will ask you to
choose another one. The chosen window manager the default for future sessions.
You can also change window manager by clicking on the one you want (if it knows
about ROX-Session).


Running ROX-Filer
~~~~~~~~~~~~~~~~~
ROX-Session runs the first
$XDG_CONFIG_DIRS/rox.sourceforge.net/ROX-Session/RunROX script. If no RunROX
script is in a configuration directory, it runs the copy inside itself. This
script runs ROX-Filer using 0launch, if available, or by running 'rox' if not.

The script should exec the filer. If the process returns, ROX-Session will
tell you that ROX-Filer crashed, and offer to run the RunROX script again.

The RunROX script also runs SetupPanel if pan_Default doesn't exist. This
script creates a default panel. You shouldn't need to edit this, since for a
single user it's easier to modify the panel directly, and for an admin or
distribution you can put a suitable default panel later in XDG_CONFIG_DIRS.


AutoStart
~~~~~~~~~
In parallel to running the RunROX script above, ROX-Session runs the first
$XDG_CONFIG_DIRS/rox.sourceforge.net/ROX-Session/Login script. If no Login
script is in a configuration directory, it runs the copy inside itself.

The default script will run all the programs in:

	<Choices>/ROX-Session/AutoStart

XXX: Should use XDG_CONFIG_DIRS, not <Choices>, like everything else!

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.

- 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 and edit it.

If the Login exits with a non-zero status, ROX-Session will warn you that it
failed.


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 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 directly on the screen for five seconds, as well
as being copied to ROX-Session's own standard error (where it often ends up in
the file ~/.xsession-errors).

Click the left mouse button on the messages to hide them (until the next
message is produced). Click the right mouse button to open a window showing
recent messages (new messages appear here instead of being shown directly on
the screen). You can also open this window by running ROX-Session again and
using 'Session Settings' to show the Options window. There is a 'Show message
log' button in the Messages section.

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.

If you don't want to see errors from a program, you can redirect them
elsewhere:

	prog 2>/dev/null

sends stream 2 ('standard error') to the big bit-bucket in the sky.
Complaining to the program's author is also a good move, as redirecting errors
could make you miss something important.


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 displays a box confirming that you want to
log out and, if you say yes, tells the first copy to quit. 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).

