[nongnu] elpa/swsw 51b8c1eb7c 080/146: ; Update documentation according to latest changes

[ELPA Syncer]

branch: elpa/swsw
commit 51b8c1eb7cba81bca65353a903c8e2bfda9f4f75
Author: Daniel Semyonov <cmstr@dsemy.com>
Commit: Daniel Semyonov <cmstr@dsemy.com>

    ; Update documentation according to latest changes
---
 NEWS      | 16 +++++++++++---
 README    | 20 +++++++++++------
 swsw.el   | 14 ++++++++----
 swsw.texi | 75 +++++++++++++++++++++++++++++++++++++++++++++++++++++----------
 4 files changed, 100 insertions(+), 25 deletions(-)

diff --git a/NEWS b/NEWS
index b9dec53345..e510df6c97 100644
--- a/NEWS
+++ b/NEWS
@@ -1,10 +1,20 @@
 swsw NEWS -- history of user-visible changes.
 See the end of the file for an explanation of the versioning scheme.
 
-* 1.2 (currently in development)
-No user facing changes have been made yet.
+* 2.0 (currently in development)
 
-* 1.1.2 (currently in development)
+** Add support for custom window management commands.
+Binding a command to a key in swsw-command-map allows you to call that
+command instead of selecting an ID.
+Currently three such commands are defined: swsw-select (o),
+swsw-select-minibuffer (m), swsw-delete (0).
+
+** Breaking changes.
+swsw-minibuffer-id is no longer defined or used anywhere, instead
+providing the same functionality through swsw-select-minibuffer.
+swsw-select no longer accepts a window ID as an optional argument.
+
+* 1.1.2
 
 ** Apply customization options immediately.
 Customizing swsw-id-chars and swsw-scope and applying those changes now
diff --git a/README b/README
index 5f6247824d..d0914561f1 100644
--- a/README
+++ b/README
@@ -27,7 +27,7 @@ M-x package-install-file RET /path/to/clone/swsw-VERSION.tar 
RET
 
 Usage:
 
-Enable `swsw-mode':
+Enable ‘swsw-mode’:
 
 (swsw-mode)
 
@@ -39,15 +39,21 @@ For use-package users:
 
 When swsw-mode is active:
 - A window ID is displayed using a mode line lighter or a display
-  function (see `swsw-display-function').
-- A single (predefined) character corresponds to the minibuffer
-  (see `swsw-minibuffer-id').
-- Window IDs are assigned to all windows on all frames (by default,
-  see `swsw-scope').
+  function (see ‘swsw-display-function’).
+- Window IDs are assigned to all windows on all frames except for
+  the minibuffer(by default, see ‘swsw-scope’).
 
 C-x o ID switches focus to the window which corresponds to ID.
 
-You can customize `swsw-mode' using the customize interface:
+C-x o m switches focus to the minibuffer if it's active.
+
+C-x o 0 ID deletes the window which corresponds to ID.
+
+More commands can be added through ‘swsw-command-map’:
+
+(define-key swsw-command-map [?a] #'my-command)
+
+You can customize ‘swsw-mode’ using the customize interface:
 
 M-x customize-group RET swsw RET
 
diff --git a/swsw.el b/swsw.el
index b900245eb5..d53d85979e 100644
--- a/swsw.el
+++ b/swsw.el
@@ -44,13 +44,19 @@
 ;; When swsw-mode is active:
 ;; - A window ID is displayed using a mode line lighter or a display
 ;;   function (see ‘swsw-display-function’).
-;; - A single (predefined) character corresponds to the minibuffer
-;;   (see ‘swsw-minibuffer-id’).
-;; - Window IDs are assigned to all windows on all frames (by default,
-;;   see ‘swsw-scope’).
+;; - Window IDs are assigned to all windows on all frames except for
+;;   the minibuffer(by default, see ‘swsw-scope’).
 ;;
 ;; C-x o ID switches focus to the window which corresponds to ID.
 ;;
+;; C-x o m switches focus to the minibuffer if it's active.
+;;
+;; C-x o 0 ID deletes the window which corresponds to ID.
+;;
+;; More commands can be added through ‘swsw-command-map’:
+;;
+;; (define-key swsw-command-map [?a] #'my-command)
+;;
 ;; You can customize ‘swsw-mode’ using the customize interface:
 ;;
 ;; M-x customize-group RET swsw RET
diff --git a/swsw.texi b/swsw.texi
index 731fb0d9c1..ddb9e61efb 100644
--- a/swsw.texi
+++ b/swsw.texi
@@ -132,9 +132,8 @@ In order to use any feature of the package, 
@code{swsw-mode} must be enabled:
 @cindex swsw-mode
 @table @asis
 @item @kbd{M-x swsw-mode RET}
-@end table
-
 You can also add @code{(swsw-mode)} to your init file, instead.
+@end table
 
 By default, window IDs will be shown as mode line lighters of the
 form @code{<ID>}.
@@ -142,15 +141,36 @@ form @code{<ID>}.
 @kindex C-x o
 @cindex swsw-select
 @table @asis
-@item @kbd{C-x o ID}
+@item @kbd{C-x o}
+Start window selection (@code{swsw-select}).
+This command sets a transient key map in which several window
+commands are defined, and window IDs can be selected.
+Selecting a window ID (by pressing @kbd{ID}) will switch to window
+corresponding to it.
+
+@kindex C-x o m
+@cindex swsw-select-minibuffer
+@item @kbd{C-x o m}
+Switch focus the minibuffer if it's active
+(@code{swsw-select-minibuffer}).
+
+@kindex C-x o 0
+@cindex swsw-delete
+@item @kbd{C-x o 0}
+Start window deletion (@code{swsw-delete}).
+This command sets a transient key map in which several window
+commands are defined, and window IDs can be selected.
+Selecting a window ID (by pressing @kbd{ID}) will delete the window
+corresponding to it.
 @end table
-Switch to the window corresponding to @code{ID} (@code{swsw-select}).
+
+@xref{Window commands} for information regarding defining new commands.
 
 @node Customization
 @chapter Customization
 
-All customization, except for defining custom display functions, can be done
-through the customize interface:
+All customization, except for defining custom display functions and
+custom window commands, can be done through the customize interface:
 
 @table @asis
 @item @kbd{M-x customize-group RET swsw RET}
@@ -162,11 +182,6 @@ list of characters. By default, the home row (@code{a s d 
f g h j k l}) is
 used.
 @end defopt
 
-@defopt swsw-minibuffer-id
-ID reserved for the minibuffer. This should be a single character. By default,
-@code{m} is used.
-@end defopt
-
 @defopt swsw-id-format
 Format string for the window ID. Display functions may use this format string
 to display the ID, but they can also ignore it. The string should contain a
@@ -185,6 +200,7 @@ frames, @code{visible} means consider all windows on all 
visible frames and
 
 @menu
 * Display functions::
+* Window commands::
 @end menu
 
 @node Display functions
@@ -225,6 +241,43 @@ mode line if SWITCH isn't @code{nil}, and remove those 
hooks if SWITCH is
 @code{nil}. This display function respects @code{swsw-id-format}.
 @end defun
 
+@node Window commands
+@section Window commands
+
+Window commands are used to perform operations on specific
+windows. They are normal commands (interactive functions) which are
+bound to key in @code{swsw-command-map}. @code{swsw-select},
+@code{swsw-select-minibuffer} and @code{swsw-delete} are implemented
+as window commands.
+
+@defvar swsw--id-map
+Key map which is populated automatically with elements corresponding
+to all tracked windows. The ID of each window is converted to a vector
+(to serve as a key sequence), and corresponds to a command which calls
+@code{last-command} with the window corresponding to the ID as the
+sole argument. There should be no reason to modify it directly;
+it is reset whenever window configuration is updated.
+@end defvar
+
+@defvar swsw-command-map
+Key map which holds (usually) single character key bindings to window
+commands. This key map is set as the parent of @code{swsw--id-map}, so
+all window commands are available when it's active, unless they are
+shadowed by a window ID.
+@end defvar
+
+@defvar swsw-window-count
+Amount of windows currently tracked. This variable can be used to
+conditionally run window commands.
+@end defvar
+
+@defun swsw--run-window-command fun
+Run FUN as a window command. Run @code{swsw-before-command-hook}, set
+@code{this-command} to FUN, and set @code{swsw--id-map} as a transient
+map which runs @code{swsw-after-command-hook} on exit. This function
+can be used to easily define new window commands.
+@end defun
+
 @node Keystroke Index
 @appendix Keystroke Index