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

[npostavs]

Dmitry Gutov <dgutov@yandex.ru> writes:

> On 07/11/2016 09:50 PM, Markus Rost wrote:
>>> please push to emacs-25.

I'm thinking also to tweak the wording a bit to make it clear that the
buffer change happens at the end of the save-excursion, not when
buffer-swap-text is called.

>From 3c66c6f163e72da7b8f5d40dab7cb2655faddf47 Mon Sep 17 00:00:00 2001
From: Noam Postavsky <npostavs@gmail.com>
Date: Sun, 10 Jul 2016 21:52:23 -0400
Subject: [PATCH v2] 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 | 5 +++++
 src/buffer.c             | 4 +++-
 2 files changed, 8 insertions(+), 1 deletion(-)

diff --git a/doc/lispref/buffers.texi b/doc/lispref/buffers.texi
index 1f7f263..e10c2b3 100644
--- 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:} If called from within @code{save-excursion}, this
+function will set the saved buffer to @var{buffer}, 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


>>
>> Oh, I am still using
>>
>> GNU Emacs 22.3.5 (x86_64-unknown-linux-gnu, GTK+ Version 2.24.23) of 
>> 2015-11-14 on euclid
>
> Sorry, you'll have to upgrade to Emacs 25 when it comes out, to see
> this fixed. Emacs 24 and earlier are not supported anymore.

To be clear, the particular behaviour that prompted this bug report will
not be fixed/changed, I'm just documenting it (obviously there are a lot
of other changes and improvements between 22.3 and 25).