jed-common 1:0.99.19-2.1 / usr / share / jed / doc / txt / yankpop.txt

This document discusses Jed's implementation of yank-pop.

Briefly, yank-pop allows one to use multiple paste buffers in a convenient
way.  Jed's implementation provides 16 such pastebuffers.  The file,
jed/lib/yankpop.sl provides the interface and in particular the following
functions:

     yp_yank                        Ctrl-Y
     yp_yank_pop                    ESC Y
     yp_bkill_word                  ESC DEL
     yp_kill_word                   ESC d
     yp_kill_line                   Ctrl-K
     yp_kill_region                 Ctrl-W
     yp_copy_region_as_kill         ESC W
     
which are meant to be bound to keys.  The second column shows the default
emacs bindings.

It should be obvious from the names of these functions that the can be
grouped into two categories: those that ``kill'' and those that ``yank''.
Associated with these two groups are two active pastebuffers--- one where
text is ``killed'' into and one where previously killed text is ``yanked''
from.  Most of the time these two pastebuffers are equivalent.  That is, a
kill followed by a subsequent yank will result in the yank using the
pastebuffer that was used for the kill.  In fact, whenever something is
killed, the yank pastebuffer automatically is set to the one used for the
kill.  Only the `yp_yank_pop' function can change the active yank
pastebuffer to something different from the active kill one.

The kill functions put what they have killed into the currently active
pastebuffer.  If the last key sequence entered from the keyboard did not
invoke one of the kill functions, the currently active pastebuffer becomes
the next one in the ring of pastebuffers and the killed text is placed in
it.  Otherwise the last key sequence invoked one of the kill functions and
the text from the kill will be appended to the text from the last kill. It
is important to note that the act of killing something sets the pastebuffer
for a subsequent yank to the pastebuffer used for the kill.

   {Terminology: By a ring of pastebuffers, it is meant that when the all
    the pastebuffers become used, the contents of the oldest one will be
    discarded and that one will become the active one.}

This sounds more complex than it really is.  Consider the act of moving
somewhere and pressing the sequence `ESC d' three times in a row to execute
the `yp_kill_word' function.  The first `ESC d' sequence results in deleting
a word and placing it in a new currently active pastebuffer since the
previous key sequence was not a kill sequence.  The other two `ESC d'
sequences follow a kill sequence, namely, the first `ESC d'.  This means
that the next two words will be appended to the first one that was killed.
So, if the `yp_yank' function is invoked via Ctrl-Y, the three killed words
will be pasted back as if they had been killed together.

There are two yank functions: `yp_yank' and `yp_yank_pop'.  The `yp_yank'
function simply pastes text into the buffer from the the current pastebuffer
for yanking.  One the other hand, the `yp_yank_pop' function must immediately
follow the `yp_yank' function or another `yp_yank_pop'.  It will delete (not
kill) the previously pasted text with the text in the pastebuffer that
comes immediately before the current yank pastebuffer in the ring of
pastebuffers.  The current yank pastebuffer will then become the one
selected by `yp_yank_pop'.  Simply stated, the `yp_yank_pop' allows the user
to cycle through the set of pastebuffers.

Again, this is best illustrated with an example.  We will continue with the
previous one.  After killing the three words as previously described,
consider moving to the top of the buffer and deleting the top line by
pressing Ctrl-K to invoke the `yp_kill_line' function.  In doing so, we are
left with two used pastebuffers: the most recent contains the line killed at
the top of the buffer and the other contains the three words that were
killed earlier.  Now move somewhere else and press Ctrl-Y to invoke the
function `yp_yank'.  This results in the pasting of the line killed at the
top of the buffer at the current position.  Now, press `ESC y' to invoke the
`yp_yank_pop' function.  This replaces the the text that was just pasted
with the three words that were kill earlier.   Continue to press the `ESC y'
key sequence.  This will result in cycling between the two pastebuffers and
replacing the text that was most recently pasted with the text from the
other pastebuffer.   The last pastebuffer for the paste will become the
active one for future yanks until the next kill.