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.