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

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

[MON KEY]

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\

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

[Juanma Barranquero]

On Tue, Aug 3, 2010 at 20:29, MON KEY <monkey@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

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

[MON KEY]

On Tue, Aug 3, 2010 at 6:07 PM, Juanma Barranquero <lekktu@gmail.com> wrote:
> On Tue, Aug 3, 2010 at 23:17, MON KEY <monkey@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\