bug#3806: 23.1.50; rename-uniquely doc

[Stephen Berman]

The doc string of rename-uniquely says:

,----
| Rename current buffer to a similar name not already taken.
| This function is useful for creating multiple shell process buffers
| or multiple mail buffers, etc.
`----

The Emacs manual (node Misc Buffer) says more:

,----
| `M-x rename-uniquely' renames the current buffer to a similar name
| with a numeric suffix added to make it both different and unique.  This
| command does not need an argument.  It is useful for creating multiple
| shell buffers: if you rename the `*shell*' buffer, then do `M-x shell'
| again, it makes a new shell buffer named `*shell*'; meanwhile, the old
| shell buffer continues to exist under its new name.  This method is
| also good for mail buffers, compilation buffers, and most Emacs
| features that create special buffers with particular names.  (With some
| of these features, such as `M-x compile', `M-x grep' an `M-x info', you
| need to switch to some other buffer before using the command, in order
| for it to make a different buffer.)
`----

The last, parenthetical, sentence in particular is important
information, and I think it should also be in the doc string, since this
is an annoying gotcha.  And for this reason, I also think it should be
more specific, not just listing "some of these features" that require
switching out of the uniquely renamed buffer, but all such known
"features".  However, the manual appears to be out of date, or just
inaccurate: invoking Info from within a uniquely renamed Info buffer
does not overwrite it but opens new Info buffer, as I just confirmed
with -Q.  So the doc needs to be at least corrected (and preferably
augmented).

If `M-x info' has indeed been "fixed" wrt rename-uniquely, then can't
`M-x {r,l}grep' and `M-x compile' likewise be fixed?  (I haven't tested
compile for this, but the grep commands do indeed, annoyingly, require
switching buffers.)  Since the requirement is documented, it is not
strictly a bug, but the behavior is suboptimal and if, as with Info, it
can be changed, then I think it should be.  I can submit a separate bug
for that.


In GNU Emacs 23.1.50.3 (i686-pc-linux-gnu, GTK+ Version 2.14.4)
 of 2009-07-08 on escher
Windowing system distributor `The X.Org Foundation', version 11.0.10502000
Important settings:
  value of $LC_ALL: nil
  value of $LC_COLLATE: nil
  value of $LC_CTYPE: nil
  value of $LC_MESSAGES: nil
  value of $LC_MONETARY: nil
  value of $LC_NUMERIC: nil
  value of $LC_TIME: nil
  value of $LANG: en_US.UTF-8
  value of $XMODIFIERS: @im=local
  locale-coding-system: utf-8-unix
  default-enable-multibyte-characters: t