[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] master 8cd975c: Document yank behavior in the right place
From: |
Karl Fogel |
Subject: |
[Emacs-diffs] master 8cd975c: Document yank behavior in the right place |
Date: |
Mon, 3 Oct 2016 00:47:33 +0000 (UTC) |
branch: master
commit 8cd975cebd588d5435fa2b333dba6c526e602933
Author: Karl Fogel <address@hidden>
Commit: Karl Fogel <address@hidden>
Document yank behavior in the right place
* lisp/simple.el (yank): Document the handling of the
`yank-handled-properties' and `yank-excluded-properties' variables,
and the `yank-handler' text property.
(yank-pop): Refer to `yank' now (bug#286)
* lisp/subr.el (insert-for-yank): Refer to `yank' now.
(insert-for-yank-1): Refer to `insert-for-yank' now.
See this thread for discussion:
https://lists.gnu.org/archive/html/emacs-devel/2016-09/threads.html#00329
From: Karl Fogel
To: Emacs Devel
Subject: Question about intended behavior of 'insert-for-yank-1'.
Date: Mon, 12 Sep 2016 00:17:14 -0500
Message-ID: <address@hidden>
---
lisp/simple.el | 38 +++++++++++++++++++++++++++++++-------
lisp/subr.el | 32 +++++---------------------------
2 files changed, 36 insertions(+), 34 deletions(-)
diff --git a/lisp/simple.el b/lisp/simple.el
index dd253ae..70bd759 100644
--- a/lisp/simple.el
+++ b/lisp/simple.el
@@ -4775,9 +4775,9 @@ If N is negative, this is a more recent kill.
The sequence of kills wraps around, so that after the oldest one
comes the newest one.
-When this command inserts killed text into the buffer, it honors
-`yank-excluded-properties' and `yank-handler' as described in the
-doc string for `insert-for-yank-1', which see."
+This command honors the `yank-handled-properties' and
+`yank-excluded-properties' variables, and the `yank-handler' text
+property, in the way that `yank' does."
(interactive "*p")
(if (not (eq last-command 'yank))
(user-error "Previous command was not a yank"))
@@ -4810,10 +4810,34 @@ at the end, and set mark at the beginning without
activating it.
With just \\[universal-argument] as argument, put point at beginning, and mark
at end.
With argument N, reinsert the Nth most recent kill.
-When this command inserts text into the buffer, it honors the
-`yank-handled-properties' and `yank-excluded-properties'
-variables, and the `yank-handler' text property. See
-`insert-for-yank-1' for details.
+This command honors the `yank-handled-properties' and
+`yank-excluded-properties' variables, and the `yank-handler' text
+property, as described below.
+
+Properties listed in `yank-handled-properties' are processed,
+then those listed in `yank-excluded-properties' are discarded.
+
+If STRING has a non-nil `yank-handler' property anywhere, the
+normal insert behavior is altered, and instead, for each contiguous
+segment of STRING that has a given value of the `yank-handler'
+property, that value is used as follows:
+
+The value of a `yank-handler' property must be a list of one to four
+elements, of the form (FUNCTION PARAM NOEXCLUDE UNDO).
+FUNCTION, if non-nil, should be a function of one argument (the
+ object to insert); FUNCTION is called instead of `insert'.
+PARAM, if present and non-nil, is passed to FUNCTION (to be handled
+ in whatever way is appropriate; e.g. if FUNCTION is `yank-rectangle',
+ PARAM may be a list of strings to insert as a rectangle). If PARAM
+ is nil, then the current segment of STRING is used.
+If NOEXCLUDE is present and non-nil, the normal removal of
+ `yank-excluded-properties' is not performed; instead FUNCTION is
+ responsible for the removal. This may be necessary if FUNCTION
+ adjusts point before or after inserting the object.
+UNDO, if present and non-nil, should be a function to be called
+ by `yank-pop' to undo the insertion of the current PARAM. It is
+ given two arguments, the start and end of the region. FUNCTION
+ may set `yank-undo-function' to override UNDO.
See also the command `yank-pop' (\\[yank-pop])."
(interactive "*P")
diff --git a/lisp/subr.el b/lisp/subr.el
index e913e37..b143812 100644
--- a/lisp/subr.el
+++ b/lisp/subr.el
@@ -2893,9 +2893,11 @@ remove properties specified by
`yank-excluded-properties'."
(defvar yank-undo-function)
(defun insert-for-yank (string)
- "Call `insert-for-yank-1' repetitively for each `yank-handler' segment.
+ "Insert STRING at point for the `yank' command.
-See `insert-for-yank-1' for more details."
+This function is like `insert', except it honors the variables
+`yank-handled-properties' and `yank-excluded-properties', and the
+`yank-handler' text property, in the way that `yank' does."
(let (to)
(while (setq to (next-single-property-change 0 'yank-handler string))
(insert-for-yank-1 (substring string 0 to))
@@ -2903,31 +2905,7 @@ See `insert-for-yank-1' for more details."
(insert-for-yank-1 string))
(defun insert-for-yank-1 (string)
- "Insert STRING at point for the `yank' command.
-This function is like `insert', except it honors the variables
-`yank-handled-properties' and `yank-excluded-properties', and the
-`yank-handler' text property.
-
-Properties listed in `yank-handled-properties' are processed,
-then those listed in `yank-excluded-properties' are discarded.
-
-If STRING has a non-nil `yank-handler' property on its first
-character, the normal insert behavior is altered. The value of
-the `yank-handler' property must be a list of one to four
-elements, of the form (FUNCTION PARAM NOEXCLUDE UNDO).
-FUNCTION, if non-nil, should be a function of one argument, an
- object to insert; it is called instead of `insert'.
-PARAM, if present and non-nil, replaces STRING as the argument to
- FUNCTION or `insert'; e.g. if FUNCTION is `yank-rectangle', PARAM
- may be a list of strings to insert as a rectangle.
-If NOEXCLUDE is present and non-nil, the normal removal of
- `yank-excluded-properties' is not performed; instead FUNCTION is
- responsible for the removal. This may be necessary if FUNCTION
- adjusts point before or after inserting the object.
-UNDO, if present and non-nil, should be a function to be called
- by `yank-pop' to undo the insertion of the current object. It is
- given two arguments, the start and end of the region. FUNCTION
- may set `yank-undo-function' to override UNDO."
+ "Helper for `insert-for-yank', which see."
(let* ((handler (and (stringp string)
(get-text-property 0 'yank-handler string)))
(param (or (nth 1 handler) string))
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [Emacs-diffs] master 8cd975c: Document yank behavior in the right place,
Karl Fogel <=