master 7b82584 1/2: Improve documentation of new behavior of 'M-y'

[Eli Zaretskii]

branch: master
commit 7b82584c694504996cc3ce302d37edc922c1eb83
Author: Eli Zaretskii <eliz@gnu.org>
Commit: Eli Zaretskii <eliz@gnu.org>

    Improve documentation of new behavior of 'M-y'
    
    * 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.
---
 doc/emacs/killing.texi | 64 ++++++++++++++++++++++++++++++--------------------
 doc/emacs/search.texi  | 12 ++++------
 doc/lispref/text.texi  | 33 ++++++++++++++++----------
 etc/NEWS               | 13 +++++-----
 lisp/minibuffer.el     |  6 +++--
 lisp/simple.el         | 60 ++++++++++++++++++++++++++++------------------
 6 files changed, 111 insertions(+), 77 deletions(-)

diff --git a/doc/emacs/killing.texi b/doc/emacs/killing.texi
index 8434040..89de9af 100644
--- a/doc/emacs/killing.texi
+++ b/doc/emacs/killing.texi
@@ -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}.
-
-  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.
+or another @kbd{M-y}.  (If @kbd{M-y} is invoked after some other
+command, it works differently, see below.)
+
+  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
diff --git a/doc/emacs/search.texi b/doc/emacs/search.texi
index 38430a2..e6b066e 100644
--- a/doc/emacs/search.texi
+++ b/doc/emacs/search.texi
@@ -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)}
diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
index 44c4b90..c90a959 100644
--- a/doc/lispref/text.texi
+++ b/doc/lispref/text.texi
@@ -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
diff --git a/etc/NEWS b/etc/NEWS
index 18831e0..a619df1 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -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'.
diff --git a/lisp/minibuffer.el b/lisp/minibuffer.el
index caf06ec..d6a6f9a 100644
--- a/lisp/minibuffer.el
+++ b/lisp/minibuffer.el
@@ -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)))
diff --git a/lisp/simple.el b/lisp/simple.el
index fc3a4bd..3f211bf 100644
--- a/lisp/simple.el
+++ b/lisp/simple.el
@@ -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.
-
-With \\[universal-argument] as argument, put point at beginning,
-and mark at end, like `yank' does."
+  "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.
+
+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)