bug#16038: 24.3; latest change to with-help-window makes temp-buffer-browse useless

[Glenn Morris <rgm@gnu.org>]

Leo Liu wrote:

> On 2014-07-07 21:54 -0400, Glenn Morris wrote:
>
>> If you want to do this (I know you already did...), you need to add an
>> incompatible change entry to NEWS about this, and you need to audit
>> every single use of with-output-to-temp-buffer to find the ones that
>> expected their output buffers to be in help mode.
>
> We made that change to prove the above two lines cause no harm other
> than not enabling help-mode. At some stage and probably pretty soon, we
> might merge the two macros with-output-to-temp-buffer and
> with-temp-buffer-window under one name (the former looks like a simple
> case of the latter). So the change is intermediate.

Sorry, this makes no sense to me.

with-output-to-temp-buffer is a documented macro with a specific purpose.
I shall now do the tedious thing of quoting the manual:

   This function executes the forms in BODY while arranging to insert
   any output they print into the buffer named BUFFER-NAME, which is
   first created if necessary, and put into Help mode.
   [...]
   If the forms in BODY do not change the major mode in the output
   buffer, so that it is still Help mode at the end of their
   execution, then `with-output-to-temp-buffer' makes this buffer
   read-only at the end, and also scans it for function and variable
   names to make them into clickable cross-references.

Now it does not do any of that.

The normal way to do this kind of thing is to introduce a new macro that
does whatever new thing you want, and deprecate the old one. Not to just
half-arsedly change the old one to do something else, without updating
any of the documentation or callers.