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

[martin rudalics]

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