@code{last-command}) whether the previous command was a kill command,
and if so appends the killed text to the most recent entry.
-@deffn Command kill-region start end
-This function kills the text in the region defined by @var{start} and
-@var{end}. The text is deleted but saved in the kill ring, along with
-its text properties. The value is always @code{nil}.
+@cindex 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.
+
+@deffn Command kill-region start end &optional region
+This function kills the stretch of text between @var{start} and
+@var{end}; but if the optional argument @var{region} is
+non-@code{nil}, 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
+@code{nil}.
In an interactive call, @var{start} and @var{end} are point and
-the mark.
+the mark, and @var{region} is always non-@code{nil}, 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.
updating the kill ring but not changing the buffer.
@end defopt
-@deffn 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}.
+@deffn Command copy-region-as-kill start end &optional region
+This function saves the stretch of text between @var{start} and
+@var{end} on the kill ring (including text properties), but does not
+delete the text from the buffer. However, if the optional argument
+@var{region} is non-@code{nil}, the function ignores @var{start} and
+@var{end}, and saves the current region instead. It always returns
+@code{nil}.
+
+In an interactive call, @var{start} and @var{end} are point and
+the mark, and @var{region} is always non-@code{nil}, 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.
-
-@c FIXME Why is it better? Why isn't copy-region-as-kill obsolete then?
-@c Why is it used in many places in Emacs?
-In Lisp programs, it is better to use @code{kill-new} or
-@code{kill-append} instead of this command. @xref{Low-Level Kill Ring}.
@end deffn
@node Yanking
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)
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."
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)
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))
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
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."