[sawfish] Doc improvements.

From: Christopher Bratusek <chrisb src gnome org>
To: svn-commits-list gnome org
Cc:
Subject: [sawfish] Doc improvements.
Date: Sat, 5 Dec 2009 10:34:02 +0000 (UTC)
commit 94c737ca3085882fa71b4301c6180997ba37a95e
Author: Teika kazura <teika lavabit com>
Date:   Sat Dec 5 14:22:58 2009 +0900

    Doc improvements.

 README.IMPORTANT            |   14 +-
 lisp/sawfish/wm/viewport.jl |   38 +-
 man/news.texi               |  139 ++++--
 man/sawfish.texi            | 1142 ++++++++++++++++++++++---------------------
 man/user-doc.texi           |    2 +
 5 files changed, 708 insertions(+), 627 deletions(-)
---
diff --git a/README.IMPORTANT b/README.IMPORTANT
index 39217d3..f06cdff 100644
--- a/README.IMPORTANT
+++ b/README.IMPORTANT
@@ -1,16 +1,22 @@
+For full changes, read the news section in info. This file
+lists only important changes.
+
 In Sawfish 1.6.0 there are the following major changes:
 
 9 mouse button support
 **********************
 
-Support for 9 mouse buttons is now optional. X.Org/XFree86
-headers only define up to 5 buttons, so we use a fully
-working bug-free but somewhat hackish workaround for getting
-buttons 6 - 9. Support for them is enabled by default, if
+Support for 6 - 9 mouse buttons is now optional. X.Org/XFree86 headers
+only define up to 5 buttons, and we use a working but somewhat hackish
+workaround for getting buttons 6 - 9 which is suspected to cause some
+problems with modifiers. Support for them is enabled by default. If
 you want to disable it, add the following flag to configure:
 
 --without-nine-mousebuttons
 
+If you drop it, then you can't use mouse button 8 to, for example,
+drag windows.
+
 sawfish-ui is now sawfish-config
 ********************************
 
diff --git a/lisp/sawfish/wm/viewport.jl b/lisp/sawfish/wm/viewport.jl
index e051e7e..8e678a5 100644
--- a/lisp/sawfish/wm/viewport.jl
+++ b/lisp/sawfish/wm/viewport.jl
@@ -98,17 +98,14 @@ the change is instantaneous."
 
 ;;; raw viewport handling
 
+  ;; The unit is pixel, NOT (col, row).
+  ;; Position (0, 0) means the top-left of the workspace.
   (defvar viewport-x-offset 0)
   (defvar viewport-y-offset 0)
 
-  (define (viewport-honor-workspace-edges)
-    "Whether or not to prevent the display from moving past the
-current viewport boundaries.  Returns true if `viewport-boundary-mode'
-is not set to 'dynamic."
-    (not (eq viewport-boundary-mode 'dynamic)))
-
   (define (warp-viewport x y)
-    "Change view by incrementing the coordinates of the x,y position."
+    "Move viewport to (x, y). The unit is pixel, not (col, row).
+Position (0, 0) is the top-left of the workspace."
     (define (move-window w)
       (unless (window-get w 'sticky-viewport)
 	(let ((pos (window-position w)))
@@ -142,9 +139,17 @@ is not set to 'dynamic."
       (setq viewport-x-offset x)
       (setq viewport-y-offset y)))
 
+  (define (viewport-honor-workspace-edges)
+    "Whether or not to prevent the display from moving past the
+current viewport boundaries.  Returns true if `viewport-boundary-mode'
+is not set to 'dynamic."
+    (not (eq viewport-boundary-mode 'dynamic)))
+
   (define (set-viewport x y)
-    "Scroll viewport view by incrementing the coordinates of the x,y position.
-The scrolling makes a number of increments equal to `scroll-viewport-steps'."
+    "Move viewport to (x, y). The unit is pixel, not (col, row).
+Position (0, 0) is the top-left of the workspace.
+
+Scroll is done whose steps are `scroll-viewport-steps'."
     (unless (= scroll-viewport-steps 1) ; fast skip if scroll is unwanted
       (let* ((xstep (quotient (- x viewport-x-offset) scroll-viewport-steps))
              (ystep (quotient (- y viewport-y-offset) scroll-viewport-steps))
@@ -240,7 +245,8 @@ well as any windows in the current workspace."
 
   (define (viewport-leave-workspace-handler ws)
     "On leaving a workspace, store information about the viewport
-configuration so that it can be restored properly later."
+configuration so that it can be restored properly later.
+`WS' is the workspace to leave."
     (let ((vp-data (list viewport-y-offset
                          viewport-x-offset
                          viewport-dimensions))
@@ -283,8 +289,7 @@ viewport is within `viewport-dimensions'."
   (add-hook 'enter-workspace-hook
             viewport-enter-workspace-handler)
 
-
-;;; screen sized viewport handling
+  ;; screen sized viewport handling
 
   (define (screen-viewport)
     "Gives the row and column of the current viewport."
@@ -322,10 +327,9 @@ viewport is within `viewport-dimensions'."
 			     (quotient (cdr pos) (screen-height))))))
 
   (define (window-outside-workspace-p window)
-    "True if `window' is outside the virtual workspace.  Note that
-this does not check which workspace the windows is in; the window is
-outside the virtual workspace if it's position is not within any
-viewport."
+    "True if `window' is outside the workspace.  Note that this does
+not check which workspace the windows is in; the window is outside the
+workspace if it's position is not within any viewport."
     (let ((pos (window-position window))
 	  (dims (window-frame-dimensions window))
 	  (left (- viewport-x-offset))
@@ -471,7 +475,7 @@ which is specified as (column . row). The return value is the cons
 cell (x . y). The values are in pixel, and are negative if it lies at
 left or above the current viewport.
 
-`VP' can be non existent one. If `VP' is nil, it is
+`VP' can be outside of the workspace. If `VP' is nil, it is
 understood as the current viewport, i.e., (0 . 0) will be returned."
     (if (consp vp)
         (let* ((cur-vp (screen-viewport)))
diff --git a/man/news.texi b/man/news.texi
index 4169022..0308947 100644
--- a/man/news.texi
+++ b/man/news.texi
@@ -13,20 +13,31 @@ they occurred between. For more detailed information see the
 
 @item The 1.6.0 release has new features and bugfixes
 
- item New/Updated requirements:
+ item Build and installation changes
 @itemize @minus
 
+ item New/Updated requirements:
+ itemize +
 @item librep 0.90.0 -> 0.90.2
-
 @item rep-gtk 0.18.4 -> 0.90.0
 @end itemize
- item Removed requirements:
- itemize @minus
 
- item LibAudiofile
+ item Removed requirements: LibAudiofile and ESounD
+ item Mouse buttons 6 - 9 support is now optional
+
+Support for 6 - 9 mouse buttons is now optional. X.Org/XFree86 headers
+only define up to 5 buttons, and we use a working but somewhat hackish
+workaround for getting buttons 6 - 9 which is suspected to cause some
+problems with modifiers. Support for them is enabled by default. If
+you want to disable it, add the following flag to configure:
+
+ code{--without-nine-mousebuttons}
+ c Well, ``code'' gives ugly (back)quote, but otherwise the first hyphen is dropped.
 
- item ESounD
+If you drop it, then you can't use mouse button 8 to, for example,
+drag windows.
 @end itemize
+
 @item Incompatible user visible changes:
 @itemize @minus
 
@@ -55,12 +66,12 @@ only if the @file{~/.sawfishrc} lacks. Now, it is always read, so you
 don't have to @code{require} it. It sets up GNOME and KDE support if
 they run, and does @code{(require 'sawfish.wm.ext.error-handler)}.
 
-Since v1.5.0 @code{~/.sawmillrc} is no longer a valid resoucefile, from
-this version on, Sawfish will rename @code{~/.sawmillrc} to
+Since Sawfish 1.5 @code{~/.sawmillrc} is no longer a valid resoucefil.
+From this version on, Sawfish will rename @code{~/.sawmillrc} to
 @code{~/.sawfishrc}, if the former does exist on your system, but the
 latter doesn't.
 
- item In SawfishConfig the "Matched Windows" group has been renamed to "Windows Rules"
+ item In configurator, the "Matched Windows" group has been renamed to "Window Rules"
 
 @item Sound support has changed. [Christopher Bratusek]
 
@@ -111,29 +122,22 @@ renamed to @code{browser-program}.
 @item Prevents crashes for quick window destructions, especially under high load
 
 There have been crashes if a window is destroyed soon after its creation.
-It happens in @code{add_window} function, and it might be due to a
-window being destroyed, garbage collected and then accessed.
+It happens in @code{add_window} function, and the cause is guessed to be
+garbage collection following window destruction before the object access.
 
 Now most parts of @code{add_window} are protected from garbage
 collection with @code{rep_PUSHGC} / @code{rep_POPGC}. It also prevents
 @code{add_window_hook} from being called with uninitialised argument.
 [Timo Korvola, Janek Kozicki]
 
- item error_handler() Vs Xinerama and X_ConfigureWindow
-
-When a window sends request_code 12 (X_ConfigureWindow), don't auto-asumme
-it to be unmapped, as this may let several windows disappear at once randomly
-not just the one that sent the request, this bug appears mostly in Xinerama
-setups, but is not limited to it. The change is not 100% failsafe at the moment
-but it reduces the failure-rate by 95% which is the reason why it is integrated
-while not beeing final. [Janek Kozicki]
+ item Random window disapperance prevention
 
- item Basic Xinerama support for Grow/Pack
+There're reports of sudden, random window disapperance, under Xinerama
+and some other drivers. It is partly prevented, but not completely.
 
-Make grow/pack Xinerama aware. Old implementations supported only 1
-Head, current does 3, but needs to be extended to support atleast 4.
-Also shrink-yank needs to be improved, but since Xinerama was previously
-not supported this patch was still applied [Nolan Leake]
+Now in error_handler() in src/display.c, when a window sends request_code
+12 (X_ConfigureWindow), don't auto-assume it to be unmapped. [Janek
+Kozicki]
 
 @item Build and Installation:
 @itemize +
@@ -149,7 +153,7 @@ not supported this patch was still applied [Nolan Leake]
 
 @item Expand REP_ENVIRON in scripts/Makefile.in [Luis Rodrigo Gallardo Cruz]
 
- item Add @code{--tag=CC} to libtool where necessary. It unbrakes compilation on some arches [Gentoo]
+ item Add @code{--tag=CC} to libtool where necessary. It unbrakes compilation on some arches [Gentoo Linux] 
 @end itemize
 @item In configurator,
 
@@ -200,10 +204,10 @@ Internally, a new function @code{remove-frame-part-value} which allows to change
 
 @item Sawfish does now support theme-tarballs compressed with XZ (aka LZMA2) and LZMA [Christopher Bratusek]
 
- item New, sawfish-mmc based @code{rename-window} function [Christopher Bratusek]
+ item Xinerama support for Grow/Pack [Nolan Leake]
 
-In practice, @code{rename-window} works, but technically speaking, the
-window name is not supposed to be changed in ICCCM.
+Make grow/pack Xinerama aware. The support still remains basic.
+Shrink-yank doesn't yet. 
 
 @item Window rules can be set by lisp
 
@@ -220,29 +224,66 @@ Rules by Matching}. An example usage is like this:
                       (maximize . vertical)))
 @end lisp
 
-In fact, this function has existed, but now it can take multiple
-rules, and the grammar has changed. The old syntax is still allowed,
-but deprecated.
+In fact, this function has existed, but now it can now specify both
+window name and class, and the grammar has changed. The old syntax is
+still allowed, but deprecated.
 
- item 5 new move-cursor commands (@code{move-cursor-} @code{northwest}, @code{northeast}, @code{southwest}, @code{southeast}), and @code{move-cursor-center} [Christopher Bratusek]
+ item Keymap translation [Scott Scriven]
 
- item Added @code{resize-by-factor} meta-function and @code{double-}, @code{halve-window-size} functions making use of it [Christopher Bratusek]
+Sawfish can ``translate'' keymaps for each window. Suppose you have
+the following lines in your @file{~/.sawfish/rc}:
 
- item Added @code{fullscreen}, @code{fullscreen-xinerama}, @code{new-workspace} and @code{new-viewport} window-matchers [Jeremy Hankins]
+ lisp
+(add-window-matcher 
+        '((WM_NAME . "^Terminal$"))
+        '(keymap-trans . (("C-n" "C-S-t")
+                          ("C-w" "C-S-w"))))
+ end lisp
 
- item Added @code{window-name} window-matcher [Christopher Bratusek]
+Then, when you press @kbd{C-n}, any windows with name ``Terminal''
+receive @kbd{C-S-t}, and so on.
 
- item Added @code{keymap-trans} window-matcher [Scott Scriven]
+This is part of window rules, but it cannot be set by configurator
+yet.
 
- item Added @code{browser} command [Christopher Bratusek]
+ item New window rules
+ itemize +
+ item Maximizations @code{fullscreen} and @code{full-xinerama} are available (@pxref{Maximizing Without Borders}) [Jeremy Hankins]
+ item Window position can also be specified by the direction, like north or east, instead of the coordinates. [Jeremy Hankins]
+ item New placement modes @code{new-workspace} and @code{new-viewport} [Jeremy Hankins]
 
- item Added @code{move-window-center} command [Christopher Bratusek]
+If @code{new-workspace} is chosen, then the window is put in an empty
+workspace, or a new workspace is created if none. A workspace with
+sticky windows only are considered empty. @code{new-viewport} is
+the same but an empty viewport is chosen. If none is, the workspace is
+enlarged, and the window is put in a new viewport.
+ item @code{window-name} can change the window's name. [Christopher Bratusek]
+ end itemize
+
+ item New commands [Christopher Bratusek]
+
+5 new move-cursor commands, 4 diagonals and 1 to center. (@pxref{Pointer Functions}
+
+Three window manipulation commands, @code{double-window-size}, @code{halve-window-size}, and @code{move-window-center}.
+
+ code{browser} invokes a browser instance.
+
+ item New funcitons
+ code{rename-window} changes the window name. [from ``mmc'' fork, Christopher Bratusek]
 
- item Added @code{viewport-windows} function (equivalent to workspace-windows) [Jeremy Hankins]
+In practice, it works, but technically speaking, the
+window name is not supposed to be changed in ICCCM.
+
+ code{viewport-windows} returns windows in a viewport. [Jeremy Hankins]
+
+ code{get-window-by-class} and @code{get-window-by-class-re} [Christopher Bratusek]
 
- item Added viewport-boundary-mode @code{dynamic} (creates a new viewport then hitting the screen-edge) [Jeremy Hankins]
+ item Dynamic Viewport Mode [Jeremy Hankins]
 
- item Improve position matcher to bind a window to a position (either @code{center} @code{east} @code{north} @code{north-east} @code{north-west} @code{south} @code{south-east} @code{south-west} @code{west}) OR to a user-given position [Jeremy Hankins]
+When you set @code{viewport-boundary-mode} to @code{dynamic},
+then the workspace grows and shrinks dynamically so that it contains
+all windows and the current viewport. For the details, @xref{Dynamic
+Viewport}.
 
 @item KDE integration module [Christopher Bratusek]
 
@@ -253,8 +294,6 @@ added.
 Unless set by user, konsole and konqueror are used for user options
 @code{xterm-program} and @code{browser-program}.
 
- item Added @code{get-window-by-class} and @code{get-window-by-class-re} [Christopher Bratusek]
-
 @item New Frame Classes [Christopher Bratusek] @*
 A ``frame class'' defines frame component. There's no user visible
 changes.
@@ -272,18 +311,24 @@ changes.
 @item @code{raise-lower-button}, a button to perform various raising and lowering actions on a window
 @end itemize
 @end itemize
- item Widget Transistion:
+ item Widget Transistion [Christopher Bratusek]
 @itemize @minus
 
- item Custom make-url-widget replaced by GtkLinkButton [Christopher Bratusek]
+ item Custom make-url-widget replaced by GtkLinkButton
 
- item Custom about-dialog replaced by GtkAboutDialog [Christopher Bratusek]
+ item Custom about-dialog replaced by GtkAboutDialog
 
- item GtkButton + GtkPreview + GtkColorSelection trio replaced by single GtkColorButton [Christopher Bratusek]
+ item GtkButton + GtkPreview + GtkColorSelection trio replaced by single GtkColorButton
 @end itemize
 @item Other Changes:
 @itemize @minus
 
+ item Startup window placement improvement [Jeremy Hankins]
+
+At Sawfish startup including restart, maximized windows and 
+position specified windows used to mess up viewport, appearing
+in wrong viewports. It is fixed.
+
 @item Renamed @code{after-add-window} to @code{maxmize-after-add-window} @*
 This function is only used in a hook [Teika Kazura]
 
diff --git a/man/sawfish.texi b/man/sawfish.texi
index fc5e25f..9475008 100644
--- a/man/sawfish.texi
+++ b/man/sawfish.texi
@@ -599,17 +599,8 @@ four-element list indicating the current cache status:
 @cindex Cursors
 
 Cursors define the shape and hot-spot of the mouse pointer's image.  A
-lisp type is provided for manipulating these objects.  In addition,
-Sawfish provides functions for manipulating the position of the
-cursor.
-
- menu
-* Cursor Appearance::
-* Cursor Positioning::
- end menu
-
- node Cursor Appearance, Cursor Positioning, Cursors, Cursors
- section Cursor Appearance
+lisp type is provided for manipulating these objects. For pointer
+related functions, @xref{Pointer Functions}.
 
 @defun cursorp arg
 Returns @code{t} if @var{arg} is a member of the cursor type.
@@ -675,50 +666,6 @@ following symbols are automatically set:
 The glyphs associated with these names are shown in Appendix I, of
 Volume Two, @cite{Xlib Reference Manual}.
 
- node Cursor Positioning,  , Cursor Appearance, Cursors
- section Cursor Positioning
-
-Sawfish provides one basic command for adjusting the relative position
-of the cursor.
-
- defun move-cursor right down
-Move the cursor @var{right} pixels to the right across the screen, and
- var{down} pixels down the screen.  The cursor stops at the edge of
-the screen (although in multi-head environments, this may not be at
-the edge of the display).
- end defun
-
-There are also more specialized cursor movement commands.
-
- defun move-cursor-left-fine
- defunx move-cursor-right-fine
- defunx move-cursor-up-fine
- defunx move-cursor-down-fine
- defunx move-cursor-northwest-fine
- defunx move-cursor-northeast-fine
- defunx move-cursor-southwest-fine
- defunx move-cursor-southeast-fine
-Move the cursor 1 pixel in the indicated direction.
- end defun
-
- defun move-cursor-center
- defunx move-cursor-left
- defunx move-cursor-right
- defunx move-cursor-up
- defunx move-cursor-down
- defunx move-cursor-northwest
- defunx move-cursor-northeast
- defunx move-cursor-southwest
- defunx move-cursor-southeast
-Move the cursor @code{move-cursor-increment} pixels in the indicated
-direction.
- end defun
-
- defvar move-cursor-increment 16
-The @code{move-cursor- var{DIRECTION}} functions move this cursor this
-many pixels at a time.
- end defvar
-
 @node Windows, Customization, Cursors, Top
 @chapter Windows
 @cindex Windows
@@ -792,25 +739,32 @@ Return true if @var{window} includes @var{atom} in its
 @end defun
 
 @menu
+Basics:
 * Window Property Lists::
 * Window Types::
 * Window Attributes::
 * Input Focus::
 * X Properties::
+* Window Groups::
+
+ noindent
+Operations on windows:
 * Window Stacking::
 * Moving and Resizing Windows::
 * Showing and Hiding Windows::
 * Destroying Windows::
 * Shading Windows::
+* Maximizing Windows::
+* Cycling Between Windows::
+* Window Rules by Matching::
+* Animating Windows::
 * Iconifying Windows::
+
+ noindent
+Windows with special properties:
 * Window Stickiness::
 * Ignored Windows::
 * Avoided Windows::
-* Maximizing Windows::
-* Animating Windows::
-* Cycling Between Windows::
-* Window Groups::
-* Window Rules by Matching::
 @end menu
 
 
@@ -1046,6 +1000,11 @@ Format to create unique window names.  Defaults to @code{"%s [%d]"}.
 Force @var{window} to have a unique title.
 @end deffn
 
+ defun rename-window win name
+Change the window's name to @var{name}. This works in practice, but
+technically ICCCM doesn't suppose window name changes.
+ end defun
+
 @defun window-icon-name window
 Return the icon name associated with @var{window}.
 @end defun
@@ -1385,7 +1344,7 @@ The cursor shape to use when selecting a window.  Defaults to
 @code{crosshair}.
 @end defvar
 
- node X Properties, Window Stacking, Input Focus, Windows
+ node X Properties, Window Groups, Input Focus, Windows
 @section X Properties
 @cindex X properties
 @cindex Properties, X
@@ -1469,8 +1428,179 @@ Arrange for function @var{fun} to be called with arguments
 to monitor.
 @end defun
 
+ node Window Groups, Window Stacking, X Properties, Windows
+ section Window Groups
+ cindex Groups, windows
+
+Sawfish provides extra tools and commands for dealing with ICCCM
+groups.  Most ``normal'' groups work the same way as they do in the
+ICCCM standard: windows have a group property that is set to the X
+window ID of the group leader.  These are ``group IDs'', and they are
+always positive integers.  In addition, Sawfish allows group IDs to
+be:
+
+ table @asis
+ item negative integers
+These are anonymous user-defined groups.
+ item symbols
+These are named user-defined groups.  Named user-defined groups are
+saved as part of window properties when saving sessions.
+ end table
+
+ defun window-group-ids
+Return the list of all group ids.
+ end defun
+
+There may be certain named groups that always exist, whether or not
+any window belongs to them.
+
+ defvar peristent-group-ids
+A list of symbols naming groups that always exist.
+ end defvar
+
+In any case, a window is limited to belonging to one group, and always
+belongs to one group.
+
+ menu
+* Assigning Windows to Groups::
+* Operations on Groups::
+ end menu
+
+ node Assigning Windows to Groups, Operations on Groups, Window Groups, Window Groups
+ subsection Assigning Windows to Groups
+ cindex Groups, assigning windows to
+
+It is possible to change the group of a window in Sawfish.  Use
+ code{add-window-to-group}, or if necessary you can set the window's
+ code{group} property explicitly.
+
+ defun add-window-to-group window group-id
+Place @var{window} in group @var{group-id}, replacing any previous
+group membership.  If @var{group-id} is @code{nil}, then Sawfish
+returns the window to whatever group membership was supplied by ICCCM.
+ end defun
+
+ defun add-window-to-new-group window
+Place @var{window} into a new group, which will have @var{window} as
+its sole member.  This is an anonymous user-defined group.  The new
+group ID is returned.
+ end defun
 
- node Window Stacking, Moving and Resizing Windows, X Properties, Windows
+The Sawfish group assignment never overrides the ICCCM group
+assignment, just suppresses it.  The @code{window-actual-group-id}
+function implements this overriding.
+
+ defun window-actual-group-id window
+Return the (Sawfish) group ID for @var{window}.  This is, in order of
+preference:
+ itemize @bullet
+ item The group ID assigned by Sawfish
+ item The group ID passed in by ICCCM.
+ item The corresponding values for an owning window, if the given window is transient.
+ item The window's own window ID.
+ end itemize
+
+This means that a window is, at the very least, part of its own group.
+ end defun
+
+Each of the following functions operates on the ``actual group ID'' as
+returned by the above function.
+
+ defun windows-by-group group-id &optional by-depth
+Return the list of windows in the group with id @var{group-id}.
+If @var{by-depth} is non-nil, then return the windows in order of
+stacking, from topmost to bottommost.
+ end defun
+
+ defun windows-in-group w &optional by-depth
+Return the list of windows in the same group as window @var{w}.
+If @var{by-depth} is non-nil, then return the windows in order of
+stacking, from topmost to bottommost.
+ end defun
+
+ defun map-window-group fun w
+Map the single argument function @var{fun} over all windows in the
+same group as window @var{w}.  Note that @var{fun} needs to operate
+using side-effects, rather than returning values.
+ end defun
+
+ defun map-other-window-groups fun w
+Map the single argument function @var{fun} over all windows not in the
+same group as window @var{w}.  Note that @var{fun} needs to operate
+using side-effects, rather than returning values.
+ end defun
+
+ defun window-group-menu &optional w
+Return a menu definition suitable for @code{popup-menu}.  This menu
+will allow the user to assign the window @var{w} into any group of a
+managed window, or into a brand new group.  The window's current group
+is checked or otherwise marked.
+ end defun
+
+ node Operations on Groups,  , Assigning Windows to Groups, Window Groups
+ subsection Operations on Groups
+ cindex Groups, operations on
+
+Most of the window manipulation functions that operate on windows are
+also available for window groups.  Each of these functions takes a
+window as argument; the affected group is that window's group.
+
+ defun iconify-group w
+ defunx uniconify-group w
+ defunx iconify-transient-group w
+ defunx uniconify-transient-group w
+These operate like their single-window counterparts.  They work by
+temporarily rebinding @code{iconify-group-mode} and
+ code{uniconify-group-mode} 
+ end defun
+
+ defun make-group-sticky w
+ defunx make-group-unsticky w
+These operate like their single-window counterparts.
+ end defun
+
+ defun toggle-group-sticky w
+If window @var{w} is sticky, all windows in its group have their
+stickyness removed.  Otherwise all windows in its group become sticky.
+ end defun
+
+ defun send-group-to-workspace w workspace
+ defunx send-group-to-next-workspace w count
+ defunx send-group-to-previous-workspace w count
+These operate like their single-window counterparts.
+ end defun
+
+ defun send-group-to-current-workspace w
+All windows in the group of @var{w} are moved from their existing
+workspaces to the nearest workspace that @var{w} is in.  Sticky
+windows are not affected.  If the window had the input focus and it is
+visible after the move, it retains the input focus.
+ end defun
+
+ defun move-group-to-current-viewport w
+ defunx move-group-viewport w
+ end defun
+
+ defun move-group-left w
+ defunx move-group-right w
+ defunx move-group-up w
+ defunx move-group-down w
+These operate like their single-window counterparts.
+ end defun
+
+ defun raise-group w
+ defunx lower-group w
+ defunx raise-lower-group w
+ defunx raise-group-depth w
+ defunx lower-group-depth w
+These operate like their single-window counterparts.
+ end defun
+
+ defun set-group-frame-style w style
+This operates like its single-window counterpart.
+ end defun
+
+ node Window Stacking, Moving and Resizing Windows, Window Groups, Windows
 @section Window Stacking
 @cindex Window stacking
 @cindex Stacking, of windows
@@ -2017,7 +2147,7 @@ by @var{window} (a window object, or numeric id).
 When a managed window is destroyed, the @code{destroy-notify-hook} will
 subsequently be invoked (@pxref{Standard Hooks}).
 
- node Shading Windows, Iconifying Windows, Destroying Windows, Windows
+ node Shading Windows, Maximizing Windows, Destroying Windows, Windows
 @section Shading Windows
 @cindex Shading windows
 @cindex Windows, shading
@@ -2049,264 +2179,7 @@ The @code{shaded} property of a window is set to @code{t} when the
 window is shaded. If a window is added with this property already set,
 then the window will appear in its shaded state.
 
-
- node Iconifying Windows, Window Stickiness, Shading Windows, Windows
- section Iconifying Windows
- cindex Iconifying windows
- cindex Windows, iconifying
-
-X defines an iconic state for windows, often windows in this state are
-displayed as small icons. Sawfish does not display these icons, instead
-iconified windows are shown slightly differently in the menu of all
-windows.
-
- deffn Command iconify-window window
-Iconify the window associated with object @var{window}.
- end deffn
-
- deffn Command uniconify-window window
-Return the window associated with @var{window} from its iconified state.
- end deffn
-
- deffn Command toggle-window-iconified window
-Minimize the window associated with @var{window}, or restore it if it
-is already minimized.
- end deffn
-
- deffn Command iconify-workspace-windows
-Minimize all windows in the current workspace.
- end deffn
-
-A window's iconic state may be tested through examination of its
- code{iconified} property---when @code{t} the window is iconified.
-But it is preferable to use explicit testing functions instead:
-
- defun window-iconified-p window
-Returns true if the window associated with @var{window} is iconified,
-false otherwise.
- end defun
-
- defun window-iconifiable-p window
-Returns true if the window associated with @var{window} can be
-iconified, false otherwise.  Some reasons a window might not be
-iconifiable are: it has a @code{never-iconify} property; it is
-already iconified; it is not a desktop window; or it is marked
- code{ignored} and @code{iconify-ignored} is not true.
- end defun
-
- defvar iconify-ignored nil
-Unmanaged (@code{ignored}) windows may be iconified.  Defaults to nil.
- end defvar
-
-Sawfish allows you to control certain behaviors when restoring
-minimized windows.
-
- defvar focus-windows-on-uniconify
-Windows are focused after being unminimized.  Defaults to false.
- end defvar
-
- defvar raise-windows-on-uniconify
-Windows are raised after being unminimized.  Defaults to true.
- end defvar
-
- defvar uniconify-to-current-workspace
-Move windows to the current workspace when they are unminimized.
-Defaults to true.
- end defvar
-
-When iconifying, it is possible to force other windows to iconify.
-
- defvr Customizable iconify-group-mode
- defvrx Customizable uniconify-group-mode
-Policy for performing chains of minimizations or restorations.  When a
-particular window is minimized or restored, it can cause other windows
-to be minimized or restored at the same time.  Their allowed values
-are set to the following list.  By default, both variables are bound
-to the symbol @code{transients}. but they are not required to have the
-same value.
- end defvr
-
- table @code
- item none
-No additional windows are minimized or restored.
- item transients
-All transient windows associated with the target window are minimized
-or restored.
- item group
-All windows in the target window's group are minimized or restored.
- end table
-
-Finally, it's possible to get the icon that would normally be
-displayed for an iconified window.
-
- defun window-icon-image window
-Return an image object representing the icon currently associated with
- var{window}, or @code{nil} if there is no such image.
- end defun
-
- node Window Stickiness, Ignored Windows, Iconifying Windows, Windows
- section Window Stickiness
- cindex Window stickiness
- cindex Sticky, windows
-
-Windows normally exist in a single workspace and a single viewport
-into that workspace.  When changing workspace or viewport, the current
-windows disappear.  This is sometimes not the correct policy; there
-are certain windows that should ``follow'' the user from window to
-window.  These are typically windows that are not bound to a
-particular activity.  The most common example is a dashboard window
-for calling other applications.  Another example might be a diagnostic
-program such as a load monitory.
-
-Each window has ``stickiness'' flags that govern this behavior.  One
-flag controls stickiness across workspaces: sticky windows will appear
-in every workspace automatically.  The other flag similarly governs
-stickiness across viewports.  A window is ``sticky'' if either of
-these flags are set.
-
-Sticky windows are often @code{ignored}, so they lack window
-decorations, and @code{avoid}ed so other windows do not cover them up.
-
- defun window-sticky-p/workspace window
- defunx window-sticky-p/viewport window
- defunx window-sticky-p window
-Returns true if @var{window} is sticky across a particular environment
-(workspaces, viewports, or either), false otherwise.
- end defun
-
- defun make-window-sticky/workspace window
- defunx make-window-sticky/viewport window
- defunx make-window-sticky window
-Make the @var{window} sticky across some environment (workspaces,
-viewports, or both).
- end defun
-
- defun make-window-unsticky/workspace window
- defunx make-window-unsticky/viewport window
- defunx make-window-unsticky window
-Make the @var{window} unsticky across some environment (workspaces,
-viewports or both).
- end defun
-
- defun toggle-window-sticky window
-If @code{window-sticky-p} would report true for @var{window}, make
- var{window} unsticky for all environments.  Otherwise make it sticky
-for all environments.
- end defun
-
- node Ignored Windows, Avoided Windows, Window Stickiness, Windows
- section Ignored Windows
- cindex Windows, ignored
- cindex ignored
-
-Sawfish has a general concept of ``ignored'' windows; the user does
-not interact normally with those windows.  The concept is actually
-defined by five different window properties:
-
- table @code
- item ignored
-The window does not receive frames.
-
- item never-focus
-The window never receives the input focus.
-
- item cycle-skip
-The window is ignored while window cycling.
-
- item window-list-skip
-The window will not be included in the window list.
-
- item task-list-skip
-The window will not be included in the task list.
-
- end table
-
-A monitor application such as ``xload'' might have all five of these
-flags set.
-
-Rather than directly manipulating the window properties, it is better
-to use the following access functions:
-
- defun window-ignored-p window
-Returns true if the window has the @code{ignored} property, false
-otherwise.
- end defun
-
- deffn Command make-window-ignored window
-Ignore the window @var{window}.
- end deffn
-
- deffn Command make-window-not-ignored window
-Unignore the window @var{window}.
- end deffn
-
- deffn Command toggle-window-ignored window
-If @code{window-ignored-p} would return true for @var{window}, make it
-unignored.  Otherwise make it ignored.
- end deffn
-
-The remaining flags only have toggle functions implemented right now:
-
- deffn Command toggle-window-never-focus window
- deffnx Command toggle-window-cycle-skip window
- deffnx Command toggle-window-list-skip window
- deffnx Command toggle-task-list-skip window
-Toggle the appropriate flag on @var{window}.
- end deffn
-
-All five of the flags are available through the window menu's
-``Toggle'' entry.
-
- node Avoided Windows, Maximizing Windows, Ignored Windows, Windows
- section Avoided Windows
- cindex Windows, avoided
- cindex avoid
-
-``Avoided'' windows are kept unobscured by other windows
-wherever possible. It is involved in window placement (@pxref{Window
-Placement}) and maximization (@pxref{Maximizing Windows}).
-Most placement modes will attempt to place a new window avoiding
-overlap with them. Windows can be maximized avoiding overlap to
-avoided windows.
-
-In this context, windows are categorized into three: windows with
- code{avoid} property, those with
- code{ignored} property (@pxref{Ignored Windows}), and the others.
-
-It is possible to avoid overlap only with avoided windows, and
-also is possible @emph{not} to avoid overlap only with ignored windows.
-
-Remember that the window with @code{avoid} property is @emph{avoided}
-by @emph{other} windows. Thus property name @code{avoid} should have
-been named ``avoided''. On the other hand, related functions and
-variables are named correctly, and no special care is necessary.
-
- defvar dont-avoid-ignored
-When non-nil (the default), ignored windows aren't avoided.
- end defvar
-
- defvar avoid-by-default
-When non-nil, any windows are avoided. Defaults to nil.
- end defvar
-
- defun window-avoided-p window
-Returns t if @var{window} is avoided by other windows.
-It is determined in the following order:
-
- enumerate
- item A window with @code{avoid} property is always avoided.
- item A window with @code{ignored} property is always @emph{not} avoided
-unless @code{dont-avoid-ignored} is non-nil.
- item Otherwise, @code{avoid-by-default} determines if it should be avoided.
- end enumerate
- end defun
-
- defun avoided-windows &optional window
-Returns a list of all windows that are avoided. If
- var{window} is defined, then it is excluded from the returned list.
- end defun
-
- node Maximizing Windows, Animating Windows, Avoided Windows, Windows
+ node Maximizing Windows, Cycling Between Windows, Shading Windows, Windows
 @section Maximizing Windows
 @cindex Maximizing windows
 @cindex Windows, maximizing
@@ -2579,41 +2452,7 @@ vertically maximized window will be restored to its original @var{h}
 dimension, but its @var{w} coordinate may have changed.
 @end defun
 
- node Animating Windows, Cycling Between Windows, Maximizing Windows, Windows
- section Animating Windows
- cindex Windows, Animating
-
-Sawfish provides certain window animation capabilities.  They have
-been described as ``lame'', so they are off by default.
-
- defvar default-window-animator
-The default window animation mode, used if a window has no explicit
-animation set.  Normally @code{none}.
- end defvar
-
- defun define-window-animator name fun
-Define a window animator called @var{name} (a symbol) that is managed
-by function @var{fun}. @var{fun} is called as @samp{(fun window op
-[action])} when it should change the state of an animation sequence.
- var{Op} may be one of the symbols @code{start}, @code{stop}.
- end defun
-
- defun autoload-window-animator name struct
-Construct an autoloader for window animator @var{name} from structure
- var{struct} 
- end defun
-
- defun run-window-animator window action
-Invoke an animation for action @var{action} on @var{window}.
- var{Action} may be one of the symbols @code{start}, @code{stop}.
- end defun
-
- defun record-window-animator window animator
-Note that @var{window} currently has an animation running, being
-controlled by animator function @var{animator}.
- end defun
-
- node Cycling Between Windows, Window Groups, Animating Windows, Windows
+ node Cycling Between Windows, Window Rules by Matching, Maximizing Windows, Windows
 @section Cycling Between Windows
 @cindex Windows, cycling between
 
@@ -2779,45 +2618,7 @@ Switch input focus to the most-recently focused window in the current
 workspace.
 @end defun
 
- node Window Groups, Window Rules by Matching , Cycling Between Windows, Windows
- section Window Groups
- cindex Groups, windows
-
-Sawfish provides extra tools and commands for dealing with ICCCM
-groups.  Most ``normal'' groups work the same way as they do in the
-ICCCM standard: windows have a group property that is set to the X
-window ID of the group leader.  These are ``group IDs'', and they are
-always positive integers.  In addition, Sawfish allows group IDs to
-be:
-
- table @asis
- item negative integers
-These are anonymous user-defined groups.
- item symbols
-These are named user-defined groups.  Named user-defined groups are
-saved as part of window properties when saving sessions.
- end table
-
- defun window-group-ids
-Return the list of all group ids.
- end defun
-
-There may be certain named groups that always exist, whether or not
-any window belongs to them.
-
- defvar peristent-group-ids
-A list of symbols naming groups that always exist.
- end defvar
-
-In any case, a window is limited to belonging to one group, and always
-belongs to one group.
-
- menu
-* Assigning Windows to Groups::
-* Operations on Groups::
- end menu
-
- node Window Rules by Matching, , Window Groups, Windows
+ node Window Rules by Matching, Animating Windows, Cycling Between Windows, Windows
 @section Window Rules by Matching
 @cindex Matching, windows
 
@@ -2870,140 +2671,297 @@ The rules are stored in variable @code{match-window-profile}. Use
 the above functions to modify its value. It is not recommended
 to directly manipulate it.
 
- node Assigning Windows to Groups, Operations on Groups, Window Groups, Window Groups
- subsection Assigning Windows to Groups
- cindex Groups, assigning windows to
+ node Animating Windows, Iconifying Windows, Window Rules by Matching, Windows
+ section Animating Windows
+ cindex Windows, Animating
 
-It is possible to change the group of a window in Sawfish.  Use
- code{add-window-to-group}, or if necessary you can set the window's
- code{group} property explicitly.
+Sawfish provides certain window animation capabilities.  They have
+been described as ``lame'', so they are off by default.
 
- defun add-window-to-group window group-id
-Place @var{window} in group @var{group-id}, replacing any previous
-group membership.  If @var{group-id} is @code{nil}, then Sawfish
-returns the window to whatever group membership was supplied by ICCCM.
- end defun
+ defvar default-window-animator
+The default window animation mode, used if a window has no explicit
+animation set.  Normally @code{none}.
+ end defvar
 
- defun add-window-to-new-group window
-Place @var{window} into a new group, which will have @var{window} as
-its sole member.  This is an anonymous user-defined group.  The new
-group ID is returned.
+ defun define-window-animator name fun
+Define a window animator called @var{name} (a symbol) that is managed
+by function @var{fun}. @var{fun} is called as @samp{(fun window op
+[action])} when it should change the state of an animation sequence.
+ var{Op} may be one of the symbols @code{start}, @code{stop}.
 @end defun
 
-The Sawfish group assignment never overrides the ICCCM group
-assignment, just suppresses it.  The @code{window-actual-group-id}
-function implements this overriding.
+ defun autoload-window-animator name struct
+Construct an autoloader for window animator @var{name} from structure
+ var{struct} 
+ end defun
 
- defun window-actual-group-id window
-Return the (Sawfish) group ID for @var{window}.  This is, in order of
-preference:
- itemize @bullet
- item The group ID assigned by Sawfish
- item The group ID passed in by ICCCM.
- item The corresponding values for an owning window, if the given window is transient.
- item The window's own window ID.
- end itemize
+ defun run-window-animator window action
+Invoke an animation for action @var{action} on @var{window}.
+ var{Action} may be one of the symbols @code{start}, @code{stop}.
+ end defun
 
-This means that a window is, at the very least, part of its own group.
+ defun record-window-animator window animator
+Note that @var{window} currently has an animation running, being
+controlled by animator function @var{animator}.
 @end defun
 
-Each of the following functions operates on the ``actual group ID'' as
-returned by the above function.
+ node Iconifying Windows, Window Stickiness, Animating Windows, Windows
+ section Iconifying Windows
+ cindex Iconifying windows
+ cindex Windows, iconifying
 
- defun windows-by-group group-id &optional by-depth
-Return the list of windows in the group with id @var{group-id}.
-If @var{by-depth} is non-nil, then return the windows in order of
-stacking, from topmost to bottommost.
- end defun
+X defines an iconic state for windows, often windows in this state are
+displayed as small icons. Sawfish does not display these icons, instead
+iconified windows are shown slightly differently in the menu of all
+windows.
 
- defun windows-in-group w &optional by-depth
-Return the list of windows in the same group as window @var{w}.
-If @var{by-depth} is non-nil, then return the windows in order of
-stacking, from topmost to bottommost.
- end defun
+ deffn Command iconify-window window
+Iconify the window associated with object @var{window}.
+ end deffn
 
- defun map-window-group fun w
-Map the single argument function @var{fun} over all windows in the
-same group as window @var{w}.  Note that @var{fun} needs to operate
-using side-effects, rather than returning values.
- end defun
+ deffn Command uniconify-window window
+Return the window associated with @var{window} from its iconified state.
+ end deffn
 
- defun map-other-window-groups fun w
-Map the single argument function @var{fun} over all windows not in the
-same group as window @var{w}.  Note that @var{fun} needs to operate
-using side-effects, rather than returning values.
+ deffn Command toggle-window-iconified window
+Minimize the window associated with @var{window}, or restore it if it
+is already minimized.
+ end deffn
+
+ deffn Command iconify-workspace-windows
+Minimize all windows in the current workspace.
+ end deffn
+
+A window's iconic state may be tested through examination of its
+ code{iconified} property---when @code{t} the window is iconified.
+But it is preferable to use explicit testing functions instead:
+
+ defun window-iconified-p window
+Returns true if the window associated with @var{window} is iconified,
+false otherwise.
 @end defun
 
- defun window-group-menu &optional w
-Return a menu definition suitable for @code{popup-menu}.  This menu
-will allow the user to assign the window @var{w} into any group of a
-managed window, or into a brand new group.  The window's current group
-is checked or otherwise marked.
+ defun window-iconifiable-p window
+Returns true if the window associated with @var{window} can be
+iconified, false otherwise.  Some reasons a window might not be
+iconifiable are: it has a @code{never-iconify} property; it is
+already iconified; it is not a desktop window; or it is marked
+ code{ignored} and @code{iconify-ignored} is not true.
 @end defun
 
- node Operations on Groups,  , Assigning Windows to Groups, Window Groups
- subsection Operations on Groups
- cindex Groups, operations on
+ defvar iconify-ignored nil
+Unmanaged (@code{ignored}) windows may be iconified.  Defaults to nil.
+ end defvar
 
-Most of the window manipulation functions that operate on windows are
-also available for window groups.  Each of these functions takes a
-window as argument; the affected group is that window's group.
+Sawfish allows you to control certain behaviors when restoring
+minimized windows.
 
- defun iconify-group w
- defunx uniconify-group w
- defunx iconify-transient-group w
- defunx uniconify-transient-group w
-These operate like their single-window counterparts.  They work by
-temporarily rebinding @code{iconify-group-mode} and
- code{uniconify-group-mode} 
- end defun
+ defvar focus-windows-on-uniconify
+Windows are focused after being unminimized.  Defaults to false.
+ end defvar
 
- defun make-group-sticky w
- defunx make-group-unsticky w
-These operate like their single-window counterparts.
+ defvar raise-windows-on-uniconify
+Windows are raised after being unminimized.  Defaults to true.
+ end defvar
+
+ defvar uniconify-to-current-workspace
+Move windows to the current workspace when they are unminimized.
+Defaults to true.
+ end defvar
+
+When iconifying, it is possible to force other windows to iconify.
+
+ defvr Customizable iconify-group-mode
+ defvrx Customizable uniconify-group-mode
+Policy for performing chains of minimizations or restorations.  When a
+particular window is minimized or restored, it can cause other windows
+to be minimized or restored at the same time.  Their allowed values
+are set to the following list.  By default, both variables are bound
+to the symbol @code{transients}. but they are not required to have the
+same value.
+ end defvr
+
+ table @code
+ item none
+No additional windows are minimized or restored.
+ item transients
+All transient windows associated with the target window are minimized
+or restored.
+ item group
+All windows in the target window's group are minimized or restored.
+ end table
+
+Finally, it's possible to get the icon that would normally be
+displayed for an iconified window.
+
+ defun window-icon-image window
+Return an image object representing the icon currently associated with
+ var{window}, or @code{nil} if there is no such image.
 @end defun
 
- defun toggle-group-sticky w
-If window @var{w} is sticky, all windows in its group have their
-stickyness removed.  Otherwise all windows in its group become sticky.
+ node Window Stickiness, Ignored Windows, Iconifying Windows, Windows
+ section Window Stickiness
+ cindex Window stickiness
+ cindex Sticky, windows
+
+Windows normally exist in a single workspace and a single viewport
+into that workspace.  When changing workspace or viewport, the current
+windows disappear.  This is sometimes not the correct policy; there
+are certain windows that should ``follow'' the user from window to
+window.  These are typically windows that are not bound to a
+particular activity.  The most common example is a dashboard window
+for calling other applications.  Another example might be a diagnostic
+program such as a load monitory.
+
+Each window has ``stickiness'' flags that govern this behavior.  One
+flag controls stickiness across workspaces: sticky windows will appear
+in every workspace automatically.  The other flag similarly governs
+stickiness across viewports.  A window is ``sticky'' if either of
+these flags are set.
+
+Sticky windows are often @code{ignored}, so they lack window
+decorations, and @code{avoid}ed so other windows do not cover them up.
+
+ defun window-sticky-p/workspace window
+ defunx window-sticky-p/viewport window
+ defunx window-sticky-p window
+Returns true if @var{window} is sticky across a particular environment
+(workspaces, viewports, or either), false otherwise.
 @end defun
 
- defun send-group-to-workspace w workspace
- defunx send-group-to-next-workspace w count
- defunx send-group-to-previous-workspace w count
-These operate like their single-window counterparts.
+ defun make-window-sticky/workspace window
+ defunx make-window-sticky/viewport window
+ defunx make-window-sticky window
+Make the @var{window} sticky across some environment (workspaces,
+viewports, or both).
 @end defun
 
- defun send-group-to-current-workspace w
-All windows in the group of @var{w} are moved from their existing
-workspaces to the nearest workspace that @var{w} is in.  Sticky
-windows are not affected.  If the window had the input focus and it is
-visible after the move, it retains the input focus.
+ defun make-window-unsticky/workspace window
+ defunx make-window-unsticky/viewport window
+ defunx make-window-unsticky window
+Make the @var{window} unsticky across some environment (workspaces,
+viewports or both).
 @end defun
 
- defun move-group-to-current-viewport w
- defunx move-group-viewport w
+ defun toggle-window-sticky window
+If @code{window-sticky-p} would report true for @var{window}, make
+ var{window} unsticky for all environments.  Otherwise make it sticky
+for all environments.
 @end defun
 
- defun move-group-left w
- defunx move-group-right w
- defunx move-group-up w
- defunx move-group-down w
-These operate like their single-window counterparts.
+ node Ignored Windows, Avoided Windows, Window Stickiness, Windows
+ section Ignored Windows
+ cindex Windows, ignored
+ cindex ignored
+
+Sawfish has a general concept of ``ignored'' windows; the user does
+not interact normally with those windows.  The concept is actually
+defined by five different window properties:
+
+ table @code
+ item ignored
+The window does not receive frames.
+
+ item never-focus
+The window never receives the input focus.
+
+ item cycle-skip
+The window is ignored while window cycling.
+
+ item window-list-skip
+The window will not be included in the window list.
+
+ item task-list-skip
+The window will not be included in the task list.
+
+ end table
+
+A monitor application such as ``xload'' might have all five of these
+flags set.
+
+Rather than directly manipulating the window properties, it is better
+to use the following access functions:
+
+ defun window-ignored-p window
+Returns true if the window has the @code{ignored} property, false
+otherwise.
 @end defun
 
- defun raise-group w
- defunx lower-group w
- defunx raise-lower-group w
- defunx raise-group-depth w
- defunx lower-group-depth w
-These operate like their single-window counterparts.
+ deffn Command make-window-ignored window
+Ignore the window @var{window}.
+ end deffn
+
+ deffn Command make-window-not-ignored window
+Unignore the window @var{window}.
+ end deffn
+
+ deffn Command toggle-window-ignored window
+If @code{window-ignored-p} would return true for @var{window}, make it
+unignored.  Otherwise make it ignored.
+ end deffn
+
+The remaining flags only have toggle functions implemented right now:
+
+ deffn Command toggle-window-never-focus window
+ deffnx Command toggle-window-cycle-skip window
+ deffnx Command toggle-window-list-skip window
+ deffnx Command toggle-task-list-skip window
+Toggle the appropriate flag on @var{window}.
+ end deffn
+
+All five of the flags are available through the window menu's
+``Toggle'' entry.
+
+ node Avoided Windows, , Ignored Windows, Windows
+ section Avoided Windows
+ cindex Windows, avoided
+ cindex avoid
+
+``Avoided'' windows are kept unobscured by other windows
+wherever possible. It is involved in window placement (@pxref{Window
+Placement}) and maximization (@pxref{Maximizing Windows}).
+Most placement modes will attempt to place a new window avoiding
+overlap with them. Windows can be maximized avoiding overlap to
+avoided windows.
+
+In this context, windows are categorized into three: windows with
+ code{avoid} property, those with
+ code{ignored} property (@pxref{Ignored Windows}), and the others.
+
+It is possible to avoid overlap only with avoided windows, and
+also is possible @emph{not} to avoid overlap only with ignored windows.
+
+Remember that the window with @code{avoid} property is @emph{avoided}
+by @emph{other} windows. Thus property name @code{avoid} should have
+been named ``avoided''. On the other hand, related functions and
+variables are named correctly, and no special care is necessary.
+
+ defvar dont-avoid-ignored
+When non-nil (the default), ignored windows aren't avoided.
+ end defvar
+
+ defvar avoid-by-default
+When non-nil, any windows are avoided. Defaults to nil.
+ end defvar
+
+ defun window-avoided-p window
+Returns t if @var{window} is avoided by other windows.
+It is determined in the following order:
+
+ enumerate
+ item A window with @code{avoid} property is always avoided.
+ item A window with @code{ignored} property is always @emph{not} avoided
+unless @code{dont-avoid-ignored} is non-nil.
+ item Otherwise, @code{avoid-by-default} determines if it should be avoided.
+ end enumerate
 @end defun
 
- defun set-group-frame-style w style
-This operates like its single-window counterpart.
+ defun avoided-windows &optional window
+Returns a list of all windows that are avoided. If
+ var{window} is defined, then it is excluded from the returned list.
 @end defun
 
+
 @node Customization, Window Frames, Windows, Top
 @chapter Customization
 @cindex Customization
@@ -4057,32 +4015,40 @@ Disable all frame parts that are a member of @var{class} in
 @cindex Viewports
 @cindex Large Desktop
 
-Sawfish can have the virtual desktop size larger then the computer
-screen size. This notion is called ``viewport'' in Sawfish.
+Sawfish can have a virtual desktop which is larger than the computer's
+screen size. This is done through the use of ``viewport''.
 
-Viewport can be thought that it displays a portion of virtual desktop,
-and the entire virtual desktop consists of the grid of ``cells'' whose
-size is of the physical screen. Viewport sits on a cell.
+Viewport can be thought of as a screen-sized hole through which you
+can view a portion of the virtual desktop.  The entire virtual desktop
+consists of the grid of ``cells'' whose size is that of the physical
+screen. Viewport moves around, and sits on a cell.
 
-Technically speaking, the word ``viewport'' should mean the currently
-displayed part of the entire desktop. But in Sawfish, the entire
-desktop is wrongly called ``viewport'', too. When focused to
-enlargement, ``large desktop'' is the correct nomenclature, but
-simply calling it ``workspace'' = ``virtual desktop'' are correct, too,
-for most cases.
+In Sawfish, the word ``viewport'' is sometimes used to mean the entire
+larger-than-normal desktop.  This is natural, but a confusion and not
+technically correct. When focused to enlargement, ``large desktop'' is
+the correct nomenclature, but simply calling it the ``workspace'' or
+the ``virtual desktop'' are correct too.
+
+The word ``viewport'' is also used to mean the cell on which the
+viewport is set, like ``Go to the next viewport.''
 
 @defvar viewport-dimensions
-The number of viewports of the virtual desktop. This is a cons cell
- code{(columns . rows)}.  Defaults to @code{(1 . 1)}.
+The dimension of the virtual destkop.  This is a cons cell
+ code{(@var{columns} . @var{rows})}.  Defaults to @code{(1 . 1)}.  The number of
+viewport cells in the virtual desktop is @code{columns} times
+ code{rows} 
 
 If @code{viewport-boundary-mode} is @code{dynamic} (@pxref{Dynamic
-Viewport}), then this variable is the current size of the current
-workspace, and does not have the meaning as a user option.
+Viewport}) then this variable is set by Sawfish to the current size of
+the current workspace and should not be set by the user.
 @end defvar
 
 @defun set-number-of-viewports width height
 Change @code{viewport-dimensions} to have the value
- code{(@var{width} . @var{height})}.
+ code{(@var{width} . @var{height})}.  If @code{viewport-boundary-mode}
+is @code{dynamic} then this sets the minimum dimensions of the virtual
+workspace (@pxref{Dynamic Viewport}) rather than setting the
+dimensions directly.
 @end defun
 
 @menu
@@ -4094,7 +4060,7 @@ Change @code{viewport-dimensions} to have the value
 @node Viewport Functions, Dynamic Viewport, Viewports, Viewports
 @section Viewport Functions
 
-Each cell is labeled with the index @code{(col, row)}, and the
+Each cell is labeled with the index @code{(@var{col}, @var{row})}, and the
 top-left cell is @code{(0, 0)}.  Indices are never negative.
 
 Sawfish implements viewport as follows. On a cell change, windows in
@@ -4112,11 +4078,11 @@ Change the viewport to visit cell (@var{col}, @var{row}).
 @end defun
 
 @defun move-viewport right down
-Move the viewport to see the cell @var{right} slots to the right and
- var{down} slots down.  Either argument may be zero or negative.
+Move the viewport to see the cell @var{right} columns right and
+ var{down} rows down.  Either argument may be zero or negative.
 @end defun
 
- defvar viewport-boundary-mode
+ defvr Customizable viewport-boundary-mode
 Decides how to act when you call @code{set-screen-viewport} and you
 try to go outside of the virtual desktop. (Its size is specified by
 @code{viewport-dimensions}.) Defaults to @code{stop}.
@@ -4127,8 +4093,8 @@ When set to @code{wrap-around}, it behaves as if the leftmost viewport
 and the rightmost are connected. Same for the top and bottom.
 
 If it is set to @code{dynamic}, then the workspace size changes
-automatically. For detail, see @xref{Dynamic Viewport}.
- end defvar
+automatically. For details, see @xref{Dynamic Viewport}.
+ end defvr
 
 @defun viewport-honor-workspace-edges
 Returns whether or not the display is permitted to move past the
@@ -4137,40 +4103,34 @@ current workspace boundaries.  It returns true if
 @end defun
 
 @defun viewport-at x y
-Returns a cons cell consisting of @code{(column . row)} of the viewport
-containing the specified @var{x} and @var{y} coordinates.  The
-coordinates are specified relative to the current viewport, so
+Returns a cons cell consisting of @code{(@var{column} . @var{row})} of
+the viewport containing the specified @var{x} and @var{y} coordinates.
+The coordinates are specified relative to the current viewport, so
 @code{(viewport-at 0 0)} is equivalent to @code{(screen-viewport)}.
 @end defun
 
 @defun viewport-offset-pixel viewport
-Returns the offset from the current viewport to @var{viewport}
-which is specified as @code{(column . row)}. The return value is the
-cons cell @code{(x . y)}. The values are in pixel, and are negative if
-it lies at left or above the current viewport.
+Returns the offset from the current viewport to @var{viewport} which
+is specified as @code{(@var{column} . @var{row})}. The return value is
+the cons cell @code{(@var{x} . @var{y})}. The values are in pixel, and are
+negative if it lies at left or above the current viewport.
 
- var{viewport} can be non existent one. If @var{viewport} is @code{nil} it
-is understood as the current viewport, i.e., @code{(0 . 0)} will be
-returned.
+ var{viewport} can be outside of the workspace. (The check is not
+done.) If @var{viewport} is @code{nil} it is understood as the
+current viewport, i.e., @code{(0 . 0)} will be returned.
 @end defun
 
-Actually, Sawfish can move viewport by any pixels, not only by
-screen size. Here're low level functions to do it.
+There are lower-level functions which move viewport by pixel, not
+by multiples of the physical screen dimensions.
 
- defun warp-viewport x y
-Change the position of the viewport, such that location
- code{(@var{x}, @var{y})} is at the top-left of the display. The unit
-is by pixels.
- end defun
+Note that use of these breaks the traditional behavior and user
+interface of Sawfish. Though they are useful, simultaneous use of
+these functions and other functions may cause weird results.
 
 @defun set-viewport x y
 Change the position of the viewport, such that location
- code{(@var{x}, @var{y})} is at the top-left of the display. The unit
-is by pixels.
-
-Unlike @code{warp-viewport}, the change takes place by dividing the
-motion into @code{scroll-viewport-steps} steps, and redisplaying after
-each step in the motion.
+ code{(@var{x}, @var{y})} is at the top-left of the display.  So
+ code{(set-viewport 0 -5)} will shift the viewport up five pixels.
 @end defun
 
 @defvr Customizable scroll-viewport-steps
@@ -4183,18 +4143,25 @@ is done. The upper limit for customization is 50.
 
 This variable is used for @code{set-viewport}. All interactive commands
 defined by Sawfish call this function, so this variable is important
-for user.
+for the user.
 @end defvr
 
 @node Dynamic Viewport, Windows and Viewports, Viewport Functions, Viewports
 @section Dynamic Viewport
 
-If the variable @code{viewport-boundary-mode} (@pxref{Viewport
-Functions}) is set to @code{dynamic}, the viewport is ``dynamic''. If
-dynamic viewport is enabled, then each workspace has its size
-indepedent of other workspaces, and it is automatically resized so
-that it contains all windows plus the current viewport. The size is set at
-Sawfish startup, and each time you move viewport.
+``Dynamic viewport'' is enabled by setting
+ code{viewport-boundary-mode} to the symbol @code{dynamic}. It has
+two features.
+
+Normally, the viewport cannot move beyond the limits set by
+ code{viewport-dimensions}, but this limitation is removed in dynamic
+viewport. The viewport is allowed to go as far as you wish.
+
+In addition, workspace is automatically resized, both enlarged and
+shrinked, so that it contains the current viewport and all
+windows. (Precisely speaking, it takes the minimum such size.)  The
+size is set when you move the viewport, and also at Sawfish
+startup. Each workspace has its own size independent of the others.
 
 Even in dynamic viewport, the top-left cell is always @code{(0, 0)},
 and the cell indices are never negative.
@@ -4202,17 +4169,26 @@ and the cell indices are never negative.
 The dynamic viewport is still an experimental feature, and its
 specification may change.
 
- defvar viewport-minimum-dimensions
-This is only useful if dynamic viewport is enabled. It means that
- code{viewport-dimensions} gets never less than this variable.
+ defvr Customizable viewport-minimum-dimensions
+This is only useful if dynamic viewport is enabled.
+ code{viewport-dimensions} will never be set to less than
+ code{viewport-minimum-dimensions}, unless it is a change requested by
+the user, either by using the configuration interface or by calling
+ code{set-number-of-viewports} 
 
 If setting @code{viewport-minimum-dimensions} by hand (not by the
 customization interface) be sure to call
- code{viewport-minimum-size-changed} after doing so.
-
-If the viewport is not dynamic, it is automatically set to the same
-value as @code{viewport-dimensions}.
- end defvar
+ code{viewport-minimum-size-changed} after doing so to ensure that the
+new minimum dimensions immediately go into effect.
+
+If @code{set-number-of-viewports} is called to set the viewport
+dimensions @code{viewport-minimum-dimensions} will be set to the same
+value.  Also, if (using the configuration interface) you set the
+viewport dimensions to less than @code{viewport-minimum-dimensions} then
+ code{viewport-minimum-dimensions} will be adjusted to match.  This way
+those who are not using dynamic viewports do not need to worry about
+ code{viewport-minimum-dimensions} 
+ end defvr
 
 Under dynamic viewport, @code{viewport-dimensions} is the current size
 of the current workspace, and does not have the meaning as a user option.
@@ -4221,13 +4197,13 @@ of the current workspace, and does not have the meaning as a user option.
 @section Windows and Viewports
 
 @defun window-viewport window
-Returns a cons cell @code{(col . row)} of the viewport
+Returns a cons cell @code{(@var{col} . @var{row})} of the viewport
 holding the top-left corner of @var{window}.
 @end defun
 
 @defun window-relative-position w
 Returns in a cons cell the coodinates of the window relative to the
-current viewport.
+viewport it occupies.
 @end defun
 
 @defun window-outside-viewport-p window &optional viewport
@@ -4264,10 +4240,10 @@ window that spans multiple cells, this function will pick the cell
 showing the window's top-left corner.
 @end defun
 
- defvar uniconify-to-current-viewport
+ defvr Customizable uniconify-to-current-viewport
 When true, windows uniconify to the current viewport, rather than to
 the viewport they were iconified on.  Defaults to true.
- end defvar
+ end defvr
 
 @node Workspaces, Multi-Head Environments, Viewports, Top
 @chapter Workspaces
@@ -5190,7 +5166,8 @@ The super modifier; note that this is a lowercase @kbd{s}
 The standard X modifiers, for @var{k} between 1 and 5
 
 @item Any
-A special modifier that matches any set of modifiers in events.
+A special modifier that matches any set of modifiers in events,
+including no modifier.
 @xref{Event Matching}.
 
 @item Release
@@ -5828,7 +5805,7 @@ Returns the number of X events waiting to be handled.
 @cindex Functions, pointer
 
 @defun query-pointer &optional from-server
-Returns a cons cell @code{(@var{x} . @var{y})} representing the current
+Returns a cons cell @code{(x . y)} representing the current
 mouse pointer position, relative to the origin of the root window.
 
 If there is a mouse update current event, the position is read
@@ -5892,6 +5869,53 @@ events from X.  The variable defaults to 2 pixels.  If not an integer,
 Sawfish assumes a threshold of 0 pixels.
 @end defvar
 
+Sawfish provides functions to move the pointer relative to the current
+positions. They're named ``move-cursor'', and defined in
+ code{sawfish wm commands move-cursor} 
+
+ defun move-cursor right down
+Move the cursor @var{right} pixels to the right across the screen, and
+ var{down} pixels down the screen.  The cursor stops at the edge of
+the screen (although in multi-head environments, this may not be at
+the edge of the display).
+ end defun
+
+There are also more specialized cursor movement functions.  All of
+them are commands, too.
+
+ defun move-cursor-left-fine
+ defunx move-cursor-right-fine
+ defunx move-cursor-up-fine
+ defunx move-cursor-down-fine
+ defunx move-cursor-northwest-fine
+ defunx move-cursor-northeast-fine
+ defunx move-cursor-southwest-fine
+ defunx move-cursor-southeast-fine
+Move the cursor 1 pixel in the indicated direction.
+ end defun
+
+ defun move-cursor-left
+ defunx move-cursor-right
+ defunx move-cursor-up
+ defunx move-cursor-down
+ defunx move-cursor-northwest
+ defunx move-cursor-northeast
+ defunx move-cursor-southwest
+ defunx move-cursor-southeast
+Move the cursor @code{move-cursor-increment} pixels in the indicated
+direction. @code{move-cursor-northeast} is equal to the northward
+move cobmined with the eastward.
+ end defun
+
+ defun move-cursor-center
+Move the cursor to the center of the screen.
+ end defun
+
+ defvar move-cursor-increment 16
+The @code{move-cursor- var{DIRECTION}} functions move this cursor this
+many pixels at a time.
+ end defvar
+
 
 @node Grab Functions, Display Functions, Pointer Functions, Miscellaneous Functions
 @section Grab Functions
diff --git a/man/user-doc.texi b/man/user-doc.texi
index 67d8ef2..de59810 100644
--- a/man/user-doc.texi
+++ b/man/user-doc.texi
@@ -2,6 +2,8 @@
 
 @chapter User Documentation for Sawfish 1.5.0
 
+Sorry, this document still needs much expansion.
+
 @enumerate
 
 @item Introduction
[Date Prev][Date Next] [Thread Prev][Thread Next] [Thread Index] [Date Index] [Author Index]