bug#16816: 24.3.50; erroneous docstring in with-temp-buffer-window

bug#16816: 24.3.50; erroneous docstring in with-temp-buffer-window

[Nicolas Richard]

The docstring of `with-temp-buffer-window' contains :

   It does not make the buffer current for BODY.

(2nd sentence of 2nd paragraph).

But I think that is wrong, because :
(with-temp-buffer-window
        (get-buffer-create "foo")
        nil
        nil
        (message "curbuf: %s"
                 (current-buffer)))

outputs "curbuf: foo"

If this is a docbug, here's a suggestion :

--- a/lisp/window.el
+++ b/lisp/window.el
@@ -149,10 +149,9 @@ BUFFER-OR-NAME must specify either a live buffer, or the name of a
 buffer (if it does not exist, this macro creates it).
 
 This construct makes buffer BUFFER-OR-NAME empty before running BODY.
-It does not make the buffer current for BODY.
-Instead it binds `standard-output' to that buffer, so that output
-generated with `prin1' and similar functions in BODY goes into
-the buffer.
+It makes the buffer current for BODY and binds `standard-output' to that
+buffer, so that output generated with `prin1' and similar functions in
+BODY goes into the buffer.
 
 At the end of BODY, this marks the specified buffer unmodified and
 read-only, and displays it in a window (but does not select it, or make



-- 
Nico.

bug#16816: 24.3.50; erroneous docstring in with-temp-buffer-window

[martin rudalics]

 > The docstring of `with-temp-buffer-window' contains :
 >
 >    It does not make the buffer current for BODY.
 >
 > (2nd sentence of 2nd paragraph).
 >
 > But I think that is wrong, because :
 > (with-temp-buffer-window
 >         (get-buffer-create "foo")
 >         nil
 >         nil
 >         (message "curbuf: %s"
 >                  (current-buffer)))
 >
 > outputs "curbuf: foo"
 >
 > If this is a docbug, here's a suggestion :
 >
 > --- a/lisp/window.el
 > +++ b/lisp/window.el
 > @@ -149,10 +149,9 @@ BUFFER-OR-NAME must specify either a live buffer, or the name of a
 >  buffer (if it does not exist, this macro creates it).
 >
 >  This construct makes buffer BUFFER-OR-NAME empty before running BODY.
 > -It does not make the buffer current for BODY.
 > -Instead it binds `standard-output' to that buffer, so that output
 > -generated with `prin1' and similar functions in BODY goes into
 > -the buffer.
 > +It makes the buffer current for BODY and binds `standard-output' to that
 > +buffer, so that output generated with `prin1' and similar functions in
 > +BODY goes into the buffer.
 >
 >  At the end of BODY, this marks the specified buffer unmodified and
 >  read-only, and displays it in a window (but does not select it, or make

`with-temp-buffer-window' should behave as `with-output-to-temp-buffer'
in this regard (at least I hope so).  So in revision 116509 I moved the
evaluation of BODY out of the scope of `with-current-buffer'.  If this
causes problems, I will revert and use your patch.

Thanks, martin

bug#16816: 24.3.50; erroneous docstring in with-temp-buffer-window

[Juanma Barranquero]

reopen 16816
quit

On Fri, Feb 21, 2014 at 2:08 PM, martin rudalics <rudalics@gmx.at> wrote:

> `with-temp-buffer-window' should behave as `with-output-to-temp-buffer'
> in this regard (at least I hope so).  So in revision 116509 I moved the
> evaluation of BODY out of the scope of `with-current-buffer'.  If this
> causes problems, I will revert and use your patch.

This breaks with-help-window. Try

 emacs -Q
 C-x C-h

the help output is inserted in the current buffer (*scratch*, in this case).

This patch fixes it.

=== modified file 'lisp/help.el'
--- lisp/help.el 2014-02-10 01:34:22 +0000
+++ lisp/help.el 2014-02-27 15:29:05 +0000
@@ -1207,7 +1207,8 @@
    (temp-buffer-window-show-hook
     (cons 'help-mode-finish temp-buffer-window-show-hook)))
        (with-temp-buffer-window
- ,buffer-name nil 'help-window-setup (progn ,@body)))))
+ ,buffer-name nil 'help-window-setup
+ (with-current-buffer ,buffer-name ,@body)))))

 ;; Called from C, on encountering `help-char' when reading a char.
 ;; Don't print to *Help*; that would clobber Help history.

bug#16816: 24.3.50; erroneous docstring in with-temp-buffer-window

[martin rudalics]

 > This breaks with-help-window. Try
 >
 >  emacs -Q
 >  C-x C-h
 >
 > the help output is inserted in the current buffer (*scratch*, in this case).

Yes.  A lousy bug.  I introduced it last year relying on the misfeature
that `with-temp-buffer-window' makes the help buffer current.  Does the
following patch fix it?

=== modified file 'lisp/help.el'
--- lisp/help.el	2014-02-10 01:34:22 +0000
+++ lisp/help.el	2014-02-27 18:31:30 +0000
@@ -498,7 +498,8 @@
  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))))
+      (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.

 > This patch fixes it.
 >
 > === modified file 'lisp/help.el'
 > --- lisp/help.el 2014-02-10 01:34:22 +0000
 > +++ lisp/help.el 2014-02-27 15:29:05 +0000
 > @@ -1207,7 +1207,8 @@
 >     (temp-buffer-window-show-hook
 >      (cons 'help-mode-finish temp-buffer-window-show-hook)))
 >         (with-temp-buffer-window
 > - ,buffer-name nil 'help-window-setup (progn ,@body)))))
 > + ,buffer-name nil 'help-window-setup
 > + (with-current-buffer ,buffer-name ,@body)))))
 >
 >  ;; Called from C, on encountering `help-char' when reading a char.
 >  ;; Don't print to *Help*; that would clobber Help history.
 >

This would restore what we had till now: BODY would get evaluated in the
help buffer and not in the original buffer.  I doubt this could have any
serious consequences (Emacs 24.3 runs this already for quite some time)
but it's inherently disturbing.

martin

bug#16816: 24.3.50; erroneous docstring in with-temp-buffer-window

[Juanma Barranquero]

On Thu, Feb 27, 2014 at 7:44 PM, martin rudalics <rudalics@gmx.at> wrote:

> Does the following patch fix it?

Yes.

> This would restore what we had till now: BODY would get evaluated in the
> help buffer and not in the original buffer.  I doubt this could have any
> serious consequences (Emacs 24.3 runs this already for quite some time)
> but it's inherently disturbing.

You're right, I suppose.

BTW, the docstring of with-help-window isn't exactly clear to me...

  Display buffer with name BUFFER-NAME in a help window evaluating BODY.

Evaluating BODY in a help window? What does this mean?

     J

bug#16816: 24.3.50; erroneous docstring in with-temp-buffer-window

[martin rudalics]

 > BTW, the docstring of with-help-window isn't exactly clear to me...
 >
 >   Display buffer with name BUFFER-NAME in a help window evaluating BODY.
 >
 > Evaluating BODY in a help window? What does this mean?

Drew's getting old.  Such an awful doc-string and he apparently never
complained ...

I'll have to fix the info entry too.  It doesn't even say that the
buffer gets displayed.

martin

bug#16816: 24.3.50; erroneous docstring in with-temp-buffer-window

[Drew Adams]

>  > BTW, the docstring of with-help-window isn't exactly clear to me...
>  >   Display buffer with name BUFFER-NAME in a help window evaluating BODY.
>  > Evaluating BODY in a help window? What does this mean?
> 
> Drew's getting old.

Everyone's getting old, from Day Zero on.

> Such an awful doc-string and he apparently never complained ...

So many bugs, so little time.  Fortunately, Juanma is there.

bug#16816: 24.3.50; erroneous docstring in with-temp-buffer-window

[martin rudalics]

 >> This would restore what we had till now: BODY would get evaluated in the
 >> help buffer and not in the original buffer.  I doubt this could have any
 >> serious consequences (Emacs 24.3 runs this already for quite some time)
 >> but it's inherently disturbing.
 >
 > You're right, I suppose.

I reverted my previous change.  It's too dangerous as the bug you
reported demonstrates.

 > BTW, the docstring of with-help-window isn't exactly clear to me...
 >
 >   Display buffer with name BUFFER-NAME in a help window evaluating BODY.
 >
 > Evaluating BODY in a help window? What does this mean?

I rewrote the doc-strings of `with-temp-buffer-window' and
`with-help-window'.  Please have a look.

martin

bug#16816: 24.3.50; erroneous docstring in with-temp-buffer-window

[martin rudalics]

 > This breaks with-help-window. Try
 >
 >  emacs -Q
 >  C-x C-h
 >
 > the help output is inserted in the current buffer (*scratch*, in this case).

Should be now fixed in the way I proposed initially.  Please check.

Thanks, martin

bug#16816: 24.3.50; erroneous docstring in with-temp-buffer-window

[Juanma Barranquero]

On Sun, Mar 16, 2014 at 11:00 AM, martin rudalics <rudalics@gmx.at> wrote:

> Should be now fixed in the way I proposed initially.  Please check.

Sorry, I forgot about this one. It works, of course.

Thanks,

   J

bug#16816: 24.3.50; erroneous docstring in with-temp-buffer-window

[martin rudalics]

 > If this is a docbug, here's a suggestion :

I made it a docbug now and largely expanded the doc-string based on your
suggestion.

martin