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

[martin rudalics <rudalics@gmx.at>]

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

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

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

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

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

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

 > That is a very roundabout way of saying that IF there previously were
 > a user who for some reason coded things up to approximate what the
 > code does now, THEN ... "Nothing has changed"!
 >
 > So-called temp-buffer display was previously coupled with help display.
 > Functions on `temp-buffer-show-hook' in existing code or user setups
 > could well depend on that behavior.  It was expected that the temp
 > buffer displayed would be in help mode - because it WAS - for 30 years.
 >
 > Sure, someone could have jumped through hoops to use
 > `with-output-to-temp-buffer' without help mode.  But that would have
 > been relatively rare.  What percentage of the uses of
 > `with-output-to-temp-buffer' in the Emacs code corresponded to this?
 > Not more than 1% would be my guess - maybe 0%.
 >
 > It is hardly the common use case of `with-output-to-temp-buffer'.
 >
 > To suggest that it is, that "nothing has changed", would be
 > disingenuous.  Yes, I note that you did not claim that in general -
 > you qualified it as being the case only for such exceptional uses
 > (without acknowledging that they are exceptional).  But the
 > impression can be got from a cursory reading that you are saying
 > that nothing has changed in general, i.e., for most uses of
 > `with-output-to-temp-buffer'.
 >
 > In fact, I have jumped through that hoop that in some of my code,
 > so I do recognize such an exception:
 >
 > (defmacro bmkp-with-output-to-plain-temp-buffer (buf &rest body)
 >    "Like `with-output-to-temp-buffer', but with no *Help* navigation stuff."
 >    `(unwind-protect
 >      (progn
 >        (remove-hook 'temp-buffer-setup-hook 'help-mode-setup)
 >        (remove-hook 'temp-buffer-show-hook  'help-mode-finish)
 >        (with-output-to-temp-buffer ,buf ,@body))
 >      (add-hook 'temp-buffer-setup-hook 'help-mode-setup)
 >      (add-hook 'temp-buffer-show-hook  'help-mode-finish)))
 >
 > But doing things like this was no doubt uncommon.  That was the point
 > of my original bug report asking that Emacs decouple temporary buffer
 > display from help display, i.e., that it provide a real temp-buffer
 > display that does not involve help (as does the macro above, in a
 > workaround way).

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

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

 >>   >    This construct is similar to `with-output-to-temp-buffer'
 >>   >    but, neither runs `temp-buffer-setup-hook' which usually puts
 >>   >    the buffer in Help mode, nor `temp-buffer-show-function' (the
 >>   >    ACTION argument replaces this).
 >>
 >> What is wrong here?
 >
 > `temp-buffer-setup-hook' no longer "usually puts the buffer in Help
 > mode".

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

 >>   > And the doc string of `temp-buffer-setup-hook', likewise, says:
 >>   >
 >>   >    This hook is normally set up with a function to put the buffer
 >>   >    in Help mode.
 >>
 >> This is still the case for the release version.  IIRC Leo Liu changed it
 >> on the trunk so the doc-string should be probably updated there.
 >
 > The doc string is not updated in the trunk build I cited, from April 29.
 > I don't have a more recent build.  But yes, the doc should be updated -
 > that was what I was pointing out.

Agreed.

 >> The connection between temporary buffers and help mode is established
 >> by `with-help-window' which uses `with-temp-buffer-window'.
 >
 > Yes, I know.
 >
 > And previously such a connection was hardwired in
 > `with-output-to-temp-buffer'.  That behavior should not have changed.
 > Not because it was good to couple the two behaviors, but because they
 > have been so coupled for a long time in `with-output-to-temp-buffers'.
 >
 > 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.

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

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

 > But for
 > 3rd-party code that supports multiple Emacs versions the change is not
 > so trivial.
 >
 > It is too bad that we have arrived here, but we have.  Now let's patch
 > things up by at least letting users know about the damage done and how
 > to make do with it.

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

martin