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'.

3 files changed, 58 insertions, 42 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 13b96b4ba5e..6e89c0d489b 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,10 @@
+2014-03-16  Martin Rudalics  <rudalics@gmx.at>
+
+        * 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'.
+
 2014-03-15  Dmitry Gutov  <dgutov@yandex.ru>
 
         * display.texi (Blinking): Update WRT to the new
@@ -6,7 +13,7 @@
 2014-03-14  Martin Rudalics  <rudalics@gmx.at>
 
         * display.texi (Temporary Displays): Say that
-        with-temp-buffer-window makes its buffer current.
+        `with-temp-buffer-window' makes its buffer current.
         * frames.texi (Size and Position): Describe new option
         `frame-resize-pixelwise'.  Rewrite descriptions of
         `set-frame-size', `set-frame-height' and `set-frame-width'.
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 27f002fe5fe..8bd657b5a9b 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -1094,29 +1094,29 @@ You can use a display table to substitute other text for the ellipsis
 buffer and then present it to the user for perusal rather than for
 editing.  Many help commands use this feature.
 
-@defmac with-output-to-temp-buffer buffer-name forms@dots{}
-This function executes @var{forms} while arranging to insert any output
-they print into the buffer named @var{buffer-name}, which is first
-created if necessary, and put into Help mode.  Finally, the buffer is
-displayed in some window, but not selected.  (See the similar
-form @code{with-temp-buffer-window} below.)
-
-If the @var{forms} do not change the major mode in the output buffer,
-so that it is still Help mode at the end of their execution, then
-@code{with-output-to-temp-buffer} makes this buffer read-only at the
-end, and also scans it for function and variable names to make them
-into clickable cross-references.  @xref{Docstring hyperlinks, , Tips
-for Documentation Strings}, in particular the item on hyperlinks in
+@defmac with-output-to-temp-buffer buffer-name body@dots{}
+This function executes the forms in @var{body} while arranging to insert
+any output they print into the buffer named @var{buffer-name}, which is
+first created if necessary, and put into Help mode.  (See the similar
+form @code{with-temp-buffer-window} below.)  Finally, the buffer is
+displayed in some window, but that window is not selected.
+
+If the forms in @var{body} do not change the major mode in the output
+buffer, so that it is still Help mode at the end of their execution,
+then @code{with-output-to-temp-buffer} makes this buffer read-only at
+the end, and also scans it for function and variable names to make them
+into clickable cross-references.  @xref{Docstring hyperlinks, , Tips for
+Documentation Strings}, in particular the item on hyperlinks in
 documentation strings, for more details.
 
-The string @var{buffer-name} specifies the temporary buffer, which
-need not already exist.  The argument must be a string, not a buffer.
-The buffer is erased initially (with no questions asked), and it is
-marked as unmodified after @code{with-output-to-temp-buffer} exits.
+The string @var{buffer-name} specifies the temporary buffer, which need
+not already exist.  The argument must be a string, not a buffer.  The
+buffer is erased initially (with no questions asked), and it is marked
+as unmodified after @code{with-output-to-temp-buffer} exits.
 
 @code{with-output-to-temp-buffer} binds @code{standard-output} to the
-temporary buffer, then it evaluates the forms in @var{forms}.  Output
-using the Lisp output functions within @var{forms} goes by default to
+temporary buffer, then it evaluates the forms in @var{body}.  Output
+using the Lisp output functions within @var{body} goes by default to
 that buffer (but screen display and messages in the echo area, although
 they are ``output'' in the general sense of the word, are not affected).
 @xref{Output Functions}.
@@ -1124,7 +1124,7 @@ they are ``output'' in the general sense of the word, are not affected).
 Several hooks are available for customizing the behavior
 of this construct; they are listed below.
 
-The value of the last form in @var{forms} is returned.
+The value of the last form in @var{body} is returned.
 
 @example
 @group
@@ -1174,28 +1174,34 @@ displaying the temporary buffer.  When the hook runs, the temporary buffer
 is current, and the window it was displayed in is selected.
 @end defvar
 
-@defmac with-temp-buffer-window buffer-or-name action quit-function forms@dots{}
+@defmac with-temp-buffer-window buffer-or-name action quit-function body@dots{}
 This macro is similar to @code{with-output-to-temp-buffer}.  Like that
-construct, it executes @var{forms} while arranging to insert any output
-they print into the buffer named @var{buffer-or-name} and displays the
+construct, it executes @var{body} while arranging to insert any output
+it prints into the buffer named @var{buffer-or-name} and displays that
 buffer in some window.  Unlike @code{with-output-to-temp-buffer},
-however, this makes the buffer current and does not switch to Help mode.
+however, it does not automatically switch that buffer to Help mode.
 
-The argument @var{buffer-or-name} specifies the temporary buffer.
-It can be either a buffer, which must already exist, or a string,
-in which case a buffer of that name is created if necessary.
-The buffer is marked as unmodified and read-only when
-@code{with-temp-buffer-window} exits.
+Like @code{with-output-to-temp-buffer} it neither makes the buffer
+specified by @var{buffer-or-name} current when executing @var{body}.
+@findex with-current-buffer-window
+The otherwise identical macro @code{with-current-buffer-window} can be
+used to execute @var{body} with that buffer current.
+
+The argument @var{buffer-or-name} specifies the temporary buffer.  It
+can be either a buffer, which must already exist, or a string, in which
+case a buffer of that name is created, if necessary.  The buffer is
+marked as unmodified and read-only when @code{with-temp-buffer-window}
+exits.
 
 This macro does not call @code{temp-buffer-show-function}.  Rather, it
 passes the @var{action} argument to @code{display-buffer} in order to
 display the buffer.
 
-The value of the last form in @var{forms} is returned, unless the
-argument @var{quit-function} is specified.  In that case,
-it is called with two arguments: the window showing the buffer
-and the result of @var{forms}.  The final return value is then
-whatever @var{quit-function} returns.
+The value of the last form in @var{body} is returned, unless the
+argument @var{quit-function} is specified.  In that case, it is called
+with two arguments: the window showing the buffer and the result of
+@var{body}.  The final return value is then whatever
+@var{quit-function} returns.
 
 @vindex temp-buffer-window-setup-hook
 @vindex temp-buffer-window-show-hook
diff --git a/doc/lispref/help.texi b/doc/lispref/help.texi
index 50103d3a8b3..9a763b60938 100644
--- a/doc/lispref/help.texi
+++ b/doc/lispref/help.texi
@@ -649,14 +649,17 @@ This function returns the name of the help buffer, which is normally
 @file{*Help*}; if such a buffer does not exist, it is first created.
 @end defun
 
+@vindex help-window-select
 @defmac with-help-window buffer-name body@dots{}
-This macro evaluates the @var{body} forms, inserting any output they
-produce into a buffer named @var{buffer-name} like
-@code{with-output-to-temp-buffer} (@pxref{Temporary Displays}).
-(Usually, @var{buffer-name} should be the value returned by the
-function @code{help-buffer}.)  It also puts the specified buffer into
-Help mode and displays a message telling the user how to quit and
-scroll the help window.
+This macro evaluates @var{body} like @code{with-output-to-temp-buffer}
+(@pxref{Temporary Displays}), inserting any output produced by its forms
+into a buffer named @var{buffer-name}.  (Usually, @var{buffer-name}
+should be the value returned by the function @code{help-buffer}.)  It
+also puts the specified buffer into Help mode and displays a message
+telling the user how to quit and scroll the help window.  It selects the
+help window if the current value of the user option
+@code{help-window-select} has been set accordingly.  It returns the last
+value in @var{body}.
 @end defmac
 
 @defun help-setup-xref item interactive-p