Advertise using `kill-new' and `kill-append' in Lisp programs.

* lisp/simple.el (copy-region-as-kill, kill-ring-save): Advertise using
`kill-new' and `kill-append' in Lisp programs.

4 files changed, 16 insertions, 2 deletions

diff --git a/doc/emacs/killing.texi b/doc/emacs/killing.texi
index 051bfe3eae8..cb33327faa1 100644
--- a/doc/emacs/killing.texi
+++ b/doc/emacs/killing.texi
@@ -109,6 +109,8 @@ number of characters.  If the numeric argument is omitted or one, they
 delete all the text in the region if it is active (@pxref{Using
 Region}).
 
+@c FIXME: `cycle-spacing' should be documented, too.  (Maybe not in
+@c this node, tho.)  --xfq
 @kindex M-\
 @findex delete-horizontal-space
 @kindex M-SPC
diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
index a1b78b213b1..b97faf54752 100644
--- a/doc/lispref/text.texi
+++ b/doc/lispref/text.texi
@@ -779,6 +779,7 @@ is deleted.  If point is on a nonblank line, the command deletes all
 blank lines immediately following it.
 
 A blank line is defined as a line containing only tabs and spaces.
+@c and the Newline character?
 
 @code{delete-blank-lines} returns @code{nil}.
 @end deffn
diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index 5edb462adb5..39279242d37 100644
--- a/lisp/ChangeLog
+++ b/lisp/ChangeLog
@@ -23,6 +23,11 @@
         New functions.
         (image-animate-timeout): Respect image :speed property.
 
+2013-08-16  Xue Fuqiao  <xfq.free@gmail.com>
+
+        * simple.el (copy-region-as-kill, kill-ring-save): Advertise using
+        `kill-new' and `kill-append' in Lisp programs.
+
 2013-08-15  Stefan Monnier  <monnier@iro.umontreal.ca>
 
         * emacs-lisp/debug.el (debugger-setup-buffer): Put point on the
diff --git a/lisp/simple.el b/lisp/simple.el
index 6825c41becc..bad0449d815 100644
--- a/lisp/simple.el
+++ b/lisp/simple.el
@@ -3622,7 +3622,10 @@ In Transient Mark mode, deactivate the mark.
 If `interprogram-cut-function' is non-nil, also save the text for a window
 system cut and paste.
 
-This command's old key binding has been given to `kill-ring-save'."
+This command's old key binding has been given to `kill-ring-save'.
+
+Do not use this function in Lisp programs, use `kill-new' or
+`kill-append' instead."
   (interactive "r")
   (if (eq last-command 'kill-region)
       (kill-append (filter-buffer-substring beg end) (< end beg))
@@ -3640,7 +3643,10 @@ If you want to append the killed line to the last killed text,
 use \\[append-next-kill] before \\[kill-ring-save].
 
 This command is similar to `copy-region-as-kill', except that it gives
-visual feedback indicating the extent of the region being copied."
+visual feedback indicating the extent of the region being copied.
+
+Do not use this function in Lisp programs, use `kill-new' or
+`kill-append' instead."
   (interactive "r")
   (copy-region-as-kill beg end)
   ;; This use of called-interactively-p is correct because the code it