GNU bug report logs - #6785
Documentation: `kill-region' needs to be re-filled in at least two places

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 6785 in the body.
You can then email your comments to 6785 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: MON KEY <monkey <at> sandpframing.com>
To: bug-gnu-emacs <at> gnu.org
Subject: Documentation: `kill-region' needs to be re-filled in at least two 
	places
Date: Tue, 3 Aug 2010 14:29:30 -0400

Documentation: `kill-region' needs to be re-filled in at least two places.

,---- (documentation 'kill-region)
|
| {...}
|
| This is the primitive for programs to kill text (as opposed to deleting it).
| Supply two arguments, character positions indicating the stretch of text
|  to be killed.
|
| {...}
|
`----


" to be killed."
 ^
This needs to be refilled.

As does this:

,----
| {...}
|
| 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.
|
`----

after:

" {...} also a kill command,"

and before:

"the text killed this {...}"


Problem is current through Bzr-100920.

--
/s_P\

Message #8 received at 6785 <at> debbugs.gnu.org (full text, mbox):

From: Juanma Barranquero <lekktu <at> gmail.com>
To: MON KEY <monkey <at> sandpframing.com>
Cc: 6785 <at> debbugs.gnu.org
Subject: Re: bug#6785: Documentation: `kill-region' needs to be re-filled in 
	at least two places
Date: Tue, 3 Aug 2010 23:01:54 +0200

On Tue, Aug 3, 2010 at 20:29, MON KEY <monkey <at> sandpframing.com> wrote:

> " to be killed."
>  ^
> This needs to be refilled.

OK.

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

> after:
>
> " {...} also a kill command,"
>
> and before:
>
> "the text killed this {...}"

 Most docstrings aren't exactly filled up to the fill-column, but
depending on legibility, punctuation, etc.

    Juanma

Message #11 received at 6785 <at> debbugs.gnu.org (full text, mbox):

From: MON KEY <monkey <at> sandpframing.com>
To: Juanma Barranquero <lekktu <at> gmail.com>
Cc: 6787 <at> debbugs.gnu.org, 6785 <at> debbugs.gnu.org
Subject: Re: bug#6785: Documentation: `kill-region' needs to be re-filled in 
	at least two places
Date: Wed, 4 Aug 2010 15:16:24 -0400

On Tue, Aug 3, 2010 at 6:07 PM, Juanma Barranquero <lekktu <at> gmail.com> wrote:
> On Tue, Aug 3, 2010 at 23:17, MON KEY <monkey <at> sandpframing.com> wrote:
>
>> In general, that doc prob. needs some attention w/re formatting,
>> and adding  some more "\n" would go a long way.
>
> Don't hesitate to send a patch :-)

OK. Following is my attempt at tweaking that doc.
Note, I took the liberty of also adjusting for the problem I described in
bug#6787 http://debbugs.gnu.org/cgi/bugreport.cgi?bug=6787

"Kill (\"cut\") buffer text in region between point and mark.
This removes the text from the buffer saving it on the kill ring.
Use the command \\[yank] to retrieve the killed text on the kill ring.
\(To save the region without killing it, use \\[kill-ring-save].)

Commands which call this function are \"kill commands\".
When the most recent previous command was a kill command, the text to be
killed by the current kill command can be appended to the most recently
killed text on the kill ring such that the killed text of each of the two
kill commnads are combined into one entry at the beginning of the kill ring.
To append the killed region to the last killed text, use \\[append-next-kill]
before \\[kill-region].

When invoked in a read-only buffer Emacs will ding and does not remove the
text from the buffer, however the text of the region is placed on kill ring.
This means a region killing command will \"copy\" text in read-only buffers
even when it does not appear to be killed (\"cut\") in the buffer.

This function is intended as the primary interface for lisp programs which
kill text (as opposed to deleting text as if by `delete-region').

When called from a program the arguments BEG and END are buffer positions
indicating the stretch of text to be killed.

When the optional third arg YANK-HANDLER is non-nil, the killed text has the
yank-handler property set non-nil. Setting this property non-nil affects
wether yank commands will apply `yank-excluded-properties' as described in
the doc string for `insert-for-yank-1', which see."

>     Juanma
>

--
/s_P\

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.