bug#8368: 24.0.50; "temp" means "help" - rename or at least document

bug#8368: 24.0.50; "temp" means "help" - rename or at least document

[Drew Adams]

I think it is a mistake to treat "temporary buffer" macros and functions
as if they necessarily dealt with particular buffers such as *Help* and
*Completions* or with particular modes such as `help-mode' and
`completion-list-mode'.
 
Based on their names and descriptions (doc), things such as
`with-output-to-temp-buffer' should simply set up a temporary buffer,
with no special treatment for it being a "help" buffer or a
"completions" buffer etc.
 
Why, for example, should `with-output-to-temp-buffer' always imply
calling `help-mode-*' in that buffer?  Based on the name, a "temporary
buffer" is not necessarily a help buffer.
 
And based on its doc, `with-output-to-temp-buffer', for example, is not
about a help buffer.  There is NOTHING in its doc that gives the
slightest suggestion that the temporary buffer is a help buffer, is in
`help-mode', etc.  Nada.  Please take a moment to read the doc string.

But in help.el we do this, at top level:
 
;; This makes `with-output-to-temp-buffer' buffers use `help-mode'.
(add-hook 'temp-buffer-setup-hook 'help-mode-setup)
(add-hook 'temp-buffer-show-hook 'help-mode-finish)
 
Yes, I know that this has been the case for a long time.  But I also
know that the effect has resulted in confusion for at least some users.
 
You can say that the problem is just the name.  In that case, the doc
should help to correct the false impression by stating explicitly that a
"temp" buffer is really a "help" buffer, in `help-mode' (by default).
 
Better, however, would be to rename *-temp-* to *-help-* whenever "temp"
really implies "help".

And after renaming functions/macros that way, I think it would be good
to have real temporary-buffer facilities - a real
`with-output-to-temp-buffer' (but we would need to pick a new name, to
avoid confusion), one that does not imply using `help-mode' etc.
 
In GNU Emacs 24.0.50.1 (i386-mingw-nt5.1.2600)
 of 2011-03-21 on 3249CTO
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (4.5) --no-opt --cflags
-Ic:/imagesupport/include'
 

bug#8368: 24.0.50; "temp" means "help" - rename or at least document

[Lars Magne Ingebrigtsen]

"Drew Adams" <drew.adams@oracle.com> writes:

> And based on its doc, `with-output-to-temp-buffer', for example, is not
> about a help buffer.  There is NOTHING in its doc that gives the
> slightest suggestion that the temporary buffer is a help buffer, is in
> `help-mode', etc.  Nada.  Please take a moment to read the doc string.
>
> But in help.el we do this, at top level:
>
> ;; This makes `with-output-to-temp-buffer' buffers use `help-mode'.
> (add-hook 'temp-buffer-setup-hook 'help-mode-setup)
> (add-hook 'temp-buffer-show-hook 'help-mode-finish)

That's pretty odd.

Digging through the ChangeLogs, this is apparently the commit that
added them, but it doesn't say why.

1999-01-11  Richard Stallman  <rms@psilocin.ai.mit.edu>

	* help.el (help-mode-finish): Renamed from help-mode-maybe.
	Don't switch to Help mode here.
	(temp-buffer-setup-hook): Use help-mode-finish.
	(help-mode-setup): New function.
	(temp-buffer-setup-hook): Use help-mode-setup.

Richard, why is `help-mode-setup' run in absolutely all
`with-output-to-temp-buffer' buffers?  This seems rather un-optimal,
since that macro is used for many other things than showing help
buffers.

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/

bug#8368: 24.0.50; "temp" means "help" - rename or at least document

[Lars Magne Ingebrigtsen]

Lars Magne Ingebrigtsen <larsi@gnus.org> writes:

> Digging through the ChangeLogs, this is apparently the commit that
> added them, but it doesn't say why.
>
> 1999-01-11  Richard Stallman  <rms@psilocin.ai.mit.edu>
>
> 	* help.el (help-mode-finish): Renamed from help-mode-maybe.
> 	Don't switch to Help mode here.
> 	(temp-buffer-setup-hook): Use help-mode-finish.
> 	(help-mode-setup): New function.
> 	(temp-buffer-setup-hook): Use help-mode-setup.
>
> Richard, why is `help-mode-setup' run in absolutely all
> `with-output-to-temp-buffer' buffers?  This seems rather un-optimal,
> since that macro is used for many other things than showing help
> buffers.

There's been no response in two months.

I think the following is a bug:

;; This makes `with-output-to-temp-buffer' buffers use `help-mode'.
(add-hook 'temp-buffer-setup-hook 'help-mode-setup)
(add-hook 'temp-buffer-show-hook 'help-mode-finish)

Would removing these be a good idea?

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/

bug#8368: 24.0.50; "temp" means "help" - rename or at least document

[Stefan Monnier]

> I think the following is a bug:

> ;; This makes `with-output-to-temp-buffer' buffers use `help-mode'.
> (add-hook 'temp-buffer-setup-hook 'help-mode-setup)
> (add-hook 'temp-buffer-show-hook 'help-mode-finish)

> Would removing these be a good idea?

Not at this stage of the development, no.


        Stefan

bug#8368: 24.0.50; "temp" means "help" - rename or at least document

[Lars Magne Ingebrigtsen]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

>> I think the following is a bug:
>
>> ;; This makes `with-output-to-temp-buffer' buffers use `help-mode'.
>> (add-hook 'temp-buffer-setup-hook 'help-mode-setup)
>> (add-hook 'temp-buffer-show-hook 'help-mode-finish)
>
>> Would removing these be a good idea?
>
> Not at this stage of the development, no.

No, I was thinking after Emacs 24.1...

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/

bug#8368: 24.0.50; "temp" means "help" - rename or at least document

[Richard Stallman]

    > Richard, why is `help-mode-setup' run in absolutely all
    > `with-output-to-temp-buffer' buffers?  This seems rather un-optimal,
    > since that macro is used for many other things than showing help
    > buffers.

I think they were initially set up in Fundamental mode.
Then, once Help mode existed, it was the right thing for most of these
buffers, so it was useful to put them in Help mode.  But there was
no way to make that optional without changing all the callers.

There are other ways to handle this, but just deleting that code would
have bad results: most of these buffers would end up in Fundamental
mode.

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use free telephony http://directory.fsf.org/category/tel/

bug#8368: 24.0.50; "temp" means "help" - rename or at least document

[Lars Magne Ingebrigtsen]

Richard Stallman <rms@gnu.org> writes:

> I think they were initially set up in Fundamental mode.
> Then, once Help mode existed, it was the right thing for most of these
> buffers, so it was useful to put them in Help mode.  But there was
> no way to make that optional without changing all the callers.
>
> There are other ways to handle this, but just deleting that code would
> have bad results: most of these buffers would end up in Fundamental
> mode.

If `help-mode' is the correct mode for these buffers, then I think
`with-output-to-temp-buffer' should be documented to put the buffer in
help mode, and it should be done explicitly in the code -- not by having
help.el alter `temp-buffer-setup-hook' when help.el is loaded.

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/

bug#8368: 24.0.50; "temp" means "help" - rename or at least document

[Drew Adams]

> If `help-mode' is the correct mode for these buffers, then I think
> `with-output-to-temp-buffer' should be documented to put the buffer in
> help mode, and it should be done explicitly in the code -- 
> not by having help.el alter `temp-buffer-setup-hook' when help.el
> is loaded.

See the original bug report.  There I stated that (a) it should at least be
documented, (b) the macros should preferably be renamed (using `-help-', not
`-temp'), and this (c):

"And after renaming functions/macros that way, I think it
 would be good to have real temporary-buffer facilities - a real
 `with-output-to-temp-buffer' (but we would need to pick a new
 name, to avoid confusion), one that does not imply using
 `help-mode' etc.

The point of the last part is that there is a need for creating and using
temporary buffers.  That should never have been co-opted for help, but now that
it is we should fix it properly: (a) call a spade a spade and (b) create new
macros for really dealing with temporary buffers.

bug#8368: 24.0.50; "temp" means "help" - rename or at least document

[Richard Stallman]

    If `help-mode' is the correct mode for these buffers, then I think
    `with-output-to-temp-buffer' should be documented to put the buffer in
    help mode, and it should be done explicitly in the code -- not by having
    help.el alter `temp-buffer-setup-hook' when help.el is loaded.

I think the reason I did it in the hook was to create a way to turn it
off.  Your change would eliminate that possibility.

It is surely possible to change how this area works, but please
don't just delete these hook settings.

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use free telephony http://directory.fsf.org/category/tel/

bug#8368: 24.0.50; "temp" means "help" - rename or at least document

[Drew Adams]

> From: Stefan Monnier Sent: Saturday, September 10, 2011 9:58 PM
>
Lars> There's been no response in two months.
Lars> I think the following is a bug:
Lars> ;; This makes `with-output-to-temp-buffer' buffers use `help-mode'.
Lars> (add-hook 'temp-buffer-setup-hook 'help-mode-setup)
Lars> (add-hook 'temp-buffer-show-hook 'help-mode-finish)
Lars> Would removing these be a good idea?
> 
> Not at this stage of the development, no.

So now it's been over a year since the bug was filed.

Can't the help mode code add those hooks only for the use of *Help* and other
help-mode buffers?  Why should all uses of `with-output-to-temp-buffer' end up
running those hook functions that are, after all, specific to help mode?

Can we please move forward on fixing this bug?

There is lots of stuff in a "temp" buffer now that has nothing to do with a
temporary buffer.

emacs -Q
(setq debug-on-error t)
(defun foo ()
  "..."
  (with-output-to-temp-buffer "*TEMP*"
    (princ "FOOOOO\n-----\n\n")))
(foo)
C-x b *TEMP*
TAB

Debugger entered--Lisp error: (error "No buttons!")
  signal(error ("No buttons!"))
  error("No buttons!")
  forward-button(1 1 1)
  call-interactively(forward-button nil nil)

No f___ing buttons?  WTF?  Who cares?

Look at all the keys bound now in a "temporary" buffer (below).  How many of
them have to do with a temporary display of something other than outright
*Help*?

The only keys I can think of that might generally make sense for a temporary
buffer mode are SPC, DEL, <, >, ?, h, q, maybe z (but why was `z' chosen to
kill?), maybe the digits and -, and maybe (if `revert-buffer-function' says so)
g.

All of the special help link and navigation commands should be reserved for a
help mode that is _derived_ from a (minimal) temporary buffer mode.

While waiting for that, users have to do something like this, just to get rid of
the *Help*-imposed stuff:

(defmacro 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)))

It makes no more sense for *Help* to have co-opted temporary buffer display than
it would have made for Info to have co-opted it.  Dunno how we ever went down
this road.

key             binding
---             -------

C-c		Prefix Command
TAB		forward-button
RET		help-follow
ESC		Prefix Command
SPC		scroll-up-command
-		negative-argument
0 .. 9	digit-argument
<		beginning-of-buffer
>		end-of-buffer
?		describe-mode
g		revert-buffer
h		describe-mode
q		quit-window
z		kill-this-buffer
DEL		scroll-down-command
<backtab>	backward-button
<mouse-2>	help-follow-mouse
<remap>	Prefix Command

C-c C-b	help-go-back
C-c C-c	help-follow-symbol
C-c C-f	help-go-forward

M-TAB		backward-button

bug#8368: 24.0.50; "temp" means "help" - rename or at least document

[martin rudalics]

 > Can't the help mode code add those hooks only for the use of *Help* and other
 > help-mode buffers?  Why should all uses of `with-output-to-temp-buffer' end up
 > running those hook functions that are, after all, specific to help mode?
 >
 > Can we please move forward on fixing this bug?
 >
 > There is lots of stuff in a "temp" buffer now that has nothing to do with a
 > temporary buffer.

Maybe we could proceed as follows:

(1) In my Emacs I moved `internal-temp-output-buffer-show' to Elisp and
intend to apply this change to the trunk soon.  Other from that, leave
`with-output-to-temp-buffer' unchanged.

(2) Provide a new macro which does almost the same as
`with-output-to-temp-buffer', runs similar hooks ...  Maybe we find some
improvements though.

(3) Change all callers of `with-output-to-temp-buffer' in Emacs 24 to
use the new macro and *not permanently* add their functions to the new
hooks.  Whether we use another wrapper for this like `with-help-window'
or bind the hook temporarily seems a matter of taste.

(4) Declare `with-output-to-temp-buffer' obsolete.

martin

bug#8368: 24.0.50; "temp" means "help" - rename or at least document

[Drew Adams]

> (1) In my Emacs I moved `internal-temp-output-buffer-show' to 
> Elisp and intend to apply this change to the trunk soon.
> Other from that, leave `with-output-to-temp-buffer' unchanged.
> 
> (2) Provide a new macro which does almost the same as
> `with-output-to-temp-buffer', runs similar hooks ...  Maybe 
> we find some improvements though.
> 
> (3) Change all callers of `with-output-to-temp-buffer' in Emacs 24 to
> use the new macro and *not permanently* add their functions to the new
> hooks.  Whether we use another wrapper for this like 
> `with-help-window' or bind the hook temporarily seems a matter of taste.
> 
> (4) Declare `with-output-to-temp-buffer' obsolete.

Hi Martin,

I'm not sure I understand all of your proposal, but I think I agree.  Let me
just say this.  If it is addressed already by your proposal (I think so), great.
If not, maybe you can try to take it into consideration.

Whether we have one or more different macros to distinguish temporary from help
displays does not matter much to me.  Likewise, the names of the macros or
whatever are not what is most important (to me).  Obviously, if possible, I
would prefer that the names reflect the meaning/behavior - so, e.g. "temp" in
one name and, say, "help" in the other.  And maybe it makes sense to derive the
help mode from the temp mode - dunno.

What is important to me is that we distinguish the two (or more) so that
programmers at least have a simple, clean way to display something in a
temporary buffer with no supposition that that buffer should also be a help
buffer.  I.e., without removing and re-adding the help-mode hooks.

Probably we will need to leave the original name for the current behavior, but
if it could be aliased to something with "help" in the name, and then the
original name deprecated, that would be better.  (I think that's part of what
you suggest.)  And create a new name for the temp-without-the-help-stuff case.

Whatever you decide will I'm sure be better than the hard-coded
take-it-or-leave-it situation we have now.  And splitting the two this way will
also reduce any pressure (e.g., from users like me) not to add more help stuff
to the help-mode version.

I hope this can be done soon.  It's been over a year since the bug report was
filed.

Thx - Drew

bug#8368: 24.0.50; "temp" means "help" - rename or at least document

[Stefan Monnier]

> Maybe we could proceed as follows:

> (1) In my Emacs I moved `internal-temp-output-buffer-show' to Elisp and
> intend to apply this change to the trunk soon.  Other from that, leave
> `with-output-to-temp-buffer' unchanged.

> (2) Provide a new macro which does almost the same as
> `with-output-to-temp-buffer', runs similar hooks ...  Maybe we find some
> improvements though.

> (3) Change all callers of `with-output-to-temp-buffer' in Emacs 24 to
> use the new macro and *not permanently* add their functions to the new
> hooks.  Whether we use another wrapper for this like `with-help-window'
> or bind the hook temporarily seems a matter of taste.

> (4) Declare `with-output-to-temp-buffer' obsolete.

Sounds like a good plan,


        Stefan

bug#8368: 24.0.50; "temp" means "help" - rename or at least document

[martin rudalics]

 > What is important to me is that we distinguish the two (or more) so that
 > programmers at least have a simple, clean way to display something in a
 > temporary buffer with no supposition that that buffer should also be a help
 > buffer.  I.e., without removing and re-adding the help-mode hooks.

You don't have to remove and re-add any hooks.  It's sufficient to turn
off help mode in the body of `with-output-to-temp-buffer'.  Similarly,
if you don't want to run `completion-list-mode-finish', turn off
`completion-list-mode' in the buffer.

 > Probably we will need to leave the original name for the current behavior, but
 > if it could be aliased to something with "help" in the name, and then the
 > original name deprecated, that would be better.  (I think that's part of what
 > you suggest.)  And create a new name for the temp-without-the-help-stuff case.

Basically, `with-output-to-temp-buffer' is a misnomer.  The buffer is not
necessarily temporary, hence `with-output-temporarily-bound-to-buffer'
would be a better name for this.  In addition, it displays the buffer in
some window and this is not reflected in the name.

martin

bug#8368: 24.0.50; "temp" means "help" - rename or at least document

[Drew Adams]

> You don't have to remove and re-add any hooks.  It's 
> sufficient to turn off help mode in the body of 
> `with-output-to-temp-buffer'.  Similarly,
> if you don't want to run `completion-list-mode-finish', turn off
> `completion-list-mode' in the buffer.

Sufficient?  That sounds like more work, not less.  Why turn help mode etc. on
automatically and then turn it off again.  Why not just remove the hook so it
does not get turned on?  I'm probably missing something in what you're
suggesting.

>  > Probably we will need to leave the original name for the 
>  > current behavior, but if it could be aliased to something
>  > with "help" in the name, and then the original name deprecated,
>  > that would be better.  (I think that's part of what
>  > you suggest.)  And create a new name for the 
>  > temp-without-the-help-stuff case.
> 
> Basically, `with-output-to-temp-buffer' is a misnomer.  The 
> buffer is not necessarily temporary, hence
> `with-output-temporarily-bound-to-buffer'
> would be a better name for this.

True, but I don't really have a problem with that.  "Temporary" can mean
different things depending on the use to which this is put.  A buffer that I
display showing some information might be considered temporary if the user is
likely to throw it away soon after seeing the info.  At another extreme, a
temporary buffer might be one that a program uses without ever displaying and
kills when done.

> In addition, it displays the buffer in
> some window and this is not reflected in the name.

True again.  This point is more important, IMO, than the "temporary" point.  It
would be good for the name to indicate that the buffer is shown to the user.

bug#8368: 24.0.50; "temp" means "help" - rename or at least document

[martin rudalics]

 >> You don't have to remove and re-add any hooks.  It's
 >> sufficient to turn off help mode in the body of
 >> `with-output-to-temp-buffer'.  Similarly,
 >> if you don't want to run `completion-list-mode-finish', turn off
 >> `completion-list-mode' in the buffer.
 >
 > Sufficient?  That sounds like more work, not less.  Why turn help mode etc. on
 > automatically and then turn it off again.  Why not just remove the hook so it
 > does not get turned on?

Because it's non-trivial to "just" do that.  We have to go through all
users of `with-output-to-temp-buffer' and check whether they want to
turn on help mode or not.  I don't have the slightest idea whether, for
example, the calls in ada-xref.el require activating help mode or not.

 > I'm probably missing something in what you're
 > suggesting.

No.  But you earlier said that

 > While waiting for that, users have to do something like this, just to get rid of
 > the *Help*-imposed stuff:
 >
 > (defmacro 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)))

and I simply explained that there's an easier way to achieve what you
want.  Obviously, dealing with `temp-buffer-show-hook' in
`with-output-to-plain-temp-buffer' isn't necessary either if you don't
run `help-mode-setup' before.

martin

bug#8368: 24.0.50; "temp" means "help" - rename or at least document

[Drew Adams]

>  >> You don't have to remove and re-add any hooks.  It's
>  >> sufficient to turn off help mode in the body of
>  >> `with-output-to-temp-buffer'.  Similarly,
>  >> if you don't want to run `completion-list-mode-finish', turn off
>  >> `completion-list-mode' in the buffer.
>  >
>  > Sufficient?  That sounds like more work, not less.  Why 
>  > turn help mode etc. on automatically and then turn it off again.
>  > Why not just remove the hook so it does not get turned on?
> 
> Because it's non-trivial to "just" do that.  We have to go through all
> users of `with-output-to-temp-buffer' and check whether they want to
> turn on help mode or not.  I don't have the slightest idea 
> whether, for example, the calls in ada-xref.el require activating
> help mode or not.

We might be miscommunicating.

First, let me say that I don't really want to argue about the solution so much
as report the problem and ask for a solution.

Second, I was not talking about changing any existing code, especially Emacs Dev
code.  I was simply saying that because help-mode stuff is currently hard-coded
into `w-o-t-t-b', then IF a programmer wants a temp buffer without that help
stuff then s?he can do something like what I wrote, as a workaround: define a
macro that uses `w-o-t-t-b', but first removes the help-stuff hooks and restores
them afterward.  That's all.

Your suggestion was IIUC to instead use `w-o-t-t-b' and just turn off help-mode
in the BODY.  OK, but that means that help-mode is entered and exited for
nothing - the hooks are run uselessly.  That's all I was pointing out.  Nothing
wrong with such useless work, but it, like my workaround, does not seem like the
solution to the problem.

> Obviously, dealing with `temp-buffer-show-hook' in
> `with-output-to-plain-temp-buffer' isn't necessary either if you don't
> run `help-mode-setup' before.

Ah, yes.  Of course that means paying even more attention etc.

Anyway, thanks for thinking about this.  I really would like to see Emacs fixed
in this regard.  To my mind (not having thought much about it, and being pretty
ignorant about it), I would think that inheritance could be used to factor out
the stuff that is not specifically for help mode (i.e., have the help-mode stuff
inherit from that).

bug#8368: 24.0.50; "temp" means "help" - rename or at least document

[martin rudalics]

 > IF a programmer wants a temp buffer without that help
 > stuff then s?he can do something like what I wrote, as a workaround: define a
 > macro that uses `w-o-t-t-b', but first removes the help-stuff hooks and restores
 > them afterward.  That's all.

S?he could also write such a macro from scratch and post the result here
together with a suitable name.

 > Your suggestion was IIUC to instead use `w-o-t-t-b' and just turn off help-mode
 > in the BODY.  OK, but that means that help-mode is entered and exited for
 > nothing - the hooks are run uselessly.

Who cares?  The overhead for removing and adding a hook (with all the
necessary protection) is just as high.

 > That's all I was pointing out.  Nothing
 > wrong with such useless work, but it, like my workaround, does not seem like the
 > solution to the problem.

We agree here.

 >> Obviously, dealing with `temp-buffer-show-hook' in
 >> `with-output-to-plain-temp-buffer' isn't necessary either if you don't
 >> run `help-mode-setup' before.
 >
 > Ah, yes.  Of course that means paying even more attention etc.
 >
 > Anyway, thanks for thinking about this.  I really would like to see Emacs fixed
 > in this regard.  To my mind (not having thought much about it, and being pretty
 > ignorant about it), I would think that inheritance could be used to factor out
 > the stuff that is not specifically for help mode (i.e., have the help-mode stuff
 > inherit from that).

That's the way to go, yes.  The question is rather one of how to avoid
confusing users when we have, for example, a `temp-buffer-setup-hook'
and a `plain-temp-buffer-setup-hook' and BOTH get run when we invoke the
inheriting macro.

martin

bug#8368: 24.0.50; "temp" means "help" - rename or at least document

[Drew Adams]

> The question is rather one of how to avoid
> confusing users when we have, for example, a `temp-buffer-setup-hook'
> and a `plain-temp-buffer-setup-hook' and BOTH get run when we 
> invoke the inheriting macro.

I thought both what you proposed and what I proposed addressed this: rename
(alias) and deprecate the old, misleading names.  Seems like we're going 'round
in circles now.  I thought we (you & I & Stefan, at least) had already agreed on
a reasonable solution.

And I was pretty clear that the names are not what is most important to me.
What matters most is to have a macro that does only the non-help stuff, separate
from the macro that does also the help stuff.  To repeat:

>> Probably we will need to leave the original name for the 
>> current behavior, but if it could be aliased to something
>> with "help" in the name, and then the original name deprecated,
>> that would be better.  (I think that's part of what
>> you suggest.)  And create a new name for the 
>> temp-without-the-help-stuff case.
>> 
>> Whatever you decide will I'm sure be better than the hard-coded
>> take-it-or-leave-it situation we have now.  And splitting the 
>> two this way will also reduce any pressure (e.g., from users
>> like me) not to add more help stuff to the help-mode version.

bug#8368: 24.0.50; "temp" means "help" - rename or at least document

[martin rudalics]

 > I thought both what you proposed and what I proposed addressed this: rename
 > (alias) and deprecate the old, misleading names.  Seems like we're going 'round
 > in circles now.  I thought we (you & I & Stefan, at least) had already agreed on
 > a reasonable solution.
 >
 > And I was pretty clear that the names are not what is most important to me.
 > What matters most is to have a macro that does only the non-help stuff, separate
 > from the macro that does also the help stuff.

Can you tell me what you mean here?  In the first paragraph you say that
you want to rename and in the second paragraph you say that the names
are not important to you.

What I proposed boils down to write (at least) two new macros: One which
sets up `help-mode' and one which does not.  The question (for me) is
whether the former should call the later and which hooks these should
run (if at all).  The `with-output-to-temp-buffer' macro would stay in
place until we can safely tell that it doesn't have any more callers.

martin

bug#8368: 24.0.50; "temp" means "help" - rename or at least document

[Drew Adams]

>  > I thought both what you proposed and what I proposed 
>  > addressed this: rename (alias) and deprecate the old,
>  > misleading names.  Seems like we're going 'round
>  > in circles now.  I thought we (you & I & Stefan, at least) 
>  > had already agreed on a reasonable solution.
>  >
>  > And I was pretty clear that the names are not what is
>  > most important to me.
     ^^^^
>  > What matters most is to have a macro that does only the 
>  > non-help stuff, separate from the macro that does also
>  > the help stuff.
> 
> Can you tell me what you mean here?  In the first paragraph 
> you say that you want to rename

Just a proposal.  If we have two macros, one for help stuff and one for only
displaying etc but with nothing specific to help-mode, that would be good.  If,
in addition, the name of the help-mode specific one could have "help" in it, so
much the better.

One way to get the naming right is to defalias any name that will be
inappropriate in the end to a new, more appropriate name (e.g. `...-help-...').

Deprecation does not mean immediate desupport, and it might not ever imply
desupport.  It means that what is deprecated _might_ be desupported at some time
in the future.  So users of the old name are not impacted.  It's just a heads-up
to users.  They are forewarned that they might want to update the name sooner
rather than later.  But they _need not_ do so until desupport happens, if it
ever does.  The new, preferred name is what will be documented and increasingly
used for new code etc.

And even earlier I said:

>> Probably we will need to leave the original name for the 
>> current behavior, but if it could be aliased to something
>> with "help" in the name, and then the
>> original name deprecated, that would be better.

> and in the second paragraph you say that the names
> are not important to you.

No.  Names are always important.  What I said was that getting good names is not
_as important_ as separating out the help-specific stuff, e.g., having two
separate macros.  Names are not the "most" important thing.

And even earlier I said:

>> Whether we have one or more different macros to distinguish 
>> temporary from help displays does not matter much to me.
>> Likewise, the names of the macros or whatever are not what
>> is most important (to me).
>>
>> Obviously, if possible, I would prefer that the names
>> reflect the meaning/behavior - so, e.g. "temp" in
>> one name and, say, "help" in the other.  And maybe it
>> makes sense to derive the help mode from the temp mode
>> - dunno.

> What I proposed boils down to write (at least) two new 
> macros: One which sets up `help-mode' and one which does not.

And I agreed.  And I said, "I don't really want to argue about the solution so
much as report the problem and ask for a solution."

> The question (for me) is whether the former should call the
> lat[t]er and which hooks these should run (if at all).

See above.  I'm sure I'm OK with whatever you decide.
As I said earlier:

>> Whatever you decide will I'm sure be better than the
>> hard-coded take-it-or-leave-it situation we have now.  

> The `with-output-to-temp-buffer' macro would stay in
> place until we can safely tell that it doesn't have any more callers.

Sounds good to me.  My only proposal in that regard was to create an alias with
a better name (e.g. `...-help-...'), and deprecate `with-output-to-temp-buffer'
to encourage use of the new name.

Am I still not clear enough?  In sum, please go for it.  I'm OK with what you
propose to do.

bug#8368: 24.0.50; "temp" means "help" - rename or at least document

[Lars Ingebrigtsen]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

>> Maybe we could proceed as follows:
>
>> (1) In my Emacs I moved `internal-temp-output-buffer-show' to Elisp and
>> intend to apply this change to the trunk soon.  Other from that, leave
>> `with-output-to-temp-buffer' unchanged.

This was done, I think...

>> (2) Provide a new macro which does almost the same as
>> `with-output-to-temp-buffer', runs similar hooks ...  Maybe we find some
>> improvements though.
>
>> (3) Change all callers of `with-output-to-temp-buffer' in Emacs 24 to
>> use the new macro and *not permanently* add their functions to the new
>> hooks.  Whether we use another wrapper for this like `with-help-window'
>> or bind the hook temporarily seems a matter of taste.
>
>> (4) Declare `with-output-to-temp-buffer' obsolete.
>
> Sounds like a good plan,

But the rest was not.  Instead `with-output-to-temp-buffer' has been
documented to run help-mode by default, so perhaps somebody decided on
not doing this changearoo?

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#8368: 24.0.50; "temp" means "help" - rename or at least document

[Lars Ingebrigtsen]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> But the rest was not.  Instead `with-output-to-temp-buffer' has been
> documented to run help-mode by default, so perhaps somebody decided on
> not doing this changearoo?

This was three years ago, and the bug report otherwise was last touched
seven years ago, so I think indeed that was the decision, and I'm
closing this bug report.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no