[sawfish] Doc.

[Christopher Bratusek <chrisb src gnome org>]

commit 127ea739010c22423bcbe246eff0c37988fc1a0e
Author: Teika kazura <teika lavabit com>
Date:   Sat Mar 20 13:52:57 2010 +0900

    Doc.
    
    Info "Events" chapter improvements. News revision.
    
    "Lock button" item is pushed back to "Other changes" section, reverting
    my own prerious edit. Sorry. (See comment in news.texi for the reason.)

 README           |    2 +-
 man/news.texi    |   30 ++++++++++++++++++++----------
 man/sawfish.texi |   52 +++++++++++++++++++++++++++++-----------------------
 src/keys.c       |    4 ++--
 4 files changed, 52 insertions(+), 36 deletions(-)
---
diff --git a/README b/README
index 59dc16a..ee4d53c 100644
--- a/README
+++ b/README
@@ -25,7 +25,7 @@ that may be achieved through separate applications.
 
 All high-level wm functions are implemented in Lisp for future
 extensibility or redefinition. Currently this includes menus (using
-GTK+), interactive window moving and resizing, virtual workspaces,
+GTK+), interactive window moving and resizing, virtual desktop,
 iconification, focus/transient window policies, frame theme definitions
 and much more.
 
diff --git a/man/news.texi b/man/news.texi
index e9a4600..12e63fe 100644
--- a/man/news.texi
+++ b/man/news.texi
@@ -14,7 +14,6 @@ they occurred between. For more detailed information see the
 @itemize @bullet
 
 @item The 1.6.3 release has some improvements.
-
 @itemize @minus
 @item Customizable lisp directory [Teika kazura]
 
@@ -48,16 +47,17 @@ It returns the process id of a window. (@pxref{Window Attributes}
 @end itemize
 @item Bugfixes
 @itemize @minus
- item Pressing the lock-button does the state-change of the window
-accordingly. [Fuchur]
-
 @item Unsupported option @code{ignore-window-input-hint} is deleted [Teika kazura] @*
 It has been invalid for long.
 
- item Honor maximize-raises in @code{maximize-window-fullscreen} and
- code{maximize-window-fullxinerama}, too, not just in maximize-window [Nolan Leake]
+ item Honor the user option @code{maximize-raises} in @code{maximize-window-fullscreen} and
+ code{maximize-window-fullxinerama}, too, not just in maximize-window
+[Nolan Leake]
 
- item More robustness of our fdo-menu implementation [Teika Kazura]
+ item More robustness in applications menu [Teika Kazura]
+
+It broke for 'R', and whitespace handling didn't follow the specification.
+Phony constants are removed, too.
 @end itemize
 
 @item Other Changes
@@ -69,13 +69,23 @@ 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.
+the news, including clarification in viewport, workspace and event,
+and window matching lisp functions.
 
 Added a faq item on multi-head and workspace.
 
-Edition number and the date of last change are dropped form the info.
+Edition number and the date of last change are dropped from the info.
 We now edit the info often, so they are not so much meaningful.
+
+ c The reason that this item is not categorized as ``bugfix'' is that
+ c 1. Lock-button, or more precisely 'fixed-position' property
+ c    lacks precise definition. It forbids moving, but resizing
+ c    is allowed. It also affects window placement, too.
+ c 2. Currently doc of window-state-change-hook is wrong, but
+ c    correction takes long.   
+ item Pressing the lock-button does the state-change of the window
+accordingly. [Fuchur] *
+Any theme shipped with Sawfish doesn't have the lock button yet, though.
 @end itemize
 @end itemize
 
diff --git a/man/sawfish.texi b/man/sawfish.texi
index ac063a6..a2e8473 100644
--- a/man/sawfish.texi
+++ b/man/sawfish.texi
@@ -5154,30 +5154,35 @@ to it.
 @chapter Events
 @cindex Events
 
-Events refer to input events from X that the window manager receives,
-either for the root window, the window frames it creates, or grabbed
-from the client windows themselves. Each event induced by the mouse or
-keyboard has a Lisp representation.
+Lisp ``event'' object is a representation of input, regardless of actual
+or expected. If it's a keypress for example, it tells which key with
+which modifiers are pressed, and that's all. Please do not confuse it
+with X or other's event which is generated only after keypress or
+other ``event''.
+
+Each X input event induced by the mouse or the keyboard has a Lisp
+representation. X input events that Sawfish receives are either for
+the root window, the window frames it creates, or grabbed from the
+client windows themselves.
+
+Sawfish can respond to X events other than input, most often via
+hooks. (@pxref{Standard Hooks})
 
 @defun eventp object
-This function returns @code{t} if its argument is an input event.
+This function returns @code{t} if its argument is an event.
 @end defun
 
 @menu
-* Event Representation::        Objects versus string names
+* Event Name Representation::   Raw object versus string name
 * Event Modifiers::             Meta, Alt, Buttons
 * Event Actions::               Keys and Clicks
 * Event Matching::
-* Synthetic Events::            Creating events that seem real
+* Synthesis of Events::            Creating events that seem real
 @end menu
 
- node Event Representation, Event Modifiers, Events, Events
- section Event Representation
-
-Each input event is represented by a cons cell containing two
-integers, and these integers encode the event. The encoding is opaque;
-the only way to access an event meaningfully is via the functions
-provided.
+ node Event Name Representation, Event Modifiers, Events, Events
+ section Event Name Representation
+ cindex Name, of Event
 
 Each event has a string representation, called its ``name''.  Names
 consist of zero or more modifiers, followed by a key or mouse action
@@ -5188,14 +5193,14 @@ hyphens @samp{-}.  For example, hitting @key{x} while holding down the
 Emacs Lisp's notation.
 
 Functions are available to convert between the name of an event and the
-actual event itself, and vice versa.
+event object itself, and vice versa.
 
 @defun lookup-event event-name
 Create and return a new input event whose name is @var{event-name}.
 
 @lisp
 (lookup-event "C-x")
-    @result{} (120 . 65540)
+    @result{} (120 . 65540) ;; Internally, event is a pair of integers.
 
 (lookup-event "C-M-Button1-Click1")
     @result{} (1 . 131340)
@@ -5211,7 +5216,7 @@ This function returns a string naming the input event @var{event}.
 @end lisp
 @end defun
 
- node Event Modifiers, Event Actions, Event Representation, Events
+ node Event Modifiers, Event Actions, Event Name Representation, Events
 @section Event Modifiers
 @cindex Event Modifiers
 @cindex Modifiers, for events
@@ -5248,7 +5253,8 @@ The hyper modifier
 
 @item Super
 @itemx s
-The super modifier; note that this is a lowercase @kbd{s}
+The super modifier; note that this is a lowercase @kbd{s}, in order to
+distiguish from shift
 
 @item Mod var{k}
 The standard X modifiers, for @var{k} between 1 and 5
@@ -5374,7 +5380,7 @@ successive clicks.  Defaults to 250 milliseconds at startup; if
 @code{nil}, Sawfish uses 250 milliseconds.
 @end defvar
 
- node Event Matching, Synthetic Events, Event Actions, Events
+ node Event Matching, Synthesis of Events, Event Actions, Events
 @section Event Matching
 @cindex Event Matching
 @cindex Matching, Events
@@ -5390,10 +5396,10 @@ Returns @code{t} if events @var{ev1} and @var{ev2} match, @code{nil}
 otherwise.
 @end defun
 
- node Synthetic Events,  , Event Matching, Events
+ node Synthesis of Events,  , Event Matching, Events
 @section Synthetic Events
- cindex Synthetic Events
- cindex Events, Synthetic
+ cindex Synthesis of Events
+ cindex Events, Synthesis
 @cindex Events, Synthesizing
 
 It is possible to create an event inside Sawfish that mimics a real
@@ -5409,7 +5415,7 @@ The current pointer position becomes the position of the event.
 @var{Event} is either an event object, or the string representation of
 an event (such as @code{"A-f"} or @code{"C-M-Button3-Click2"}).
 Strings are parsed into event objects before any work is done.
- xref{Event Representation}.
+ xref{Event Name Representation}.
 
 If @var{propagate} is true, the event will propagate up the window
 ancestor chain until it is handled.
diff --git a/src/keys.c b/src/keys.c
index 17d5fce..981729b 100644
--- a/src/keys.c
+++ b/src/keys.c
@@ -746,8 +746,8 @@ static struct key_def default_codes[] = {
     { 0, 0, 0 }
 };
 
-/* Puts the integers defining the event described in DESC into CODE
-   and MODS. */
+/* Convert an event described by a string DESC into integers
+   CODE and MODS. */
 static bool
 lookup_event(unsigned long *code, unsigned long *mods, char *desc)
 {