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

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 6788 in the body.
You can then email your comments to 6788 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: `delete-region' should explicity mention its 
	parameters.
Date: Tue, 3 Aug 2010 15:10:55 -0400

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\

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

From: Lars Magne Ingebrigtsen <larsi <at> gnus.org>
To: MON KEY <monkey <at> sandpframing.com>
Cc: 6788 <at> debbugs.gnu.org
Subject: Re: Documentation: `delete-region' should explicity mention its
	parameters.
Date: Thu, 14 Jul 2011 15:41:20 +0200

MON KEY <monkey <at> sandpframing.com> writes:

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

I've now clarified the doc string in Emacs 24.

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/

Previous Next

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