Rewrite README using org-mode

README.md

@@ -1,16 +0,0 @@
-window-numbering
-================
-
-Numbered window shortcuts for Emacs
-
-[![Build Status](https://travis-ci.org/nschum/window-numbering.el.png?branch=master)](https://travis-ci.org/nschum/window-numbering.el)
-
-Enable `window-numbering-mode` and use M-1 through M-0 to navigate.
-
-If you want to affect the numbers, use window-numbering-before-hook or
-window-numbering-assign-func.
-For instance, to always assign the calculator window the number 9, add the
-following to your .emacs:
-
-    (setq window-numbering-assign-func
-          (lambda () (when (equal (buffer-name) "*Calculator*") 9)))

README.org

@@ -0,0 +1,145 @@
+[[https://github.com/syl20bnr/spacemacs][file:https://cdn.rawgit.com/syl20bnr/spacemacs/442d025779da2f62fc86c2082703697714db6514/assets/spacemacs-badge.svg]]
+
+#+TITLE: Window numbers for Emacs !
+
+* Contents :TOC:
+ - [[#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]]
+
+* Introduction
+Window numbers for Emacs: Navigate your windows and frames using numbers !
+
+This package is an extended and actively maintained version of the
+https://github.com/nschum/window-numbering.el package by Nikolaj Schumacher,
+with some ideas and code taken from https://github.com/abo-abo/ace-window.
+
+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
+  cd /path/to/install/folder
+  git clone https://github.com/deb0ch/winum.el
+#+END_SRC
+
+- Add the following to your Emacs configuration:
+
+#+BEGIN_SRC emacs-lisp
+  (add-to-list 'load-path "/path/to/install/folder/winum.el/")
+
+  (require 'window-numbering)
+
+  (window-numbering-mode)
+#+END_SRC
+
+
+* How to use
+** Navigate windows
+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,
+where N is the maximum window number.
+
+See [[#configuration][configuration]] to rebind them any way you prefer.
+
+** Delete windows
+Use ~M-1~ to ~M-9~ with an Emacs prefix argument to delete a window instead of
+selecting it.
+
+* Configuration
+** Custom keymap
+   To define your own bindings and override the default ones, override
+ =window-numbering-keymap= before activating the mode:
+
+   #+BEGIN_SRC emacs-lisp
+  (require 'window-numbering)
+
+  (setq window-numbering-keymap (let ((map (make-sparse-keymap)))
+				  (define-key map "\M-m 0" 'select-window-0)
+				  ; ...
+				  (define-key map "\M-m 9" 'select-window-9)
+				  map))
+  (window-numbering-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
+=convenience= > =window-numbering=:
+
+- =window-numbering-scope=
+
+Frames affected by a number set. Choices are 'frame-local 'visible or 'global.
+
+Default: 'global
+
+- =window-numbering-reverse-frame-list=
+
+If t, order frames by reverse order of creation. Has effect only when
+`window-numbering-scope' is not 'frame-local.
+
+Default: nil
+
+- =window-numbering-auto-assign-0-to-minibuffer=
+
+If non-nil, =window-numbering-mode= assigns 0 to the minibuffer if active.
+
+Default: t
+
+- =window-numbering-before-hook=
+
+Hook called before =window-numbering-mode= starts assigning numbers. The list of
+windows to be numbered is passed as a parameter. Use =window-numbering--assign=
+to manually assign some of them a number. If you want to assign a number to just
+one buffer, use =window-numbering-assign-func= instead.
+
+Default: nil
+
+- =window-numbering-assign-func=
+
+Function called for each window by =window-numbering-mode=. This is called
+before automatic assignment begins. The function should return a number to have
+it assigned to the current-window, nil otherwise.
+
+Default: nil
+
+Example: always assign the calculator window the number 9:
+
+#+BEGIN_SRC emacs-lisp
+    (setq window-numbering-assign-func
+	  (lambda () (when (equal (buffer-name) "*Calculator*") 9)))
+#+END_SRC
+
+- =window-numbering-mode-line-position=
+
+The position in the mode-line `window-numbering-mode' displays the number.
+
+Default: 1
+
+- =window-numbering-window-number-max= 10
+
+Max number of windows that can be numbered.
+
+Default: 10
+
+- =window-numbering-ignored-buffers=
+
+List of buffers to ignore when selecting window.
+
+Default: '(" *which-key*")
+
+- face: =window-numbering-face=
+
+Face used for the number in the mode-line.
+

window-numbering.el

@@ -47,7 +47,7 @@
 ;;      force update or `window-numbering-get-number' fails and messes the
 ;;      modeline until next update.
 (defcustom window-numbering-scope 'global
-  "The scope of number sets."
+  "Frames affected by a number set."
   :group 'window-numbering
   :type  '(choice
            (const :tag "frame local" frame-local)
@@ -65,6 +65,7 @@ Has effect only when `window-numbering-scope' is not 'frame-local."
   :group 'window-numbering
   :type  'boolean)
 
+;; TODO see if useful
 (defcustom window-numbering-before-hook nil
   "Hook called before `window-numbering-mode' starts assigning numbers.
 The list of windows to be numbered is passed as a parameter.
@@ -86,7 +87,7 @@ return a number to have it assigned to the current-window, nil otherwise."
   :group 'window-numbering
   :type  'integer)
 
-(defcustom window-numbering--window-number-max 10
+(defcustom window-numbering-window-number-max 10
   "Max number of windows that can be numbered."
   :group 'window-numbering
   :type  'integer)
@@ -125,7 +126,7 @@ return a number to have it assigned to the current-window, nil otherwise."
     (window-numbering--deinit)))
 
 ;; define interactive functions window-numbering-select-window-[0..n]
-(dotimes (i window-numbering--window-number-max)
+(dotimes (i (max 10 window-numbering-window-number-max))
   (eval `(defun ,(intern (format "select-window-%s" i)) (&optional arg)
            ,(format "Jump to window %d.\nIf prefix ARG is given, delete the\
  window instead of selecting it." i)
@@ -150,7 +151,7 @@ If prefix ARG is given, delete the window instead of selecting it."
                                    window-numbering--frames-table))
                    window-numbering--window-vector))
         window)
-    (if (and (>= i 0) (< i window-numbering--window-number-max)
+    (if (and (>= i 0) (< i window-numbering-window-number-max)
              (setq window (aref windows i)))
         window
       (error "No window numbered %s" i))))
@@ -159,36 +160,6 @@ If prefix ARG is given, delete the window instead of selecting it."
 ;;      - prefix argument
 ;;      - read-from-minibuffer
 
-;;;###autoload
-(defun window-numbering-install-mode-line (&optional position)
-  "Install the window number from `window-numbering-mode' to the mode-line.
-POSITION: position in the mode-line."
-  (let ((mode-line (default-value 'mode-line-format))
-        (res))
-    (dotimes (i (min (or position window-numbering-mode-line-position 1)
-                     (length mode-line)))
-      (push (car mode-line) res)
-      (pop mode-line))
-    (push '(:eval (window-numbering-get-number-string)) res)
-    (while mode-line
-      (push (car mode-line) res)
-      (pop mode-line))
-    (setq-default mode-line-format (nreverse res)))
-  (force-mode-line-update t))
-
-;;;###autoload
-(defun window-numbering-clear-mode-line ()
-  "Remove the window number of `window-numbering-mode' from the mode-line."
-  (let ((mode-line (default-value 'mode-line-format))
-        (res))
-    (while mode-line
-      (let ((item (car mode-line)))
-        (unless (equal item '(:eval (window-numbering-get-number-string)))
-          (push item res)))
-      (pop mode-line))
-    (setq-default mode-line-format (nreverse res)))
-  (force-mode-line-update t))
-
 ;;;###autoload
 (defun window-numbering-get-number-string (&optional window)
   "Get the current or specified window's current number as a propertized string.
@@ -245,8 +216,8 @@ Such a structure allows for per-frame bidirectional fast access.")
   "Initialize window-numbering-mode."
   (if (eq window-numbering-scope 'frame-local)
       (setq window-numbering--frames-table (make-hash-table :size window-numbering--max-frames))
-    (setq window-numbering--numbers-table (make-hash-table :size window-numbering--window-number-max)))
+    (setq window-numbering--numbers-table (make-hash-table :size window-numbering-window-number-max)))
-  (window-numbering-install-mode-line)
+  (window-numbering--install-mode-line)
   (add-hook 'minibuffer-setup-hook 'window-numbering--update)
   (add-hook 'window-configuration-change-hook 'window-numbering--update)
   (dolist (frame (frame-list))
@@ -255,20 +226,48 @@ Such a structure allows for per-frame bidirectional fast access.")
 
 (defun window-numbering--deinit ()
   "Actions performed when turning off window-numbering-mode."
-  (window-numbering-clear-mode-line)
+  (window-numbering--clear-mode-line)
   (remove-hook 'minibuffer-setup-hook 'window-numbering--update)
   (remove-hook 'window-configuration-change-hook 'window-numbering--update)
   (setq window-numbering--frames-table nil))
 
+(defun window-numbering--install-mode-line (&optional position)
+  "Install the window number from `window-numbering-mode' to the mode-line.
+POSITION: position in the mode-line."
+  (let ((mode-line (default-value 'mode-line-format))
+        (res))
+    (dotimes (i (min (or position window-numbering-mode-line-position 1)
+                     (length mode-line)))
+      (push (car mode-line) res)
+      (pop mode-line))
+    (push '(:eval (window-numbering-get-number-string)) res)
+    (while mode-line
+      (push (car mode-line) res)
+      (pop mode-line))
+    (setq-default mode-line-format (nreverse res)))
+  (force-mode-line-update t))
+
+(defun window-numbering--clear-mode-line ()
+  "Remove the window number of `window-numbering-mode' from the mode-line."
+  (let ((mode-line (default-value 'mode-line-format))
+        (res))
+    (while mode-line
+      (let ((item (car mode-line)))
+        (unless (equal item '(:eval (window-numbering-get-number-string)))
+          (push item res)))
+      (pop mode-line))
+    (setq-default mode-line-format (nreverse res)))
+  (force-mode-line-update t))
+
 (defun window-numbering--update ()
   "Update window numbers."
   (setq window-numbering--remaining (window-numbering--available-numbers))
   (if (eq window-numbering-scope 'frame-local)
       (puthash (selected-frame)
-               (cons (make-vector window-numbering--window-number-max nil)
+               (cons (make-vector window-numbering-window-number-max nil)
-                     (make-hash-table :size window-numbering--window-number-max))
+                     (make-hash-table :size window-numbering-window-number-max))
                window-numbering--frames-table)
-    (setq window-numbering--window-vector (make-vector window-numbering--window-number-max nil))
+    (setq window-numbering--window-vector (make-vector window-numbering-window-number-max nil))
     (clrhash window-numbering--numbers-table))
   (when (and window-numbering-auto-assign-0-to-minibuffer
              (active-minibuffer-window))
@@ -354,11 +353,11 @@ This hashtable is not stored the same way depending on the value of
     window-numbering--numbers-table))
 
 (defun window-numbering--available-numbers ()
-  "Return a list of numbers from 1 to `window-numbering--window-number-max'.
+  "Return a list of numbers from 1 to `window-numbering-window-number-max'.
 0 is the last element of the list."
   (let ((numbers))
-    (dotimes (i window-numbering--window-number-max)
+    (dotimes (i window-numbering-window-number-max)
-      (push (% (1+ i) window-numbering--window-number-max) numbers))
+      (push (% (1+ i) window-numbering-window-number-max) numbers))
     (nreverse numbers)))
 
 (defun window-numbering--switch-to-window (window)