>From 15d1a619039254df5ba1a43aa97e011bdb40175c Mon Sep 17 00:00:00 2001 From: "Basil L. Contovounesios" Date: Wed, 18 Apr 2018 18:35:38 +0100 Subject: [PATCH 2/2] 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. --- doc/lispref/text.texi | 14 +++++++++----- lisp/simple.el | 31 +++++++++++++++++-------------- 2 files changed, 26 insertions(+), 19 deletions(-) diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi index 8cb6cf6242..da09b4ae1c 100644 --- a/doc/lispref/text.texi +++ b/doc/lispref/text.texi @@ -1143,7 +1143,7 @@ Low-Level Kill Ring @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}, @@ -1156,8 +1156,10 @@ Low-Level Kill Ring @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 @@ -1169,8 +1171,10 @@ Low-Level Kill Ring 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 diff --git a/lisp/simple.el b/lisp/simple.el index 15c4a92804..8d04471a63 100644 --- a/lisp/simple.el +++ b/lisp/simple.el @@ -4341,12 +4341,11 @@ kill-ring-yank-pointer "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") @@ -4366,7 +4365,7 @@ kill-new 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 @@ -4402,20 +4401,24 @@ kill-new (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) -- 2.17.0