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

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

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'