[Emacs-diffs] master 3b9d689: Add docs for display-buffer action display-buffer-use-some-frame

[Stephen Leake]

branch: master
commit 3b9d689c2abb294250de6c690d77e9175952be72
Author: Stephen Leake <address@hidden>
Commit: Stephen Leake <address@hidden>

    Add docs for display-buffer action display-buffer-use-some-frame
    
    * lisp/window.el (display-buffer-use-some-frame): improve doc string
    
    * doc/lispref/windows.texi (Display Action Functions): add
      display-buffer-use-some-frame
    
    * etc/NEWS: mention display-buffer-use-some-frame
---
 doc/lispref/windows.texi |   17 +++++++++++++++++
 etc/NEWS                 |    5 +++++
 lisp/window.el           |   16 +++++++---------
 3 files changed, 29 insertions(+), 9 deletions(-)

diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index 750397c..41f02aa 100644
--- a/doc/lispref/windows.texi
+++ b/doc/lispref/windows.texi
@@ -2301,6 +2301,23 @@ the function specified in @code{pop-up-frame-function}
 is added to the newly created frame's parameters.
 @end defun
 
address@hidden display-buffer-use-some-frame buffer alist
+This function tries to ``display'' @var{buffer} by trying to find a
+frame that meets a predicate (by default any frame other than the
+current frame).
+
+If @var{alist} has a address@hidden @code{`inhibit-switch-frame} entry,
+avoid raising the frame.
+
+If @var{alist} has a non-nil @code{frame-predicate} entry, its value is a
+function taking one argument (a frame), returning non-nil if the
+frame is a candidate; this function replaces the default predicate.
+
+If this function chooses a window on another frame, it makes that frame
+visible and, unless @var{alist} contains an @code{inhibit-switch-frame}
+entry (@pxref{Choosing Window Options}), raises that frame if necessary.
address@hidden defun
+
 @defun display-buffer-pop-up-window buffer alist
 This function tries to display @var{buffer} by splitting the largest
 or least recently-used window (typically one on the selected frame).
diff --git a/etc/NEWS b/etc/NEWS
index 5bb7a00..6dbe6b3 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -84,6 +84,11 @@ command line when `initial-buffer-choice' is non-nil.
 
 * Changes in Emacs 25.1
 
+** New display-buffer action function display-buffer-use-some-frame
+This displays the buffer in an existing frame other than the current
+frame, and allows the caller to specify a frame predicate to exclude
+frames.
+
 ** New doc command `describe-symbol'.  Works for functions, vars, faces, etc...
 
 ** `isearch' and `query-replace' now perform character folding in matches.
diff --git a/lisp/window.el b/lisp/window.el
index 986c553..238e53c 100644
--- a/lisp/window.el
+++ b/lisp/window.el
@@ -6489,19 +6489,17 @@ its documentation for additional customization 
information."
 ;;; `display-buffer' action functions:
 
 (defun display-buffer-use-some-frame (buffer alist)
-  "Display BUFFER in an existing frame other than the current frame.
-If successful, return the window used; otherwise return nil.
+  "Display BUFFER in an existing frame that meets a predicate
+(by default any frame other than the current frame).  If
+successful, return the window used; otherwise return nil.
 
 If ALIST has a non-nil `inhibit-switch-frame' entry, avoid
 raising the frame.
 
-If ALIST has a non-nil `pop-up-frame-parameters' entry, the
-corresponding value is an alist of frame parameters to give the
-new frame.
-
-If ALIST has a non-nil `frame-predicate' entry, the corresponding
-value is a function taking one argument (a frame), returning
-non-nil if the frame is a candidate."
+If ALIST has a non-nil `frame-predicate' entry, its value is a
+function taking one argument (a frame), returning non-nil if the
+frame is a candidate; this function replaces the default
+predicate."
   (let* ((predicate (or (cdr (assoc 'frame-predicate alist))
                         (lambda (frame)
                           (and