[Emacs-diffs] emacs-25 86130ad: Improve documentation of kill commands

[Eli Zaretskii]

branch: emacs-25
commit 86130adf1ef6ca8e8feabcc0fe966f84bf5d42dc
Author: Eli Zaretskii <address@hidden>
Commit: Eli Zaretskii <address@hidden>

    Improve documentation of kill commands
    
    * lisp/simple.el (region-extract-function, delete-backward-char)
    (delete-forward-char, kill-region, copy-region-as-kill)
    (kill-ring-save): Better document the optional argument REGION in
    the doc strings.  Mention in the doc strings that text put in the
    kill-ring can be filtered by 'filter-buffer-substring'.
    
    * doc/lispref/text.texi (Kill Functions): Mention that functions
    described in this subsection can filter text they put in the
    kill-ring.  Add a cross-reference to "Buffer Contents" and an
    index entry.  Document the optional argument 'region' and its
    effect.
    (Bug#21315)
---
 doc/lispref/text.texi |   42 +++++++++++++++++++++++++------------
 lisp/simple.el        |   55 +++++++++++++++++++++++++++++++++++-------------
 2 files changed, 68 insertions(+), 29 deletions(-)

diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
index dfd85bf..4d26638 100644
--- a/doc/lispref/text.texi
+++ b/doc/lispref/text.texi
@@ -899,13 +899,25 @@ adds it to the most recent element.  It determines 
automatically (using
 @code{last-command}) whether the previous command was a kill command,
 and if so appends the killed text to the most recent entry.
 
address@hidden Command kill-region start end
-This function kills the text in the region defined by @var{start} and
address@hidden  The text is deleted but saved in the kill ring, along with
-its text properties.  The value is always @code{nil}.
address@hidden filtering killed text
+  The commands described below can filter the killed text before they
+save it in the kill ring.  They call @code{filter-buffer-substring}
+(@pxref{Buffer Contents}) to perform the filtering.  By default,
+there's no filtering, but major and minor modes and hook functions can
+set up filtering, so that text saved in the kill ring is different
+from what was in the buffer.
+
address@hidden Command kill-region start end &optional region
+This function kills the stretch of text between @var{start} and
address@hidden; but if the optional argument @var{region} is
address@hidden, it ignores @var{start} and @var{end}, and kills the
+text in the current region instead.  The text is deleted but saved in
+the kill ring, along with its text properties.  The value is always
address@hidden
 
 In an interactive call, @var{start} and @var{end} are point and
-the mark.
+the mark, and @var{region} is always address@hidden, so the command
+always kills the text in the current region.
 
 If the buffer or text is read-only, @code{kill-region} modifies the kill
 ring just the same, then signals an error without modifying the buffer.
@@ -919,18 +931,20 @@ error if the buffer or text is read-only.  Instead, it 
simply returns,
 updating the kill ring but not changing the buffer.
 @end defopt
 
address@hidden Command copy-region-as-kill start end
-This command saves the region defined by @var{start} and @var{end} on
-the kill ring (including text properties), but does not delete the text
-from the buffer.  It returns @code{nil}.
address@hidden Command copy-region-as-kill start end &optional region
+This function saves the stretch of text between @var{start} and
address@hidden on the kill ring (including text properties), but does not
+delete the text from the buffer.  However, if the optional argument
address@hidden is address@hidden, the function ignores @var{start} and
address@hidden, and saves the current region instead.  It always returns
address@hidden
+
+In an interactive call, @var{start} and @var{end} are point and
+the mark, and @var{region} is always address@hidden, so the command
+always saves the text in the current region.
 
 The command does not set @code{this-command} to @code{kill-region}, so a
 subsequent kill command does not append to the same kill ring entry.
-
address@hidden FIXME Why is it better?  Why isn't copy-region-as-kill obsolete 
then?
address@hidden Why is it used in many places in Emacs?
-In Lisp programs, it is better to use @code{kill-new} or
address@hidden instead of this command.  @xref{Low-Level Kill Ring}.
 @end deffn
 
 @node Yanking
diff --git a/lisp/simple.el b/lisp/simple.el
index 2ccb016..17b9c91 100644
--- a/lisp/simple.el
+++ b/lisp/simple.el
@@ -974,7 +974,8 @@ If DELETE is `delete-only', then only delete the region and 
the return value
 is undefined.  If DELETE is nil, just return the content as a string.
 If DELETE is `bounds', then don't delete, but just return the
 boundaries of the region as a list of (START . END) positions.
-If anything else, delete the region and return its content as a string.")
+If anything else, delete the region and return its content as a string,
+after filtering it with `filter-buffer-substring'.")
 
 (defvar region-insert-function
   (lambda (lines)
@@ -999,6 +1000,10 @@ Optional second arg KILLFLAG, if non-nil, means to kill 
(save in
 kill ring) instead of delete.  Interactively, N is the prefix
 arg, and KILLFLAG is set if N is explicitly specified.
 
+When killing, the killed text is filtered by
+`filter-buffer-substring' before it is saved in the kill ring, so
+the actual saved text might be different from what was killed.
+
 In Overwrite mode, single character backward deletion may replace
 tabs with spaces so as to back over columns, unless point is at
 the end of the line."
@@ -1034,7 +1039,11 @@ To disable this, set variable `delete-active-region' to 
nil.
 
 Optional second arg KILLFLAG non-nil means to kill (save in kill
 ring) instead of delete.  Interactively, N is the prefix arg, and
-KILLFLAG is set if N was explicitly specified."
+KILLFLAG is set if N was explicitly specified.
+
+When killing, the killed text is filtered by
+`filter-buffer-substring' before it is saved in the kill ring, so
+the actual saved text might be different from what was killed."
   (declare (interactive-only delete-char))
   (interactive "p\nP")
   (unless (integerp n)
@@ -4249,21 +4258,25 @@ The command \\[yank] can retrieve it from there.
 If you want to append the killed region to the last killed text,
 use \\[append-next-kill] before \\[kill-region].
 
+Any command that calls this function is a \"kill command\".
+If the previous command was also a kill command,
+the text killed this time appends to the text killed last time
+to make one entry in the kill ring.
+
+The killed text is filtered by `filter-buffer-substring' before it is
+saved in the kill ring, so the actual saved text might be different
+from what was killed.
+
 If the buffer is read-only, Emacs will beep and refrain from deleting
 the text, but put the text in the kill ring anyway.  This means that
 you can use the killing commands to copy text from a read-only buffer.
 
 Lisp programs should use this function for killing text.
  (To delete text, use `delete-region'.)
-Supply two arguments, character positions indicating the stretch of text
- to be killed.
-Any command that calls this function is a \"kill command\".
-If the previous command was also a kill command,
-the text killed this time appends to the text killed last time
-to make one entry in the kill ring.
-
-The optional argument REGION if non-nil, indicates that we're not just killing
-some text between BEG and END, but we're killing the region."
+Supply two arguments, character positions BEG and END indicating the
+ stretch of text to be killed.  If the optional argument REGION is
+ non-nil, the function ignores BEG and END, and kills the current
+ region instead."
   ;; Pass mark first, then point, because the order matters when
   ;; calling `kill-append'.
   (interactive (list (mark) (point) 'region))
@@ -4308,8 +4321,14 @@ 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.
 
-The optional argument REGION if non-nil, indicates that we're not just copying
-some text between BEG and END, but we're copying the region.
+The copied text is filtered by `filter-buffer-substring' before it is
+saved in the kill ring, so the actual saved text might be different
+from what was in the buffer.
+
+When called from Lisp, save in the kill ring the stretch of text
+between BEG and END, unless the optional argument REGION is
+non-nil, in which case ignore BEG and END, and save the current
+region instead.
 
 This command's old key binding has been given to `kill-ring-save'."
   ;; Pass mark first, then point, because the order matters when
@@ -4334,8 +4353,14 @@ system cut and paste.
 If you want to append the killed line to the last killed text,
 use \\[append-next-kill] before \\[kill-ring-save].
 
-The optional argument REGION if non-nil, indicates that we're not just copying
-some text between BEG and END, but we're copying the region.
+The copied text is filtered by `filter-buffer-substring' before it is
+saved in the kill ring, so the actual saved text might be different
+from what was in the buffer.
+
+When called from Lisp, save in the kill ring the stretch of text
+between BEG and END, unless the optional argument REGION is
+non-nil, in which case ignore BEG and END, and save the current
+region instead.
 
 This command is similar to `copy-region-as-kill', except that it gives
 visual feedback indicating the extent of the region being copied."