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

[Eli Zaretskii <eliz@gnu.org>]

> From: npostavs@users.sourceforge.net
> Cc: 4655@debbugs.gnu.org,  lekktu@gmail.com,  monnier@iro.umontreal.ca,  dgutov@yandex.ru,  rost@math.uni-bielefeld.de,  larsi@gnus.org
> Date: Wed, 13 Jul 2016 19:50:49 -0400
> 
> Okay, here is my final version, I will push tomorrow.
> 
> >From f0295dbfceb3264f93d583537ff184b63779adea Mon Sep 17 00:00:00 2001
> From: Noam Postavsky <npostavs@gmail.com>
> Date: Sun, 10 Jul 2016 21:52:23 -0400
> Subject: [PATCH v3] Document buffer-swap-text+save-excursion interaction
> 
> * doc/lispref/buffers.texi (Swapping Text):
> * src/buffer.c (Fbuffer_swap_text): Add warning about interaction of
> `buffer-swap-text' and `save-excursion' (Bug #4655).
> ---
>  doc/lispref/buffers.texi | 6 ++++++
>  src/buffer.c             | 4 +++-
>  2 files changed, 9 insertions(+), 1 deletion(-)
> 
> diff --git a/doc/lispref/buffers.texi b/doc/lispref/buffers.texi
> index 1f7f263..740d7cf 100644
> --- a/doc/lispref/buffers.texi
> +++ b/doc/lispref/buffers.texi
> @@ -1211,6 +1211,12 @@ 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:} If this function is called from within a
> +@code{save-excursion} form, the current buffer will be set to
> +@var{buffer} upon leaving the form, since the marker used by
> +@code{save-excursion} to save the position and buffer will be swapped
> +as well.
>  @end defun
>  
>    If you use @code{buffer-swap-text} on a file-visiting buffer, you
> diff --git a/src/buffer.c b/src/buffer.c
> index e4269c0..89f4479 100644
> --- a/src/buffer.c
> +++ b/src/buffer.c
> @@ -2231,7 +2231,9 @@ advance_to_char_boundary (ptrdiff_t byte_pos)
>  
>  DEFUN ("buffer-swap-text", Fbuffer_swap_text, Sbuffer_swap_text,
>         1, 1, 0,
> -       doc: /* Swap the text between current buffer and BUFFER.  */)
> +       doc: /* Swap the text between current buffer and BUFFER.
> +Using this function from `save-excursion' might produce surprising
> +results, see Info node `(elisp)Swapping Text'.  */)
>    (Lisp_Object buffer)
>  {
>    struct buffer *other_buffer;
> -- 
> 2.8.0

Thanks, looks good.