[sawfish] Doc: mainly texi "windows" chapter organization.

[Christopher Bratusek <chrisb src gnome org>]

commit 12ee5be44148276bdaad3ba79738c3b355836e21
Author: Teika kazura <teika lavabit com>
Date:   Sat Mar 6 13:47:50 2010 +0900

    Doc: mainly texi "windows" chapter organization.
    
    Groups are revised.
    New sections: "Getting Windows", "Stacking Vilibility", "Activating Window".
    Functions `display-window' and `activate-window' are documented.
    Option `unshade-selected-windows' is documented.
    Distinction between 'window-wants-input-p' and 'window-really-wants-input-p' is described.
    Minor error fix: 'window-transient-p' returns the parent id, not t, when transient.
    
    Docstring with trailing "\\w" puts the widget right to the label in the configurator.
    
    Faq item on per head workspace switching.

 OPTIONS                                |    2 +-
 lisp/sawfish/wm/util/display-window.jl |   24 ++-
 man/faq.texi                           |   12 +
 man/news.texi                          |   15 +
 man/sawfish.texi                       |  494 ++++++++++++++++++--------------
 src/events.c                           |   11 +-
 src/windows.c                          |   11 +-
 7 files changed, 346 insertions(+), 223 deletions(-)
---
diff --git a/OPTIONS b/OPTIONS
index 1c58e7f..9caee65 100644
--- a/OPTIONS
+++ b/OPTIONS
@@ -509,7 +509,7 @@
 ;;    "Raise windows when they are unshaded.")
 
 ;;  (defcustom unshade-selected-windows nil
-;;    "Unshade selected windows.")
+;;    "Unshade window when selected.")
 
 ;; maximize options
 
diff --git a/lisp/sawfish/wm/util/display-window.jl b/lisp/sawfish/wm/util/display-window.jl
index 7aed6b6..1dbf23e 100644
--- a/lisp/sawfish/wm/util/display-window.jl
+++ b/lisp/sawfish/wm/util/display-window.jl
@@ -37,15 +37,19 @@
 	  sawfish.wm.util.window-order)
 
   (defcustom unshade-selected-windows nil
-    "Unshade selected windows."
+    "Unshade window when selected."
     :type boolean
     :group min-max)
 
 ;;; Activating windows
 
+  ;; No Sawfish code except display-window calls this function.
+  ;; But this is a command, too, so don't delete it.
   (define (display-window-without-focusing
 	   w #!optional preferred-space #!key will-refocus)
-    "Display the workspace/viewport containing the window W."
+    "Display the window, by choosing the workspace/viewport containing
+the window W, and by showing it, i.e. the window is uniconified, or
+unshaded if necessary."
     (when w
       (when (window-iconified-p w)
 	(uniconify-window w))
@@ -64,10 +68,19 @@
     display-window-without-focusing
     #:spec (lambda ()
 	     (require 'sawfish.wm.util.prompt)
-	     (list (prompt-for-window))))
+	     (list (prompt-for-window)))
+    #:doc "Display the window, but don't focus. You're prompted to type in the name."
+    )
 
+  #|
+    Currently, the optional argument `preferred-space' is not used
+    anywhere in the Sawfish code, so I didn't describe it in the texi.
+    Consider removing it, and instead implementing many other options
+    with #!key.
+  |#
   (define (display-window w #!optional preferred-space)
-    "Display the workspace containing the window W, then focus on W."
+    "Do everything necessary to make window W ready for user,
+i.e. display, focus, etc."
     (when w
       (display-window-without-focusing
        w preferred-space
@@ -77,4 +90,5 @@
   (define-command 'display-window display-window
     #:spec (lambda ()
 	     (require 'sawfish.wm.util.prompt)
-	     (list (prompt-for-window)))))
+	     (list (prompt-for-window)))
+    #:doc "Display the window. You're prompted to type in the name."))
diff --git a/man/faq.texi b/man/faq.texi
index 1619eac..7cf2357 100644
--- a/man/faq.texi
+++ b/man/faq.texi
@@ -196,6 +196,18 @@ $ visudo                 # add the group "shutdown" to sudoers
 
 That's it, now everyone in the @code{shutdown} group can do it!
 
+ item I have multiple heads. Is it possible to switch workspace per head?
+
+You have to devise a trick, because the strict answer is no.  There's
+``sticky-head'' script which partly achives it on the wiki, but it's
+still incomplete: @url{http://sawfish.wikia.com/wiki/Sticky-head}
+
+Technically, Sawfish's workspace implements ``virtual desktop''
+specified in the window manager standard (ewmh), which has to be
+at least the size of the X screen, so the workspace has to containt
+all heads. ``Per head workspace'' has to be implemented as a new
+mechanism on top of workspace.
+
 @item Why don't you use GUILE?
 
 Mainly because I'm lazy; I had already written rep, and therefore
diff --git a/man/news.texi b/man/news.texi
index 736f6da..dcc51b3 100644
--- a/man/news.texi
+++ b/man/news.texi
@@ -35,6 +35,21 @@ files.  Of course, you can define new modules, too.
 @item Pressing the lock-button does the state-change of the window
 accordingly. [Fuchur]
 @end itemize
+
+ item Other Changes
+ itemize @minus
+ item Info improvements [Teika kazura]
+
+``Windows'' chapter is partly revised. Function @code{display-window}
+is documented. Difference between @code{window-wants-input-p} and
+ code{window-really-wants-input-p} is described.
+
+In past few versions we made more changes which were not described in
+the news, including clarification in viewport and workspace, and window
+matching lisp functions.
+
+Added a faq item on multi-head and workspace.
+ end itemize
 @end itemize
 
 @heading 1.6.2 "Mighty Disco King"
diff --git a/man/sawfish.texi b/man/sawfish.texi
index 7e2edf3..7dfcdd7 100644
--- a/man/sawfish.texi
+++ b/man/sawfish.texi
@@ -682,96 +682,191 @@ Returns @code{t} if @var{arg} is a member of the window type, and has a
 client window associated with it.
 @end defun
 
- defun managed-windows
-Returns a list containing all managed window objects, in the order that
-they were adopted by the window manager (first to last).
- end defun
+ menu
+Basics:
+* Window Attributes::
+* Getting Windows:: Get window by name, class, all, etc.
+* Window Property Lists::
+* Window Types::  Some windows have type, like transient.
+* Input Focus::
+* X Properties::
+* Window Groups::
 
- defun get-window-by-id xid
-Return a window object with id @var{xid}, or @code{nil}.
+ noindent
+Operations on windows:
+* Activating Window:: Make a window ready for use.
+* 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::
+ end menu
+
+ node Window Attributes, Getting Windows, , Windows
+ section Window Attributes
+ cindex Window attributes
+ cindex Attributes, of windows
+ cindex Windows, attributes of
+
+Many attributes are described in the related sections.
+
+First, basic attributes, like name, class, id, etc.
+ defun window-name window
+Return the name associated with @var{window}.
 @end defun
 
- defun get-window-by-name name
-Return a window object with name @var{name}, or @code{nil}.
+ defun window-full-name window
+Return the full-name associated with @var{window}. This may or may not
+be the same as the normal name.
 @end defun
 
- defun get-window-by-name-re name
-Return a window object with name matching regular expression
- var{name}, or @code{nil}.
+Sawfish provides functions to ensure that window names are unique.
+
+ defun uniquify-name proposal existing
+Uniquify the string @var{proposal} against the list of strings
+ var{existing}   Uses the format string @code{uniquify-name-format} to
+generate unique names.
 @end defun
 
- defun get-window-by-class class
-Return a window object with class @var{class}, or @code{nil}.
+ defvar uniquify-name-format
+Format to create unique window names.  Defaults to @code{"%s [%d]"}.
+ end defvar
+
+ deffn Function uniquify-window-name window
+ deffnx Command uniquify-window-name window
+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 get-window-by-class-re class
-Return a window object with class matching regular expression
- var{class}, or @code{nil}.
+ defun window-class window
+Return the class that @var{window} belongs to as a string, or nil if
+ var{window} has no associated class.
 @end defun
 
- defun activate-window window
-Do everything necessary to make @var{window} active, including raising
-it, giving it focus, etc.  Certain steps may be skipped (e.g., giving
-focus) if the window doesn't allow that operation.
+ defun window-id window
+If window object @var{window} has a client window associated with,
+return an integer defining its xid, otherwise return @code{nil}.
 @end defun
 
- defun filter-windows pred
-Return the list of windows (mapped or unmapped) that match the
-predicate function @var{pred}.
+ defun root-window-id
+Returns the numeric ID of the root window of the managed screen.
 @end defun
 
- defun map-windows function
-Call @code{(@var{function} @var{window})} on all existing windows.
-Returns the value of the last @var{function} invocation.  If any
- var{function} returns @code{nil}, @code{map-windows} returns
- code{nil} immediately.
+ defun window-dimensions window
+Returns a cons cell @code{(@var{width} . @var{height})} defining the
+dimensions of the client window associated with object @var{window}.
 @end defun
 
- defun window-class window
-Return the class that @var{window} belongs to as a string, or nil if
- var{window} has no associated class.
+ defun window-position window
+Returns a cons-cell @code{(@var{x} . @var{y})} defining the position
+relative to the root window of @var{window}.
 @end defun
 
 @defun get-window-wm-protocols window
 Return a list of symbols defining the X11 window manager protocols
 supported by client @var{window}.
 @end defun
+
 @defun window-supports-wm-protocol-p window atom
 Return true if @var{window} includes @var{atom} in its
 @code{WM_PROTOCOLS} property.
 @end defun
 
- menu
-Basics:
-* Window Property Lists::
-* Window Types::
-* Window Attributes::
-* Input Focus::
-* X Properties::
-* Window Groups::
+ noindent
+Listed here are window visibility predicates:
+ code{stacking-visibility}, @code{window-obscured} (@pxref{Stacking
+Visibility}), @code{window-visible-p} (@pxref{Showing and Hiding
+Windows}), @code{window-shaped-p} (@pxref{Shading Windows}),
+ code{window-iconified-p} (@pxref{Iconifying Windows}),
+ code{window-in-workspace-p} (@pxref{Workspaces and Windows}),
+ code{window-outside-viewport-p} (@pxref{Windows and Viewports}).
 
 @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::
+Various predicates:
+ defun window-mapped-p window
+Return @code{t} if the client window associated with object
+ var{window} is mapped. (Note that this doesn't necessarily mean that
+it is visible.)
+ end defun
+
+ defun window-shaped-p window
+Return @code{t} if @var{window} is shaped (possibly not rectangular).
+ end defun
+
+ defun window-urgent-p window
+Return @code{t} if the ``Urgency'' hint of the window associated with
+ var{window} is set.
+ end defun
+
+ defun window-wants-input-p window
+ defunx window-really-wants-input-p window
+See @xref{Input Focus}.
+ end defun
+
+ node Getting Windows, Window Property Lists, Window Attributes, Windows
+ section Getting Windows
+ cindex Getting Windows
+
+First, functions which treat all windows.
+
+ defun managed-windows
+Returns a list containing all managed window objects, in the order that
+they were adopted by the window manager (first to last).
+ end defun
+
+ defun map-windows function
+Call @code{(@var{function} @var{window})} on all existing windows.
+Returns the value of the last @var{function} invocation.  If any
+ var{function} returns @code{nil}, @code{map-windows} returns
+ code{nil} immediately.
+ end defun
 
 @noindent
-Windows with special properties:
-* Window Stickiness::
-* Ignored Windows::
-* Avoided Windows::
- end menu
+Functions to get specific windows.
 
+ defun get-window-by-id xid
+Return a window object with id @var{xid}, or @code{nil}.
+ end defun
 
- node Window Property Lists, Window Types, , Windows
+ defun get-window-by-name name
+Return a window object with name @var{name}, or @code{nil}.
+ end defun
+
+ defun get-window-by-name-re name
+Return a window object with name matching regular expression
+ var{name}, or @code{nil}.
+ end defun
+
+ defun get-window-by-class class
+Return a window object with class @var{class}, or @code{nil}.
+ end defun
+
+ defun get-window-by-class-re class
+Return a window object with class matching regular expression
+ var{class}, or @code{nil}.
+ end defun
+
+ defun filter-windows pred
+Return the list of windows (mapped or unmapped) that match the
+predicate function @var{pred}.
+ end defun
+
+ node Window Property Lists, Window Types, Getting Windows, Windows
 @section Window Property Lists
 @cindex  Window property lists
 @cindex Property lists, of windows
@@ -830,7 +925,7 @@ Remove @var{property} of @var{window}. Returns @code{t} for success,
 @code{nil} if the property did not exist.
 @end defun
 
- node Window Types, Window Attributes, Window Property Lists, Windows
+ node Window Types, Input Focus, Window Property Lists, Windows
 @section Window Types
 @cindex Window types
 @cindex Types, of windows
@@ -847,8 +942,9 @@ window appears. Many windows do not have any types.
 a main application.  They tend to have less window decorations, and
 are intended to last a short time only.
 
- defun window-transient-p arg
-Returns @code{t} if @var{arg} represents a transient window.
+ defun window-transient-p window
+Returns @code{nil} if @var{window} isn't marked as a transient window.
+Otherwise returns an integer, the xid of the parent window.
 @end defun
 
 @defun mark-window-as-transient w
@@ -971,146 +1067,7 @@ docks. Defaults to
 The stacking depth of dock windows.  Defaults to 0.
 @end defvar
 
- node Window Attributes, Input Focus, Window Types, Windows
- section Window Attributes
- cindex Window attributes
- cindex Attributes, of windows
- cindex Windows, attributes of
-
- defun window-name window
-Return the name associated with @var{window}.
- end defun
-
- defun window-full-name window
-Return the full-name associated with @var{window}. This may or may not
-be the same as the normal name.
- end defun
-
-Sawfish provides functions to ensure that window names are unique.
-
- defun uniquify-name proposal existing
-Uniquify the string @var{proposal} against the list of strings
- var{existing}   Uses the format string @code{uniquify-name-format} to
-generate unique names.
- end defun
-
- defvar uniquify-name-format
-Format to create unique window names.  Defaults to @code{"%s [%d]"}.
- end defvar
-
- deffn Function uniquify-window-name window
- deffnx Command uniquify-window-name window
-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
-
- defun window-mapped-p window
-Return @code{t} if the client window associated with object
- var{window} is mapped. (Note that this doesn't necessarily mean that
-it is visible.)
- end defun
-
- defun window-transient-p window
-Returns @code{nil} if @var{window} isn't marked as a transient window.
-Otherwise returns an integer, the xid of the parent window.
- end defun
-
- defun window-shaped-p window
-Return @code{t} if @var{window} is shaped (possibly not rectangular).
- end defun
-
- defun window-id window
-If window object @var{window} has a client window associated with,
-return an integer defining its xid, otherwise return @code{nil}.
- end defun
-
- defun root-window-id
-Returns the numeric ID of the root window of the managed screen.
- end defun
-
- defun window-group-id window
-If @var{window} is part of a group, return the X window id of the
-leader of that group.  Otherwise return @code{nil}.
- end defun
-
- defun window-wants-input-p window
-Return @code{t} when the client window associated with object
- var{window} has asked for the input focus to be assigned to it when
-applicable (through the @code{input} field of its @code{WM_HINTS}
-property).
- end defun
-
- defun window-really-wants-input-p window
-Return @code{nil} if the client window associated with object
- var{window} should never be focused, @code{t} otherwise.
- end defun
-
- defun window-dimensions window
-Returns a cons cell @code{(@var{width} . @var{height})} defining the
-dimensions of the client window associated with object @var{window}.
- end defun
-
- defun window-position window
-Returns a cons-cell @code{(@var{x} . @var{y})} defining the position
-relative to the root window of @var{window}.
- end defun
-
- defun window-size-hints window
-Return an alist defining the size-hints structure specified by the
-client window associated with @var{window}. Possible keys in the alist
-are @code{min-height}, @code{max-height}, @code{min-width},
- code{max-width}, @code{height-inc}, @code{width-inc},
- code{min-aspect}, @code{max-aspect}, @code{base-height},
- code{base-width}, @code{user-position}, @code{program-position},
- code{user-size}, @code{program-size}, @code{window-gravity},
- code{border-size} 
- end defun
-
- defun stacking-visibility window
-Returns @code{unobscured} if @code{window} is unobscured,
- code{fully-obscured} if one or more windows completely obscure
- code{window}, or @code{partially-obscured} if one or more window
-partially obscure @code{window}.
-
-Deciding between fully and partially obscured can be expensive.  If
- code{window-obscured} satisfies your needs, use that in preference to
- code{stacking-visibility} 
- end defun
-
- defun window-obscured window
-Returns @code{nil} if @code{window} is unobscured, @code{t} if
- code{window} is completely obscured by exactly one other window, or a
-list of windows that partially obscure @code{window}.
-
-If a list of partially obscuring windows is returned, taken together
-they may or may not fully obscure @code{window}.
- end defun
-
- deffn {Obsolete Function} window-visibility window
-Returns a symbol defining the current visibility of @var{window}.
-Possible returned symbols are @code{fully-obscured},
- code{partially-obscured} or @code{unobscured}.
-
- code{window-visibility} is deprecated.  It is unreliable when using
-the Composite extention, as every window is reported unobscured.  Use
- code{window-obscured} and @code{stacking-visibility} instead.
- end deffn
-
- defun window-urgent-p window
-Return @code{t} if the ``Urgency'' hint of the window associated with
- var{window} is set.
- end defun
-
-
- node Input Focus, X Properties, Window Attributes, Windows
+ node Input Focus, X Properties, Window Types, Windows
 @section Input Focus
 @cindex Input focus
 @cindex Keyboard focus
@@ -1131,6 +1088,21 @@ Sets the focus to the client window associated with @var{window}.
 If @var{window} is @code{nil}, then no window will have the focus.
 @end defun
 
+ defun window-wants-input-p window
+If you're unsure, use @code{window-really-wants-input-p} function
+described below.
+
+Return @code{t} when the window @var{window} wants input focus in X
+sense, i.e. if it has asked for the input focus to be assigned to,
+through the @code{input} field of its @code{WM_HINTS} property.
+ end defun
+
+ defun window-really-wants-input-p window
+Like @code{window-wants-input-p}, but in addition, this function also
+takes into account user option provided by Sawfish, i.e. if the window
+has @code{never-focus} property or not.
+ end defun
+
 The window manager is responsible for switching the input focus from
 client window to client window.  Sawfish implements several
 @dfn{focus modes} that provide this behavior.  Each focus mode is
@@ -1307,6 +1279,9 @@ When true, focusing a window doesn't change it's position in the stack of
 most-recently focused windows.
 @end defvar
 
+ noindent
+Other focus related functions:
+
 @defun window-in-cycle-p window &keyword ignore-cycle-skip
 Returns @code{t} if the window @var{window} should be included when
 cycling between windows.  Desktop windows and those with the
@@ -1432,7 +1407,7 @@ Arrange for function @var{fun} to be called with arguments
 to monitor.
 @end defun
 
- node Window Groups, Window Stacking, X Properties, Windows
+ node Window Groups, Activating Window, X Properties, Windows
 @section Window Groups
 @cindex Groups, windows
 
@@ -1451,6 +1426,11 @@ 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-id window
+If @var{window} is part of a group, return the X window id of the
+leader of that group.  Otherwise return @code{nil}.
+ end defun
+
 @defun window-group-ids
 Return the list of all group ids.
 @end defun
@@ -1604,22 +1584,55 @@ These operate like their single-window counterparts.
 This operates like its single-window counterpart.
 @end defun
 
- node Window Stacking, Moving and Resizing Windows, Window Groups, Windows
+ node Activating Window, Window Stacking, Window Groups, Windows
+ section Activating Window
+ cindex Activating Window
+ cindex Activation, of a window
+
+When user wants to use a window, displaying, focusing, raising, etc,
+are necessary. Functions in this section do such jobs.
+
+ defun display-window window
+Roughly speaking, do everything necessary to make @var{window} ready
+for user.
+
+The operations are done in the following order. If the window is
+iconified, it gets un-iconified. The workspace and the viewport in
+which the window lies is selected. Unshade if necessary. (See
+ code{unshade-selected-windows} variable below.) Then call the
+ code{activate-window} function described below.
+
+It is defined in @code{sawfish.wm.util.display-window} module.
+ end defun
+
+ defun activate-window window
+Raise, focus, warp pointer if necessary, and mark the window as the
+top of window order. Don't focus if the window doesn't allow that
+operation.
+ end defun
+
+ defvr Customizable unshade-selected-windows
+When non-nil, unshade windows when selected.
+ end defvr
+
+ node Window Stacking, Moving and Resizing Windows, Activating Window, Windows
 @section Window Stacking
 @cindex Window stacking
 @cindex Stacking, of windows
 @cindex Windows, stacking
 
 The stacking order of the display defines the order in which windows
-are shown, from topmost to bottommost.  Sawfish maintains this list.
-Raising or lowering windows changes their positions in this list.
+are shown, from topmost to bottommost. It's Sawfish that maintains
+this list.  Raising or lowering windows changes their positions in
+this list.
 
 @menu
 * Stacking Order::
+* Stacking Visibility::
 * Raising and Lowering Windows::
 @end menu
 
- node Stacking Order, Raising and Lowering Windows, Window Stacking, Window Stacking
+ node Stacking Order, Stacking Visibility, Window Stacking, Window Stacking
 @subsection Stacking Order
 
 @defun stacking-order
@@ -1690,7 +1703,45 @@ consistent state including window @var{w}. This is achieved by raising
 or lowering window W as appropriate.
 @end defun
 
- node Raising and Lowering Windows,  , Stacking Order, Window Stacking
+ node Stacking Visibility,  Raising and Lowering Windows, Stacking Order, Window Stacking
+ subsection Stacking Visibility
+ cindex Visibility, stacking
+ cindex Stacking, visibility
+ cindex Covering, of windows
+
+There're functions which tell how the window is covered by others.
+
+ defun stacking-visibility window
+Returns @code{unobscured} if @code{window} is unobscured,
+ code{fully-obscured} if one or more windows completely obscure
+ code{window}, or @code{partially-obscured} if one or more window
+partially obscure @code{window}.
+
+Deciding between fully and partially obscured can be expensive.  If
+ code{window-obscured} satisfies your needs, use that in preference to
+ code{stacking-visibility} 
+ end defun
+
+ defun window-obscured window
+Returns @code{nil} if @code{window} is unobscured, @code{t} if
+ code{window} is completely obscured by exactly one other window, or a
+list of windows that partially obscure @code{window}.
+
+If a list of partially obscuring windows is returned, taken together
+they may or may not fully obscure @code{window}.
+ end defun
+
+ deffn {Obsolete Function} window-visibility window
+Returns a symbol defining the current visibility of @var{window}.
+Possible returned symbols are @code{fully-obscured},
+ code{partially-obscured} or @code{unobscured}.
+
+ code{window-visibility} is deprecated.  It is unreliable when using
+the Composite extention, as every window is reported unobscured.  Use
+ code{window-obscured} and @code{stacking-visibility} instead.
+ end deffn
+
+ node Raising and Lowering Windows,  , Stacking Visibility, Window Stacking
 @subsection Raising and Lowering Windows
 @cindex Windows, raising
 @cindex Windows, lowering
@@ -1739,9 +1790,10 @@ possibly associated windows to the bottom of their level, otherwise
 raise them to the top of their level.
 @end deffn
 
- defvar user-raise-type
-Indicates which windows the @code{lower-window*}, @code{raise-window*}
-and @code{raise-lower-window*} functions affect.  This variable can be
+ defvr Customizable user-raise-type
+This user option indicates which windows the @code{lower-window*},
+ code{raise-window*} and @code{raise-lower-window*} functions affect.
+This variable can be
 
 @table @code
 @item none
@@ -1753,7 +1805,7 @@ This is the default.
 The specific argument window and all windows in its group are
 affected.
 @end table
- end defvar
+ end defvr
 
 @defun maybe-raise-window w
 If window @var{w} supports the @code{_SAWFISH_WM_RAISE_WINDOW}
@@ -1863,6 +1915,17 @@ The @var{hints} parameters is either the size hints alist to use, or
 to retrieve the window's hints.
 @end defun
 
+ defun window-size-hints window
+Return an alist defining the size-hints structure specified by the
+client window associated with @var{window}. Possible keys in the alist
+are @code{min-height}, @code{max-height}, @code{min-width},
+ code{max-width}, @code{height-inc}, @code{width-inc},
+ code{min-aspect}, @code{max-aspect}, @code{base-height},
+ code{base-width}, @code{user-position}, @code{program-position},
+ code{user-size}, @code{program-size}, @code{window-gravity},
+ code{border-size} 
+ end defun
+
 Usually, however, it is left to the user to configure windows. The
 following functions may be called interactively: their sole argument is
 then either the window that received the current event or the currently
@@ -2782,6 +2845,10 @@ Return an image object representing the icon currently associated with
 @var{window}, or @code{nil} if there is no such image.
 @end defun
 
+ defun window-icon-name window
+Return the icon name associated with @var{window}.
+ end defun
+
 @node Window Stickiness, Ignored Windows, Iconifying Windows, Windows
 @section Window Stickiness
 @cindex Window stickiness
@@ -3052,6 +3119,11 @@ form, they declare a special variable stored in the symbol
 @var{variable}, whose value is set to @var{value} if the variable is
 currently unbound, with a documentation string @var{documentation}.
 
+In the configurator, gtk widget appears left to the docstring. But if
+the docstring ends with ``\\w'' (literally in the source; the first
+backslash for escaping the second), then the widget is put right to
+the text. This feature is supported by only some widgets.
+
 All other parameters are key-value pairs as with @code{defgroup}. The
 possible pairs are as follows:
 
@@ -6971,10 +7043,6 @@ An optional, window-local, keymap. @xref{Keymaps}.
 When set, and click-to-focus mode is enabled, the click that focuses a
 window is passed through to the client window.
 
- item ignore-window-input-hint
-When set the value of the window's input hint is ignored, i.e. the
-focus @emph{will} be given to the window when appropriate
-
 @item never-focus
 When set the window will @emph{never} be given the input focus
 
diff --git a/src/events.c b/src/events.c
index 6daefd7..629799c 100644
--- a/src/events.c
+++ b/src/events.c
@@ -1364,7 +1364,10 @@ ungrab_pointer (void)
 /* Window-local event handlers */
 
 /* Register that FUN should be called for any events received from
-   the window with id W. */
+   the window with id W.
+
+   Currently used for windows created by Sawfish: edge-flip,
+   display-message, and x-create-window. */
 void
 register_event_handler (Window w, void (*fun)(XEvent *ev))
 {
@@ -1479,7 +1482,11 @@ handle_input_mask(long mask)
     commit_queued_focus_change ();
 }
 
-/* Handle all available X events on file descriptor FD. */
+/* Handle all available X events on file descriptor FD.
+   ... Well, this comment has been around for years, but FD is ignored...
+
+   This is the entrance of Sawfish event loop.
+ */
 void
 handle_sync_input (int fd)
 {
diff --git a/src/windows.c b/src/windows.c
index 330f763..7239f64 100644
--- a/src/windows.c
+++ b/src/windows.c
@@ -1025,8 +1025,11 @@ DEFUN("window-wants-input-p", Fwindow_wants_input_p, Swindow_wants_input_p,
 ::doc:sawfish.wm.windows.subrs#window-wants-input-p::
 window-wants-input-p WINDOW
 
-Return t if the client window associated with object WINDOW has hinted
+Return t if the WINDOW wants focus in X sense, i.e. if it has hinted
 that it would like to be given the input focus when applicable.
+
+If unsure, use `window-really-wants-input-p' which also takes into
+account `never-focus' window property.
 ::end:: */
 {
     rep_DECLARE1(win, WINDOWP);
@@ -1087,6 +1090,9 @@ window-visibility WINDOW
 
 Return a symbol defining the visibility of WINDOW. Possible returned
 symbols are `fully-obscured', `partially-obscured' or `unobscured'.
+
+This function is deprecated. Instead use `window-obscured' and
+`stacking-visibility'.
 ::end:: */
 {
     repv sym = Qnil;
@@ -1194,7 +1200,8 @@ DEFUN("window-visible-p", Fwindow_visible_p, Swindow_visible_p,
 ::doc:sawfish.wm.windows.subrs#window-visible-p::
 window-visible-p WINDOW
 
-Return t if WINDOW is currently visible (i.e. not hidden, see `hide-window').
+Return t if WINDOW is not hidden by `hide-window'. Notice there're
+various cases where a window is not visible.
 ::end:: */
 {
     rep_DECLARE1(win, WINDOWP);