[sawfish] Doc changes.

[Christopher Bratusek <chrisb src gnome org>]

commit e82754b5de114d9c7dd6f49347bfd7d3b36067f0
Author: Teika kazura <teika lavabit com>
Date:   Sat Jan 9 13:01:23 2010 +0900

    Doc changes.
    
    Corrections and descrption / format improvements in grow, pack, shrink and yank.
    Verbose instruction on how to compile docs.
    Describes exactly what 'obsolete' variables are.
    Comments in sourecs.

 lisp/sawfish/cfg/wm.jl                  |    2 +-
 lisp/sawfish/wm/commands/grow-pack.jl   |   20 +++---
 lisp/sawfish/wm/commands/shrink-yank.jl |   10 ++-
 lisp/sawfish/wm/util/compat.jl          |    9 ++-
 lisp/sawfish/wm/util/nokogiri.jl        |    2 +-
 man/Makefile.in                         |    8 ++-
 man/faq.texi                            |    2 +
 man/news.texi                           |    2 +
 man/sawfish.texi                        |  132 +++++++++++--------------------
 9 files changed, 82 insertions(+), 105 deletions(-)
---
diff --git a/lisp/sawfish/cfg/wm.jl b/lisp/sawfish/cfg/wm.jl
index 93ffeba..6f85b63 100644
--- a/lisp/sawfish/cfg/wm.jl
+++ b/lisp/sawfish/cfg/wm.jl
@@ -1,4 +1,4 @@
-;; nokogiri-wm.jl -- WM communication
+;; wm.jl -- interface to WM as a server
 ;;
 ;; Copyright (C) 2000 John Harper <john dcs warwick ac uk>
 ;;
diff --git a/lisp/sawfish/wm/commands/grow-pack.jl b/lisp/sawfish/wm/commands/grow-pack.jl
index f5399c9..027dfce 100644
--- a/lisp/sawfish/wm/commands/grow-pack.jl
+++ b/lisp/sawfish/wm/commands/grow-pack.jl
@@ -20,9 +20,9 @@
 
 ;; This package provides functions to `grow' or `pack' a window in four
 ;; directions.  `Growing' means to grow the window in the indicated
-;; direction until it `bumps into' another window or by a given amount.
+;; direction until it touches another window or by a given amount.
 ;; `Packing' means to move the window in the indicated direction until
-;; it `bumps into' another window or by a given amount.
+;; it touches another window or by a given amount.
 
 (define-structure sawfish.wm.commands.grow-pack
 
@@ -101,17 +101,17 @@ Only `avoided' windows are bumped."
   ;; Entry points.
 
   (define (grow-window-left w #!optional arg)
-    "Grows window to the left until it `bumps into' another window.
+    "Grows window to the left until it touches another window.
 See `grow-window-up'."
     (grow-window w 'left arg))
 
   (define (grow-window-right w #!optional arg)
-    "Grows window to the right until it `bumps into' another window.
+    "Grows window to the right until it touches another window.
 See `grow-window-up'."
     (grow-window w 'right arg))
 
   (define (grow-window-up w #!optional arg)
-    "Grows window upwards until it `bumps into' another window.
+    "Grows window upwards until it touches another window.
 If the top edge was beyond the screen edge, it is brought back in.
 With a universal prefix arg, maximize upwards instead.
 With a numeric prefix arg, grow upwards by that many increments specified by
@@ -119,29 +119,29 @@ window or pixels instead."
     (grow-window w 'up arg))
 
   (define (grow-window-down w #!optional arg)
-    "Grows window downwards until it `bumps into' another window.
+    "Grows window downwards until it touches another window.
 See `grow-window-up'."
     (grow-window w 'down arg))
 
   (define (pack-window-left w #!optional arg)
-    "Moves window to the left until it `bumps into' another window.
+    "Moves window to the left until it touches another window.
 See `pack-window-up'."
     (pack-window w 'left arg))
 
   (define (pack-window-right w #!optional arg)
-    "Moves window to the right until it `bumps into' another window.
+    "Moves window to the right until it touches another window.
 See `pack-window-up'."
     (pack-window w 'right arg))
 
   (define (pack-window-up w #!optional arg)
-    "Moves window upwards until it `bumps into' another window.
+    "Moves window upwards until it touches another window.
 If the top edge was beyond the screen edge, it is moved back in.
 With a universal prefix arg, move upwards maximally instead.
 With a numeric prefix arg, move upwards by that many pixels instead."
     (pack-window w 'up arg))
 
   (define (pack-window-down w #!optional arg)
-    "Moves window downwards until it `bumps into' another window.
+    "Moves window downwards until it touches another window.
 See `pack-window-up'."
     (pack-window w 'down arg))
 
diff --git a/lisp/sawfish/wm/commands/shrink-yank.jl b/lisp/sawfish/wm/commands/shrink-yank.jl
index 54080b3..81b9db8 100644
--- a/lisp/sawfish/wm/commands/shrink-yank.jl
+++ b/lisp/sawfish/wm/commands/shrink-yank.jl
@@ -46,6 +46,8 @@
 
   (define-structure-alias shrink-yank sawfish.wm.commands.shrink-yank)
 
+;;; Customization options are defined in grow-pack.jl
+
 ;;; Commands:
 
   (define (shrink-window-left window)
@@ -69,22 +71,22 @@ overlaps with one less window than before."
     (shrink-window window 'down))
 
   (define (yank-window-left window)
-    "Yanks WINDOW to the left until it overlaps with one less window
+    "Moves WINDOW to the left until it overlaps with one less window
 than before."
     (yank-window window 'left))
 
   (define (yank-window-right window)
-    "Yanks WINDOW to the right until it overlaps with one less window
+    "Moves WINDOW to the right until it overlaps with one less window
 than before."
     (yank-window window 'right))
 
   (define (yank-window-up window)
-    "Yanks WINDOW upwards until it overlaps with one less window than
+    "Moves WINDOW upwards until it overlaps with one less window than
 before."
     (yank-window window 'up))
 
   (define (yank-window-down window)
-    "Yanks WINDOW downwards until it overlaps with one less window than
+    "Moves WINDOW downwards until it overlaps with one less window than
 before."
     (yank-window window 'down))
 
diff --git a/lisp/sawfish/wm/util/compat.jl b/lisp/sawfish/wm/util/compat.jl
index 56d2917..2e14f68 100644
--- a/lisp/sawfish/wm/util/compat.jl
+++ b/lisp/sawfish/wm/util/compat.jl
@@ -1,4 +1,4 @@
-;; compat.jl -- aliases for obsolete functions
+;; compat.jl -- support for obsolete functions and variables
 
 ;; Copyright (C) 1999 John Harper <john dcs warwick ac uk>
 
@@ -35,7 +35,7 @@
 	  sawfish.wm.commands
 	  sawfish.wm.workspace)
 
-;;; obsolete functions
+;;; obsolete functions are collected here
 
   (define (show-message #!optional text font fg bg position)
     (let ((attrs nil))
@@ -49,6 +49,7 @@
 	(setq attrs (cons (cons 'position position) attrs)))
       (display-message text attrs)))
 
+  ;; Define alias for Renamed functions. 
   (define ws-copy-window copy-window-to-workspace)
   (define ws-move-window move-window-to-workspace)
   (define ws-insert-workspace insert-workspace)
@@ -80,6 +81,10 @@
 
 ;;; obsolete options
 
+  ;; 1. If these options are set in ~/.sawfish/custom, then they are
+  ;;    ignored. This means the next time you save the file `custom',
+  ;;    they are removed.
+  ;; 2. You can't set value to them via custom related methods.
   (mapc (lambda (x)
 	  (put x 'custom-obsolete t))
 	'(viewport-columns viewport-rows preallocated-workspaces
diff --git a/lisp/sawfish/wm/util/nokogiri.jl b/lisp/sawfish/wm/util/nokogiri.jl
index 9ada0de..7e2e744 100644
--- a/lisp/sawfish/wm/util/nokogiri.jl
+++ b/lisp/sawfish/wm/util/nokogiri.jl
@@ -1,4 +1,4 @@
-;; nokogiri-sawfish.jl -- code to load into window manager
+;; nokogiri.jl -- interface to sawfish-config
 ;;
 ;; Copyright (C) 2000 John Harper <john dcs warwick ac uk>
 ;;
diff --git a/man/Makefile.in b/man/Makefile.in
index 2f976b6..bcbff9b 100644
--- a/man/Makefile.in
+++ b/man/Makefile.in
@@ -36,18 +36,24 @@ all : sawfish.info ../NEWS ../USERDOC ../FAQ
 ../USERDOC : user-doc.texi
 	$(MAKEINFO) $(MAKEINFOFLAGS) --no-headers $< -o ../USERDOC
 
+# Usually this suffices:
+# makeinfo --no-validate  --no-headers news.texi > ../NEWS
 ../NEWS : news.texi
 	$(MAKEINFO) $(MAKEINFOFLAGS) --no-validate --no-headers $< -o ../NEWS
 
+# Usually this suffices:
+# makeinfo --no-validate  --no-headers news.texi > ../FAQ
 ../FAQ : faq.texi
 	$(MAKEINFO) $(MAKEINFOFLAGS) --no-validate --no-headers $< -o ../FAQ
 
+# Usually this suffices:
+# makeinfo  -I . sawfish.texi -o sawfish.info
 sawfish.info : $(SRCS)
 	$(MAKEINFO) $(MAKEINFOFLAGS) -I $(srcdir) $< -o sawfish.info
 
 install : sawfish.info installdirs
 	for f in sawfish.info*; do \
- 	  $(INSTALL_DATA) $$f $(DESTDIR)$(infodir); \
+	  $(INSTALL_DATA) $$f $(DESTDIR)$(infodir); \
 	done
 	-install-info --info-dir=$(DESTDIR)$(infodir) sawfish.info
 	for f in sawfish*.1; do \
diff --git a/man/faq.texi b/man/faq.texi
index 2f2dbb2..1619eac 100644
--- a/man/faq.texi
+++ b/man/faq.texi
@@ -1,5 +1,7 @@
 @c -*- texinfo -*-
 
+ c To compile: makeinfo --no-validate  --no-headers faq.texi > FAQ
+
 @chapter Frequently Asked Questions
 
 @enumerate
diff --git a/man/news.texi b/man/news.texi
index af67fbe..c86a82b 100644
--- a/man/news.texi
+++ b/man/news.texi
@@ -1,5 +1,7 @@
 @c -*- texinfo -*-
 
+ c To compile: makeinfo --no-validate  --no-headers news.texi > NEWS
+
 @chapter News
 
 This lists the user-visible changes made to Sawfish, and which releases
diff --git a/man/sawfish.texi b/man/sawfish.texi
index 3a7e3d7..5be59c8 100644
--- a/man/sawfish.texi
+++ b/man/sawfish.texi
@@ -1,4 +1,7 @@
 \input texinfo  @c -*-Texinfo-*-
+
+ c To compile: makeinfo  -I . sawfish.texi -o sawfish.info
+
 @setfilename sawfish.info
 @settitle sawfish Programming Manual
 @footnotestyle end
@@ -1891,108 +1894,65 @@ resize that window.
 @end deffn
 
 @deffn Command double-window-size window
-Double the size of @var{window}
- end deffn
-
- deffn Command halve-window-size window
-Halve the size of @var{window}
+ deffnx Command halve-window-size window
+Double / halve the size of @var{window}
 @end deffn
 
-Sawfish supports increasing a windows size until it bumps into another
+Sawfish supports increasing the windows size until it touches another
 window. This is called ``grow''. ``Shrink'' achieves the opposite,
-i.e. it decreases a windows size, until it does no longer overlap any
-other window, or more precisely, until it overlaps with one less window.
+i.e. it decreases the windows size, until it does no longer overlap any
+other window. More precisely, the grow can be done repeatedly, each
+time until the edge meets another edge, and shrink is done so that
+it overlaps with one less window.
 
 @deffn Command grow-window-up window #!optional arg
-Grows @var{window} upwards until it "bumps into" another window.
-If the top edge was beyond the screen edge, it is brought back in.
-With a universal prefix @var{arg}, maximize upwards instead. With a numeric
-prefix @var{arg}, grow upwards by that many increments specified by
-window or pixels instead.
- end deffn
-
- deffn Command grow-window-down window #!optional arg
-Grows @var{window} downwards until it "bumps into" another window.
-See @code{grow-window-up}.
- end deffn
-
- deffn Command grow-window-left window #!optional arg
-Grows @var{window} left until it "bumps into" another window.
-See @code{grow-window-up}.
- end deffn
-
- deffn Command grow-window-right window #!optional arg
-Grows @var{window} right until it "bumps into" another window.
-See @code{grow-window-up}.
+ deffnx Command grow-window-down window #!optional arg
+ deffnx Command grow-window-left window #!optional arg
+ deffnx Command grow-window-right window #!optional arg
+Grows @var{window} upwards / downwards / left / right until it touches
+another window.  If that edge is beyond the screen edge, it is
+brought back in. With a universal prefix @var{arg}, maximize in that
+direction instead. With a numeric prefix @var{arg}, grow by that many
+increments specified by window or pixels instead.
 @end deffn
 
 @deffn Command shrink-window-up window
-Shrinks @var{window} by moving the lower edge upwards until it
-intersects with one window less than before.
- end deffn
-
- deffn Command shrink-window-down window
-Shrinks @var{window} by moving the upper edge downwards until it
-intersects with one window less than before.
- end deffn
-
- deffn Command shrink-window-left window
-Shrinks @var{window} by moving the right edge to the left until it
-intersects with one window less than before.
- end deffn
-
- deffn Command shrink-window-right window
-Shrinks @var{window} by moving the left edge to the right until it
-intersects with one window less than before.
+ deffnx Command shrink-window-down window
+ deffnx Command shrink-window-left window
+ deffnx Command shrink-window-right window
+Shrinks @var{window} by moving one edge upwards / downwards / left /
+right until it intersects with one window less than before. (So,
+in @code{shrink-window-up} for example, the lower edge is moved.)
+
+Window won't be made smaller than the minimum size, or
+ code{shrink-window-minimum-size}  More precisely, size truncation
+may make the window smaller than these values.
 @end deffn
 
 Moving counterparts, instead of resizing of ``grow'' and ``shrink'',
-are ``pack'' and ``yank''. So, ``pack'' moves until the window bumps
-into another, and ``yank'' moves until the overlap reduces.
+are ``pack'' and ``yank''. So, ``pack'' moves until the window touches
+another, and ``yank'' moves until the overlap reduces.
 
 @deffn Command pack-window-up window #! optional arg
-Moves @var{window} upwards until it "bumps into" another window.
-If the top edge was beyond the screen edge, it is moved back in.
-With a universal prefix @var{arg}, move upwards maximally instead.
-With a numeric prefix @var{arg}, move upwards by that many pixels instead.
- end deffn
-
- deffn Command pack-window-down #!optional arg
-Moves @var{window} downwards until it "bumps into" another window.
-See @code{pack-window-up}.
- end deffn
-
- deffn Command pack-window-left window #!optional arg
-Moves @var{window} left until it "bumps into" another window.
-See @code{pack-window-up}.
- end deffn
-
- deffn Command pack-window-right window #!optional arg
-Moves @var{window} right until it "bumps into" another window.
-See @code{pack-window-up}.
+ deffnx Command pack-window-down #!optional arg
+ deffnx Command pack-window-left window #!optional arg
+ deffnx Command pack-window-right window #!optional arg
+Moves @var{window} upwards / downwards / left /right until it touches
+another window.  If that edge is beyond the screen edge, it is moved
+back in.  With a universal prefix @var{arg}, move in that direction
+maximally instead.  With a numeric prefix @var{arg}, move by that many
+pixels instead.
 @end deffn
 
 @deffn Command yank-window-up window
-Yanks @var{window} upwards until it inserts with one window less than
-before.
+ deffnx Command yank-window-down window
+ deffnx Command yank-window-left window
+ deffnx Command yank-window-right window
+Yanks @var{window} upwards / downwards / left / right until it
+overlaps with one less window than before.
 @end deffn
 
- deffn Command yank-window-down window
-Yanks @var{window} downwards until it inserts with one window less than
-before.
- end deffn
-
- deffn Command yank-window-left window
-Yanks @var{window} left until it inserts with one window less than
-before.
- end deffn
-
- deffn Command yank-window-right window
-Yanks @var{window} right until it inserts with one window less than
-before.
- end deffn
-
-grow, pack, shrink and yank behavior can be customized through the
+Grow, pack, shrink and yank behavior can be customized through the
 following variables:
 
 @defvar grow-is-maximize
@@ -2034,8 +1994,8 @@ The default value is @code{10}.
 @end defvar
 
 @defvar yank-window-minimum-visible
-The minimum amount of window left visible, if yanked over the edge.
-The default value is @code{10}.
+The minimum amount of window left visible, if yanked over the screen
+edge. The default value is @code{10}.
 @end defvar
 
 @deffn Command move-window-center windows