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

Improve kill-related documentation (bug#31209)

Browse source 
* 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.
This commit is contained in:
Basil L. Contovounesios 2018-04-18 18:35:38 +01:00 • committed by Noam Postavsky
parent 0b432248d8
commit 343d70b10e
2 changed files with 26 additions and 19 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

14
doc/lispref/text.texi
View file

@ -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

31
lisp/simple.el
View file

@ -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)