RFC: an introduction to configuring sawfish

[Adam <ack94598 yahoo com>]

(I forgot to include the text version, how embarassing.)

I have written an introduction to configuring sawfish, called "How To
Make Sawfish Do Nothing".  The official version is and will be at
http://www.ideogram.com/do-nothing/sawfish.html
A text version is included below for your convenience.

The target audience is the novice Linux user who may not even know
programming but can still benefit from sawfish's configurability.

The environment assumed is Debian/Woody and GNOME 2.  (Instructions on
how to install GNOME 2 on Debian/Woody will be in another document).

Any and all comments are welcome, from technical corrections to style
suggestions to HTML critiques.

Eventually I hope to add more in the series such as "How To Make GNU
Emacs Do Nothing", "How To Make Gnome-Terminal Do Nothing", and "How To
Make The Gnome Desktop Do Nothing".

Please do link to the page if you find it worthy.

Some specific questions I have:

Right now the instructions use the Configurator to set three keybindings
that could equally well be set in ~/.sawfishrc.  Reasons to put it in
the .sawfishrc are (1) I seem to run into a bug losing the root menu
when I set too many keybindings at once, and (2) setting them in the
.sawfishrc makes the instructions shorter.  Which do you prefer?

How do I set a paragraph style not to leave blank lines between paragraphs?

I am now subscribed to all mailing-lists receiving this message so no
separate email to me is needed.

Thanks,
Adam

0.  Make sawfish your window-manager

The default window-manager for GNOME is metacity.  To replace it with
sawfish, enter at a terminal window:

$ killall metacity; sawfish &

(The $ represents the prompt, do not type it.)  To save this setup go
to the GNOME menubar at the top of the screen, click Actions, select
"Log Out", check "Save current setup" on the popup dialog, click OK,
and then log in again.

1.  Root menu and Configurator

Middle-click the root window (the background), select Customize/All
Settings.  It may take a few seconds to appear, don't click while
waiting.

Click Miscellaneous tab.  Click Error Handling tab.  Next to "Display
error message to: " click and select "screen".  This way if there is
an error at least you will know.

Click the right-pointing triangle at the top-right corner of the
dialog to get to more tabs.

Click Move/Resize tab.  Check the "Show current position of windows
while moving" checkbox.

Click Sound tab.  Check the "Play sound effects for window events."
checkbox.

Click left-pointing triangle to go back to previous tabs.

Click Bindings tab.  Next to "Context:" select "Root window".  There
should only be one entry and it is selected.  Click "Edit...".  In the
popup dialog click "Grab...".  Right-click.  The entry next to "Key:"
should change to "Button3-Click" (the mouse buttons are numbered 1-2-3
from left to right).  Click OK.  From now on you must right-click the
background to get the root menu.

Next to "Context:" select "Window".  Select the second line, "Move
window interactively".  Click "Edit...".  Click "Grab...".  Hold down
the Windows key and left-click.  The "Key:" entry should change to
"Super-Button1-Click".  Click OK.  From now on you must hold down the
Windows key, hold down the left mouse button and drag to move a
window.

Select the third line.  Click "Edit...".  Click "Grab...".  Hold down
the Windows key and middle-click.  Use the scrollbar on the right to
find "Iconify window" in the Command list.  Select it.  Click OK.
From now on you can hold down the Windows key and middle-click to hide
a window.  To find and show hidden windows click on the icon at the
top right of the GNOME menubar and click on the appropriate line of
the menu that pops up.

Select the fourth line, "Resize window interactively".  Click
"Edit...".  Click "Grab...".  Hold down the Windows key and
right-click.  Click OK.  From now on you must hold down the Windows
key, hold down the right mouse button and drag to resize a window.

You can read through the rest of the keybindings to see what functions
sawfish supports and how to access them.  The "W-[key]" keys mean hold
down the Alt key and press [key] (on my version of GNOME).

Click Close.

This procedure creates the file ~/.sawfish/custom.  You should not
edit it directly, however you can use the GUI to find the string
corresponding to a desired key combination (for use in ~/.sawfishrc,
step 2) by adding the keybinding using "Grab..." and reading the
generated ~/.sawfish/custom.

Sometimes on my version of sawfish (1.2) the root menu breaks, often
after editing a lot of keybindings at once.  If this happens you can
restart sawfish with:

$ sawfish-client -f restart

If the problem remains, delete ~/.sawfish/custom and add the
keybindings one at a time (Close the Configurator dialog after each
keybinding added).

2.  Make ~/.sawfishrc

Edit a file in your home directory called .sawfishrc, cut and paste
the following text not including the cut lines into it, and save the
file.

----8<----cut----8<----

;; -*- lisp -*-

(require 'sawmill-defaults)

(defun ak-left-fill-window ()
  (resize-window-to (input-focus) (/ (screen-width) 2) (screen-height))
  (move-window-to (input-focus) 0 0)
)

(defun ak-right-fill-window ()
  (resize-window-to (input-focus) (/ (screen-width) 2) (screen-height))
  (move-window-to (input-focus) (/ (screen-width) 2) 0)
)

(bind-keys global-keymap "Super-Left" ak-left-fill-window)
(bind-keys global-keymap "Super-Right" ak-right-fill-window)

----8<----cut----8<----

Sawfish uses the programming language Lisp for configuration and
extension.  Computer science undergraduates typically learn Lisp in a
few days.  For this task you will not need to do even that.

sawmill-defaults is the global sawfish defaults package.  You should
always have this require line at the top of your .sawfishrc.

defun defines a new Lisp function.  The two simple functions supplied
give you an idea of how it works.

The last two lines define keybindings.  "Super-Left" means hold down
the Windows key and press the left arrow.  You MUST capitalize exactly
as shown or it will break.

You can use the GUI to grab key combinations and read the resulting
~/.sawfish/custom file to find the string you want.  However some
functions listed in custom require a window argument which I will not
explain here.

3.  Create a theme

Enter:

$ mkdir -p ~/.sawfish/themes/min

"min" is the name of the theme we are creating.  You will change this
to something else if you create another theme.

Edit a file in ~/.sawfish/themes/min/ called theme.jl, cut and paste
the following text not including the cut lines into it, and save the
file.

----8<----cut----8<----

;; min/theme.jl

(defgroup min "Minimal Theme"
  :group appearance)

(add-frame-style 'min
		 (lambda (w type)
		   nil))

----8<----cut----8<----

This creates a frame-style with no frames.  Don't worry about the
details for now.

Bring up the root menu (right-click the background), select
Customize/Appearance.  Click the down-pointing triangle on the right.
Select "min".  Click close.

Congratulations, your sawfish now does nothing.  To make a window fill
the left or right half of the screen, click on it, then hold down the
Windows key and press the left or right arrow respectively.  To hide a
window, hold down the Windows key and middle-click on it.  To find and
show hidden windows click on the icon at the top right of the GNOME
menubar and click on the appropriate line of the popup menu.

4.  More themes

Here is a theme that does a bit more than nothing:

----8<----cut----8<----

;; line/theme.jl

(defgroup line "Line Theme"
  :group appearance)
	
(let*
    (frame `(((background . "white")
    	      (left-edge . 0)
	      (right-edge . 0)
	      (top-edge . -10)
	      (height . 1))))

  (add-frame-style 'line
		   (lambda (w type)
		     frame)))

----8<----cut----8<----

You can find sawfish supplied themes (in Debian) under
/usr/share/sawfish/[version]/themes/, where [version] on my system is
1.2.  A simple theme that actually does something is
/usr/share/sawfish/1.2/themes/simple/.  The .png files are images of
the icons that are used by the theme in its title bars.

You can find sawfish themes on the web at
http://themes.freshmeat.net/browse/927/?topic_id=927

A running sawfish defaults to rereading the current theme
automatically every few seconds.  You can turn this off in the
Configurator under Miscellaneous/Miscellaneous.  To force sawfish to
reload the theme immediately you can restart it.

When editing Lisp you must put the parentheses in the right places
(Lisp is said to stand for Lots of Insignificant Silly Parentheses).
An editor that shows you which close parenthesis matches which open
parenthesis and auto-indents is invaluable.  To know what's going on
you must know Lisp syntax and the arguments of the functions you are
using.  You can fake it by observing closely the format of an existing
theme, but tracking down a mistake can be time-consuming even for a
moderately experienced Lisp programmer.

5.  Lisp packages

You can find Lisp functions written by other users in packages at
http://sawfish.skylab.org/WikiSawfishLibrary

To use them, enter:

$ mkdir ~/.sawfish/lisp

Download the package and put it in ~/.sawfish/lisp.  It will be named
"[package].jl".

Add the following line to your ~/.sawfishrc:

(require '[package])

There may be other package-specific instructions.

Now you can use functions defined by [package] in your .sawfishrc (on
lines below the appropriate require line).

6.  Miscellaneous

The Sawfish Wiki http://sawfish.skylab.org/ may be useful.

The (old but useful) Lisp programming documentation for sawfish:
http://sawmill.sourceforge.net/prog-manual.html

To send me email you can use http://www.ideogram.com/sendemail.html

Adam