RE: with-output-to-temp-buffer and help-mode

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

> > So I think this should just be reverted.
> 
> See Martin's comment in
> http://debbugs.gnu.org/cgi/bugreport.cgi?bug=16038#14, there seems to be
> problems either way.

No, the solution should have been simple.
http://debbugs.gnu.org/cgi/bugreport.cgi?bug=16038#71

Better yet, read the whole thread, and the thread of the original
bug report (from me) that Martin referred to.

> Note also temp-buffer-setup-hook is part of the public hooks of
> with-output-to-temp-buffer so the macro makes no guarantee it will be in
> Help mode. I.e. it is permissible for a user to have (add-hook
> 'temp-buffer-setup-hook 'fancy-help-mode t)
> 
> The more important reason is we have variants of those macros and it is
> time to consolidate them. I'll find time to do that. Sorry just came
> back from a break and it has been very busy lately. But I'll get to it
> soon.

Please don't.

The last go-round of such "consolidation" is how we got into the
current mess.  Please see my original report of the problem and my
suggestion for fixing it.  You can start with the URL above.

The solution to the (minor) problem that "temp" was really about
"help" and there was nothing for temporary buffers *without*
help-mode should have been (as originally suggested) to:
(1) rename the "temp" macro (`with-output-to-temp-buffer') while
keeping the old name as an alias AND (2) create a new macro that
really is for temporary buffers (without any help-mode stuff).

What we got instead was a new macro for help (good) and a blind
removal of the help-mode stuff from the existing "temp" macro (bad!).

That requires every existing use of `with-output-to-temp-buffer' to
be revisited and adjusted to use the new help macro (or not, rarely)
instead.

Worse: For code that needs to work with multiple Emacs versions, it
also means adding an ugly workaround or two.  Something like this,
for instance, substituting it for (existing occurrences of the old)
`with-output-to-temp-buffer':

(defmacro my-kludgy-with-help-window (buffer &rest body)
  "`with-help-window', if available; else `with-output-to-temp-buffer'."
  (if (fboundp 'with-help-window)
      `(with-help-window ,buffer ,@body)
    `(with-output-to-temp-buffer ,buffer ,@body)))

Of course, wholesale replacement by such a macro would not deal
directly or correctly with existing occurrences of
`with-output-to-temp-buffer' where there was accompanying code that 
removed/inhibited the help-mode stuff (i.e., that tried to treat it
as really just a temporary buffer).

Whatever the workaround, each occurrence of `with-output-to-temp-buffer'
really needs to be checked to see what TRT to do is.

It's hard for me to believe that (a) things were "fixed" the way
they were and (b) that it has taken so long for someone besides me
to speak up about DTRT (thank you, Glenn).

FWIW: I have great respect for Martin's work.  This time, for
whatever reasons, and whatever combination of fixers was responsible
for the state we're in now, things have not turned out so well.

To me, the right solution is still the same: (a) revert the changes
to `with-output-to-temp-buffer' and (b) keep the changes to the
Emacs code that use the fine new macro (`with-help-window').

In addition, to address the original problem I reported, (c) create
a new macro with `temp' in the name, which does no help-mode stuff -
it would do essentially what the current (i.e., changed)
`with-output-to-temp-buffer' does, and (d) alias
`with-output-to-temp-buffer' to `with-help-window' and deprecate
`with-output-to-temp-buffer'.

The change for the last paragraph, (c) and (d), is *not* urgent.
It is essentially a nice-to-have, to end up with "temp" meaning
only temporary (not also help) and "help" meaning help.

But (a) and (b) should be done now (before Emacs 24.4), to bring
some sanity back.  Those of us who have already adjusted our code
to fit the new mess will just have to unadjust it.