bug#4605: Description of `buffer-swap-text' is vague and inadequate.

bug#4605: Description of `buffer-swap-text' is vague and inadequate.

[Alan Mackenzie]

Hi, Stefan, Hi, Emacs!

The Elisp manual page "Swapping Text", says that `buffer-swap-text'
"swaps text between the current buffer and its argument BUFFER."

This tells me nothing.  I'd have to read the source (or maybe try it
out) to find out what this function does.

What does "swap" mean here?  How much text is "swapped".  What does
"between" mean?

A naive guess would suggest this command takes a bit of text out of
buffer A and dumps it into buffer B, simultaneously moving a bit of B
into A.

There is also no entry in .../src/ChangeLog (or ChangeLog.10, ...)
marking the introduction of this command.

-- 
Alan Mackenzie (Nuremberg, Germany).

bug#4608: Description of `buffer-swap-text' is vague and inadequate.

[Stefan Monnier]

> The Elisp manual page "Swapping Text", says that `buffer-swap-text'
> "swaps text between the current buffer and its argument BUFFER."

> This tells me nothing.  I'd have to read the source (or maybe try it
> out) to find out what this function does.

> What does "swap" mean here?  How much text is "swapped".  What does
> "between" mean?

> A naive guess would suggest this command takes a bit of text out of
> buffer A and dumps it into buffer B, simultaneously moving a bit of B
> into A.

No, it swaps the whole freakin' text, including text-properties,
markers, and overlays.  So at the end, buffer A has buffer B's text and
vice versa.

> There is also no entry in .../src/ChangeLog (or ChangeLog.10, ...)
> marking the introduction of this command.

grep disagrees:

   % grep buffer.swap.text src/ChangeLog*
   src/ChangeLog:  * buffer.c (Fbuffer_swap_text): Use POINTER_TYPE.
   src/ChangeLog:  * buffer.c (Fbuffer_swap_text) [REL_ALLOC]: Reset ralloc's internal
   src/ChangeLog:  * buffer.c (Fbuffer_swap_text): Signal error if swapping a dead buffer.
   src/ChangeLog:  * buffer.c (Fbuffer_swap_text): Remove redundant marker manipulation.
   src/ChangeLog:  * buffer.c (Fbuffer_swap_text): Reset window->point markers.
   src/ChangeLog:  * buffer.c (Fbuffer_swap_text): New function.
   % 


-- Stefan

bug#4608: Description of `buffer-swap-text' is vague and inadequate.

[Juanma Barranquero]

On Thu, Oct 1, 2009 at 15:56, Stefan Monnier <monnier@iro.umontreal.ca> wrote:

[Stefan, you've duplicated the bug because of Cc: bug-gnu-emacs@gnu.org]

> grep disagrees:
>
>   % grep buffer.swap.text src/ChangeLog*
>   src/ChangeLog:  * buffer.c (Fbuffer_swap_text): Use POINTER_TYPE.
>   src/ChangeLog:  * buffer.c (Fbuffer_swap_text) [REL_ALLOC]: Reset ralloc's internal
>   src/ChangeLog:  * buffer.c (Fbuffer_swap_text): Signal error if swapping a dead buffer.
>   src/ChangeLog:  * buffer.c (Fbuffer_swap_text): Remove redundant marker manipulation.
>   src/ChangeLog:  * buffer.c (Fbuffer_swap_text): Reset window->point markers.
>   src/ChangeLog:  * buffer.c (Fbuffer_swap_text): New function.
>   %

Or, using our own tool:

C:\emacs\src> grep-changelog --text=buffer.swap.text --reverse

2008-02-25  Stefan Monnier  <monnier@iro.umontreal.ca>

        * buffer.c (Fbuffer_swap_text): New function.
        (syms_of_buffer): Defsubr it.

2008-09-07  Stefan Monnier  <monnier@iro.umontreal.ca>

        * buffer.c (Fbuffer_swap_text): Reset window->point markers.

2008-11-21  Stefan Monnier  <monnier@iro.umontreal.ca>

        * buffer.c (Fbuffer_swap_text): Remove redundant marker manipulation.
        Fix copy/paste typo.  Add checks.

2008-12-09  Chong Yidong  <cyd@stupidchicken.com>

        * buffer.c (Fbuffer_swap_text): Signal error if swapping a dead buffer.

2008-12-24  Jason Rumney  <jasonr@gnu.org>

        * buffer.c (Fbuffer_swap_text) [REL_ALLOC]: Reset ralloc's internal
        record of what points where.  (Bug#716)

2008-12-25  Jason Rumney  <jasonr@gnu.org>

        * buffer.c (Fbuffer_swap_text): Use POINTER_TYPE.


    Juanma

bug#4617: Description of `buffer-swap-text' is vague and inadequate.

[Alan Mackenzie]

Hi, Stefan,

On Thu, Oct 01, 2009 at 09:56:00AM -0400, Stefan Monnier wrote:
> > The Elisp manual page "Swapping Text", says that `buffer-swap-text'
> > "swaps text between the current buffer and its argument BUFFER."

> > This tells me nothing.  I'd have to read the source (or maybe try it
> > out) to find out what this function does.

> > What does "swap" mean here?  How much text is "swapped".  What does
> > "between" mean?

> > A naive guess would suggest this command takes a bit of text out of
> > buffer A and dumps it into buffer B, simultaneously moving a bit of B
> > into A.

> No, it swaps the whole freakin' text, including text-properties,
> markers, and overlays.  So at the end, buffer A has buffer B's text and
> vice versa.

Ah.  OK, got you!  I'll patch in a "the" sometime, to make it "swaps THE
text between .....".  But overlays?  Overlays aren't part of the text
(thought text-properties are).  But this has probably been talked through
anyway, some long time ago.

Sounds like a brilliant idea, though - you could use this for several
major modes in the same "buffer", somehow.  

> > There is also no entry in .../src/ChangeLog (or ChangeLog.10, ...)
> > marking the introduction of this command.

> grep disagrees:

Apologies.  I was grepping for "buffer-swap-text".

> -- Stefan

-- 
Alan Mackenzie (Nuremberg, Germany).