Rename/rewrite recently added option and function in window.el

* lisp/window.el (window-at-x-y): Rename from `window-at-pos'.
Fix doc-string.
(delete-window-choose-selected): Rename from
`delete-window-set-selected'.  Fix doc-string.
(delete-window): Adjust to above renaming.
* doc/emacs/windows.texi (Change Window): Mention new option
`delete-window-choose-selected'.
* etc/NEWS:
* doc/lispref/windows.texi (Deleting Windows): Follow up on
above renamings.

4 files changed, 42 insertions, 27 deletions

diff --git a/doc/emacs/windows.texi b/doc/emacs/windows.texi
index c66deb77487..5e07e83ee53 100644
--- a/doc/emacs/windows.texi
+++ b/doc/emacs/windows.texi
@@ -310,6 +310,8 @@ the space that it occupied is given to an adjacent window (but not the
 minibuffer window, even if that is active at the time).  Deleting the
 window has no effect on the buffer it used to display; the buffer
 continues to exist, and you can still switch to it with @kbd{C-x b}.
+The option @code{delete-window-choose-selected} allows to choose which
+window becomes the new selected window instead.
 
 @findex kill-buffer-and-window
 @kindex C-x 4 0
diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index bcb492d68f7..6792d1b2d2f 100644
--- a/doc/lispref/windows.texi
+++ b/doc/lispref/windows.texi
@@ -1322,17 +1322,27 @@ When @code{delete-window} deletes the selected window of its frame, it
 has to make another window the new selected window of that frame.  The
 following option allows to choose which window gets selected instead.
 
-@defopt delete-window-set-selected
+@defopt delete-window-choose-selected
 This option allows to specify which window should become a frame's
 selected window after @code{delete-window} has deleted the previously
-selected one.
+selected one.  Possible choices are
+
+@itemize
+@item @code{mru}
+(the default) to choose the most recently used window on that frame.
+
+@item @code{pos}
+to choose the window comprising the frame coordinates of point of the
+previously selected window on that frame.
+
+@item @code{nil}
+to choose the first window (the window returned by
+@code{frame-first-window}) on that frame.
+@end itemize
 
-Possible choices are @code{mru} (the default) to select the most
-recently used window on that frame and @code{pos} to choose the window
-at the position of point of the previously selected window.  If this
-option is @code{nil}, it means to choose the frame's first window
-instead.  Note that a window with a non-@code{nil}
-@code{no-other-window} parameter is never chosen.
+A window with a non-@code{nil} @code{no-other-window} parameter is
+chosen only if all other windows on that frame have that parameter set
+to a non-@code{nil} value too.
 @end defopt
 
 @deffn Command delete-other-windows &optional window
diff --git a/etc/NEWS b/etc/NEWS
index f3db28d3cb1..1693342f0af 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -605,14 +605,14 @@ These options include 'windmove-default-keybindings',
 ** Windows
 
 +++
-*** New option 'delete-window-set-selected'.
+*** New option 'delete-window-choose-selected'.
 This allows to choose a frame's selected window after deleting the
 previously selected one.
 
 +++
 *** New argument NO-OTHER for some window functions.
 'get-lru-window', ‘get-mru-window’ and 'get-largest-window' now accept a
-new optional argument NO-OTHER which if non-nil avoids returning a
+new optional argument NO-OTHER which, if non-nil, avoids returning a
 window whose 'no-other-window' parameter is non-nil.
 
 +++
diff --git a/lisp/window.el b/lisp/window.el
index e7551f30c32..ff4a39a2a0a 100644
--- a/lisp/window.el
+++ b/lisp/window.el
@@ -4142,16 +4142,16 @@ frame can be safely deleted."
       ;; of its frame.
       t))))
 
-(defun window-at-pos (x y &optional frame no-other)
+(defun window-at-x-y (x y &optional frame no-other)
   "Return live window at coordinates X, Y on specified FRAME.
-X and Y are counted in pixels from an origin at 0, 0 of FRAME's
-native frame.  A coordinate on an edge shared by two windows is
-attributed to the window on the right (or below).  Return nil if
-no such window can be found.
+X and Y are FRAME-relative pixel coordinates.  A coordinate on an
+edge shared by two windows is attributed to the window on the
+right (or below).  Return nil if no such window can be found.
 
 Optional argument FRAME must specify a live frame and defaults to
 the selected one.  Optional argument NO-OTHER non-nil means to
-not return a window with a non-nil 'no-other-window' parameter."
+return nil if the window located at the specified coordinates has
+a non-nil `no-other-window' parameter."
   (setq frame (window-normalize-frame frame))
   (let* ((root-edges (window-edges (frame-root-window frame) nil nil t))
          (root-left (nth 2 root-edges))
@@ -4169,7 +4169,7 @@ not return a window with a non-nil 'no-other-window' parameter."
                (throw 'window window)))))
        frame))))
 
-(defcustom delete-window-set-selected 'mru
+(defcustom delete-window-choose-selected 'mru
   "How to choose a frame's selected window after window deletion.
 When a frame's selected window gets deleted, Emacs has to choose
 another live window on that frame to serve as its selected
@@ -4177,14 +4177,17 @@ window.  This option allows to control which window gets selected
 instead.
 
 The possible choices are 'mru' (the default) to select the most
-recently used window on that frame and 'pos' to choose the window
-at the position of point of the previously selected window.  If
-this is nil, choose the frame's first window instead.  A window
-with a non-nil 'no-other-window' parameter is never chosen."
+recently used window on that frame, and 'pos' to choose the
+window at the frame coordinates of point of the previously
+selected window.  If this is nil, choose the frame's first window
+instead.  A window with a non-nil `no-other-window' parameter is
+chosen only if all windows on that frame have that parameter set
+to a non-nil value."
   :type '(choice (const :tag "Most recently used" mru)
                  (const :tag "At position of deleted" pos)
                  (const :tag "Frame's first " nil))
   :group 'windows
+  :group 'frames
   :version "28.1")
 
 (defun delete-window (&optional window)
@@ -4207,7 +4210,7 @@ that is its frame's root window.
 
 If WINDOW is the selected window on its frame, choose some other
 window as that frame's selected window according to the value of
-the option `delete-window-set-selected'."
+the option `delete-window-choose-selected'."
   (interactive)
   (setq window (window-normalize-window window))
   (let* ((frame (window-frame window))
@@ -4263,7 +4266,7 @@ the option `delete-window-set-selected'."
           ;; Can't do without resizing fixed-size windows.
           (window--resize-siblings window (- size) horizontal t)))
 
-        (when (eq delete-window-set-selected 'pos)
+        (when (eq delete-window-choose-selected 'pos)
           ;; Remember edges and position of point of the selected window
           ;; of WINDOW'S frame.
           (setq frame-selected-window-edges
@@ -4276,8 +4279,8 @@ the option `delete-window-set-selected'."
         (window--pixel-to-total frame horizontal)
 
         ;; If we deleted the selected window of WINDOW's frame, choose
-        ;; another one based on `delete-window-set-selected'.  Note
-        ;; that both `window-at-pos' and `get-mru-window' may fail to
+        ;; another one based on `delete-window-choose-selected'.  Note
+        ;; that both `window-at-x-y' and `get-mru-window' may fail to
         ;; produce a suitable window in which case we will fall back on
         ;; its frame's first window, chosen by `delete-window-internal'.
         (cond
@@ -4287,7 +4290,7 @@ the option `delete-window-set-selected'."
                ;; selected window.  Try to find the window that is now
                ;; at that position.
                (let ((new-frame-selected-window
-                      (window-at-pos
+                      (window-at-x-y
                        (+ (nth 0 frame-selected-window-edges)
                           (car frame-selected-window-pos))
                        (+ (nth 1 frame-selected-window-edges)
@@ -4297,7 +4300,7 @@ the option `delete-window-set-selected'."
                       ;; Select window at WINDOW's position at point.
                       (set-frame-selected-window
                        frame new-frame-selected-window)))))
-         ((and (eq delete-window-set-selected 'mru)
+         ((and (eq delete-window-choose-selected 'mru)
                ;; Try to use the most recently used window.
                (let ((mru-window (get-mru-window frame nil nil t)))
                  (and mru-window