bug#6788: Documentation: `delete-region' should explicity mention its parameters.

[MON KEY <monkey@sandpframing.com>]

Documentation: `delete-region' should explicitly mention its parameters.

,----  (documentation 'delete-region)
|
| Delete the text between point and mark.
|
| When called from a program, expects two arguments,
| positions (integers or markers) specifying the stretch to be deleted.
|
`----

`delete-region' can be called-interactively and exists on the menu-bar:

(where-is 'delete-region t)
=> <menu-bar> <edit> <clear> (delete-region)

But doesn't have a default global key-binding (at least w/ Emacs 23.2).

While it is reasonable that the docs indicate the _command_ will:

 "Delete the text between point and mark."

The docstring should also explicitly mention the parameters elsewhere
as delete region can be called programmatically (and probably more
often so than from user input).  The following portion:

 "When called from a program, expects two arguments, positions
  (integers or markers) specifying the stretch to be deleted."

Would be better stated as:

 "When called from a program, the arguments START and END are buffer
  positions (integers or markers) specifying a region to delete."

Additionally, to the extent with which this function is presented as a
user command i.e. as indicated by it's accessibility from the menu-bar
and by the docstring's opening phraseology; I would propose that some
indication be given that the delete-region _command_ does not alter
the kill-ring in a like manner as the `kill-region' command by stating:

 "Delete the text between point and mark.
  This command deletes buffer text without modifying the kill ring."

Providing such an indication would be in keeping with the current
docstring of `kill-region's second sentence:

 "Kill ("cut") text between point and mark.
 This deletes the text from the buffer and saves it in the kill ring."

--
/s_P\