procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Improve documentation of kill commands

Browse source 
* 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)
This commit is contained in:
Eli Zaretskii 2015-12-07 18:20:43 +02:00
parent eb85d55cea
commit 86130adf1e
2 changed files with 68 additions and 29 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

42
doc/lispref/text.texi
View file

@ -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.
@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.
@ -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
@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

55
lisp/simple.el
View file

@ -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."