bug#17397: 24.4.50; REGRESSION: `temp-buffer-show-hook' is no longer invoked for `describe-variable'

[Drew Adams <drew.adams@oracle.com>]

>  >> Both `with-output-to-temp-buffer' and `with-temp-buffer-window' are
>  >> and can be used for other things than displaying *Help*.
>  >
>  > For `with-output-to-temp-buffer':  NOW, yes.  Before, no - it was
>  > pretty much hardwired to help mode.
>  >
>  > So there will be users and existing 3rd-party code that depend on
>  > that behavior, which endured for 30 years or so.
>  >
>  > This is why I have argued that the right fix for that problem was
>  > not to change the behavior of `with-output-to-temp-buffer', and thus
>  > gratuitously break such code and user expectations, but to make a
>  > new macro for dealing with temporary buffer display that was not
>  > hardwired to help.
>  >
>  > Emacs itself could move to using that new macro, of course, but there
>  > should be no reason to break the longstanding behavior of
>  > `with-output-to-temp-buffer'.
> 
> It wasn't my intention to change the longstanding behavior of
> `with-output-to-temp-buffer'.

Well, it's done.  Is it your intention to revert that change? ;-)

>  > What did I say?  Yes, I read that in the manual.  What about a function
>  > that has been on `temp-buffer-setup-hook' or `temp-buffer-show-hook',
>  > and that was specifically put there for help, i.e., that expects help
>  > mode?
> 
> Generally assuming that a temporary buffer is always in help mode is
> wrong.  Callers of `with-output-to-temp-buffer' can always change the
> mode as, for example, ediff does.

As we have discussed at length elsewhere, `with-output-to-temp-buffer' was
NOT just about temporary buffers.  In spite of its name, it was about a
temporary buffer in help mode.  That's a fact of life.  I lamented the
name-vs-behavior mismatch, and filed a bug about that, but that's the way
it became over time, and it's been that way for a very long time now.

>  > Is it necessarily appropriate to put that function on the *-window-*
>  > hooks, without modifying it to work around use in a non-help mode?
>  > I don't think that is the case, in general.  And I don't see a hook
>  > that is analogous and specifically for help.
>  >
>  > In my case of `fit-frame-if-one-window', this is not a problem AFAICT
>  > - I added it to `temp-buffer-window-show-hook'.  But in the general
>  > case there is a problem in moving a function from a temp-buffer hook to
>  > a temp-buffer-window hook, whenever that function is specifically aimed
>  > at help (expects help mode).
>  >
>  > Sure, users and libraries can also change such a function, so that it
>  > tests the buffer or mode to see whether it involves help.  But this is
>  > gratuitous hassling, IMO - it should not be necessary.
>  >
>  > I made the further point that none of this is documented, AFAICT.
>  > Nothing about migrating one's use of temp-buffer stuff to whatever
>  > is appropriate for Emacs 24.4+.  Nothing about incompatible
>  > behavior changes for the temp-buffer stuff.
> 
> It was wrong to put a function on `temp-buffer-show-hook' without
> testing whether the associated buffer was in help mode when the
> intention is to run the function for help mode buffers only.

I disagree.  `with-output-to-temp-buffer' simply has never (almost never;
I cannot find an old enough version where it was ever the case) been about
temp buffers other than help-mode buffers.

You cannot just reinterpret things based on what the name suggests it
should do.  It has not done what its name says for 30 years now.

On the contrary, in the very rare cases where someone actually tried to
use `w-o-t-t-b' for something other than help mode, s?he had to jump
through a hoop to get that behavior.

It is not up to all functions that have been on that hook to test whether
the buffer is in help mode.  The behavior has been to ALWAYS put the buffer
in help mode. To get a different behavior you needed to jump through a
hoop (removing stuff from `temp-buffer-setup-hook').

>  >>   > Should I be adding `fit-frame-if-one-window' to `temp-buffer-window'
>  >>   > for Emacs 24.4, to get the effect it has in Emacs 24.3 (and prior)
>  >>   > by being on `temp-buffer-show-hook'?
>  >>
>  >> I suppose you want to add it to `temp-buffer-window-show-hook'.
>  >
>  > I supposed so too, and I did.  I asked the question several times,
>  > hoping to incite adding some migration explanation to the doc.  But
>  > thanks anyway for confirming.  I still hope someone updates the doc.
>  >
>  > But again, though that is OK for `fit-frame-if-one-window', since I
>  > want to invoke that regardless of which temp buffer is displayed, it
>  > is not OK in general for functions that have been on
>  > `temp-buffer-show-hook'.
>  >
>  > It is likely that at least some such functions are specific to help
>  > mode, since `temp-buffer-show-hook' was dedicated to help previously
>  > (and for so long).
> 
> Such functions were based on a wrong assumption.

No, they were not.  They were based on the longstanding and documented
behavior of `with-output-to-temp-buffer'.  See above.  The macro was
simply misnamed for what it did.  And there unfortunately was no macro
that did what its name suggests.  That was the original bug I reported.

>  > What do you tell library maintainers or users who have a function on
>  > `temp-buffer-show-hook' that is appropriate for help mode but not
>  > for other temp buffers?  Such information should be in the doc, IMO.
> 
> I tell them here on this list that such a function should have tested
> whether the buffer is in help mode.

Not helpful, IMO.

>  >> Emacs has a `temp-buffer-resize-mode' which is tied to temporary buffers
>  >> and not to `help-mode'.  To "deal with other possible uses" of temporary
>  >> buffers, a function run by `temp-buffer-show-hook' or
>  >> `temp-buffer-window-show-hook' should probably check whether the buffer
>  >> is in help mode.
>  >
>  > It will have to, now.  Too bad.
> 
> On the contrary.  Older versions of Emacs running your code will benefit
> from more correct code.

"It", not "I".  I don't have any such code.

Anyway, that is not "on the contrary".  You confirm that "It will have to,
now."  What is too bad is that the function code needs to be changed at all.

There was no need to change the misnamed `with-output-to-temp-buffer'
behavior.  You even claimed above that that was not your intention.  If the
behavior had not been changed then there would be no "too bad" here - no need
to change a function someone has on the hook.

> So you fit a frame shown by `bmkp-with-output-to-plain-temp-buffer' even
> if the buffer is not in help mode?

Yes.  I already made it clear that my use of `fit-frame-if-one-window'
on `temp-buffer-show-hook' is not a problem for non-help modes.  And I
said clearly that I have added it to `temp-buffer-window-show-hook'.

That will not be true in general for functions that users and libraries
have on `with-output-to-temp-buffer'.  That's the point here.

>  > What was wrong was the way this decoupling was done in Emacs:
>  > changing the behavior of macro `with-output-to-temp-buffer'.  That
>  > was misguided, IMHO, and not necessary.  That boat has apparently
>  > sailed, however.
> 
> Maybe.

You mean there's hope?

> I see.  This is due to Leo's change.

>  > The right approach would have been to (a) leave
>  > `with-output-to-temp-buffer' the way it was, (b) decouple temp-buffer
>  > display from help mode by coming up with new macros, and (c) use the
>  > new macros in the Emacs source code (this has been done).
>  >
>  > That way, the Emacs code would no longer use `with-output-to-temp-
>  > buffer', and thus would no longer depend on a coupling of temp-buffer
>  > display with help, BUT users would not be bothered and existing 3rd-party
>  > code would not be broken by a change to `with-output-to-temp-buffer': it
>  > would continue to work as usual, coupling temp with help as before.
>  > Eventually, `with-output-to-temp-buffer' would be abandoned everywhere,
>  > naturally.
> 
> I might agree with you here.

You mean there's hope? ;-)

>  > I pointed this out in my original bug report.  That is not what was
>  > done.  We now have to live with the consequences of the incompatible
>  > change.  That calls for doc that explains the change and how to deal
>  > with it.
>  >
>  > The doc (manual and/or NEWS) should clearly point out (a) what
>  > `with-output-to-temp-buffer' does now,
> 
> Here ...

If you mean that it suffices to let users know about such things in a
bug thread then I disagree.  In particular, NEWS should mention incompatible
changes and tell users how to migrate code to accommodate those changes.

>  > and (b) that it does not do what
>  > it has always done before, and (c) this is how to migrate existing code
>  > that uses it: A, B, C,...Z.
>  >
>  > For Emacs's source code the change was trivial: replace uses of
>  > `with-output-to-temp-buffer' with uses of the new macro.
> 
> ... and here ...

Dunno what you are saying here; sorry.  "Here ... and here ..." what?

> ... you're lumping together a change in `with-help-window' with a change
> affecting `with-output-to-temp-buffer'.  I can only address the former.

Why do you say that?  I have no problem with the creation of
`with-help-window' and its use in Emacs code, including instead of
`with-output-to-temp-buffer'.  It is the incompatible
change to `with-output-to-temp-buffer' that is the problem.  That, and a
lack of doc mentioning such things to users.