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

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

>  >> 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? ;-)
> 
> No.  I'm too surprised that it didn't cause any misbehavior so far.

Bug reports of regressions don't count?

>  > 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.
> 
> Since after Leo has taken it out, I haven't seen any complaints yet.  So
> even if it is a fact of life it apparently didn't have any real impact.
> Now if only all facts of life were like this ...

This and related bug reports are complaints.  And they describe real impact.

>  > 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.
> 
> Obviously not.  But if a function wants to act only upon buffers in help
> mode, that function should check whether the buffer is in help mode.

Not if the macro used is `with-output-to-temp-buffer', since it has always
taken care of establishing help mode.  Until now.

>  > The behavior has been to ALWAYS put the buffer in help mode.
> 
> If the intention was to ALWAYS put the buffer in help mode, there would
> not have been any reason to do it with a hook.  Rather, the `help-mode'
> call would have been hardcoded in `with-output-to-temp-buffer'.

Do you really want to argue about what the original intentions were?
`with-output-to-temp-buffer' was co-opted to serve only help, fairly
early in its history.  The name itself betrays a mismatch between its
(longstanding) behavior and what its original intention might have been
(as reflected by its name).

You seem to be stretching, to find any justification whatsoever for this
incompatible change to the behavior of `with-output-to-temp-buffer'.  If
you hide your eyes, of course you won't see - nothing I can do about that.

>  >>   > 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.
> 
> I see only one manual reference for `temp-buffer-setup-hook' which says
> that "This hook is normally set up with a function to put the buffer in
> Help mode.".  The term "normally" clearly implies that an application in
> order to be safe must handle behavior that is not normal.

You are ignoring reality.  Code and users have had a reasonable expectation
for 30 years about the behavior of `with-output-to-temp-buffer', and that
has now been thrown out the window gratuitously.

Gratuitously, because nothing was gained by it.  Emacs could just as well
have moved on to use new and different macros, without changing the
`w-o-t-t-b' behavior.  That was totally uncalled for and serves no purpose.
Not necessary.

>  >>   > 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.
> 
> Our opinions differ.

Yes.  Some info from a developer that is only buried in some bug thread
might be helpful to the few who read that thread.  But not more useful
than that.

Emacs users deserve better communication.  Especially about incompatible
changes.  Especially about behavior that has remained stable for 30 years.
Not communicating such info properly is irresponsible, IMHO.

> If you mean that we should document the removal of `help-mode' from
> `temp-buffer-setup-hook' then I obviously agree.

Good.  And consequently from `with-output-to-temp-buffer-buffer',
which is what users will see in their code.

Start with that.  Plus an explanation of how to migrate code that
expects `with-output-to-temp-buffer-buffer' to establish help mode.
(Mention `with-help-window', `with-temp-buffer-window', etc.)

Better would of course be to not screw `with-output-to-temp-buffer' at
all.  Emacs gains nothing by messing with that, and would lose nothing
by restoring its behavior.  I've seen no argument showing a loss by
doing that.  Do you have such an argument?

Changing `w-o-t-t-b' is not at all necessary to accomplish the clean
separation of temp buffer setup from help buffer setup that was the
goal (and which I was the one to propose, FWIW).