bug#4655: 23.1.50; buffer-swap-text oddity

[Eli Zaretskii]

> From: npostavs@users.sourceforge.net
> Date: Sun, 10 Jul 2016 21:58:36 -0400
> Cc: Markus Rost <rost@math.uni-bielefeld.de>,
>       Juanma Barranquero <lekktu@gmail.com>, 4655@debbugs.gnu.org,
>       Stefan Monnier <monnier@iro.umontreal.ca>
> 
> --- a/doc/lispref/buffers.texi
> +++ b/doc/lispref/buffers.texi
> @@ -1211,6 +1211,11 @@ Swapping Text
>  overlays, the text properties, the undo list, the value of the
>  @code{enable-multibyte-characters} flag (@pxref{Text Representations,
>  enable-multibyte-characters}), etc.
> +
> +@strong{Warning:} The current buffer will be set to @var{buffer} if
> +this function is called from within @code{save-excursion}, since the
> +marker used by @code{save-excursion} to save the position and buffer
> +will be swapped as well.
>  @end defun

Fine with me, but I think we should also add a single sentence to the
doc string, something like

  Using this function from `save-excursion' might produce surprising
  results, see Info node `(elisp)Swapping Text'.

With that taken care of, please push to emacs-25.

Thanks.