[sawfish] Doc. Comments in source to prevent error during init. Comment on _SAWFISH_WM_RAISE_WINDOW and _SAWFI

[Christopher Bratusek <chrisb src gnome org>]

commit 6bde4cd86d062bee2707f89fedaa7b2e16bd2b36
Author: Teika kazura <teika lavabit com>
Date:   Sat Feb 27 13:17:47 2010 +0900

    Doc.
    Comments in source to prevent error during init.
    Comment on _SAWFISH_WM_RAISE_WINDOW and _SAWFISH_WM_LOWER_WINDOW.
    `select-window' returns nil for the root window.

 lisp/sawfish/wm/commands.jl         |    6 ++++++
 lisp/sawfish/wm/custom.jl           |    6 ++++++
 lisp/sawfish/wm/misc.jl             |    6 ++++++
 lisp/sawfish/wm/state/iconify.jl    |    4 +++-
 lisp/sawfish/wm/util/with-output.jl |    6 ++++++
 lisp/sawfish/wm/windows.jl          |    8 ++++++++
 man/sawfish.texi                    |    6 +++++-
 7 files changed, 40 insertions(+), 2 deletions(-)
---
diff --git a/lisp/sawfish/wm/commands.jl b/lisp/sawfish/wm/commands.jl
index 812e9ad..db4e420 100644
--- a/lisp/sawfish/wm/commands.jl
+++ b/lisp/sawfish/wm/commands.jl
@@ -41,6 +41,12 @@
 	  rep.regexp
 	  rep.util.autoloader
 	  rep.lang.doc
+	  #|
+	    Don't add more sawfish.wm.* here unless you know what
+	    you're doing. Instead, embed 'require' in definition. It's
+	    because this file is read from windows.jl. See windows.jl
+	    for more.
+	  |#
 	  sawfish.wm.misc
 	  sawfish.wm.events
 	  sawfish.wm.windows.subrs
diff --git a/lisp/sawfish/wm/custom.jl b/lisp/sawfish/wm/custom.jl
index 9cba39c..5f3ca4b 100644
--- a/lisp/sawfish/wm/custom.jl
+++ b/lisp/sawfish/wm/custom.jl
@@ -56,6 +56,12 @@
 	  rep.data.tables
 	  rep.structures
 	  rep.system
+	  #|
+	     Don't add more sawfish.wm.* here unless you know what
+	     you're doing. Instead, embed 'require' in
+	     definition. It's because this file is read from
+	     windows.jl. See windows.jl for more.
+	  |#
 	  sawfish.wm.commands
 	  sawfish.wm.gaol
 	  sawfish.wm.colors
diff --git a/lisp/sawfish/wm/misc.jl b/lisp/sawfish/wm/misc.jl
index e247438..129905b 100644
--- a/lisp/sawfish/wm/misc.jl
+++ b/lisp/sawfish/wm/misc.jl
@@ -24,6 +24,12 @@
 		   rep.regexp
 		   rep.module-system
 		   rep.io.files
+		   #|
+		     Don't add more sawfish.wm.* here unless you know
+		     what you're doing. Instead, embed 'require' in
+		     definition. It's because this file is read
+		     from windows.jl. See windows.jl for more.
+		   |#
 		   sawfish.wm.windows.subrs
 		   sawfish.wm.events))
 
diff --git a/lisp/sawfish/wm/state/iconify.jl b/lisp/sawfish/wm/state/iconify.jl
index 69278fb..32a3fb3 100644
--- a/lisp/sawfish/wm/state/iconify.jl
+++ b/lisp/sawfish/wm/state/iconify.jl
@@ -1,4 +1,4 @@
-;; iconify.jl -- handling window state
+;; iconify.jl -- iconification & (bah) stickiness
 
 ;; Copyright (C) 1999 John Harper <john dcs warwick ac uk>
 
@@ -18,6 +18,8 @@
 ;; along with sawfish; see the file COPYING.  If not, write to
 ;; the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.
 
+;;; By historical reason, stickiness is here, too.
+
 (define-structure sawfish.wm.state.iconify
 
     (export window-iconified-p
diff --git a/lisp/sawfish/wm/util/with-output.jl b/lisp/sawfish/wm/util/with-output.jl
index 2bdafd5..74ef1a3 100644
--- a/lisp/sawfish/wm/util/with-output.jl
+++ b/lisp/sawfish/wm/util/with-output.jl
@@ -25,6 +25,12 @@
 
     (open rep
 	  rep.regexp
+	  #|
+	    Don't add more sawfish.wm.* here unless you know what
+	    you're doing. Instead, embed 'require' in definition. It's
+	    because this file is read from windows.jl -> custom.jl.
+	    See windows.jl for more.
+	  |#
 	  sawfish.wm.misc)
 
   (define-structure-alias with-output sawfish.wm.util.with-output)
diff --git a/lisp/sawfish/wm/windows.jl b/lisp/sawfish/wm/windows.jl
index b00843d..ebb1aef 100644
--- a/lisp/sawfish/wm/windows.jl
+++ b/lisp/sawfish/wm/windows.jl
@@ -62,6 +62,12 @@
     (open rep
 	  rep.system
 	  rep.regexp
+	  #|
+	    Don't add more sawfish.wm.* here unless you know what
+	    you're doing. Instead, embed 'require' in definition.
+	    It's because this file is read in early stage of Sawfish
+	    init.
+	  |#
 	  sawfish.wm.windows.subrs
 	  sawfish.wm.gaol
 	  sawfish.wm.custom
@@ -436,6 +442,8 @@ string `uniquify-name-format' to generate unique names."
   (defvar select-window-cursor-shape 'crosshair)
 
   (define (select-window)
+    "Wait for a click, and returns the clicked window. Nil for the root
+window."
     (allow-events 'async-pointer)
     (when (grab-pointer nil select-window-cursor-shape)
       (unwind-protect
diff --git a/man/sawfish.texi b/man/sawfish.texi
index 2672996..7e2edf3 100644
--- a/man/sawfish.texi
+++ b/man/sawfish.texi
@@ -1339,7 +1339,8 @@ unclear.
 @defun select-window
 Waits for the user to left-click on a window, and returns that window.
 The mouse cursor changes shape, and all normal input events are
-suppressed until a window is selected.
+suppressed until a window is selected. For root window, @code{nil} is
+returned.
 @end defun
 
 @defvar select-window-cursor-shape
@@ -1766,6 +1767,9 @@ protocol, ask it whether it wants to lower itself or not.  Otherwise,
 lower the window unconditionally.
 @end defun
 
+These two protocols were used in nautilus, but the current situation
+is unknown.
+
 Sawfish has more general operations that raising a window to the top
 or lowering it to the bottom.  It can place a window relative to one
 or more other managed windows.