Some fixes around delete-other-frames' and next-frame'

* src/frame.c (Fdelete_frame): Clarify doc-string.
* lisp/frame.el (delete-other-frames): Delete other frames on
FRAME's terminal instead of the current terminal.  Delete
non-minibuffer-only surrogate frames too.  See
http://lists.gnu.org/archive/html/emacs-devel/2016-08/msg00467.html
* doc/lispref/frames.texi (Deleting Frames): Minor fixes for
docs of `delete-frame' and `frame-live-p'.  Add entry for
`delete-other-frames'.
(Finding All Frames): Fix doc of `next-frame'.

doc/lispref/frames.texi

@@ -1904,10 +1904,11 @@ to it.
 
 @deffn Command delete-frame &optional frame force
 @vindex delete-frame-functions
-This function deletes the frame @var{frame}.  Unless @var{frame} is a
-tooltip, it first runs the hook @code{delete-frame-functions} (each
-function gets one argument, @var{frame}).  By default, @var{frame} is
-the selected frame.
+This function deletes the frame @var{frame}.  The argument @var{frame}
+must specify a live frame (see below) and defaults to the selected
+frame.  Unless @var{frame} specifies a tooltip, this function first runs
+the hook @code{delete-frame-functions} (each function getting one
+argument, @var{frame}).
 
 A frame cannot be deleted as long as its minibuffer serves as surrogate
 minibuffer for another frame (@pxref{Minibuffers and Frames}).
@@ -1916,9 +1917,9 @@ but if @var{force} is non-@code{nil}, then you are allowed to do so.
 @end deffn
 
 @defun frame-live-p frame
-The function @code{frame-live-p} returns non-@code{nil} if the frame
-@var{frame} has not been deleted.  The possible non-@code{nil} return
-values are like those of @code{framep}.  @xref{Frames}.
+This function returns non-@code{nil} if the frame @var{frame} has not
+been deleted.  The possible non-@code{nil} return values are like those
+of @code{framep}.  @xref{Frames}.
 @end defun
 
   Some window managers provide a command to delete a window.  These work
@@ -1927,6 +1928,15 @@ When Emacs gets one of these commands, it generates a
 @code{delete-frame} event, whose normal definition is a command that
 calls the function @code{delete-frame}.  @xref{Misc Events}.
 
+@deffn Command delete-other-frames &optional frame
+This command deletes all frames on @var{frame}'s terminal, except
+@var{frame}.  If @var{frame} uses another frame's minibuffer, that
+minibuffer frame is left untouched.  The argument @var{frame} must
+specify a live frame and defaults to the selected frame.  Internally,
+this command works by calling @code{delete-frame} with @var{force}
+@code{nil} for all frames that shall be deleted.
+@end deffn
+
 @node Finding All Frames
 @section Finding All Frames
 @cindex frames, scanning all
@@ -1946,11 +1956,11 @@ visible, even though only the selected one is actually displayed.
 @end defun
 
 @defun next-frame &optional frame minibuf
-This function lets you cycle conveniently through all the frames on
-the current display from an arbitrary starting point.  It returns the
-next frame after @var{frame} in the cycle.  If @var{frame} is
-omitted or @code{nil}, it defaults to the selected frame (@pxref{Input
-Focus}).
+This function lets you cycle conveniently through all the frames on a
+specific terminal from an arbitrary starting point.  It returns the
+frame following @var{frame}, in the list of all live frames, on
+@var{frame}'s terminal.  The argument @var{frame} must specify a live
+frame and defaults to the selected frame.
 
 The second argument, @var{minibuf}, says which frames to consider:
 

lisp/frame.el

@@ -1874,30 +1874,29 @@ In the 3rd, 4th, and 6th examples, the returned value is relative to
 the opposite frame edge from the edge indicated in the input spec."
   (cons (car spec) (frame-geom-value-cons (car spec) (cdr spec) frame)))
 
-
 (defun delete-other-frames (&optional frame)
-  "Delete all frames on the current terminal, except FRAME.
+  "Delete all frames on FRAME's terminal, except FRAME.
 If FRAME uses another frame's minibuffer, the minibuffer frame is
-left untouched.  FRAME nil or omitted means use the selected frame."
+left untouched.  FRAME must be a live frame and defaults to the
+selected one."
   (interactive)
-  (unless frame
-    (setq frame (selected-frame)))
-  (let* ((mini-frame (window-frame (minibuffer-window frame)))
-	 (frames (delq mini-frame (delq frame (frame-list)))))
-    ;; Only consider frames on the same terminal.
-    (dolist (frame (prog1 frames (setq frames nil)))
-      (if (eq (frame-terminal) (frame-terminal frame))
-          (push frame frames)))
-    ;; Delete mon-minibuffer-only frames first, because `delete-frame'
-    ;; signals an error when trying to delete a mini-frame that's
-    ;; still in use by another frame.
-    (dolist (frame frames)
-      (unless (eq (frame-parameter frame 'minibuffer) 'only)
-	(delete-frame frame)))
-    ;; Delete minibuffer-only frames.
-    (dolist (frame frames)
-      (when (eq (frame-parameter frame 'minibuffer) 'only)
-	(delete-frame frame)))))
+  (setq frame (window-normalize-frame frame))
+  (let ((minibuffer-frame (window-frame (minibuffer-window frame)))
+        (this (next-frame frame t))
+        next)
+    ;; In a first round consider minibuffer-less frames only.
+    (while (not (eq this frame))
+      (setq next (next-frame this t))
+      (unless (eq (window-frame (minibuffer-window this)) this)
+        (delete-frame this))
+      (setq this next))
+    ;; In a second round consider all remaining frames.
+    (setq this (next-frame frame t))
+    (while (not (eq this frame))
+      (setq next (next-frame this t))
+      (unless (eq this minibuffer-frame)
+        (delete-frame this))
+      (setq this next))))
 
 ;; miscellaneous obsolescence declarations
 (define-obsolete-variable-alias 'delete-frame-hook

src/frame.c

@@ -1826,7 +1826,7 @@ delete_frame (Lisp_Object frame, Lisp_Object force)
 
 DEFUN ("delete-frame", Fdelete_frame, Sdelete_frame, 0, 2, "",
        doc: /* Delete FRAME, permanently eliminating it from use.
-FRAME defaults to the selected frame.
+FRAME must be a live frame and defaults to the selected one.
 
 A frame may not be deleted if its minibuffer serves as surrogate
 minibuffer for another frame.  Normally, you may not delete a frame if