docs: update README for new features

README.org

@@ -5,6 +5,7 @@
 * Contents :TOC:noexport:
 - [[#introduction][Introduction]]
 - [[#changelog][Changelog]]
+  - [[#aug-26-2024][Aug. 26 2024]]
   - [[#sep-11-2019][Sep. 11 2019]]
   - [[#nov-15-2018][Nov. 15 2018]]
   - [[#initial-release-whats-changed-since-window-numbering][Initial release: what's changed since window-numbering]]
@@ -28,6 +29,9 @@ as identifiers, as opposed to strictly increasing numbers. The public
 API is largely the same, however, and simple numbers are still the default.
 
 * Changelog
+** Aug. 26 2024
+- Added support for arbitrary Lisp objects (non-nil, compared with =equal=) as indices.
+- Added customize variable =winum-auto-assign-function= to control auto-assigning behavior.
 ** Sep. 11 2019
 - Added customize variable =winum-ignored-buffers-regexp= to ignored buffers
   based on regexps.
@@ -100,7 +104,7 @@ your Emacs configuration:
 | Key binding | Description                                                                                 |
 |-------------+---------------------------------------------------------------------------------------------|
 | ~C-x w <n>~ | select window <n>, where <n> ranges from 0 to 9. A negative argument deletes the window.    |
-| ~C-x w `~   | select window by number. Number can be given as prefix arg or will be read from minibuffer. |
+| ~C-x w `~   | select window by index. Integer indices can be given as prefix arg, or the index will be read from minibuffer. |
 
 - =select-window-0-or-10=
 
@@ -110,23 +114,19 @@ your Emacs configuration:
   You can rebind this to the more straightforward =select-window-0= if you
   prefer.
 
-- =select-window-by-number=
+- =select-window-by-index=
 
-  If you happen to have more than 10 windows, you can use the
- =select-window-by-number= function, bound by default to ~C-x w `~.
+  If you happen to have more than 10 windows, or if you want to select a window that
+  doesn't have an integer index, you can use the =select-window-by-index= function, bound
+  by default to ~C-x w `~.
 
   This function allows several ways to input the window number:
 
   - Use a numbered prefix argument.\\
  *Ex:* ~C-1 C-2 C-x w `~ to select window 12.
-  - Use a negative prefix argument to delete the window.\\
- *Ex:* ~C-- C-1 C-2 C-x w `~ to delete window 12.
-  - Use the negative prefix argument to delete window 0.\\
- *Ex:* ~C-- C-x w `~ to delete window 0.
   - Use the default prefix argument to delete current window.\\
  *Ex:* ~C-u C-x w `~ 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.
+  - If no prefix argument is given, an un-evaluated Lisp value is read from minibuffer.
 
 * Configuration
 ** Keybindings
@@ -151,8 +151,8 @@ override =winum-keymap= in the minor mode bindings table:
 #+BEGIN_SRC emacs-lisp
   (setq winum-keymap
       (let ((map (make-sparse-keymap)))
-        (define-key map (kbd "C-`") 'winum-select-window-by-number)
-        (define-key map (kbd "C-²") 'winum-select-window-by-number)
+        (define-key map (kbd "C-`") 'winum-select-window-by-index)
+        (define-key map (kbd "C-²") 'winum-select-window-by-index)
         (define-key map (kbd "M-0") 'winum-select-window-0-or-10)
         (define-key map (kbd "M-1") 'winum-select-window-1)
         (define-key map (kbd "M-2") 'winum-select-window-2)
@@ -174,7 +174,7 @@ Note that it is important to set =winum-keymap= /before/ the =require=.
 You can also use the more conventional =define-key= on =winum-keymap=:
 
 #+BEGIN_SRC emacs-lisp
-  (define-key winum-keymap (kbd "C-x y o l o") 'winum-select-window-by-number)
+  (define-key winum-keymap (kbd "C-x y o l o") 'winum-select-window-by-index)
 #+END_SRC
 
 *NB:* Both ~`~ and ~²~ are mapped to =winum-select-window-by-number= by default
@@ -200,11 +200,11 @@ Several options are available through Emacs' Customize interface under
 
   Default: =nil=
 
-- =winum-auto-assign-0-to-minibuffer=
+- =winum-minibuffer-auto-assign=
 
-  If non-nil, =winum-mode= assigns 0 to the minibuffer if active.
+  If non-nil, =winum-mode= automatically assigns this index to the minibuffer.
 
-  Default: =t=
+  Default: =0=
 
 - =winum-assign-functions=
 
@@ -243,6 +243,18 @@ Several options are available through Emacs' Customize interface under
 
   Default: =nil=
 
+- =winum-auto-assign-function=
+  
+  The function called to auto-assign indices to windows.
+
+  This function is called after =winum-assign-functions= to automatically assign
+  indices to the remaining windows. It must take in a list of windows and call
+  the function =winum--assign= to assign an index to each, while avoiding
+  assigning any indices already taken (stored in =winum--assigned-indices=).
+  Members of this list should be tested for using `equal'.
+
+  Default: =#'winum--auto-assign=
+
 - =winum-auto-setup-mode-line=
 
   When nil, =winum-mode= will not display window numbers in the mode-line. You
@@ -289,8 +301,8 @@ available winum options.
 #+BEGIN_SRC emacs-lisp
   (setq winum-keymap
       (let ((map (make-sparse-keymap)))
-        (define-key map (kbd "C-`") 'winum-select-window-by-number)
-        (define-key map (kbd "C-²") 'winum-select-window-by-number)
+        (define-key map (kbd "C-`") 'winum-select-window-by-index)
+        (define-key map (kbd "C-²") 'winum-select-window-by-index)
         (define-key map (kbd "M-0") 'winum-select-window-0-or-10)
         (define-key map (kbd "M-1") 'winum-select-window-1)
         (define-key map (kbd "M-2") 'winum-select-window-2)
@@ -319,7 +331,7 @@ available winum options.
 
   (setq window-numbering-scope            'global
         winum-reverse-frame-list          nil
-        winum-auto-assign-0-to-minibuffer t
+        winum-minibuffer-auto-assign      0
         winum-assign-func                 'my-winum-assign-func
         winum-auto-setup-mode-line        t
         winum-format                      " %s "