Frequently Asked Questions
**************************

  1. I installed Sawmill but it's not working!  All I see when I start
     X is the default stipple background: no programs, no menus, no
     pager.

     This is exactly what it's supposed to do. Sawmill is a *window
     manager* and as such is not responsible for setting the background,
     starting programs or displaying a pager--these can all be done
     using separate applications (e.g. by using a desktop environment
     such as GNOME).

     The default menu binding is somewhat obscure; you must
     middle-click on the background to bring up the menus. (If you have
     a two-button mouse, try clicking both buttons simultaneously)

     If, after reading this, you still think that sawmill isn't working,
     please send mail describing the problem to the sawmill mailing list
     <sawmill@aarg.net>

  2. How do I add customizations?

     There are several files controlling this:

    `~/.sawmillrc'
          Hand written lisp code, loaded at startup. This is where
          almost all explicit customization should be done.

    `sawmill-defaults'
          This lisp library is only loaded if there's no `.sawmillrc'
          file.

    `~/.sawmill/custom'
          This stores customizations created by the configuration tool;
          it shouldn't really be edited manually.

          This file is loaded *after* `sawmill-defaults', but *before*
          `.sawmillrc'.

  3. I created `.sawmillrc', now things have changed?

     If a `~/.sawmillrc' file exists, it prevents `sawmill-defaults'
     from being loaded. But it's `sawmill-defaults' that loads some of
     the common window manager features, so add the line

          (require 'sawmill-defaults)

     to your `.sawmillrc' file if you want to start with all the
     standard features loaded.

  4. What's this `sawmill-client' program?

     This allows you to connect to a window manager process and evaluate
     arbitrary Lisp forms. Do `sawmill-client -?' for more details
     (`sawmill-client -' for a read-eval-print loop)

     By default you can only connect from the host running the wm
     (through a unix-domain socket). To enable the network based
     server, evaluate the lisp form `(server-net-init)'.

     Note however that this connects through the X server, meaning that
     anyone who can open windows on your display can also execute any
     Lisp code on the host running the window manager (and by extension,
     *execute any program*).

     So *don't* run the net server with X access control disabled
     (unless you're not connected to a network)

  5. How do I bind a key to execute a shell command?

     This isn't yet possible through the configuration tool. However
     these bindings can be defined in your `~/.sawmillrc' file. For
     example:

          (bind-keys global-keymap
            "C-M-ESC" '(system "xterm &"))

     binds the event `C-M-ESC' to the Lisp code to start an `xterm'
     subprocess

  6. How do I make clicking on a window raise the window?

     Bind the event `Button1-Click1' in the `window-keymap' to the
     `raise-window-and-pass-through-click' command

  7. How do I redefine the `Applications' menu?

     See the `Popup Menus' node in the Info manual (*note Popup
     Menus::.)

  8. How do I read the Info manual?

     Either execute the command `info sawmill', or enter the Info mode
     within Emacs (`C-h i') and type `g (sawmill) RET'.

     If you're using GNOME, then try executing `gnome-help-browser
     info:sawmill'.

  9. How do I create a new theme?

     See the `Window Frames' node of the Info manual (*note Window
     Frames::.)

     Basically though, create a directory `~/.sawmill/themes/FOO' where
     FOO is the name of your theme. Then copy any images into this
     directory and create a file `theme.jl' that will be loaded to
     initialise the theme

     The configuration tool will display the contents of a file called
     `README' in the directory (but make it 80-column text, and only a
     few lines)

     Recent versions of sawmill include a program `sawmill-themer' that
     allows simple themes to be created using a GTK+ interface. Ian
     McKellar has created `GimpMill':

          GimpMill is a GIMP plugin written in Python using James
          Henstrige's really cool Python GIMP bindings. It allows the
          construction of Sawmill themes within The GIMP - extending
          the GIMP interface to allow theme creation like the GAP
          extends it to allow animation creation.

     GimpMill is available from
     `http://www.yakk.net/projects.gimpmill.html'

 10. How do I port an Enlightenment theme to sawmill?

     There's no automatic translation available. Get the images used in
     the window border, then write a `theme.jl' file telling the window
     manager how they are used to form a window frame

     See the `themes/brushed-metal' directory for an example, and the
     Info manual for the documentation

 11. Are there any other themes available?

     Thanks to those nice people at themes.org, there's now
     `http://sawmill.themes.org/' for your theming pleasure

 12. Why don't GTK themes work with sawmill?

     There was a problem with older versions of the `gtk-engines'
     package preventing engine based themes working with several
     interpreted languages. Get the latest `gtk-engines' from
     `ftp://ftp.gnome.org/'

 13. Why don't you use GUILE?

     Mainly because I'm lazy; I had already written rep, and therefore
     understood it completely, whereas I have never used GUILE. Also,
     rep has some features not available in GUILE (byte-code
     compilation, autoloading, built-in event-loop, ...)

     But before you flame me: yes I do think scheme is a more elegant
     language

 14. Will you add feature X?

     Possibly. But only if it can be written in Lisp, or doesn't
     conflict with the overall design aims.

     These aims are to build a lightweight, generally applicable, set of
     core window management functions, then write *all* high-level
     functionality as Lisp extensions

 15. Is there a sawmill mailing list?

     Yes, thanks to Erik Arneson <erik@starseed.com> who manages it.

     To subscribe, send a message to <majordomo@aarg.net> with
     `subscribe sawmill' in the body.

     The list is archived at `http://inanna.starseed.com/sawmill'.

 16. Is there a sawmill IRC channel?

     From Ryan Pavlik <rpav@mythosource.org>:

          Sawmill has an irc channel too! It's on EFNet, and called (of
          all crazy things), #sawmill. So break out your irc clients,
          or hop on over if you're already addicted. Theme, lisp,
          general sawmill, and most other random discussion welcome.

          If you need an EFNet server, check www.efnet.net for a
          listing.

 17. Why does sawmill look weird/crash on Solaris?

     Sawmill works stably on Solaris, but you may need to do two things:

       1. Disable use of MIT-SHM by Imlib (run the program
          `imlib_config', the MIT-SHM option is on the `Rendering' page)

       2. Recompile GTK+ using the `--disable-xim' option to configure


