bug#16038: 24.3; latest change to with-help-window makes temp-buffer-browse useless

bug#16038: 24.3; latest change to with-help-window makes temp-buffer-browse useless

[Leo Liu]

with-help-window has been changed to use with-temp-buffer-window.
temp-buffer-window-show has special treatment for
temp-buffer-resize-mode but not temp-buffer-browse-mode (in GNU ELPA).

There seems to be a significant overlap between with-temp-buffer-window
and with-output-to-temp-buffer. I wonder if there is a better design of
with-temp-buffer-window that re-use/blend with
with-output-to-temp-buffer. I also find the similar hooks (setup/show
hooks) between these macros confusing.

Maybe what need isn't a macro close to with-output-to-temp-buffer but
one (e.g with-temp-window) close to with-temp-buffer.

Thank you for considering these points,
Leo

bug#16038: 24.3; latest change to with-help-window makes temp-buffer-browse useless

[martin rudalics]

 > with-help-window has been changed to use with-temp-buffer-window.
 > temp-buffer-window-show has special treatment for
 > temp-buffer-resize-mode but not temp-buffer-browse-mode (in GNU ELPA).
 >
 > There seems to be a significant overlap between with-temp-buffer-window
 > and with-output-to-temp-buffer. I wonder if there is a better design of
 > with-temp-buffer-window that re-use/blend with
 > with-output-to-temp-buffer. I also find the similar hooks (setup/show
 > hooks) between these macros confusing.

`with-help-window' does some things differently which I could not put
into `with-output-to-temp-buffer' due to compatibility issues.  Can't
you put `temp-buffer-browse-mode' on `temp-buffer-window-show-hook'?

 > Maybe what need isn't a macro close to with-output-to-temp-buffer but
 > one (e.g with-temp-window) close to with-temp-buffer.

The idea of `with-temp-buffer' is to create a temporary buffer where you
evaluate things and _kill_ that buffer immediately afterwards.  The idea
of `with-temp-buffer-window' is to show the buffer and keep it around at
least until you quit the window.

martin

bug#16038: 24.3; latest change to with-help-window makes temp-buffer-browse useless

[Leo Liu]

On 2014-01-11 22:01 +0800, martin rudalics wrote:
[snipped 10 lines]
> `with-help-window' does some things differently which I could not put
> into `with-output-to-temp-buffer' due to compatibility issues.  Can't
> you put `temp-buffer-browse-mode' on `temp-buffer-window-show-hook'?

Thanks, Martin, for your response.

with-output-to-temp-buffer usually are used to show useful text.
with-temp-buffer-window is sometimes used to show temporary text such as
used by dired to show a list of marked files. Certainly I can put a hook
temp-buffer-window-show-hook but then I also need to opt out those
temporary cases. And it seems temp-buffer-resize-mode is now
unnecessarily coupled with the window.el code, i.e. if we were to move
temp-buffer-resize-mode to a standalone package it won't work without
help from window.el.

The more interesting question is is it possible to merge these two
macros? For example, will it work if we can re-design the first argument
of with-output-to-temp-buffer to accept a list (BUFFER-OR-NAME ACTION
QUIT-FUNCTION) or an atom BUFFER-OR-NAME?

Leo

bug#16038: 24.3; latest change to with-help-window makes temp-buffer-browse useless

[martin rudalics]

 > with-output-to-temp-buffer usually are used to show useful text.
 > with-temp-buffer-window is sometimes used to show temporary text such as
 > used by dired to show a list of marked files.

IIRC my primary purpose writing `with-temp-buffer-window' was to get
`with-help-window' right and this does not necessarily show temporary
text.

 > Certainly I can put a hook
 > temp-buffer-window-show-hook but then I also need to opt out those
 > temporary cases.

You would have had to do this anyway: Earlier there was only
`with-output-to-temp-buffer' and so the marked files of dired would have
been shown with `with-output-to-temp-buffer' instead.  I suppose we use
`with-temp-buffer-window' now because this allows us to "quit" the
window easier.

 > And it seems temp-buffer-resize-mode is now
 > unnecessarily coupled with the window.el code, i.e. if we were to move
 > temp-buffer-resize-mode to a standalone package it won't work without
 > help from window.el.

`temp-buffer-resize-mode' which uses `resize-temp-buffer-window' is
still in help.el although it doesn't really belong there.  And
`resize-temp-buffer-window' calls `fit-window-to-buffer' which is
inherently tied to the window code.  So the core of
`temp-buffer-resize-mode' was with the window resizing code ever since.

 > The more interesting question is is it possible to merge these two
 > macros? For example, will it work if we can re-design the first argument
 > of with-output-to-temp-buffer to accept a list (BUFFER-OR-NAME ACTION
 > QUIT-FUNCTION) or an atom BUFFER-OR-NAME?

I'd rather get rid of `with-output-to-temp-buffer' ;-)

If you look into our mail archives, you should find a couple of
complaints about `with-output-to-temp-buffer' putting the buffer in
`help-mode' (via `temp-buffer-setup-hook') and the like.  I tried to
avoid these when I wrote `with-temp-buffer-window'.

Assume two applications A and B: A expects `with-output-to-temp-buffer'
to put the buffer in `help-mode'.  B wants to avoid that the buffer is
put in `help-mode'.  I can offer B to use `with-temp-buffer-window'
instead while A can continue to work as usual.  Eventually I'd like A to
use `with-temp-buffer-window' too and put the buffer in `help-mode'
itself.  But there were too many `with-output-to-temp-buffer' calls in
the code base and I was not able to look into them.

martin

bug#16038: 24.3; latest change to with-help-window makes temp-buffer-browse useless

[Leo Liu]

On 2014-01-11 23:41 +0800, martin rudalics wrote:
> I'd rather get rid of `with-output-to-temp-buffer' ;-)

Yes, please make one of them obsolete.

> If you look into our mail archives, you should find a couple of
> complaints about `with-output-to-temp-buffer' putting the buffer in
> `help-mode' (via `temp-buffer-setup-hook') and the like.  I tried to
> avoid these when I wrote `with-temp-buffer-window'.
>
> Assume two applications A and B: A expects `with-output-to-temp-buffer'
> to put the buffer in `help-mode'.  B wants to avoid that the buffer is
> put in `help-mode'.  I can offer B to use `with-temp-buffer-window'
> instead while A can continue to work as usual.  Eventually I'd like A to
> use `with-temp-buffer-window' too and put the buffer in `help-mode'
> itself.  But there were too many `with-output-to-temp-buffer' calls in
> the code base and I was not able to look into them.

Indeed it seems with-temp-buffer-window is more powerful. Please take
steps to deprecate the other macro. It is this that looks rather ugly:

1) temp-buffer-setup-hook,        temp-buffer-show-hook,
2) temp-buffer-window-setup-hook, temp-buffer-window-show-hook

Leo

bug#16038: 24.3; latest change to with-help-window makes temp-buffer-browse useless

[martin rudalics]

 > It is this that looks rather ugly:
 >
 > 1) temp-buffer-setup-hook,        temp-buffer-show-hook,
 > 2) temp-buffer-window-setup-hook, temp-buffer-window-show-hook

I know.  But this was predated by

;; This makes `with-output-to-temp-buffer' buffers use `help-mode'.
(add-hook 'temp-buffer-setup-hook 'help-mode-setup)
(add-hook 'temp-buffer-show-hook 'help-mode-finish)

and nobody suggested how to cleanly disentangle these.

martin

bug#16038: 24.3; latest change to with-help-window makes temp-buffer-browse useless

[Leo Liu]

On 2014-01-12 17:53 +0800, martin rudalics wrote:
> I know.  But this was predated by
>
> ;; This makes `with-output-to-temp-buffer' buffers use `help-mode'.
> (add-hook 'temp-buffer-setup-hook 'help-mode-setup)
> (add-hook 'temp-buffer-show-hook 'help-mode-finish)
>
> and nobody suggested how to cleanly disentangle these.
>
> martin

Stefan,

Could you comment on this issue? Could we remove the following two
add-hooks?

--8<---------------cut here---------------start------------->8---
(add-hook 'temp-buffer-setup-hook 'help-mode-setup)
(add-hook 'temp-buffer-show-hook 'help-mode-finish)
--8<---------------cut here---------------end--------------->8---

Martin,

Assume help-mode and with-output-to-temp-buffer are decoupled, is it
possible to merge the two macros with-output-to-temp-buffer and
with-temp-buffer-window?

Thank you,
Leo

bug#16038: 24.3; latest change to with-help-window makes temp-buffer-browse useless

[Stefan Monnier]

> Could you comment on this issue? Could we remove the following two
> add-hooks?

> --8<---------------cut here---------------start------------->8---
> (add-hook 'temp-buffer-setup-hook 'help-mode-setup)
> (add-hook 'temp-buffer-show-hook 'help-mode-finish)
> --8<---------------cut here---------------end--------------->8---

What makes you think we could?


        Stefan

bug#16038: 24.3; latest change to with-help-window makes temp-buffer-browse useless

[Leo Liu]

On 2014-01-14 09:47 +0800, Stefan Monnier wrote:
> What makes you think we could?
>
>
>         Stefan

I have no idea why those hooks are needed in the first place. Thus
asking. The commit that added this is:

revno: 39713
committer: Miles Bader <miles@gnu.org>
timestamp: Tue 2001-10-09 11:17:39 +0000
message:
  Don't require `view' when compiling.
  (help-with-tutorial, describe-function, describe-function-1)
  (variable-at-point, describe-variable, locate-library):
  Functions moved into `help-funs.el'.
  (help-manyarg-func-alist): Variable moved into `help-funs.el'.
  (help-mode, help-mode-setup, help-mode-finish, help-button-action)
  (help-setup-xref, help-xref-following, help-make-xrefs)
  (help-xref-button, help-insert-xref-button, help-xref-interned)
  (help-xref-go-back, help-go-back, help-do-xref, help-follow)
  (help-xref-on-pp): Functions moved into `help-mode.el'
  (help-mode-map, help-xref-stack, help-xref-stack-item)
  (help-highlight-p, help-highlight-face, help-back-label)
  (help-xref-symbol-regexp, help-xref-mule-regexp)
  (help-xref-info-regexp): Variables moved into `help-mode.el'.
  (help-symbol, help-back, help-info, help-customize-variable)
  (help-function-def, help-variable-def):
  Button-types moved into `help-mode.el'.
  (load-symbol-file-load-history, symbol-file):
  Functions moved into `subr.el'.
  (symbol-file-load-history-loaded): Variable moved into `subr.el'.
  (view-lossage): Call `help-setup-xref' instead of doing it manually.


Now that with-help-window is implemented on top of
with-temp-buffer-window, it seems they are useless.

The whole thing also looks odd how temp-buffer is tied to
help-buffer/window etc?

Leo

bug#16038: 24.3; latest change to with-help-window makes temp-buffer-browse useless

[Stefan Monnier]

> I have no idea why those hooks are needed in the first place.

They were needed because temp-buffer was tied to help-buffer/window.

> The commit that added this is:
> revno: 39713
> committer: Miles Bader <miles@gnu.org>
> timestamp: Tue 2001-10-09 11:17:39 +0000
> message:
>   Don't require `view' when compiling.
>   (help-with-tutorial, describe-function, describe-function-1)
>   (variable-at-point, describe-variable, locate-library):
>   Functions moved into `help-funs.el'.
>   (help-manyarg-func-alist): Variable moved into `help-funs.el'.
>   (help-mode, help-mode-setup, help-mode-finish, help-button-action)
>   (help-setup-xref, help-xref-following, help-make-xrefs)
>   (help-xref-button, help-insert-xref-button, help-xref-interned)
>   (help-xref-go-back, help-go-back, help-do-xref, help-follow)
>   (help-xref-on-pp): Functions moved into `help-mode.el'
>   (help-mode-map, help-xref-stack, help-xref-stack-item)
>   (help-highlight-p, help-highlight-face, help-back-label)
>   (help-xref-symbol-regexp, help-xref-mule-regexp)
>   (help-xref-info-regexp): Variables moved into `help-mode.el'.
>   (help-symbol, help-back, help-info, help-customize-variable)
>   (help-function-def, help-variable-def):
>   Button-types moved into `help-mode.el'.
>   (load-symbol-file-load-history, symbol-file):
>   Functions moved into `subr.el'.
>   (symbol-file-load-history-loaded): Variable moved into `subr.el'.
>   (view-lossage): Call `help-setup-xref' instead of doing it manually.

Are you sure?  This looks like a commit that mostly moves code around.
I think those hook functions are older.

> Now that with-help-window is implemented on top of
> with-temp-buffer-window, it seems they are useless.

That could be.  But someone needs to look in detail at whether that's
the case or not.

> The whole thing also looks odd how temp-buffer is tied to
> help-buffer/window etc?

You know, hysterical raisins'n stuff.


        Stefan

bug#16038: 24.3; latest change to with-help-window makes temp-buffer-browse useless

[Drew Adams]

> I have no idea why those hooks are needed in the first place.

Uh, for when you want to associate some action with either setting
up or showing a so-called "temp" buffer (which unfortunately for
the name means a help buffer, since we have now loaded such buffers
and their displays down with help-specific stuff).

For example, to have the frame be automatically fit to the buffer
contents if there is only one window, you can do this (if you have
library `autofit-frame.el'):

(add-hook 'temp-buffer-show-hook
          'fit-frame-if-one-window
          'append)

bug#16038: 24.3; latest change to with-help-window makes temp-buffer-browse useless

[Leo Liu]

On 2014-01-15 05:55 +0800, Drew Adams wrote:
> Uh, for when you want to associate some action with either setting
> up or showing a so-called "temp" buffer (which unfortunately for
> the name means a help buffer, since we have now loaded such buffers
> and their displays down with help-specific stuff).
>
> For example, to have the frame be automatically fit to the buffer
> contents if there is only one window, you can do this (if you have
> library `autofit-frame.el'):
>
> (add-hook 'temp-buffer-show-hook
>           'fit-frame-if-one-window
>           'append)

Sorry if I haven't been clear. This is not proposing removing those
hooks but removing the add-hooks i.e.:

  (add-hook 'temp-buffer-setup-hook 'help-mode-setup)
  (add-hook 'temp-buffer-show-hook 'help-mode-finish)

Leo

bug#16038: 24.3; latest change to with-help-window makes temp-buffer-browse useless

[Leo Liu]

On 2014-01-15 05:38 +0800, Stefan Monnier wrote:
> Are you sure?  This looks like a commit that mostly moves code around.
> I think those hook functions are older.

I am not sure the repo goes back further than 2001.

>> Now that with-help-window is implemented on top of
>> with-temp-buffer-window, it seems they are useless.
>
> That could be.  But someone needs to look in detail at whether that's
> the case or not.

I have been using the trunk without those add-hooks and haven't seen any
ill-effect for the past week.

Leo

bug#16038: 24.3; latest change to with-help-window makes temp-buffer-browse useless

[Stefan Monnier]

>>> Now that with-help-window is implemented on top of
>>> with-temp-buffer-window, it seems they are useless.
>> That could be.  But someone needs to look in detail at whether that's
>> the case or not.
> I have been using the trunk without those add-hooks and haven't seen any
> ill-effect for the past week.

Could you explain why it doesn't have any ill-effect?
Put it another way, could you try to characterize in which case it would
make a difference, and then try and figure out (or argue) that such
a situation never happens or at least is very unlikely.


        Stefan

bug#16038: 24.3; latest change to with-help-window makes temp-buffer-browse useless

[Leo Liu]

On 2014-01-22 11:02 +0800, Stefan Monnier wrote:
[snipped 7 lines]
> Could you explain why it doesn't have any ill-effect?
> Put it another way, could you try to characterize in which case it would
> make a difference, and then try and figure out (or argue) that such
> a situation never happens or at least is very unlikely.
>
>
>         Stefan

On 2014-01-22 11:07 +0800, Glenn Morris wrote:
[snipped 3 lines]
> bzr log -c 1
>
>   -> timestamp: Thu 1985-04-18 00:48:29 +0000
>
>
> Anyway, vc-annotate is your friend:
>
> (add-hook 'temp-buffer-setup-hook 'help-mode-setup)
> appeared in r24049, 1999-01-11.
>
> (add-hook 'temp-buffer-show-hook 'help-mode-finish)
> appeared in r20061, 1997-10-15 (as help-mode-maybe).

Thanks.

------------------------------------------------------------
revno: 20061
committer: Karl Heuer <kwzh@gnu.org>
timestamp: Wed 1997-10-15 23:36:30 +0000
message:
  (help-mode-maybe): New function, on temp-buffer-show-hook.
  (describe-key, describe-mode): Don't call help-mode here.
  (view-lossage, describe-function, describe-variable): Likewise.

------------------------------------------------------------
revno: 24049
committer: Richard M. Stallman <rms@gnu.org>
timestamp: Mon 1999-01-11 15:25:41 +0000
message:
  (help-mode-finish): Renamed from help-mode-maybe.
  Don't switch to Help mode here.
  (temp-buffer-setup-hook): Use help-mode-finish.
  (help-mode-setup): New function.
  (temp-buffer-setup-hook): Use help-mode-setup.

So these hooks were added for help mode which is no longer using
with-output-to-temp-buffer but with-temp-buffer-window i.e. they are not
needed any more.

Stefan, do you have anything in mind that might be affected without
these add-hooks? Removing them would of course leave temp-buffers in
fundamental mode. But other than that I haven't seen anything strange.

Leo

bug#16038: 24.3; latest change to with-help-window makes temp-buffer-browse useless

[Stefan Monnier]

> Stefan, do you have anything in mind that might be affected without
> these add-hooks?

No, I don't know the code enough to have any idea about it.

> Removing them would of course leave temp-buffers in fundamental mode.
> But other than that I haven't seen anything strange.

OK, so let's remove them as soon as the trunk re-opens.


        Stefan

bug#16038: 24.3; latest change to with-help-window makes temp-buffer-browse useless

[Leo Liu]

On 2014-01-22 21:44 +0800, Stefan Monnier wrote:
>> Removing them would of course leave temp-buffers in fundamental mode.
>> But other than that I haven't seen anything strange.
>
> OK, so let's remove them as soon as the trunk re-opens.

Stefan, OK, I'll take care of this.

Martin, now that we have this good news, will you be able to go ahead
with deprecating with-output-to-temp-buffer and merge it with
with-temp-buffer-window or vice versa?

Thanks,
Leo

bug#16038: 24.3; latest change to with-help-window makes temp-buffer-browse useless

[Drew Adams]

> Martin, now that we have this good news, will you be able to go ahead
> with deprecating with-output-to-temp-buffer and merge it with
> with-temp-buffer-window or vice versa?

Huh?  What's this about?  Why on Earth would we deprecate
`with-output-to-temp-buffer'?  How about some reasons for such a
proposal?

My code and other 3rd-party libraries use `with-output-to-temp-buffer'
all over the place.

But I have no code that uses `with-temp-buffer-window'.  And googling
for it shows one hit to the Elisp manual and the rest are hits to
Emacs bugs!  I do not see zillions of users of
`with-temp-buffer-window', which was not introduced until Emacs 24.3.

bug#16038: 24.3; latest change to with-help-window makes temp-buffer-browse useless

[Leo Liu]

On 2014-01-24 01:48 +0800, Drew Adams wrote:
> Huh?  What's this about?  Why on Earth would we deprecate
> `with-output-to-temp-buffer'?  How about some reasons for such a
> proposal?
>
> My code and other 3rd-party libraries use `with-output-to-temp-buffer'
> all over the place.
>
> But I have no code that uses `with-temp-buffer-window'.  And googling
> for it shows one hit to the Elisp manual and the rest are hits to
> Emacs bugs!  I do not see zillions of users of
> `with-temp-buffer-window', which was not introduced until Emacs 24.3.

We are trying to consolidate the features of the two macros into one so
no feature is lost.

Leo

bug#16038: 24.3; latest change to with-help-window makes temp-buffer-browse useless

[Drew Adams]

> > Huh?  What's this about?  Why on Earth would we deprecate
> > `with-output-to-temp-buffer'?  How about some reasons for such a
> > proposal?
> >
> > My code and other 3rd-party libraries use `with-output-to-temp-buffer'
> > all over the place.
> >
> > But I have no code that uses `with-temp-buffer-window'.  And googling
> > for it shows one hit to the Elisp manual and the rest are hits to
> > Emacs bugs!  I do not see zillions of users of
> > `with-temp-buffer-window', which was not introduced until Emacs 24.3.
> 
> We are trying to consolidate the features of the two macros into one so
> no feature is lost.

Yes, clearly.  I got that.  But why would you even consider
`with-temp-buffer-window', rather than `with-output-to-temp-buffer', as
the end target of your consolidation?

Incorporate whatever you feel you need to into
`with-output-to-temp-buffer', as long as "no feature is lost" from it.
But please do not consider deprecating `with-output-to-temp-buffer'.
It was that possibility that was mentioned and that I replied to.

If you feel that you need to deprecate something here, deprecate the
new addition, `with-temp-buffer-window', which has hardly been used
anywhere.

bug#16038: 24.3; latest change to with-help-window makes temp-buffer-browse useless

[martin rudalics]

 > Yes, clearly.  I got that.  But why would you even consider
 > `with-temp-buffer-window', rather than `with-output-to-temp-buffer', as
 > the end target of your consolidation?
 >
 > Incorporate whatever you feel you need to into
 > `with-output-to-temp-buffer', as long as "no feature is lost" from it.
 > But please do not consider deprecating `with-output-to-temp-buffer'.
 > It was that possibility that was mentioned and that I replied to.
 >
 > If you feel that you need to deprecate something here, deprecate the
 > new addition, `with-temp-buffer-window', which has hardly been used
 > anywhere.

The same author wrote in http://debbugs.gnu.org/cgi/bugreport.cgi?bug=8368

   Sounds good to me.  My only proposal in that regard was to create an alias with
   a better name (e.g. `...-help-...'), and deprecate `with-output-to-temp-buffer'
   to encourage use of the new name.

martin, who couldn't resist

bug#16038: 24.3; latest change to with-help-window makes temp-buffer-browse useless

[Drew Adams]

> The same author wrote in http://debbugs.gnu.org/cgi/bugreport.cgi?bug=8368
> 
>    Sounds good to me.  My only proposal in that regard was to create an
>    alias with a better name (e.g. `...-help-...'), and deprecate
>    `with-output-to-temp-buffer' to encourage use of the new name.
> 
> martin, who couldn't resist

Yes, I said:

  Probably we will need to leave the original name for the current
  behavior, but if it could be aliased to something with "help" in
  the name, and then the original name deprecated, that would be better.
  (I think that's part of what you suggest.)  And create a new name
  for the temp-without-the-help-stuff case.

If you read the whole thread for bug #8368 then you will understand.
Is the current discussion about fixing bug #8368?  If you fix that
problem as requested, great.

I'm all in favor of what was requested in bug #8368.  The name of
`with-output-to-temp-buffer' is not good.  That macro has been abused
for a long time by stuffing help-related stuff into it.

That does not mean that we shouldn't have a macro that does what
`with-output-to-temp-buffer' does.  And as noted above, users should
be encouraged, over time, to use the new, "help"-related name.

If you have a complete fix for bug #8368, fine - please go for it.
That is not what I think I am seeing in the bug #16038 thread.

Fixing bug #8368 includes not only renaming `with-output-to-temp-buffer'
to something like `with-output-to-help-buffer' - AND fixing its doc
to reflect what it really does - it is about help, but ALSO doing
the same for any other `*-temp-*' things that really are `-*help*-'
things.

And, in particular, ALSO create real temporary-buffer facilities,
including a real `with-output-to-temp-buffer' (but renamed, to
avoid confusion), unencumbered by help-related stuff.

IOW, fix the names and doc of the misnamed `*-temp-*' things to
reflect the fact that they are about help.  AND create real
temporary-buffer things that are unrelated to help.

I stressed the bit about creating real temporary-buffer things:

  The point of the last part is that there is a need for creating
  and using temporary buffers.  That should never have been co-opted
  for help, but now that it is we should fix it properly: (a) call
  a spade a spade and (b) create new macros for really dealing with
  temporary buffers.

And a year later...

  Can we please move forward on fixing this bug?
  There is lots of stuff in a "temp" buffer now that has nothing to
  do with a temporary buffer.  All of the special help link and
  navigation commands should be reserved for a help mode that is
  _derived_ from a (minimal) temporary buffer mode.

And later...

  I was pretty clear that the names are not what is most important
  to me.  What matters most is to have a macro that does only the
  non-help stuff, separate from the macro that does also the help
  stuff.

And this, especially pertinent to the current discussion:

  Deprecation does not mean immediate desupport, and it might not
  ever imply desupport.  It means that what is deprecated _might_ be
  desupported at some time in the future.

  So users of the old name are not impacted.  It's just a heads-up
     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  to users.  They are forewarned that they might want to update the
  name sooner rather than later.  But they _need not_ do so until
  desupport happens, if it ever does.  The new, preferred name is
  what will be documented and increasingly used for new code etc.

Can you explain how bug #16038 relates to bug #8368?  Is the latter
being fixed by the fix by the fix for the former?

Yes, I would like to see bug #8368 fixed.  And I notice that some
of what was pointed out in the #8368 report seems to be rediscovered
now for bug #16038.  #8368 is still a bug, AFAIK.

bug#16038: 24.3; latest change to with-help-window makes temp-buffer-browse useless

[martin rudalics]

 > Yes, I said:
 >
 >   Probably we will need to leave the original name for the current
 >   behavior, but if it could be aliased to something with "help" in
 >   the name, and then the original name deprecated, that would be better.
 >   (I think that's part of what you suggest.)  And create a new name
 >   for the temp-without-the-help-stuff case.
 >
 > If you read the whole thread for bug #8368 then you will understand.
 > Is the current discussion about fixing bug #8368?  If you fix that
 > problem as requested, great.
 >
 > I'm all in favor of what was requested in bug #8368.  The name of
 > `with-output-to-temp-buffer' is not good.  That macro has been abused
 > for a long time by stuffing help-related stuff into it.
 >
 > That does not mean that we shouldn't have a macro that does what
 > `with-output-to-temp-buffer' does.  And as noted above, users should
 > be encouraged, over time, to use the new, "help"-related name.
 >
 > If you have a complete fix for bug #8368, fine - please go for it.
 > That is not what I think I am seeing in the bug #16038 thread.
 >
 > Fixing bug #8368 includes not only renaming `with-output-to-temp-buffer'
 > to something like `with-output-to-help-buffer' - AND fixing its doc
 > to reflect what it really does - it is about help, but ALSO doing
 > the same for any other `*-temp-*' things that really are `-*help*-'
 > things.
 >
 > And, in particular, ALSO create real temporary-buffer facilities,
 > including a real `with-output-to-temp-buffer' (but renamed, to
 > avoid confusion), unencumbered by help-related stuff.
 >
 > IOW, fix the names and doc of the misnamed `*-temp-*' things to
 > reflect the fact that they are about help.  AND create real
 > temporary-buffer things that are unrelated to help.
 >
 > I stressed the bit about creating real temporary-buffer things:
 >
 >   The point of the last part is that there is a need for creating
 >   and using temporary buffers.  That should never have been co-opted
 >   for help, but now that it is we should fix it properly: (a) call
 >   a spade a spade and (b) create new macros for really dealing with
 >   temporary buffers.
 >
 > And a year later...
 >
 >   Can we please move forward on fixing this bug?
 >   There is lots of stuff in a "temp" buffer now that has nothing to
 >   do with a temporary buffer.  All of the special help link and
 >   navigation commands should be reserved for a help mode that is
 >   _derived_ from a (minimal) temporary buffer mode.
 >
 > And later...
 >
 >   I was pretty clear that the names are not what is most important
 >   to me.  What matters most is to have a macro that does only the
 >   non-help stuff, separate from the macro that does also the help
 >   stuff.
 >
 > And this, especially pertinent to the current discussion:
 >
 >   Deprecation does not mean immediate desupport, and it might not
 >   ever imply desupport.  It means that what is deprecated _might_ be
 >   desupported at some time in the future.
 >
 >   So users of the old name are not impacted.  It's just a heads-up
 >      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 >   to users.  They are forewarned that they might want to update the
 >   name sooner rather than later.  But they _need not_ do so until
 >   desupport happens, if it ever does.  The new, preferred name is
 >   what will be documented and increasingly used for new code etc.
 >
 > Can you explain how bug #16038 relates to bug #8368?  Is the latter
 > being fixed by the fix by the fix for the former?
 >
 > Yes, I would like to see bug #8368 fixed.  And I notice that some
 > of what was pointed out in the #8368 report seems to be rediscovered
 > now for bug #16038.  #8368 is still a bug, AFAIK.

Maybe you should try to fix this problem:

 > But I have no code that uses `with-temp-buffer-window'.

martin

bug#16038: 24.3; latest change to with-help-window makes temp-buffer-browse useless

[Drew Adams]

> Maybe you should try to fix this problem:
> 
>  > But I have no code that uses `with-temp-buffer-window'.

What problem?  Just what are you suggesting, concretely?
What's the relation to fixing bug #8368?

bug#16038: 24.3; latest change to with-help-window makes temp-buffer-browse useless

[martin rudalics]

 > What problem?  Just what are you suggesting, concretely?
 > What's the relation to fixing bug #8368?

First re-read the thread of bug#8368.  Then read the doc-string of
`with-temp-buffer-window'.  Then re-read the thread of bug#8368.  Then
re-read the doc-string ...

martin

bug#16038: 24.3; latest change to with-help-window makes temp-buffer-browse useless

[Drew Adams]

> > Maybe you should try to fix this problem:
> >  > But I have no code that uses `with-temp-buffer-window'.
> >
> > What problem?  Just what are you suggesting, concretely?
> > What's the relation to fixing bug #8368?
> 
> First re-read the thread of bug#8368.  Then read the doc-string of
> `with-temp-buffer-window'.  Then re-read the thread of bug#8368.
> Then re-read the doc-string ...

I have.  But why do you say that -- is bug #8368 fixed?

If you have a concrete suggestion, please offer it.
And what is the "problem" that needs fixing with my not having
any code that uses `with-temp-buffer-window'?

If bug #8368 is now fixed, great: What code to replace with what
code, concretely?  Are the misnamed macros and hooks being renamed
as well?

I don't see that in the doc string of `with-temp-buffer-window'.
If a macro and the hooks it uses are all about *Help* then they
should not be named `with-output-to-temp-buffer',
`temp-buffer-setup-hook' etc.  They should have "help" in their
names instead of "temp".   ===> bug #8368.

Adding new hooks that have almost the same names but very different
meanings and uses is a bad idea.  `temp-buffer-window-setup-hook'
and `temp-buffer-setup-hook' sound like they would be similar, with
the difference being "window".  Alas no.

I don't have a problem with your new names.  The problem is with
the old names, and with not deprecating them, _especially_ after
adding false-friend new names.

The old macros and hooks should be renamed to use "help" - with
aliases provided for the old names, with deprecation of the old
names, and preferably with no plan to _ever_ desupport the old
names.  (Deprecation does not imply desupport.  It allows for
later desupport, but in some cases desupport is not possible or
advisable or necessary.)

FWIW, the NEWS is, I would think, one good place to put
deprecation notices.  If `with-output-to-temp-buffer' is
deprecated, we should learn in the NEWS that this is the case
AND what it is replaced by. IOW, tell users how to update their
code.  Likewise for the misnamed hooks etc.

Instead, at least so far, NEWS has only this: 

  *** New macro `with-temp-buffer-window', similar to
  `with-output-to-temp-buffer'.

That "similar to" might do more harm than help.

bug#16038: 24.3; latest change to with-help-window makes temp-buffer-browse useless

[martin rudalics]

 >> First re-read the thread of bug#8368.  Then read the doc-string of
 >> `with-temp-buffer-window'.  Then re-read the thread of bug#8368.
 >> Then re-read the doc-string ...
 >
 > I have.  But why do you say that

To help you understand what you are saying.

 > -- is bug #8368 fixed?

I don't know and I don't care.  I almost forgot about it until you
decided to participate in the present thread.

 > If you have a concrete suggestion, please offer it.
 > And what is the "problem" that needs fixing with my not having
 > any code that uses `with-temp-buffer-window'?

The one you apparently have with `with-output-to-temp-buffer'.

 > If bug #8368 is now fixed, great: What code to replace with what
 > code, concretely?

Your code that uses `with-output-to-temp-buffer'.

 > Are the misnamed macros and hooks being renamed
 > as well?
 >
 > I don't see that in the doc string of `with-temp-buffer-window'.
 > If a macro and the hooks it uses are all about *Help* then they
 > should not be named `with-output-to-temp-buffer',
 > `temp-buffer-setup-hook' etc.  They should have "help" in their
 > names instead of "temp".   ===> bug #8368.
 >
 > Adding new hooks that have almost the same names but very different
 > meanings and uses is a bad idea.  `temp-buffer-window-setup-hook'
 > and `temp-buffer-setup-hook' sound like they would be similar, with
 > the difference being "window".  Alas no.
 >
 > I don't have a problem with your new names.  The problem is with
 > the old names, and with not deprecating them, _especially_ after
 > adding false-friend new names.
 >
 > The old macros and hooks should be renamed to use "help" - with
 > aliases provided for the old names, with deprecation of the old
 > names, and preferably with no plan to _ever_ desupport the old
 > names.  (Deprecation does not imply desupport.  It allows for
 > later desupport, but in some cases desupport is not possible or
 > advisable or necessary.)

Maybe Leo would have started to do that if you had not interfered.  I
suggest you apologize and consult with him on how to proceed on this
matter.

 > FWIW, the NEWS is, I would think, one good place to put
 > deprecation notices.  If `with-output-to-temp-buffer' is
 > deprecated, we should learn in the NEWS that this is the case
 > AND what it is replaced by. IOW, tell users how to update their
 > code.  Likewise for the misnamed hooks etc.
 >
 > Instead, at least so far, NEWS has only this:
 >
 >   *** New macro `with-temp-buffer-window', similar to
 >   `with-output-to-temp-buffer'.
 >
 > That "similar to" might do more harm than help.

That's life.

martin

bug#16038: 24.3; latest change to with-help-window makes temp-buffer-browse useless

[Drew Adams]

>  > -- is bug #8368 fixed?
> 
> I don't know and I don't care.

That's too bad.  Especially for someone who participated actively
in that thread and proposed (it seemed) a solution for it, to
which Stefan seemed to give the go-ahead.  Sorry you feel that way.

> I almost forgot about it until you decided to participate in the
> present thread.

I'm glad that my participation reminded you of #8368, and you then
brought it into this discussion.  You were right to do so.  It is
relevant - not just the bug but the discussion thread.

>  > If you have a concrete suggestion, please offer it.
>  > And what is the "problem" that needs fixing with my not having
>  > any code that uses `with-temp-buffer-window'?
> 
> The one you apparently have with `with-output-to-temp-buffer'.

And just what problem is that?  You say there is a problem to
fix in my code.  What is the problem?  (And what is the fix you
have in mind?)

>  > If bug #8368 is now fixed, great: What code to replace with what
>  > code, concretely?
> 
> Your code that uses `with-output-to-temp-buffer'.

Why should that be replaced?  And if it should, just what should
it to be replaced with?  That is part of deprecating something:
tell users what they should change to what in existing code. E.g.,

(old-foo this that) ==>
  (new-bar something-else that 42 (1- this))

or whatever.

>  > Are the misnamed macros and hooks being renamed as well?
>  >
>  > I don't see that in the doc string of `with-temp-buffer-window'.
>  > If a macro and the hooks it uses are all about *Help* then they
>  > should not be named `with-output-to-temp-buffer',
>  > `temp-buffer-setup-hook' etc.  They should have "help" in their
>  > names instead of "temp".   ===> bug #8368.
>  >
>  > Adding new hooks that have almost the same names but very different
>  > meanings and uses is a bad idea.  `temp-buffer-window-setup-hook'
>  > and `temp-buffer-setup-hook' sound like they would be similar, with
>  > the difference being "window".  Alas no.
>  >
>  > I don't have a problem with your new names.  The problem is with
>  > the old names, and with not deprecating them, _especially_ after
>  > adding false-friend new names.
>  >
>  > The old macros and hooks should be renamed to use "help" - with
>  > aliases provided for the old names, with deprecation of the old
>  > names, and preferably with no plan to _ever_ desupport the old
>  > names.  (Deprecation does not imply desupport.  It allows for
>  > later desupport, but in some cases desupport is not possible or
>  > advisable or necessary.)
> 
> Maybe Leo would have started to do that if you had not interfered.
> I suggest you apologize and consult with him on how to proceed on
> this matter.

Suggest all you want, if it makes you feel better.  But I do not
feel that I interfered in any way.  Nor do I think I have anything
to apologize for.  But you are welcome to apologize to me for
suggesting that I have done something wrong and have something to
apologize for. ;-)

There might be some incomplete or incoherent changes that still
need fixing or finishing.  Dunno.  But if so, none of those are
my doing.  And in spite of that state, no, I would not think of
asking you or anyone else for an apology for that.  People do
their best, whether or not what they do is TRT or sufficient.

On the contrary - to the extent that things will be improved,
bravo and thank you, to you, Leo, or whomever.  To the extent
that that is not so, or only partly so, I hope that the job
can be finished as mentioned in bug #8368.
 
>  > FWIW, the NEWS is, I would think, one good place to put
>  > deprecation notices.  If `with-output-to-temp-buffer' is
>  > deprecated, we should learn in the NEWS that this is the case
>  > AND what it is replaced by. IOW, tell users how to update their
>  > code.  Likewise for the misnamed hooks etc.
>  >
>  > Instead, at least so far, NEWS has only this:
>  >
>  >   *** New macro `with-temp-buffer-window', similar to
>  >   `with-output-to-temp-buffer'.
>  >
>  > That "similar to" might do more harm than help.
> 
> That's life.

It is neither fate nor accident, but the result of someone's
doing.  See above, about people doing their best whether or
not it is sufficient.  Yes, that is part of life.

bug#16038: 24.3; latest change to with-help-window makes temp-buffer-browse useless

[martin rudalics]

 > And just what problem is that?  You say there is a problem to
 > fix in my code.  What is the problem?

The one from http://debbugs.gnu.org/cgi/bugreport.cgi?bug=8368#32.

 > (And what is the fix you
 > have in mind?)
 >
 >>  > If bug #8368 is now fixed, great: What code to replace with what
 >>  > code, concretely?
 >>
 >> Your code that uses `with-output-to-temp-buffer'.
 >
 > Why should that be replaced?  And if it should, just what should
 > it to be replaced with?

With `with-temp-buffer-window'.

 > That is part of deprecating something:
 > tell users what they should change to what in existing code. E.g.,
 >
 > (old-foo this that) ==>
 >   (new-bar something-else that 42 (1- this))
 >
 > or whatever.

I don't propose to deprecate something.  I offer a solution to a
problem.

 > Suggest all you want, if it makes you feel better.

Then better don't ask for suggestions.

martin

bug#16038: 24.3; latest change to with-help-window makes temp-buffer-browse useless

[Drew Adams]

>  > And just what problem is that?  You say there is a problem to
>  > fix in my code.  What is the problem?
> 
> The one from http://debbugs.gnu.org/cgi/bugreport.cgi?bug=8368#32.

That demo example was not from my code, as you know.  It
demonstrates bug #8368, showing why it needs to be fixed.
And it is still pertinent, AFAIK.

>  > (And what is the fix you have in mind?)

And the fix is?

>  >>  > If bug #8368 is now fixed, great: What code to replace
>  >>  > with what code, concretely?
>  >>
>  >> Your code that uses `with-output-to-temp-buffer'.
>  >
>  > Why should that be replaced?  And if it should, just what
>  > should it to be replaced with?
> 
> With `with-temp-buffer-window'.

How so?  Is it a one-one replacement?  What about the hooks?

If `with-temp-buffer-window' is supposed to be the replacement for
`with-output-to-temp-buffer' then that needs to be stated clearly
in the NEWS.

Including a spec of what the replacement should be for different
`with-output-to-temp-buffer' input patterns (formal parameters).
And including hook use (correspondences).  With any significant
differences and limitations pointed out.

That is how to help users transition from the old to the new.
I imagine that you are well aware of that, but it's perhaps
better not to guess.

Consider by contrast this NEWS entry, which helps users
understand how to use `cl-flet' by pointing out how it differs
from (Emacs Lisp) `flet':

  *** `cl-flet' is not like `flet' (which is deprecated).
  Instead it obeys the behavior of Common-Lisp's `flet'.
  In particular, in cl-flet function definitions are lexically
  scoped, whereas in flet the scoping is dynamic.

>  > That is part of deprecating something:
>  > tell users what they should change to what in existing
>  > code.  E.g.,
>  > (old-foo this that) ==>
>  >   (new-bar something-else that 42 (1- this))
>  > or whatever.
> 
> I don't propose to deprecate something.

It seems to me that that is part of what bug #16038, and this
discussion, are about.  It is also part of what bug #8368 is
about.

You ask us to reread #8368, to guess how your new macro responds
to that bug.  That bug speaks specifically about deprecating
`with-output-to-temp-buffer'.

And in that context the deprecation would involve a simple
renaming (one-one).

> I offer a solution to a problem.

What is the solution, beyond chanting the mantra
`with-temp-buffer-window'?  What `with-output-to-temp-buffer'
patterns map to what `with-temp-buffer-window' patterns?
What about the various hooks?

>  >> Maybe Leo would have started to do that if you had not
>  >> interfered.  I suggest you apologize and consult with him
>  >> on how to proceed on this matter.
>
>  > Suggest all you want, if it makes you feel better.  But I
>  > do not feel that I interfered in any way.  Nor do I think
>  > I have anything to apologize for.
> 
> Then better don't ask for suggestions.

No one asked for ad hominem, off-the-wall "suggestions".

Of course, you elided your actual suggestion (restored here),
as well as what I said about it (restored here), giving the
impression that it might have actually been a helpful, technical
suggestion that I objected to when I said, "Suggest all you want".

bug#16038: 24.3; latest change to with-help-window makes temp-buffer-browse useless

[martin rudalics]

 >>  > And just what problem is that?  You say there is a problem to
 >>  > fix in my code.  What is the problem?
 >>
 >> The one from http://debbugs.gnu.org/cgi/bugreport.cgi?bug=8368#32.
 >
 > That demo example was not from my code, as you know.  It
 > demonstrates bug #8368, showing why it needs to be fixed.
 > And it is still pertinent, AFAIK.

So this example bears no resemblance to code you ever wrote or run?
It's just a hoax to attract the attention of developers to how people
could shoot themselves in the foot?  Now I understand why no-one else
cared.  This taught me a lesson ...

martin

bug#16038: 24.3; latest change to with-help-window makes temp-buffer-browse useless

[Drew Adams]

>  >>> And just what problem is that?  You say there is a problem to
>  >>> fix in my code.  What is the problem?
>  >>
>  >> The one from
>  >> http://debbugs.gnu.org/cgi/bugreport.cgi?bug=8368#32.
>  >
>  > That demo example was not from my code, as you know.  It
>  > demonstrates bug #8368, showing why it needs to be fixed.
>  > And it is still pertinent, AFAIK.
> 
> So this example bears no resemblance to code you ever wrote or run?
> It's just a hoax to attract the attention of developers to how
> people could shoot themselves in the foot?  Now I understand why
> no-one else cared.  This taught me a lesson ...

What are you on about, Martin?  That example underlines, in a
simple way, the mismatch between `with-output-to-temp-buffer', which
is only for help buffers, and "with output to a temporary buffer",
which its name suggests.  That's all.  It is entirely germain to
the bug.

It is a trivial, minimal example pointing out some of the problems
described in the bug report:

  (defun foo () "..."
    (with-output-to-temp-buffer "*TEMP*" (princ "FOOO\n---\n\n")))
  (foo) C-x b *TEMP* TAB
  Debugger entered--Lisp error: (error "No buttons!")

And no, I do not use `with-output-to-temp-buffer' that way in my
code.  I know enough not to expect that it does what it says, and
to use it only for a help buffer.

That does not change the fact that the name is misleading and
that Emacs could benefit from a real "with output to a temporary
buffer", in addition to this misnamed macro, which is really
"with output to a help buffer".

It's not a hoax.  It's a bug report.  Whether no one besides me
cares is their choice.  But I suspect that someone does care,
since you have gone to some trouble to write a new macro and
there is now some talk (even if you say it is not from you) in
favor of deprecating the name `with-output-to-temp-buffer'.

Wrt such a possible deprecation: let's do it right.  That's all.

bug#16038: 24.3; latest change to with-help-window makes temp-buffer-browse useless

[Glenn Morris]

Leo Liu wrote:

> I am not sure the repo goes back further than 2001.

bzr log -c 1

  -> timestamp: Thu 1985-04-18 00:48:29 +0000


Anyway, vc-annotate is your friend:

(add-hook 'temp-buffer-setup-hook 'help-mode-setup)
appeared in r24049, 1999-01-11.

(add-hook 'temp-buffer-show-hook 'help-mode-finish)
appeared in r20061, 1997-10-15 (as help-mode-maybe).

bug#16038: 24.3; latest change to with-help-window makes temp-buffer-browse useless

[Glenn Morris]

Leo Liu wrote:

> Could we remove the following two add-hooks?
>
>
> --8<---------------cut here---------------start------------->8---
> (add-hook 'temp-buffer-setup-hook 'help-mode-setup)
> (add-hook 'temp-buffer-show-hook 'help-mode-finish)
> --8<---------------cut here---------------end--------------->8---


If you want to do this (I know you already did...), you need to add an
incompatible change entry to NEWS about this, and you need to audit
every single use of with-output-to-temp-buffer to find the ones that
expected their output buffers to be in help mode. Which I guess would
be, umm, all of them?

The first one I tried:

emacs -Q -f report-emacs-bug

*Bug Help* buffer is in Help mode in 24.3.92, and fundamental in trunk.

Does it actually matter in that case? Maybe not, but the buffer was
clearly intended te be in help mode.

And here's a case where it definitely does matter
http://debbugs.gnu.org/cgi/bugreport.cgi?bug=17966


(This report has become rather long; I hope it doesn't get too much longer.)

bug#16038: 24.3; latest change to with-help-window makes temp-buffer-browse useless

[Glenn Morris]

Glenn Morris wrote:

> Leo Liu wrote:
>
>> Could we remove the following two add-hooks?
>>
>>
>> --8<---------------cut here---------------start------------->8---
>> (add-hook 'temp-buffer-setup-hook 'help-mode-setup)
>> (add-hook 'temp-buffer-show-hook 'help-mode-finish)
>> --8<---------------cut here---------------end--------------->8---
>
> If you want to do this (I know you already did...), you need to add an
> incompatible change entry to NEWS about this, and you need to audit
> every single use of with-output-to-temp-buffer to find the ones that
> expected their output buffers to be in help mode.

And of course you need to update the documentation too.

(Are you sure this is worth it?)

bug#16038: 24.3; latest change to with-help-window makes temp-buffer-browse useless

[Glenn Morris]

PS personally I'd advise you to just revert this change.
Read the description of with-output-to-temp-buffer in the elisp manual.
As we showed with vc-annotate, it behaved like that "for ever".
The help-mode thing is an integral part of what it does.

AFAICS, you didn't really say why you want to change this.
If you don't like the hooks being non-empty by default,
you could perhaps move that code to the body.

If you don't like the association of "temp buffer" and help, think of it
as with-output-to-temp-help-buffer, if that makes you happier.

bug#16038: 24.3; latest change to with-help-window makes temp-buffer-browse useless

[Drew Adams]

> PS personally I'd advise you to just revert this change.
> Read the description of with-output-to-temp-buffer in the elisp manual.
> As we showed with vc-annotate, it behaved like that "for ever".
> The help-mode thing is an integral part of what it does.
> 
> AFAICS, you didn't really say why you want to change this.
> If you don't like the hooks being non-empty by default,
> you could perhaps move that code to the body.
> 
> If you don't like the association of "temp buffer" and help, think of it
> as with-output-to-temp-help-buffer, if that makes you happier.

Which is what I argued in the original thread(s): the name is
misleading - nothing more.  The macro is (was, before this change)
about a help buffer, not about an arbitrary temporary buffer.

The right way to make the desired change is to introduce a new,
non-help-mode-related macro and use that where desired, not to
gratuitously change the behavior of the longstanding macro
`with-output-to-temp-buffer'.  (And preferably rename the latter
using defalias, so that the new name indicates that it is about
help mode - e.g., `with-output-to-temp-help-buffer'.)

As just one user, this unfortunate change caused me to make
version-adjusting code to handle it, in multiple libraries of mine.
Not a big deal, but it should not have been necessary at all.

However, Glenn, it seems this was already decided, with Eli, Stefan,
and Martin unpersuaded by my (and apparently your) argument.

Ref: bugs 8368, 17109, 17397, 17146 (and 16038)

bug#16038: 24.3; latest change to with-help-window makes temp-buffer-browse useless

[Leo Liu]

On 2014-07-07 21:54 -0400, Glenn Morris wrote:
> If you want to do this (I know you already did...), you need to add an
> incompatible change entry to NEWS about this, and you need to audit
> every single use of with-output-to-temp-buffer to find the ones that
> expected their output buffers to be in help mode.

We made that change to prove the above two lines cause no harm other
than not enabling help-mode. At some stage and probably pretty soon, we
might merge the two macros with-output-to-temp-buffer and
with-temp-buffer-window under one name (the former looks like a simple
case of the latter). So the change is intermediate.

Leo

bug#16038: 24.3; latest change to with-help-window makes temp-buffer-browse useless

[Glenn Morris]

Leo Liu wrote:

> On 2014-07-07 21:54 -0400, Glenn Morris wrote:
>
>> If you want to do this (I know you already did...), you need to add an
>> incompatible change entry to NEWS about this, and you need to audit
>> every single use of with-output-to-temp-buffer to find the ones that
>> expected their output buffers to be in help mode.
>
> We made that change to prove the above two lines cause no harm other
> than not enabling help-mode. At some stage and probably pretty soon, we
> might merge the two macros with-output-to-temp-buffer and
> with-temp-buffer-window under one name (the former looks like a simple
> case of the latter). So the change is intermediate.

Sorry, this makes no sense to me.

with-output-to-temp-buffer is a documented macro with a specific purpose.
I shall now do the tedious thing of quoting the manual:

   This function executes the forms in BODY while arranging to insert
   any output they print into the buffer named BUFFER-NAME, which is
   first created if necessary, and put into Help mode.
   [...]
   If the forms in 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 `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.

Now it does not do any of that.

The normal way to do this kind of thing is to introduce a new macro that
does whatever new thing you want, and deprecate the old one. Not to just
half-arsedly change the old one to do something else, without updating
any of the documentation or callers.