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

From: martin rudalics <[email-masked]>
Date: Thu, 15 May 2014 09:50:31 +0200

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

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

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

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

 > To get a different behavior you needed to jump through a
 > hoop (removing stuff from `temp-buffer-setup-hook').

IIRC clients do that by simply changing the mode in the BODY of
`with-output-to-temp-buffer'.

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

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

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

Then I don't understand why you've been asking for help before.

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

It should never have been written that way.  So "now" is a good occasion
to fix this.

 > 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 let's delay this discussion until "someone" shows up.

 > You mean there's hope?

That the `with-output-to-temp-buffer' change will be reverted?  If
someone finds a real problem in it, yes.

 >> I might agree with you here.
 >
 > You mean there's hope? ;-)

See above.

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

If you mean that we should document the removal of `help-mode' from
`temp-buffer-setup-hook' then I obviously agree.  I have no idea what
else you mean to do.

martin