From: Kim F. Storm <storm@cua.dk>
Date: Mon, 27 Jan 2003 21:44:48 +0000 (+0000)
Subject: (kill-new): Improve doc string for yank-handler.
X-Git-Tag: ttn-vms-21-2-B4~11440
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=2a262563661b44a04d25472fe82c843e2fa53074;p=emacs.git

(kill-new): Improve doc string for yank-handler.
Signal args-out-of-range error if yank-handler is specified for
an empty string.
---

diff --git a/lisp/simple.el b/lisp/simple.el
index b4d1d609bc7..ac531e9674c 100644
--- a/lisp/simple.el
+++ b/lisp/simple.el
@@ -1764,13 +1764,23 @@ Optional second argument REPLACE non-nil means that STRING will replace
 the front of the kill ring, rather than being added to the list.
 
 Optional third arguments YANK-HANDLER controls how the STRING is later
-inserted into a buffer; see `insert-for-yank' for details."
-  (when (> (length string) 0)
-    (if yank-handler 
-	(put-text-property 0 1 'yank-handler yank-handler string)
-      (remove-text-properties 0 1 '(yank-handler nil) string)))
-  (and (fboundp 'menu-bar-update-yank-menu)
-       (menu-bar-update-yank-menu string (and replace (car kill-ring))))
+inserted into a buffer; see `insert-for-yank' for details.  
+When a yank handler is specified, STRING must be non-empty (the yank
+handler is stored as a `yank-handler'text property on STRING).
+
+When the yank handler has a non-nil PARAM element, the original STRING
+argument is not used by `insert-for-yank'.  However, since Lisp code
+may access and use elements from the kill-ring directly, the STRING
+argument should still be a \"useful\" string for such uses."
+  (if (> (length string) 0)
+      (if yank-handler 
+	  (put-text-property 0 1 'yank-handler yank-handler string)
+	(remove-list-of-text-properties 0 1 '(yank-handler) string))
+    (if yank-handler
+	(signal 'args-out-of-range 
+		(list string "yank-handler specified for empty string"))))
+  (if (fboundp 'menu-bar-update-yank-menu)
+      (menu-bar-update-yank-menu string (and replace (car kill-ring))))
   (if (and replace kill-ring)
       (setcar kill-ring string)
     (setq kill-ring (cons string kill-ring))