procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Improve documentation of new behavior of 'M-y'

Browse source 
* lisp/minibuffer.el (minibuffer-local-map): Switch the order of
'\r' and '\n' bindings.
* lisp/simple.el (yank-pop, read-from-kill-ring)
(yank-from-kill-ring): Doc fixes.

* doc/emacs/search.texi (Isearch Yank):
* doc/emacs/killing.texi (Yanking): Improve the description of the
new functionality of 'M-y'.
* doc/lispref/text.texi (Yank Commands): Remove inaccurate
description of 'M-y' in Isearch.

* etc/NEWS: Improve the wording of 'M-y' entry.
This commit is contained in:
Eli Zaretskii 2021-05-17 15:17:57 +03:00
parent e761e12498
commit 7b82584c69
6 changed files with 109 additions and 75 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

62
doc/emacs/killing.texi
View file

@ -289,8 +289,9 @@ way to move or copy text is to kill it and then yank it elsewhere.
@item C-y
Yank the last kill into the buffer, at point (@code{yank}).
@item M-y
Replace the text just yanked with an earlier batch of killed text
(@code{yank-pop}). @xref{Earlier Kills}.
Either replace the text just yanked with an earlier batch of killed
text (@code{yank-pop}), or allow to select from the list of
previously-killed batches of text. @xref{Earlier Kills}.
@item C-M-w
Cause the following command, if it is a kill command, to append to the
previous kill (@code{append-next-kill}). @xref{Appending Kills}.
@ -354,7 +355,7 @@ with @kbd{C-h v kill-ring}.
@kbd{C-y} to yank text that is no longer the most recent kill. This
is useful if you remember which kill ring entry you want. If you
don't, you can use the @kbd{M-y} (@code{yank-pop}) command to cycle
through the possibilities.
through the possibilities or to select one of the earlier kills.
@kindex M-y
@findex yank-pop
@ -363,26 +364,29 @@ that was yanked and replaces it with the text from an earlier kill.
So, to recover the text of the next-to-the-last kill, first use
@kbd{C-y} to yank the last kill, and then use @kbd{M-y} to replace it
with the previous kill. This works only after a @kbd{C-y}
or another @kbd{M-y}.
or another @kbd{M-y}. (If @kbd{M-y} is invoked after some other
command, it works differently, see below.)
You can understand @kbd{M-y} in terms of a last-yank pointer which
points at an entry in the kill ring. Each time you kill, the last-yank
pointer moves to the newly made entry at the front of the ring.
@kbd{C-y} yanks the entry which the last-yank pointer points to.
@kbd{M-y} moves the last-yank pointer to a different entry, and the
text in the buffer changes to match. Enough @kbd{M-y} commands can move
the pointer to any entry in the ring, so you can get any entry into the
buffer. Eventually the pointer reaches the end of the ring; the next
@kbd{M-y} loops back around to the first entry again.
You can understand this operation mode of @kbd{M-y} in terms of a
last-yank pointer which points at an entry in the kill ring. Each
time you kill, the last-yank pointer moves to the newly made entry at
the front of the ring. @kbd{C-y} yanks the entry which the last-yank
pointer points to. @kbd{M-y} moves the last-yank pointer to a
different entry, and the text in the buffer changes to match. Enough
@kbd{M-y} commands can move the pointer to any entry in the ring, so
you can get any entry into the buffer. Eventually the pointer reaches
the end of the ring; the next @kbd{M-y} loops back around to the first
entry again.
@kbd{M-y} moves the last-yank pointer around the ring, but it does
not change the order of the entries in the ring, which always runs from
the most recent kill at the front to the oldest one still remembered.
@kbd{M-y} can take a numeric argument, which tells it how many entries
to advance the last-yank pointer by. A negative argument moves the
pointer toward the front of the ring; from the front of the ring, it
moves around to the last entry and continues forward from there.
When used after @kbd{C-y} or @kbd{M-y}, @kbd{M-y} can take a numeric
argument, which tells it how many entries to advance the last-yank
pointer by. A negative argument moves the pointer toward the front of
the ring; from the front of the ring, it moves around to the last
entry and continues forward from there.
Once the text you are looking for is brought into the buffer, you can
stop doing @kbd{M-y} commands and it will stay there. It's just a copy
@ -394,14 +398,22 @@ pointer remains at the same place in the kill ring, so repeating
When you call @kbd{C-y} with a numeric argument, that also sets the
last-yank pointer to the entry that it yanks.
Alternatively, when the previous command was not a yank command,
@kbd{M-y} activates the minibuffer where you can browse previous kills
using the minibuffer history commands (@pxref{Minibuffer History}), or
you can use completion commands (@pxref{Completion}) on a list of
previously killed blocks of text from the kill ring. Exiting the
minibuffer will insert the selected text to the buffer. With a plain
prefix argument (@kbd{C-u M-y}), this command leaves the cursor in
front of the inserted text, and sets the mark at the end.
You can also invoke @kbd{M-y} after a command that is not a yank
command. In that case, @kbd{M-y} prompts you in the minibuffer for
one of the previous kills. You can use the minibuffer history
commands (@pxref{Minibuffer History}) to navigate or search through
the entries in the kill ring until you find the one you want to
reinsert. Or you can use completion commands (@pxref{Completion
Commands}) to complete on the list of entries in the kill ring or pop
up the @file{*Completions*} buffer with the candidate entries from
which you can choose. After selecting the kill-ring entry, you can
optionally edit it in the minibuffer. Finally, type @kbd{RET} to exit
the minibuffer and insert the selected text.
When invoked with a plain prefix argument (@kbd{C-u M-y}) after a
command that is not a yank command, @kbd{M-y} leaves the cursor in
front of the inserted text, and sets the mark at the end, like
@kbd{C-y} does.
@node Appending Kills
@subsection Appending Kills

12
doc/emacs/search.texi
View file

@ -301,13 +301,11 @@ from point to the @var{n}th occurrence of the specified character.
@findex isearch-yank-x-selection
Within incremental search, @kbd{C-y} (@code{isearch-yank-kill})
appends the current kill to the search string. @kbd{M-y}
(@code{isearch-yank-pop}), if called after @kbd{C-y}, replaces that
appended text with an earlier kill, similar to the usual @kbd{M-y}
(@code{yank-pop}) command. When @kbd{M-y} is called not after
@kbd{C-y}, then it activates the minibuffer where you can select
a previous kill to append to the search string (@pxref{Earlier
Kills}). Clicking @kbd{mouse-2} in the echo area appends the current
X selection (@pxref{Primary Selection}) to the search string
(@code{isearch-yank-pop}), if called after @kbd{C-y} during
incremental search, replaces that appended text with an earlier kill,
similar to the usual @kbd{M-y} (@code{yank-pop}) command. Clicking
@kbd{mouse-2} in the echo area appends the current X selection
(@pxref{Primary Selection}) to the search string
(@code{isearch-yank-x-selection}).
@kindex C-M-d @r{(Incremental search)}

33
doc/lispref/text.texi
View file

@ -1118,25 +1118,32 @@ one, it rotates the kill ring to place the yanked string at the front.
@end deffn
@deffn Command yank-pop &optional arg
This command replaces the just-yanked entry from the kill ring with a
different entry from the kill ring.
This works only immediately after a @code{yank} or another
@code{yank-pop}. At such a time, the region contains text that was just
inserted by yanking. @code{yank-pop} deletes that text and inserts in
its place a different piece of killed text. It does not add the deleted
text to the kill ring, since it is already in the kill ring somewhere.
It does however rotate the kill ring to place the newly yanked string at
the front.
When invoked immediately after a @code{yank} or another
@code{yank-pop}, this command replaces the just-yanked entry from the
kill ring with a different entry from the kill ring. When this
command is invoked like that, the region contains text that was just
inserted by another yank command. @code{yank-pop} deletes that text
and inserts in its place a different piece of killed text. It does
not add the deleted text to the kill ring, since it is already in the
kill ring somewhere. It does however rotate the kill ring to place
the newly yanked string at the front.
If @var{arg} is @code{nil}, then the replacement text is the previous
element of the kill ring. If @var{arg} is numeric, the replacement is
the @var{arg}th previous kill. If @var{arg} is negative, a more recent
kill is the replacement.
The sequence of kills in the kill ring wraps around, so that after the
oldest one comes the newest one, and before the newest one goes the
oldest.
The sequence of kills in the kill ring wraps around, so if
@code{yank-pop} is invoked repeatedly and reaches the oldest kill, the
one that comes after it is the newest one, and the one before the
newest one is the oldest one.
This command can also be invoked after a command that is not a yank
command. In that case, it prompts in the minibuffer for a kill-ring
entry, with completion, and uses the kill ring elements as the
minibuffer history (@pxref{Minibuffer History}). This allows the user
to interactively select one of the previous kills recorded in the kill
ring.
The return value is always @code{nil}.
@end deffn

13
etc/NEWS
View file

@ -334,12 +334,13 @@ forms, but this command has now been changed to work more like
'eval-defun', and reset the values as specified.
+++
** Standalone 'M-y' uses the minibuffer to complete previous kills.
When 'M-y' is typed not after a yank command, it activates the minibuffer
where you can browse previous kills using the minibuffer history or
completion. In Isearch, you can bind 'C-s M-y' to the command
'isearch-yank-pop' that uses the minibuffer with completion on
previous kills to read a string and append it to the search string.
** Standalone 'M-y' allows interactive selection from previous kills.
'M-y' can now be typed after a command that is not a yank command.
When invoked like that, it prompts in the minibuffer for one of the
previous kills, offering completion and minibuffer-history navigation
through previous kills recorded in the kill ring. A similar feature
in Isearch can be invoked if you bind 'C-s M-y' to the command
'isearch-yank-pop'.
---
** New user options 'copy-region-blink-delay' and 'delete-pair-blink-delay'.

6
lisp/minibuffer.el
View file

@ -2449,8 +2449,10 @@ The completion method is determined by `completion-at-point-functions'."
(define-key map "\C-g" 'abort-minibuffers)
(define-key map "\M-<" 'minibuffer-beginning-of-buffer)
(define-key map "\r" 'exit-minibuffer)
(define-key map "\n" 'exit-minibuffer))
;; Put RET last so that it is shown in doc strings in preference to
;; C-j, when using the \\[exit-minibuffer] notation.
(define-key map "\n" 'exit-minibuffer)
(define-key map "\r" 'exit-minibuffer))
(defvar minibuffer-local-completion-map
(let ((map (make-sparse-keymap)))

58
lisp/simple.el
View file

@ -5566,26 +5566,25 @@ Normally set from the UNDO element of a yank-handler; see `insert-for-yank'.")
"Replace just-yanked stretch of killed text with a different stretch.
The main use of this command is immediately after a `yank' or a
`yank-pop'. At such a time, the region contains a stretch of
reinserted previously-killed text. `yank-pop' deletes that text
and inserts in its place a different stretch of killed text by
traversing the value of the `kill-ring' variable.
reinserted (\"pasted\") previously-killed text. `yank-pop' deletes
that text and inserts in its place a different stretch of killed text
by traversing the value of the `kill-ring' variable and selecting
another kill from there.
With no argument, the previous kill is inserted.
With argument N, insert the Nth previous kill.
If N is negative, this is a more recent kill.
If N is negative, it means to use a more recent kill.
The sequence of kills wraps around, so that after the oldest one
comes the newest one.
The sequence of kills wraps around, so if you keep invoking this command
time after time, and pass the oldest kill, you get the newest one.
You can also invoke this command after a command other than `yank'
or `yank-pop'. This is the same as invoking `yank-from-kill-ring',
including the effect of the prefix argument; see there for the details.
This command honors the `yank-handled-properties' and
`yank-excluded-properties' variables, and the `yank-handler' text
property, in the way that `yank' does.
When this command is called not immediately after a `yank' or a
`yank-pop', then it activates the minibuffer with its completion
and history filled with previously-killed items from the
`kill-ring' variable, and reads a string to yank at point.
See `yank-from-kill-ring' for more details."
property, in the way that `yank' does."
(interactive "p")
(if (not (eq last-command 'yank))
(yank-from-kill-ring (read-from-kill-ring) current-prefix-arg)
@ -5678,7 +5677,7 @@ With ARG, rotate that many kills forward (or backward, if negative)."
(defvar read-from-kill-ring-history)
(defun read-from-kill-ring ()
"Read a string from `kill-ring' using completion and minibuffer history."
"Read a `kill-ring' entry using completion and minibuffer history."
;; `current-kill' updates `kill-ring' with a possible interprogram-paste
(current-kill 0)
(let* ((history-add-new-input nil)
@ -5722,6 +5721,10 @@ With ARG, rotate that many kills forward (or backward, if negative)."
(define-key map "?" nil)
map)))
(completing-read
;; FIXME: This prompt is specific to using this function from
;; yank-related commands, but the function could be used in
;; other contexts. Should the prompt be passed via an
;; argument?
"Yank from kill-ring: "
(lambda (string pred action)
(if (eq action 'metadata)
@ -5732,15 +5735,26 @@ With ARG, rotate that many kills forward (or backward, if negative)."
'read-from-kill-ring-history))))
(defun yank-from-kill-ring (string &optional arg)
"Insert the `kill-ring' item selected from the minibuffer history.
Use minibuffer navigation and search commands to browse the
previously-killed items from the `kill-ring' variable in the
minibuffer history before typing RET to insert the selected item,
or use completion on the elements of `kill-ring'. You can edit
the item in the minibuffer before inserting it.
"Select a stretch of previously killed text and insert (\"paste\") it.
This command allows to choose one of the stretches of text killed
or yanked by previous commands, which are recorded in `kill-ring',
and reinsert the chosen kill at point.
With \\[universal-argument] as argument, put point at beginning,
and mark at end, like `yank' does."
This command prompts for a previously-killed text in the minibuffer.
Use the minibuffer history and search commands, or the minibuffer
completion commands, to select a previously-killed text. In
particular, typing \\<minibuffer-local-completion-map>\\[minibuffer-complete] at the prompt will pop up a buffer showing
all the previously-killed stretches of text from which you can
choose the one you want to reinsert.
Once you select the text you want to reinsert, type \\<minibuffer-local-map>\\[exit-minibuffer] to actually
insert it and exit the minibuffer.
You can also edit the selected text in the minibuffer before
inserting it.
With \\[universal-argument] as argument, this command puts point at
beginning of the inserted text and mark at the end, like `yank' does.
When called from Lisp, insert STRING like `insert-for-yank' does."
(interactive (list (read-from-kill-ring) current-prefix-arg))
(push-mark)
(insert-for-yank string)