Fix behavior of with-temp-buffer-window (Bug#16816, Bug#17007).

* window.el (with-temp-buffer-window): Don't make BUFFER-OR-NAME
current (Bug#16816, Bug#17007).
(with-current-buffer-window): New macro doing the same as
`with-temp-buffer-window' but with BUFFER-OR-NAME current.
* help.el (help-print-return-message): Warn in doc-string to not
use this in `with-help-window'.
(describe-bindings-internal): Call `describe-buffer-bindings'
from within help buffer.  See Juanma's scenario in (Bug#16816).
(with-help-window): Update doc-string.
* dired.el (dired-mark-pop-up):
* files.el (save-buffers-kill-emacs):
* register.el (register-preview): Use `with-current-buffer-window'
instead of `with-temp-buffer-window'.
* display.texi (Temporary Displays): Rewrite descriptions of
`with-output-to-temp-buffer' and `with-temp-buffer-window'.
* help.texi (Help Functions): Rewrite description of
`with-help-window'.

1 files changed, 19 insertions, 17 deletions

diff --git a/lisp/help.el b/lisp/help.el
index 46094e9f6b0..14dda6456cf 100644
--- a/lisp/help.el
+++ b/lisp/help.el
@@ -133,7 +133,9 @@ This function assumes that `standard-output' is the help buffer.
 It computes a message, and applies the optional argument FUNCTION to it.
 If FUNCTION is nil, it applies `message', thus displaying the message.
 In addition, this function sets up `help-return-method', which see, that
-specifies what to do when the user exits the help buffer."
+specifies what to do when the user exits the help buffer.
+
+Do not call this in the scope of `with-help-window'."
   (and (not (get-buffer-window standard-output))
        (let ((first-message
 	      (cond ((or
@@ -498,7 +500,10 @@ The optional argument PREFIX, if non-nil, should be a key sequence;
 then we display only bindings that start with that prefix."
   (let ((buf (current-buffer)))
     (with-help-window (help-buffer)
-      (describe-buffer-bindings buf prefix menus))))
+      ;; Be aware that `describe-buffer-bindings' puts its output into
+      ;; the current buffer.
+      (with-current-buffer (help-buffer)
+	(describe-buffer-bindings buf prefix menus)))))
 
 (defun where-is (definition &optional insert)
   "Print message listing key sequences that invoke the command DEFINITION.
@@ -1180,28 +1185,25 @@ Return VALUE."
 ;; providing the following additional twists:
 
 ;; (1) It puts the buffer in `help-mode' (via `help-mode-setup') and
-;; adds cross references (via `help-mode-finish').
+;;     adds cross references (via `help-mode-finish').
 
 ;; (2) It issues a message telling how to scroll and quit the help
-;; window (via `help-window-setup').
+;;     window (via `help-window-setup').
 
 ;; (3) An option (customizable via `help-window-select') to select the
-;; help window automatically.
+;;     help window automatically.
 
 ;; (4) A marker (`help-window-point-marker') to move point in the help
-;; window to an arbitrary buffer position.
-
-;; Note: It's usually always wrong to use `help-print-return-message' in
-;; the body of `with-help-window'.
+;;     window to an arbitrary buffer position.
 (defmacro with-help-window (buffer-name &rest body)
-  "Display buffer with name BUFFER-NAME in a help window.
-Evaluate the forms in BODY with the buffer specified by
-BUFFER-NAME current, put that buffer in `help-mode', display the
-buffer in a window (see `with-temp-buffer-window' for details)
-and issue a message how to deal with that \"help\" window when
-it's no more needed.  Select the help window if the current value
-of the user option `help-window-select' says so.  Return last
-value in BODY."
+  "Display buffer named BUFFER-NAME in a help window.
+Evaluate the forms in BODY with standard output bound to a buffer
+called BUFFER-NAME (creating it if it does not exist), put that
+buffer in `help-mode', display the buffer in a window (see
+`with-temp-buffer-window' for details) and issue a message how to
+deal with that \"help\" window when it's no more needed.  Select
+the help window if the current value of the user option
+`help-window-select' says so.  Return last value in BODY."
   (declare (indent 1) (debug t))
   `(progn
      ;; Make `help-window-point-marker' point nowhere.  The only place