			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.

The first time you log in, ROX-Session asks you to choose a window manager
(except for Zero Install users; you get OroboROX by default automatically).
Select one from the list provided and click on 'Start window manager'.
If the window mananger crashes, or you quit it, ROX-Session will ask you to
choose again. If your preferred window manager isn't on the list then you
can enter its name manually. Click on 'OK' to make the chosen window
manager the default for future sessions.

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).


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
~~~~~~~~~~~
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. The default script will run all the programs in:

	<Choices>/ROX-Session/AutoStart

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 into Choices/ROX-Session and edit it there.

There is also a RunROX script which works in a similar way, but runs
ROX-Filer with a panel and a pinboard set up. Unlike Login, this script should
not exit. If it does, ROX-Session will offer to run it again. You can move
this into Choices/ROX-Session to customise it, as with Login.

The SetupPanel script is used to create a default panel if none is set up. 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 in /usr/[local]/share/Choices/ROX-Filer/pan_Default.


Listing ROX in the login box
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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.

kdm users can use kcontrol to set things up in a similar way (but put the
'ROX' script in /usr/local/bin or similar).

ROX-Session is able to add itself to the gdm2 menu automatically.


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

There are also a couple of lines in ROX-Session/AppRun to turn on anti-aliased
font support. You may need to edit these lines to turn support off (if
it doesn't work on your system, or you want the nasty old font system back).

Note: In GTK+-2.2, the new font system became the default. In GTK-2.4 it
is likely that the old font system will no longer be available. Therefore,
it would be better to fix any problems with the new font system now rather
than just use the old one.


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
  try to compile itself first.

- 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).

