Deprecate with-displayed-buffer-window, use body-function instead (bug#39822)

* doc/lispref/display.texi (Temporary Displays):
Remove defmac with-displayed-buffer-window.

* doc/lispref/windows.texi (Buffer Display Action Alists):
Add body-function.

* lisp/window.el (with-displayed-buffer-window): Declare macro obsolete.
(window--display-buffer): Call 'body-function' after displaying the buffer.

* lisp/dired.el (dired-mark-pop-up):
* lisp/files.el (save-buffers-kill-emacs):
* lisp/minibuffer.el (minibuffer-completion-help):
Replace with-displayed-buffer-window with with-current-buffer-window
and add action alist entry 'body-function' with former macro body.

2 files changed, 9 insertions, 6 deletions

diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 2b25d6023cd..9fbf995d7e4 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -1318,12 +1318,6 @@ the buffer specified by @var{buffer-or-name} current for running
 @var{body}.
 @end defmac
 
-@defmac with-displayed-buffer-window buffer-or-name action quit-function &rest body
-This macro is like @code{with-current-buffer-window} but unlike that
-displays the buffer specified by @var{buffer-or-name} @emph{before}
-running @var{body}.
-@end defmac
-
 A window showing a temporary buffer can be fitted to the size of that
 buffer using the following mode:
 
diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index d0791d40196..00142d87dcc 100644
--- a/doc/lispref/windows.texi
+++ b/doc/lispref/windows.texi
@@ -3048,6 +3048,15 @@ since there is no guarantee that an arbitrary caller of
 @code{display-buffer} will be able to handle the case that no window
 will display the buffer.  @code{display-buffer-no-window} is the only
 action function that cares about this entry.
+
+@vindex body-function@r{, a buffer display action alist entry}
+@item body-function
+The value must be a function taking one argument (a displayed window).
+This function can be used to fill the displayed window's body with
+some contents.  It is called @emph{after} the buffer is displayed, and
+@emph{before} the entries @code{window-height}, @code{window-width}
+and @code{preserve-size} are applied that could resize the window
+to fit it to the inserted contents.
 @end table
 
 By convention, the entries @code{window-height}, @code{window-width}