improve README.org

README.org

@@ -2,20 +2,14 @@
 
 #+TITLE: Window numbers for Emacs !
 
-**** TODO better example for assign-func
-**** TODO example with all options
-
 * Contents :TOC:
-       - [[#better-example-for-assign-func][better example for assign-func]]
-       - [[#example-with-all-options][example with all options]]
  - [[#introduction][Introduction]]
  - [[#installation][Installation]]
  - [[#how-to-use][How to use]]
-   - [[#navigate-windows][Navigate windows]]
-   - [[#delete-windows][Delete windows]]
  - [[#configuration][Configuration]]
    - [[#custom-keymap][Custom keymap]]
    - [[#customize-options][Customize options]]
+   - [[#configuration-file-example][Configuration file example]]
 
 * Introduction
 Window numbers for Emacs: Navigate your windows and frames using numbers !
@@ -28,7 +22,6 @@ This version brings, among other things, support for number sets across multiple
 frames, giving the user a smoother experience of multi-screen Emacs.
 
 * Installation
-
 - Clone the repo:
 
 #+BEGIN_SRC shell
@@ -46,104 +39,170 @@ frames, giving the user a smoother experience of multi-screen Emacs.
   (winum-mode)
 #+END_SRC
 
-
 * How to use
-** Navigate windows
+- =select-window-[0..9]=
-Use ~M-1~ to ~M-9~ to navigate windows numbered 1 to 9.
 
-The functions for selecting windows are the =select-window-[1..N]= functions,
+  Use ~M-1~ to ~M-9~ to navigate windows numbered 1 to 9.
-where N is the maximum window number.
 
-See [[#configuration][configuration]] to rebind them any way you prefer.
+  By default, ~M-0~ is bound to =select-window-0-or-10=, which behaves like
+  the other ones except that if 0 is not assigned it will act on the window 10
+  instead.
 
-** Delete windows
+  You can rebind this to the more straightforward =select-window-0= if you
-Use ~M-1~ to ~M-9~ with an Emacs prefix argument to delete a window instead of
+  prefer.
-selecting it.
+
+- =select-window-by-number=
+
+  If you happen to have more than 10 windows, you can use the
+ =select-window-by-number= function, bound by default to ~C-`~.
+
+  This function allows several ways to input the window number:
+
+  - Use a numbered prefix argument.\\
+ *Ex:* ~C-1 C-2 C`~ to select window 12.
+  - Use a negative prefix argument to delete the window.\\
+ *Ex:* ~C-- C-1 C-2 C`~ to delete window 12.
+  - Use the negative prefix argument to delete window 0.\\
+ *Ex:* ~C-- C-`~ to delete window 0.
+  - Use the default prefix argument to delete current window.\\
+ *Ex:* ~C-u C-`~ to delete current window.
+  - If no prefix argument ig given, a number is read from minibuffer. A negative
+    input will delete the window instead of selecting it.
+
+ *NB:* On Spacemacs you can specify the prefix argument using ~SPC u~.
+ *Ex:* ~SPC u - 1 2 C-`~ to delete window 12.
 
 * Configuration
 ** Custom keymap
-   To define your own bindings and override the default ones, override
+To define your own bindings and override the default ones, override
- =winum-keymap= before activating the mode:
+=winum-keymap= before activating the mode:
 
-   #+BEGIN_SRC emacs-lisp
+#+BEGIN_SRC emacs-lisp
-     (require 'winum)
+  (require 'winum)
 
-     (setq winum-keymap (let ((map (make-sparse-keymap)))
+  (setq winum-keymap (let ((map (make-sparse-keymap)))
-			  (define-key map "\M-m 0" 'select-window-0)
+                       (define-key map "\M-m 0" 'select-window-0)
-					     ; ...
+                                          ; ...
-			  (define-key map "\M-m 9" 'select-window-9)
+                       (define-key map "\M-m 9" 'select-window-9)
-			  map))
+                       map))
-     (winum-mode)
+  (winum-mode)
 #+END_SRC
 
 This way your bindings will not error when the mode is turned off.
 
 ** Customize options
 
-Several options are available through Emacs' =Customize= interface under
+Several options are available through Emacs' Customize interface under
 =convenience= > =winum=:
 
 - =winum-scope=
 
-Frames affected by a number set. Choices are 'frame-local 'visible or 'global.
+  Frames affected by a number set. Choices are ='frame-local= ='visible= or
+ ='global=.
 
-Default: 'global
+  Default: ='global=
 
 - =winum-reverse-frame-list=
 
-If t, order frames by reverse order of creation. Has effect only when
+  If t, order frames by reverse order of creation. Has effect only when
-`winum-scope' is not 'frame-local.
+ =winum-scope= is not ='frame-local=.
 
-Default: nil
+  Default: =nil=
 
 - =winum-auto-assign-0-to-minibuffer=
 
-If non-nil, =winum-mode= assigns 0 to the minibuffer if active.
+  If non-nil, =winum-mode= assigns 0 to the minibuffer if active.
 
-Default: t
+  Default: =t=
 
 - =winum-assign-func=
 
-Function called for each window by =winum-mode=. This is called
+  Function called for each window by =winum-mode=. This is called before
-before automatic assignment begins. The function should return a number to have
+  automatic assignment begins. The function should return a number to have it
-it assigned to the current-window, nil otherwise.
+  assigned to the current-window, =nil= otherwise.
 
-Default: nil
+  Default: =nil=
 
-Example: always assign the calculator window the number 9:
+  Example: always assign *Calculator* the number 9 and *NeoTree* the number 0:
 
 #+BEGIN_SRC emacs-lisp
-    (setq winum-assign-func
+  (defun my-winum-assign-func ()
-	  (lambda () (when (equal (buffer-name) "*Calculator*") 9)))
+    (cond
+     ((equal (buffer-name) "*Calculator*")
+      9)
+     ((string-match-p (buffer-name) ".*\\*NeoTree\\*.*")
+      0)
+     (t
+      nil)))
+
+  (setq winum-assign-func 'my-winum-assign-func)
 #+END_SRC
 
 - =winum-auto-setup-mode-line=
 
-When nil, `winum-mode' will not display window numbers in the mode-line.
+  When nil, =winum-mode= will not display window numbers in the mode-line. You
-You might want this to be nil if you use a package that already manages window
+  might want this to be nil if you use a package that already manages window
-numbers in the mode-line.
+  numbers in the mode-line.
 
-Default: t
+  Default: =t=
 
 - =winum-mode-line-position=
 
-The position in the mode-line `winum-mode' displays the number.
+  The position in the mode-line =winum-mode= displays the number.
 
-Default: 1
+  Default: 1
-
-- =winum-window-number-max= 10
-
-Max number of windows that can be numbered.
-
-Default: 10
 
 - =winum-ignored-buffers=
 
-List of buffers to ignore when selecting window.
+  List of buffers to ignore when selecting window.
 
-Default: '(" *which-key*")
+  Default: ='(" *which-key*")=
 
 - face: =winum-face=
 
-Face used for the number in the mode-line.
+  Face used for the number in the mode-line.
 
+** Configuration file example
+
+Here is an example that you could put in your =.emacs=, which includes all
+available winum options.
+
+#+BEGIN_SRC emacs-lisp
+  (add-to-list 'load-path "/path/to/install/folder/winum.el/")
+
+  (require 'winum)
+
+  (defun my-winum-assign-func ()
+    (cond
+     ((equal (buffer-name) "*Calculator*")
+      9)
+     ((string-match-p (buffer-name) ".*\\*NeoTree\\*.*")
+      0)
+     (t
+      nil)))
+
+  (set-face-property 'winum-face :weight 'bold)
+
+  (setq window-numbering-scope            'global
+	winum-reverse-frame-list          nil
+	winum-auto-assign-0-to-minibuffer t
+	winum-assign-func                 'my-winum-assign-func
+	winum-auto-setup-mode-line        t
+	winum-mode-line-position          1
+	winum-ignored-buffers             '(" *which-key*")
+	winum-keymap (let ((map (make-sparse-keymap)))
+		       (define-key map (kbd "C-`") 'select-window-by-number)
+		       (define-key map (kbd "M-0") 'select-window-0-or-10)
+		       (define-key map (kbd "M-1") 'select-window-1)
+		       (define-key map (kbd "M-2") 'select-window-2)
+		       (define-key map (kbd "M-3") 'select-window-3)
+		       (define-key map (kbd "M-4") 'select-window-4)
+		       (define-key map (kbd "M-5") 'select-window-5)
+		       (define-key map (kbd "M-6") 'select-window-6)
+		       (define-key map (kbd "M-7") 'select-window-7)
+		       (define-key map (kbd "M-8") 'select-window-8)
+		       (define-key map (kbd "M-9") 'select-window-9)
+		       map))
+
+  (winum-mode)
+#+END_SRC