Commit 343d70b1 authored by Basil L. Contovounesios's avatar Basil L. Contovounesios Committed by Noam Postavsky

Improve kill-related documentation (bug#31209)

* doc/lispref/text.texi (Low-Level Kill Ring): Fix typo under
current-kill.  Mention interprogram-paste-function under kill-new
and kill-append.
* lisp/simple.el (save-interprogram-paste-before-kill, kill-new)
(kill-append-merge-undo, kill-append): Touch-up docstrings.
parent 0b432248
......@@ -1142,7 +1142,7 @@ If @var{n} is zero, indicating a request for the latest kill,
@code{current-kill} calls the value of
@code{interprogram-paste-function} (documented below) before
consulting the kill ring. If that value is a function and calling it
returns a string or a list of several string, @code{current-kill}
returns a string or a list of several strings, @code{current-kill}
pushes the strings onto the kill ring and returns the first string.
It also sets the yanking pointer to point to the kill-ring entry of
the first string returned by @code{interprogram-paste-function},
......@@ -1155,8 +1155,10 @@ move the yanking pointer.
@defun kill-new string &optional replace
This function pushes the text @var{string} onto the kill ring and
makes the yanking pointer point to it. It discards the oldest entry
if appropriate. It also invokes the value of
@code{interprogram-cut-function} (see below).
if appropriate. It also invokes the values of
@code{interprogram-paste-function} (subject to
the user option @code{save-interprogram-paste-before-kill})
and @code{interprogram-cut-function} (see below).
If @var{replace} is non-@code{nil}, then @code{kill-new} replaces the
first element of the kill ring with @var{string}, rather than pushing
......@@ -1168,8 +1170,10 @@ This function appends the text @var{string} to the first entry in the
kill ring and makes the yanking pointer point to the combined entry.
Normally @var{string} goes at the end of the entry, but if
@var{before-p} is non-@code{nil}, it goes at the beginning. This
function also invokes the value of @code{interprogram-cut-function}
(see below).
function calls @code{kill-new} as a subroutine, thus causing the
values of @code{interprogram-cut-function} and possibly
@code{interprogram-paste-function} (see below) to be invoked by
extension.
@end defun
@defvar interprogram-paste-function
......
......@@ -4319,12 +4319,11 @@ ring directly.")
"The tail of the kill ring whose car is the last thing yanked.")
(defcustom save-interprogram-paste-before-kill nil
"Save clipboard strings into kill ring before replacing them.
When one selects something in another program to paste it into Emacs,
but kills something in Emacs before actually pasting it,
this selection is gone unless this variable is non-nil,
in which case the other program's selection is saved in the `kill-ring'
before the Emacs kill and one can still paste it using \\[yank] \\[yank-pop]."
"Save existing clipboard text into kill ring before replacing it.
A non-nil value ensures that Emacs kill operations do not
irrevocably overwrite existing clipboard text by saving it to the
`kill-ring' prior to the kill. Such text can subsequently be
retrieved via \\[yank] \\[yank-pop]]."
:type 'boolean
:group 'killing
:version "23.2")
......@@ -4344,7 +4343,7 @@ Optional second argument REPLACE non-nil means that STRING will replace
the front of the kill ring, rather than being added to the list.
When `save-interprogram-paste-before-kill' and `interprogram-paste-function'
are non-nil, saves the interprogram paste string(s) into `kill-ring' before
are non-nil, save the interprogram paste string(s) into `kill-ring' before
STRING.
When the yank handler has a non-nil PARAM element, the original STRING
......@@ -4379,20 +4378,24 @@ argument should still be a \"useful\" string for such uses."
(if interprogram-cut-function
(funcall interprogram-cut-function string)))
;; It has been argued that this should work similar to `self-insert-command'
;; which merges insertions in undo-list in groups of 20 (hard-coded in cmds.c).
;; It has been argued that this should work like `self-insert-command'
;; which merges insertions in `buffer-undo-list' in groups of 20
;; (hard-coded in `undo-auto-amalgamate').
(defcustom kill-append-merge-undo nil
"Whether appending to kill ring also makes \\[undo] restore both pieces of text simultaneously."
"Amalgamate appending kills with the last kill for undo.
When non-nil, appending or prepending text to the last kill makes
\\[undo] restore both pieces of text simultaneously."
:type 'boolean
:group 'killing
:version "25.1")
(defun kill-append (string before-p)
"Append STRING to the end of the latest kill in the kill ring.
If BEFORE-P is non-nil, prepend STRING to the kill.
Also removes the last undo boundary in the current buffer,
depending on `kill-append-merge-undo'.
If `interprogram-cut-function' is set, pass the resulting kill to it."
If BEFORE-P is non-nil, prepend STRING to the kill instead.
If `interprogram-cut-function' is non-nil, call it with the
resulting kill.
If `kill-append-merge-undo' is non-nil, remove the last undo
boundary in the current buffer."
(let* ((cur (car kill-ring)))
(kill-new (if before-p (concat string cur) (concat cur string))
(or (= (length cur) 0)
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment